Quickstart

Quickstart

This page gives the shortest safe path to useful output.

PIC has two normal use modes:

• install from PyPI for quick smoke checks and your own inputs;
• clone the repository for full practical workflows with bundled examples, fixtures, and development checks.

Path A: Installed Package

Use this when you want to check that PIC works and run simple local commands.

python -m pip install percolation-inversion-compiler
pic agent explain
pic demo installed-smoke --profile development
pic demo bootstrap --output-dir pic-demo
pic agent intake --text "Candidate packet: route evidence and preserve residuals." --profile development
pic runtime step --state pic-demo/runtime_state.json --input pic-demo/runtime_step_input.json --profile development

This path does not need the source repository.

Path B: Source Checkout

Use this when you want examples, fixtures, canonical-source audits, release checks, or full development workflows.

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 readiness --profile development
uv run pic agent doctor --profile development
uv run pic agent intake --text "Candidate packet: route evidence and preserve residuals." --profile development

Read The First Report

After an intake command, inspect:

• accepted
• operationally_usable
• settled
• missing_obligations
• residual_ledger
• agent_tasks
• route_execution_requests

Useful output often has settled=false. That means PIC preserved unresolved work instead of pretending the claim is complete.

Production Identity Flow

For production packet promotion, derive accepted identity context first.

uv run pic identity derive-context --population examples/agent_population_signed.json --profile production --output identity-context.json
uv run pic agent intake --text "Signed packet candidate." --profile production --identity-context identity-context.json

Cryptographic identity proves protocol-relative key control. It does not prove legal identity, real-world personhood, or global uniqueness.

Network And External Intake

Offline examples are safe starting points:

uv run pic agent communication-guide --profile development --no-allow-live-connectors
uv run pic agent network-readiness --profile development --no-allow-live-connectors
uv run pic ecology ingest-general --source examples/agent_network/feed.xml --kind rss
uv run pic ecology ingest-general --source examples/agent_network/page.html --kind web-page

Live HTTP, GitHub, Zenodo, and arXiv intake require explicit opt-in. External content remains a candidate until verifier, semantic edge, identity, rollback, and residual policies pass.

Next Pages

• Concepts in Plain Language
• Agent Guide
• CLI Recipes