Metadata-Version: 2.1
Name: retvest-ril
Version: 0.1.0a2
Summary: Retvest Intelligence Language CLI and dry-run transaction runtime
Author: Retvest AI
License: Proprietary
Project-URL: Source, https://github.com/cliffordprince1/retvest-ril
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic[email]==2.10.2
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
Provides-Extra: test
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "test"
Requires-Dist: pytest<9,>=8; extra == "test"

# Retvest Intelligence Language

RIL is a local transaction proof for governed AI work.

v0.1 proves dry-run pass/block behavior. v0.2 adds explicit local vault commit
proof. The current local slice also proves corpus-backed evidence packet
generation, support verification, fake hosted model export control, and an
explicit OpenAI provider adapter demo.

Full usage guide: `docs/ril/USAGE.md`.

## Governed DATA without PostgreSQL

RIL's default DATA target is its own append-only engine:

```bash
ril data plan program.ril --tenant tenant_acme --json
ril data run program.ril --tenant tenant_acme --engine-dir .ril-data \
  --agent agent:triage --authority lease:triage-42 \
  --lease-token-file .secrets/lease.token --evidence evidence:packet-7 --json
```

The lease must already exist in the engine. Writes are authority-checked, fsynced,
hash-chained, time-travel readable, and replay-verifiable. PostgreSQL is optional:
use `--target postgres` only when adopting RIL around an existing database.

Founder-facing proof:

```text
make ril-demo
```

This writes `.ril_runs/ril_demo/proof_summary.json` and
`.ril_runs/ril_demo/proof_summary.md` alongside the happy and blocked work
packages.

Explicit local commit proof:

```text
make ril-commit-demo
```

This writes a verified dry-run package, synthetic approval receipt, immutable
vault package, commit receipt, duplicate commit block result, vault verify
result, and proof summaries under `.ril_runs/ril_commit_demo/`.

Source corpus proof:

```text
make ril-corpus-demo
```

This builds a Markdown/TXT source corpus, writes `source_corpus.json`,
`source_manifest.json`, `chunks.json`, and `classification.json`, and proves
unsupported file types block.

Corpus-backed evidence packet proof:

```text
make ril-evidence-demo
```

This builds a source corpus, retrieves registry-declared keyword chunks,
generates a structured evidence packet, writes `retrieval_result.json`, accepts
the happy path, blocks an unresolved citation, and blocks an unsupported cited
claim.

Hosted model export-control proof:

```text
make ril-hosted-llm-export-demo
```

This proves `ALLOW EXPORT`/`DENY EXPORT` over a fake hosted model boundary:
internal corpus with tenant consent calls the fake provider, while no-consent
and secret corpus cases block before provider call.

Explicit OpenAI adapter proof:

```text
make ril-openai-adapter-demo
```

This deterministic target proves OpenAI-compatible response parsing, local
Ollama/vLLM endpoint routing without a real secret, remote no-key fail-closed
behavior, and the same verifier gates used after provider output.
Ollama defaults to native `/api/chat`; vLLM defaults to OpenAI-compatible
`/v1/chat/completions`.

Consumer Runtime outcome helper example:

```text
make runtime-outcome-example-check
```

The complete executable example is
`examples/consumer_runtime_outcome_receipt.py`. Its request and response
payloads are pinned to the shipped OpenAPI examples by the owner-repo gate.

```python
from ril import (
    ConsumerRuntimeOutcomeReceipt,
    ConsumerRuntimeOutcomeRequest,
    RuntimeAuditReceipt,
    validate_consumer_runtime_outcome_receipt_pair,
)

request = ConsumerRuntimeOutcomeRequest.model_validate(request_payload)
response = ConsumerRuntimeOutcomeReceipt.model_validate(response_payload)
assert isinstance(response.receipt, RuntimeAuditReceipt)
validate_consumer_runtime_outcome_receipt_pair(
    request,
    response,
    tenant_ref="tenant_acme_bank",
    work_id="work_01J1RTVSTKYC00001",
)
```

The `ConsumerRuntimeOutcomeRequest` and `ConsumerRuntimeOutcomeReceipt` helpers
are aliases for the shipped `RuntimeOutcomeReceiptRequest` and
`RuntimeOutcomeReceiptResponse` contract types. Keep examples in the OpenAPI
contract field shape; do not use stale camelCase helper payloads. DTO parsing
enforces only the shipped field constraints. Call the pair validator to enforce
route ownership, request/receipt bindings, receipt ordering, and audit-chain
semantics. Pair validation also requires the final outcome's nested audit
receipt to have a non-null `previous_digest`: generic runtime genesis receipts
may be unchained, but an outcome must advance the existing work audit chain.

DB-backed Consumer Runtime ownership proof:

```text
make consumer-runtime-db-proof-check
make consumer-runtime-postgres-proof-check
```

The first focused gate runs the full suite against a temporary SQLite database.
The second starts an ephemeral real PostgreSQL server and exercises registration,
heartbeat, bounded work lease, metadata-only evidence persistence, and competing
lease serialization. Both prove stale heartbeats and stolen lease tokens fail
closed without work or evidence side effects while appending privacy-minimized
refusal facts. Bearer tokens are persisted only as SHA-256 digests, and all
accepted and denied transitions form an immutable, replay-verifiable audit hash
chain. This local executable proof does not own or replace platform API state.

<!-- consumer-runtime-outcome-request:start -->
```json
{
  "agent_id": "agent_01J1RTVSTACME00001",
  "approval_id": "approval_01J1RTVSTKYC00001",
  "completed_at": "2026-06-27T11:18:44Z",
  "evidence_receipt_ids": [
    "evrec_01J1RTVSTKYC00001"
  ],
  "lease_token": "lease_tok_01J1RTVSTKYC00001",
  "outcome": "succeeded",
  "result_digest": "6666666666666666666666666666666666666666666666666666666666666666",
  "summary": "Daily KYC queue reconciliation completed with all evidence digests attached."
}
```
<!-- consumer-runtime-outcome-request:end -->

<!-- consumer-runtime-outcome-response:start -->
```json
{
  "accepted_at": "2026-06-27T11:18:45Z",
  "outcome_receipt_id": "outrec_01J1RTVSTKYC00001",
  "receipt": {
    "agent_id": "agent_01J1RTVSTACME00001",
    "audit_uri": "audit://tenant_acme_bank/runtime/rtrec_01J1OUTCOME0001.json",
    "created_at": "2026-06-27T11:18:45Z",
    "digest": "6666666666666666666666666666666666666666666666666666666666666666",
    "previous_digest": "5555555555555555555555555555555555555555555555555555555555555555",
    "receipt_id": "rtrec_01J1OUTCOME0001",
    "receipt_type": "outcome",
    "tenant_ref": "tenant_acme_bank",
    "work_id": "work_01J1RTVSTKYC00001"
  },
  "tenant_ref": "tenant_acme_bank",
  "work_id": "work_01J1RTVSTKYC00001"
}
```
<!-- consumer-runtime-outcome-response:end -->

Operator-led paid-pilot proof:

```text
make ril-pilot-operator-demo
```

This initializes a pilot workspace, creates a PASS review, records named
customer approval, commits with review, verifies the vault, builds
`audit_packet.zip`, and proves a REJECT review blocks commit.

Acceptance gate:

```text
make ril-real-v0
```

Editor highlighting and file icons:

```text
make ril-editor-vscode-vsix
make ril-editor-vscode-install
```

Long syntax showcase:

```text
examples/ril/showcase/enterprise_compliance_showcase.ril
```

Developer commands:

```text
apps/api/.venv/bin/pip install apps/ril --no-build-isolation
source apps/api/.venv/bin/activate

ril check examples/ril/compliance_evidence_packet/workflow.ril
ril corpus build examples/ril/source_corpus --name pilot_policy_corpus \
  --declared-class internal --out .ril_runs/source_corpus_demo
ril evidence build --registry .ril_runs/ril_evidence_demo/happy_path/ril.registry.json \
  --source-corpus policy_corpus --retriever keyword_retriever \
  --generator deterministic_evidence_packet --out .ril_runs/ril_evidence_demo/debug
ril explain examples/ril/compliance_evidence_packet/workflow.ril --json
ril preflight examples/ril/compliance_evidence_packet/workflow.ril \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json
ril run examples/ril/compliance_evidence_packet/workflow.ril --dry-run \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json
ril approve .ril_runs/.../work_package.json --role compliance_lead \
  --out .ril_runs/.../approval.json
ril commit .ril_runs/.../work_package.json \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json \
  --approval .ril_runs/.../approval.json
ril vault verify \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json \
  --target compliance_vault
```

`make ril-real-v0` performs no real model provider API calls. The fake hosted
provider remains the deterministic export-control proof. The OpenAI-compatible
adapter proof is explicit, deterministic, and kept outside `ril-real-v0`.
Dry-run remains non-committing but may still require EXPORT policy; real local vault writes
require the explicit approve/commit command chain.

Real v0 accepts the repo-local non-editable install above. Editable
`pip install -e apps/ril` support is tooling debt until the repo API venv loads
editable paths correctly.
