PIP — Prescriptive Intelligence Protocol (V1.0-beta)

A framework that turns a customer's tribal knowledge (SOPs, policies, past decisions) plus data access into structured prescriptions — decisions proposed with evidence, impact estimates, confidence, and a one-click path to execute.

Prescriptive intelligence is the walk stage between co-pilots (crawl) and autonomous software (run). PIP is the scaffolding that makes the paradigm tangible.

What's in V1.0-beta

• Seven-phase pipeline: bootstrap → connect → awareness → diagnose → prescribe → execute → learn.
• Declarative edges: user writes intent.md, drops SOPs into folders, fills one connections.yaml.
• Prompts as first-class artifacts under pipproto/prompts/ — the real IP.
• Consolidated SOPs are markdown-first artifacts with a required structured extract block for parsing.
• Awareness uses a bounded model-authored Python compute step to derive rollups before final reasoning.
• Paragraph-form hypotheses + rejected hypotheses with written rejection reasoning (the diagnosis engine is not a label classifier).
• Permission-gated execution (allow / ask / deny) with a written reason on every call — even allow.
• Cumulative verdict/outcome store → graduation candidates for auto-execution.

What's deliberately NOT in V1.0-beta

• No UI. Outputs are structured JSON.
• No production-grade transport features. Reads support local_file JSON or simple HTTP GET; writes support dry-run or simple bearer-auth JSON POST/PUT/PATCH.
• No RAG. Consolidated SOPs carry [ref: ...] markers back to raw source files.
• No PDF/DOCX ingestion. Markdown and plain text only.
• No pagination, retries, rollback, OAuth, or rich workflow orchestration.

See PIP-plan.md-style commentary inline in each phase module for detail.

Setup

Dependencies are installed directly on the machine (no venv):

python -c "import pydantic, yaml, click, openai; print('ok')"

If anything is missing, install it with python -m pip install <pkg>.

Set your OpenRouter key:

export OPENROUTER_API_KEY=sk-or-v1-...

Default models (changeable in pip.config.yaml):

• openai/gpt-5.4-mini — standard calls
• openai/gpt-5.4-mini — strong calls in the current demo config as well

Running the ReturnFlow demo

python -m pipproto.cli --root examples/returnflow-demo bootstrap      # Phase 1: consolidate SOPs + build domain model
python -m pipproto.cli --root examples/returnflow-demo awareness      # Phase 3: pull seeded data, compute KPIs, flag anomalies
python -m pipproto.cli --root examples/returnflow-demo diagnose       # Phase 4: hypothesis-driven diagnosis
python -m pipproto.cli --root examples/returnflow-demo prescribe      # Phase 5: ranked prescriptions
python -m pipproto.cli --root examples/returnflow-demo execute --yes  # Phase 6: dry-run execution, auto-approve 'ask'

Or, after bootstrap, the runtime shortcut:

python -m pipproto.cli --root examples/returnflow-demo run            # awareness → diagnose → prescribe

Verdicts and outcomes:

python -m pipproto.cli --root examples/returnflow-demo verdict rx-2026-04-20-001 accepted --reason "Approved by ops"
python -m pipproto.cli --root examples/returnflow-demo outcome rx-2026-04-20-001 0.11
python -m pipproto.cli --root examples/returnflow-demo graduate

Outputs land under outputs/{awareness,diagnoses,prescriptions,executions}/. Verdicts and outcomes land under learning/feedback-store.json.

Execution note:

• execution.dry_run: true means Phase 6 simulates writes and logs what would have happened.
• Set execution.dry_run: false to make real HTTP write calls through the configured transport.

Layout

pip.config.yaml          runtime config + model strings
intent.md                customer's voice — threaded through every phase
sops/                    per-decision folders, each with raw/ + generated consolidated.md
connections.yaml         single file: reads + writes, with permission per write
pipproto/                framework source (phases/, prompts/, types, cli)
outputs/                 generated per-run artifacts
learning/                verdicts, outcomes, graduation candidates
examples/returnflow-demo/ a fully-populated post-purchase example

Starting a new domain

mkdir my-deployment && cd my-deployment
cp ../examples/returnflow-demo/pip.config.yaml .
# author intent.md describing what you want PIP to do
# create sops/<core-business-decision>/raw/*.md with your real SOPs
python -m pipproto.cli --root . bootstrap      # generates consolidated SOPs + domain-model.json + connections.yaml skeleton
# fill in connections.yaml (local_file or simple GET endpoint for reads, JSON write endpoints, permission per write)
python -m pipproto.cli --root . run

No cartridges ship with PIP. Cartridges emerge from your SOPs.