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, schema export, bundled demos, and your own inputs. Use a source checkout when you want the full examples/... tree, canonical TeX audits, development checks, and release engineering 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 agent check --compact --text "Candidate packet: preserve residuals." --profile development
pic agent runbook --profile development
pic demo installed-smoke --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 check --compact --text "Candidate packet: route evidence and preserve residuals." --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 check --compact --text "Candidate packet: preserve residuals." --profile development
pic agent runbook --profile development
pic agent guide --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 agent readiness --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.
• workflow_usable: the compact agent workflow can guide next safe actions.
• 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.

Installed Package vs Source Checkout

PyPI is the practical path for first use. A clone is only required for repository fixtures, canonical TeX audits, release checks, and full development workflows.

pic demo bootstrap --output-dir pic-demo
pic runtime step --state pic-demo/runtime_state.json --input pic-demo/runtime_step_input.json --profile development
pic schema --all --output-dir schemas

Next Pages

• Use Cases
• Core Concepts
• For AI Agents