Getting Started

Getting Started

This page gives the first setup choices in general terms.

Use the installed package when you want a quick local checker. Use a source checkout when you want the full examples, fixtures, development checks, and research workflows.

Option 1: pip Install

Use this path for quick smoke checks, bundled demos, schema inspection, and your own JSON or text inputs.

python -m pip install percolation-inversion-compiler
pic agent explain
pic demo installed-smoke --profile development
pic agent intake --text "Candidate packet: preserve residuals." --profile development

Optional extras are available when you need identity checks, live connector support, or the local service layer:

python -m pip install "percolation-inversion-compiler[identity,connectors,server]"

Option 2: Source Checkout

Use this path for full practical workflows with repository fixtures and examples/....

git clone https://github.com/kadubon/percolation-inversion-compiler.git
cd percolation-inversion-compiler
uv sync --all-extras --dev

Then run commands through uv:

uv run pic agent explain
uv run pic agent guide --profile development
uv run pic agent intake --text "Candidate packet: route evidence and preserve residuals." --profile development

CLI

The CLI is the fastest way to inspect how PIC thinks.

pic agent explain
pic agent guide --profile development
pic agent intake --text "Candidate packet: preserve residuals." --profile development
pic schema --type AgentIntakeReport

After a source checkout, use:

uv run pic agent explain
uv run pic agent guide --profile development
uv run pic runtime step --state examples/runtime_state.json --input examples/runtime_step_input.json --profile development

Python SDK

Use the SDK when PIC should run inside another agent runtime, CI tool, or application.

from percolation_inversion_compiler.agent import AgentIntakeRequest, run_agent_intake

report = run_agent_intake(
    AgentIntakeRequest(
        agent_output="Candidate packet: preserve residuals and route missing verifier work.",
        profile="development",
    )
)

print(report.accepted)
print(report.operationally_usable)
print(report.settled)
print(report.missing_obligations)
print(report.residual_summary)

First Output Fields To Read

• accepted: the report envelope passed finite acceptance checks.
• operationally_usable: the result can guide routing under the selected profile.
• settled: scoped finite obligations are discharged. This is often false.
• missing_obligations: required checks that remain unresolved.
• residual_ledger: visible remaining debt, uncertainty, or external assumptions.

Next Pages

• Use Cases
• Core Concepts
• For AI Agents