Getting Started

Getting Started

This page helps you choose the right install path.

Use the pip install path when you want practical checks, schema export, bundled demos, Phase Ecology Lab diagnostics, CCR handoff JSONL, TRC trace checks, and your own JSON or text inputs.

Use the source checkout path when you need the full examples/... tree, development tests, canonical TeX audits, or release engineering.

Option 1: pip Install

This is the normal starting point for most users.

python -m pip install percolation-inversion-compiler
pic agent explain
pic agent check --compact --text "Candidate packet: preserve residuals." --profile development
pic phase plan --compact --text "Candidate packet: preserve residuals." --profile development
pic demo installed-smoke --profile development
pic demo bootstrap --output-dir pic-demo

For the v0.9 ASI-proxy loop reports:

pic token extract-pipeline --trace pic-demo/phase_lab_runtime_report.json --compact
pic token admissibility --token pic-demo/agent_report.json --compact
pic performance report
pic cache status

Then run the packaged Phase Lab demo:

pic phase lab init --output-dir pic-demo/phase-lab
pic phase lab ingest --store pic-demo/phase-lab --report pic-demo/phase_lab_runtime_report.json
pic phase lab observe --store pic-demo/phase-lab --window latest
pic phase lab graph --store pic-demo/phase-lab
pic phase lab closure --store pic-demo/phase-lab
pic phase lab executable-paths --store pic-demo/phase-lab
pic phase lab certify --store pic-demo/phase-lab --threshold pic-demo/phase_lab_threshold.json

The core install is enough for compact checks, bundled demos, schemas, snapshots, Phase Lab diagnostics, CCR task/residual JSONL, and TRC trace checks.

Use optional extras 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 when you want repository fixtures, examples, full development checks, or canonical audits.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
git clone https://github.com/kadubon/percolation-inversion-compiler.git
cd percolation-inversion-compiler
uv sync --all-extras --dev

macOS and Linux uv install:

curl -LsSf https://astral.sh/uv/install.sh | sh

Fallback uv install:

python -m pip install uv

Then run commands through uv run:

uv run pic agent check --compact --text "Candidate packet: preserve residuals." --profile development
uv run pic phase lab init --output-dir pic-phase-lab
uv run pic phase lab ingest --store pic-phase-lab --report examples/phase_lab/runtime_report_1.json
uv run pic phase lab graph --store pic-phase-lab
uv run pic phase plan --compact --emit ccr-tasks --output tasks.jsonl
uv run pic trc trace-normalize --input examples/asi_proxy_benchmark_bundle/trc_agent_trace.json --output trace_nf.json
uv run pic trc trace-check --trace trace_nf.json --output trace_check.json

What To Read First

• Quickstart for the shortest command paths.
• ASI Proxy Loop v0.9 for token, observation, residual, and CCR loop flow.
• Token Reports and Agent Loop for token extraction and admissibility.
• CCR Interop for v0.6.0 runtime handoff records.
• ASI Proxy Acceleration for TRC operation-readiness and ASI-proxy wording.
• Phase Ecology Lab for windowed diagnostics.
• Core Concepts for the terms used in reports.
• Safety and Limits before treating any output as authority.

First Interpretation Rule

PIC is fail-closed. accepted=true does not mean "go execute this." settled=false does not mean "the command failed." Token extraction is not settlement, and token admissibility is not capital admission. Useful diagnostics can be produced while unresolved work stays visible.