# Vincio

> Vincio is a Python platform for building AI applications you can trust in
> production. It compiles everything that goes *into* a model — prompts, memory,
> retrieved evidence, tools, schemas, and policies — into an optimized,
> validated, observable, provider-neutral **context packet**, then checks,
> measures, and traces everything that comes *out*.

Package: `pip install vincio` · Python 3.11+ · Apache 2.0 · SemVer.
Main entry point: `from vincio import ContextApp`.

This file is generated from `vincio.__all__` by `vincio._docmap` and gated for
freshness (a new public symbol must appear here), the way `api-generated.md` and
the error catalog are. It is a complete, machine-readable digest of the public
surface; for prose see the docs under `docs/` (start at `docs/learning-path.md`
and `docs/reference/capability-map.md`).

## Install

```bash
pip install vincio                  # core (only pydantic, httpx, pyyaml, typing-extensions)
pip install "vincio[openai]"        # + a provider (also: anthropic, google, mistral)
pip install "vincio[chroma]"        # + a vector store (also: pinecone, lancedb, pgvector, ...)
pip install "vincio[server]"        # + the FastAPI server (vincio serve / from vincio.server import create_app)
pip install "vincio[all]"           # every optional integration
```

Every heavy integration (vector stores, OCR, server, OpenTelemetry, charts, ...)
is an opt-in extra; the core is dependency-light and runs offline.

## Quickstart

```python
from vincio import ContextApp

# Uses your configured provider (set a provider+key, e.g. provider="openai" with
# OPENAI_API_KEY in the env). The DEFAULT provider is OpenAI, so configure one.
app = ContextApp(name="docs_qa", provider="openai", model="gpt-4o-mini")
app.add_source("docs", path="./docs", retrieval="hybrid")
app.set_policy("answer_only_from_sources", True)
result = app.run("How do I configure SSO?")
result.output; result.citations; result.trace_id; result.cost_usd

# Run FULLY OFFLINE (no key, no network): pass the bundled deterministic mock.
# It auto-generates schema-valid output, so the whole pipeline runs in CI.
from vincio.providers import MockProvider
app = ContextApp(name="dev", provider=MockProvider(), model="mock-1")

# Typed output: pass a Pydantic class; result.output is a validated instance
# (the mock fills it schema-valid offline; a real model fills it for real).
from pydantic import BaseModel
class Triage(BaseModel):
    label: str; confidence: float
app = ContextApp(name="triage", provider=MockProvider(), model="mock-1", output_schema=Triage)
app.run("export button 500s").output.label
```

## Ergonomic front door (vincio.tasks)

One-line, task-shaped constructors over `ContextApp` for the common jobs, plus
one fluent `Flow`. Each is `@experimental`, re-exported at top level, and lowers
to the exact same governed `ContextApp.run` packet as the verbose builder path
(retrieval, grounding, validation, rails, budgets, tracing, audit chain all
apply unchanged). `.app` on every facade is the escape hatch to all deep methods.

```python
from vincio import rag, extractor, tool_agent, evaluation, chat, Flow

rag("./docs").ask("How do I configure SSO?")             # grounded RAG Q&A
extractor(Triage).extract("export button 500s")          # typed extraction
tool_agent(tools=[lookup], writes=[refund]).run(task)    # approval-gated tools
evaluation(dataset, gates={"groundedness": ">= 0.8"}).run()   # offline eval + CI gate
chat().send("What's my refund window?")                  # a multi-turn Assistant
Flow(provider=p, model=m).retrieve("./docs").ground().run(question)  # one packet, fluent
```

## Mental model

- One object, `ContextApp`, owns the pipeline. Configure it, then `run`/`arun`/
  `stream`/`astream`/`submit`/`batch`. The surface is also grouped into six
  lazily-constructed capability facades — `app.runs`, `app.knowledge`,
  `app.governance`, `app.optimization`, `app.serving`, `app.training` — each a
  narrow view delegating to the same implementation.
- The run pipeline is one path: normalize → classify → policy → memory recall →
  retrieve → compile context (score / dedupe / conflict / compress / budget) →
  compile prompt (cache-aware) → model (+ bounded tool loop) → validate (schema /
  citations / policy, principled repair) → evaluate → trace → memory write.
- Deterministic where it matters: security, permissions, validation, and budgets
  are enforced in code, never gated on model output.
- Offline development uses the bundled `MockProvider` (pass it explicitly, or set
  a provider+key for a real run). It emits schema-valid output so the whole
  pipeline — validation, evals, traces, audit, cost — runs with no network.
- Every run yields one `RunResult` (typed output, citations, trace_id, cost_usd,
  usage, eval_scores, excluded_context), one trace, one cost entry, and one
  hash-chained audit entry.
- Errors all derive from `VincioError` and carry a stable `.code`, a
  `.remediation`, and a `.docs_url`. Catch the family with one `except`.
- Optional heavy features ride extras (`vincio[...]`); the dependency-light,
  offline-first path is always the default.

## Examples (three tiers, all runnable offline)

- `examples/notebooks/*.ipynb` — Google Colab-ready notebooks (one `pip install`,
  offline by default): quickstart, RAG, agents & tools, evaluation, data analysis.
- `examples/00`–`22` — complete, heavily-commented feature tours, one per subsystem.
- `examples/applications/` — real-world small backends: a FastAPI grounded-RAG
  service, a ticket-triage API, a structured-extraction service, and a CLI
  research agent. Each splits an offline-testable `core.py` from a FastAPI
  `main.py` and runs on the mock or a real model with one env var.

## Capability map (app.* by facet)

Every public `app.*` verb, grouped by capability facade. See docs/reference/capability-map.md for the concept/guide/example each links to.

### Runs
_Execute the pipeline: configure, run, stream, orchestrate, and produce deliverables._

- `app.abatch` — Async :meth:`batch`.
- `app.acited_report` — Build a cited report from an answer and its evidence (async) → a document artifact.
- `app.aclose` — Close the app's providers and release their resources.
- `app.add_output_schema` — Register an alternative output schema, routed by task or content.
- `app.add_skill` — Load an Agent Skill (``SKILL.md`` path or a :class:`Skill`) and inject it through the compiler with progressive disclosure: a one-line summary is always available; the full body is included only when a run's task is relevant. Set ``register_scripts=True`` to expose bundled scripts as sandboxed, permissioned tools.
- `app.add_tool` — Enable a tool: a callable (registered now) or the name of a tool already registered on app.tool_registry.
- `app.aedit_video` — Edit/extend a video through a :class:`~vincio.generation.video.VideoProvider`, metered, audited (``video_edit``), and C2PA-stamped (the manifest marks it as edited).
- `app.agenerate_image` — Generate image(s) through an :class:`~vincio.generation.image.ImageProvider`, metered against the budget, audited (``image_generate``), and C2PA-stamped per asset.
- `app.agenerate_video` — Generate a video through a :class:`~vincio.generation.video.VideoProvider`, metered against the budget, audited (``video_generate``), and C2PA-stamped per clip.
- `app.agent` — Build a bounded agent over the app's tools, memory, and retrieval.
- `app.areason` — Run universal reasoning once and return its full reasoning receipt.
- `app.aresearch` — Async :meth:`research`.
- `app.arun` — Run the full context-engineering pipeline asynchronously → :class:`RunResult`.
- `app.assistant` — Open a conversational, session-aware :class:`~vincio.assistant.Assistant`.
- `app.astream` — Run the full pipeline with end-to-end streaming.
- `app.asynthesize_speech` — Synthesize speech through a :class:`~vincio.generation.speech.SpeechProvider`, metered, audited (``speech_synthesize``), and audio-provenance-stamped.
- `app.atest_time_search` — Run verifier-guided test-time search over this app.
- `app.batch` — Run a set of inputs through a provider Batch API at ~half the cost.
- `app.build_document` — Render a validated result into a cited, contract-checked artifact.
- `app.cited_report` — Resolve ``[E1]`` citations into a rendered, footnoted, cited report.
- `app.computer_use` — Open a grounded, verified, reversible computer-use **action plane**.
- `app.configure` — Configure the prompt and run defaults declaratively (objective, role, rules, …).
- `app.crew` — Build a multi-agent crew over a shared blackboard.
- `app.edit_video` — Synchronous :meth:`aedit_video`.
- `app.enable_computer_use` — Register a computer-use action surface (navigate / click / type / screenshot) as audited, permissioned tools.
- `app.enable_self_correction` — Turn on bounded validate → critique → repair cycles for failed outputs. Structure-only: the critique and repair prompt forbid changing factual content, and all validators re-run each cycle.
- `app.generate_image` — Synchronous :meth:`agenerate_image`.
- `app.generate_video` — Synchronous :meth:`agenerate_video`.
- `app.graph` — A durable :class:`StateGraph` bound to the app's tracer and metadata store: checkpoints persist wherever the app's runs do, so threads survive restarts when the store is SQLite/Postgres.
- `app.predictor` — A :class:`~vincio.prompts.signatures.Predict` bound to the app's provider and model: ``app.predictor(Triage)(ticket="...")``.
- `app.reason` — Synchronous :meth:`areason`.
- `app.reasoning` — Build a :class:`~vincio.agents.reasoning.ReasoningController`.
- `app.research` — Run the deep-research loop: search → read → reflect → verify → synthesize, emitting a cited, budget-bounded, eval-scored report.
- `app.run` — Run the full context-engineering pipeline synchronously → :class:`RunResult`.
- `app.set_policy` — Set a run policy (e.g. ``answer_only_from_sources``).
- `app.stats` — Return a snapshot of the app's configured sources, tools, evaluators, and memory.
- `app.stream` — Synchronous streaming convenience: collects the async event stream and yields the events in order (like provider.stream_sync).
- `app.submit` — Start a run in the background and return a :class:`RunHandle`.
- `app.synthesize_speech` — Synchronous :meth:`asynthesize_speech`.
- `app.task` — Configure the app from a task class::
- `app.test_time_search` — Synchronous :meth:`atest_time_search`.
- `app.use_hosted_tools` — Surface provider-native hosted tools (``web_search`` / ``file_search`` / ``code_interpreter`` / ``computer_use``) as namespaced Vincio tools.
- `app.use_pack` — Apply a domain pack: prompt config + schema + policies + evaluators + rails.
- `app.use_reasoning_controller` — Install a reasoning controller so the runtime sets effort per run.
- `app.use_reasoning_engine` — Install adaptive universal reasoning on ordinary ``run`` / ``arun``.
- `app.use_web_search` — Give this app's model — **any** model — governed access to the open web.
- `app.voice_agent` — Open an end-to-end :class:`~vincio.realtime.VoiceAgent`.
- `app.web_crawl` — Crawl a site into a governed, offline-verifiable :class:`~vincio.web.WebCollection`.
- `app.workflow` — Create a deterministic :class:`Workflow` builder bound to this app's tracer.

### Knowledge
_Feed the compiler: sources, retrieval, memory, structured data, and the analytics plane._

- `app.add_memory` — Enable the scoped memory engine (hybrid vector+graph recall by default).
- `app.add_source` — Register a knowledge source: load, chunk, and index documents.
- `app.aggregate_stream` — Group a dataset larger than memory by one or more columns and reduce measures over each group in a single bounded-memory pass.
- `app.analyze_data` — Run a bounded, multi-step analysis over a registered dataset and return a **cited analytical narrative** — the data plane's analyst agent.
- `app.consolidate_memory` — Run episodic→semantic memory consolidation as a maintenance pass.
- `app.context_budget_report` — The installed governor's live context-budget report (or ``None``).
- `app.data_catalog` — The app's lazily-created :class:`~vincio.data.DataCatalog` — the grounding source for :meth:`query_data` and the catalog a :meth:`~vincio.data.QueryResult.verify` re-executes against.
- `app.data_engagement` — Thread the whole data & analytics plane behind one governed call-path.
- `app.enable_memory_os` — Expose self-editing memory (MemGPT/Letta-class) as permissioned tools.
- `app.federated_data_engagement` — Run a governed analytics query **across organizations** without pooling the raw rows — the cross-org / federated twin of :meth:`data_engagement`.
- `app.fit_dataset` — Fit a dataset far larger than the window into a fixed token budget: a full-fidelity column profile plus a representative sample sized to whatever budget the profile leaves.
- `app.generate_chart` — Turn a cited query result into a **content-bound, data-bound** chart — the data plane's generated analytical artifact.
- `app.govern_packet` — Admit a run's evidence into the installed long-horizon governor.
- `app.ingest_files` — Ad-hoc file ingestion for run(files=[...]): load, chunk, index.
- `app.load_media` — Ingest audio/video as a timestamped transcript Document (:func:`vincio.documents.load_media`).
- `app.load_video` — Ingest a video as a temporally-segmented Document (:func:`vincio.documents.load_video`).
- `app.map_stream` — Run an analytical transform over a dataset larger than memory *at scale* by chunking it into the provider Batch API.
- `app.metric_lineage` — The **column-level provenance** of a governed metric — the base columns and source it rests on, resolving the derived-column graph and any ratio references.
- `app.profile_dataset` — Compute a deterministic, bounded-memory column profile of a dataset — per column its type, null rate, cardinality, extrema, mean/stddev, percentiles, a distribution histogram, and exemplars.
- `app.query_data` — Turn a natural-language question (or explicit SQL / dataframe ops) over a registered dataset into a query that is **schema-grounded and verified before it runs**, executed where the data lives rather than materialized into the prompt, and whose answer **cites the exact rows and cells** it rests on — the analytics analogue of a cited report, offline-verifiable.
- `app.query_metric` — Compute a **governed metric** — a measure resolved through a :class:`~vincio.data.SemanticLayer` and computed **one way everywhere**.
- `app.recall` — Ergonomic memory recall over user/agent/session scopes.
- `app.register_dataset` — Register a dataset in the app's data catalog so :meth:`query_data` can ground and execute a query against it by name.
- `app.remember` — Ergonomic memory write; creates the memory engine on first use.
- `app.retrieve_evidence` — Run the LAGER lazy loop directly → an :class:`~vincio.lager.EvidencePack`.
- `app.retrieve_facts` — Retrieve by the facts a task *needs*, reporting per-fact coverage and gaps.
- `app.sample_dataset` — Draw a representative sample of up to ``n`` rows that stands in for the whole dataset, replacing a biased first-N cutoff.
- `app.screen_data` — Screen a tabular input for schema violations, constraint breaks, and anomalies on the same deterministic rail path PII and injection detection ride. The decision lands on the shared audit chain (``data_quality``).
- `app.semantic_layer` — Define a :class:`~vincio.data.SemanticLayer` over a registered table — measures, dimensions, and derived columns declared **once** so a question maps to a **governed metric** rather than a raw column.
- `app.stream_analytics` — Open a governed real-time analytics driver over an **unbounded event stream** — the profiling, query, governed-metric, and quality primitives re-expressed window by window.
- `app.stream_dataset` — Open a dataset larger than memory as a lazy, schema-bearing :class:`~vincio.data.RowStream` — the out-of-core handle the streaming operators consume in bounded passes.
- `app.table_evidence` — Build first-class tabular evidence — a typed, columnar dataset rendered header-once — from rows, records, a :class:`~vincio.data.Dataset`, or a legacy ``TableData``.
- `app.task_brief` — The current task-frame brief — the compact, constraint-first digest of every ``anchor=True`` source, injected as pinned evidence on every run — or ``None`` when no anchors are registered.
- `app.use_context_governor` — Install a long-horizon :class:`~vincio.context.ContextGovernor`.
- `app.use_lager` — Attach a LAGER engine: reasoning-driven retrieval replaces top-k.

### Governance
_Prove it is safe: compliance, security, privacy, identity, verification, assurance, and the cross-org trust fabric._

- `app.achoreograph` — Run a durable, compensating cross-org saga; return a :class:`SagaResult`.
- `app.add_rail` — Add a programmable input/output rail (topic, format, safety, custom).
- `app.admit` — Decide a counterparty's admitted exposure from its earned standing.
- `app.agather_reputation` — Assemble a current prior by pulling signed artifacts from a bounded peer set.
- `app.aibom` — Generate an AI bill of materials (:class:`~vincio.governance.AIBOM`) for the live model/embedder/reranker, with SHA-256 model-hash slots.
- `app.anegotiate` — Run a bounded buyer/seller negotiation; return a :class:`NegotiationResult`.
- `app.annex_iv` — Generate EU AI Act Annex IV technical documentation as a cited artifact.
- `app.arbitrate` — Adjudicate a disputed contract from the records its parties submit.
- `app.aresume_choreography` — Resume a saga from this app's durable store after a restart.
- `app.assurance_case` — Assemble the platform's evidence into one continuously-checkable safety argument.
- `app.attest_custody` — Attest a poster's proven reserves into a signed, content-bound proof-of-reserves.
- `app.attest_liabilities` — Attest a poster's total obligations into a signed, content-bound proof-of-liabilities.
- `app.attest_reputation` — Issue a signed, portable attestation of a counterparty's earned standing.
- `app.behavior_monitor` — Build a :class:`~vincio.verify.RuntimeMonitor` over one or more :class:`~vincio.verify.BehaviorSpec`\ s.
- `app.build_seniority_schedule` — Rank a poster's obligations into a signed, content-bound seniority schedule.
- `app.build_set_off_statement` — Collapse the mutual obligations between a poster and one creditor into a statement.
- `app.certify` — Emit a portable, offline-verifiable production-certification report.
- `app.check_completeness` — Fold creditor claims against a liability attestation into a completeness check.
- `app.check_history_consistency` — Walk a poster's liability snapshots for cross-time monotonicity (no debt silently dropped).
- `app.check_residency` — Enforce data-residency routing: refuse disallowed egress.
- `app.check_root_consistency` — Compare liability attestations across creditors for cross-org non-equivocation.
- `app.choreograph` — Synchronous wrapper around :meth:`achoreograph`.
- `app.clear_settlements` — Net a fleet's settlement books into one minimal cleared set.
- `app.compliance_report` — Map this app's controls to OWASP/NIST/MITRE frameworks as a coverage matrix, backed by red-team and eval evidence (:class:`~vincio.governance.ComplianceReport`).
- `app.cross_org_engagement` — Thread the whole cross-org settlement & credit fabric behind one call-path.
- `app.discharge_liability` — Issue a signed, content-bound :class:`~vincio.settlement.Discharge` of what ``poster`` owes.
- `app.draw_pool` — Draw one backed contract's settlement against a collateral pool (draw or release).
- `app.enforce_contract` — Check delivered work against a contract and record the verdict.
- `app.erase_source` — Right-to-erasure-by-source: purge a source from indexes, memory, caches, and generated artifacts, logged on the hash-chained audit chain.
- `app.fria` — Generate an EU AI Act Art. 27 fundamental-rights impact assessment.
- `app.gather_reputation` — Synchronous wrapper around :meth:`agather_reputation`.
- `app.guard_collateral` — Fold a counterparty's collateral pools into a bounded re-use guard.
- `app.identity` — Mint a portable, self-certifying :class:`~vincio.security.AgentIdentity`.
- `app.import_reputation` — Combine other orgs' attestations into a prior that weights negotiation.
- `app.inclusion_proof` — Build an offline-verifiable inclusion proof for one creditor's liability claim.
- `app.issue_credential` — Issue a signed, offline-verifiable :class:`~vincio.security.AgentCredential`.
- `app.mark_output` — Build a C2PA-style synthetic-content provenance manifest for output (:class:`~vincio.governance.ProvenanceManifest`).
- `app.meter` — A :class:`~vincio.settlement.Meter` accruing usage against a contract.
- `app.model_card` — Generate a :class:`~vincio.governance.ModelCard` from the live config.
- `app.negotiate` — Synchronous wrapper around :meth:`anegotiate`.
- `app.post_collateral_pool` — Post one stake backing many contracts as a signed, offline-verifiable margin account.
- `app.post_escrow` — Post collateral against a contract as a signed, offline-verifiable escrow.
- `app.principal_for` — Build the :class:`Principal` (user, tenant, scopes) for an input.
- `app.privacy_report` — Per-subject differential-privacy budget roll-up.
- `app.prove_solvency` — Fold a reserve proof against a liability proof into a proof-of-solvency.
- `app.register_rail_predicate` — Register a custom rail predicate: ``(text, params) -> falsy | message``.
- `app.resolve_insolvency` — Distribute a poster's proven reserves across its ranked liabilities into a resolution.
- `app.resume_choreography` — Synchronous wrapper around :meth:`aresume_choreography`.
- `app.revoke_attestation` — Withdraw a prior attestation, by its hash, as a signed revocation.
- `app.risk_tier` — Classify this app into the EU AI Act risk tiers (advisory).
- `app.serve_attestations` — Expose this app's earned standing as a queryable attestation peer over A2A.
- `app.serve_choreography` — Expose this org's choreography handlers over A2A.
- `app.serve_negotiation` — Expose a local negotiating :class:`~vincio.negotiation.Party` over A2A.
- `app.set_privacy_budget` — Set a per-subject (or default) differential-privacy budget.
- `app.set_residency` — Pin allowed provider regions; runs outside them are refused egress.
- `app.settle` — Close the books on contracted work: reconcile, sign, audit, and record.
- `app.settle_escrow` — Resolve a posted escrow against a settlement record (release or forfeit).
- `app.settle_saga` — Close the books on every contract a cross-org saga ran under.
- `app.settlement_report` — Per-counterparty settlement roll-up — beside the cost report.
- `app.shield` — Build a :class:`~vincio.verify.Shield` that prevents a behavioural violation.
- `app.synthesize_program` — Synthesize and verify a small data-transform program.
- `app.system_card` — Generate a :class:`~vincio.governance.SystemCard` (model + retrieval + memory + safety filters + human-oversight points) from the live config.
- `app.tenant_filter` — Tenant-scope filter for retrieval.
- `app.trace_lineage` — Return the source → chunk → evidence → output lineage for a source name or document id (:class:`~vincio.governance.LineageRecord`).
- `app.use_consent_ledger` — Attach a :class:`~vincio.governance.consent.ConsentLedger`.
- `app.use_identity` — Bind ``identity`` as this app's signer so every artifact carries its DID.
- `app.use_privacy_accountant` — Attach a differential-privacy accountant over the learning loop.
- `app.use_settlement_book` — Attach a durable, hash-chained ledger of cross-org settlements.
- `app.use_shield` — Install (or clear, with ``None``) a behavioural shield on the tool runtime.
- `app.verify_governance` — Formally verify the governance invariants hold, ahead of any run.
- `app.verify_reasoning` — Attach and check a deterministic :class:`~vincio.verify.Certificate` to an answer.

### Optimization
_Make it better and cheaper: cost, evaluation, self-improvement, routing, caching, and energy._

- `app.add_evaluator` — Register a metric (by name or callable) that scores every run.
- `app.add_metric_rail` — Use an eval metric as a runtime guardrail. The same metric that gates releases offline blocks (or warns on) generations at run time::
- `app.add_online_evaluator` — Score a sampled fraction of live runs with ``metric`` after each run completes, writing the score as a time series on the metadata store (no traffic mirrored anywhere). Scoring runs off the hot path; sampling bounds the overhead. The same metric object can gate releases offline and act as a runtime guardrail::
- `app.add_optimizer` — Register an optimization dimension the improvement loop may tune.
- `app.add_validator` — Register a semantic output validator (blocking by default).
- `app.aflush_online` — Await any in-flight online evaluations (for tests and shutdown).
- `app.agate_swap` — Gate a model swap on replayed golden traces + an eval/cost/latency/ behavioral diff with statistical backing. Returns a :class:`~vincio.evals.swap.SwapVerdict`.
- `app.aswap_regression` — Swap only the model on a fixed dataset and return a statistically grounded :class:`~vincio.evals.swap.SwapRegressionReport`.
- `app.benchmark_suite` — Run the open evaluation plane over this app and return a ``SuiteRun``.
- `app.calibrate_judge` — Reflectively tune an LLM judge's evaluation steps for κ agreement.
- `app.canary` — Ramp ``percent``% of live traffic onto ``candidate_model`` with online scoring and auto-rollback to the primary (and prompt-registry head) on regression. Returns the :class:`~vincio.providers.shadow.CanaryRouter`, which also becomes the app's provider.
- `app.cost_report` — Roll up attributed model cost by ``tenant``/``feature``/``user``/ ``model``/``provider``/``run`` (returns a :class:`CostReport`).
- `app.enable_prompt_caching` — Turn on provider-aware prompt caching (default on).
- `app.energy_report` — Roll up estimated energy + carbon by ``tenant``/``feature``/``user``/ ``model``/``provider``/``run`` (returns an :class:`EnergyReport`).
- `app.eval_target` — EvalRunner adapter: run one case through the app.
- `app.evaluate` — Evaluate the app over a dataset and return an :class:`EvalReport`.
- `app.experiment` — A production-style A/B over prompt/model/config variants of this app, compared on eval metrics *and* cost with significance tests. Returns an :class:`~vincio.evals.experiments.Experiment` handle; if ``variants`` and ``dataset`` are given, every variant is evaluated first::
- `app.gate_compression` — Adopt a learned compressor only if it preserves cited facts and quality.
- `app.gate_swap` — Synchronous :meth:`agate_swap`.
- `app.improvement_loop` — The trace → dataset → eval → optimize → promote loop on this app.
- `app.kv_prefix_report` — The installed KV-prefix pool's reuse report (or ``None``).
- `app.reflective_optimize` — Run the GEPA-style reflective optimizer against ``dataset``.
- `app.reputation_report` — Per-member cross-fleet reputation roll-up.
- `app.resolve_provider` — Resolve the model provider for a run, enforcing data residency first.
- `app.self_improvement` — The unified, declarative self-improvement contract.
- `app.semantic_cache_report` — The installed semantic cache's stats (or ``None``).
- `app.set_cost_budget` — Enforce a per-tenant/feature/user cost budget.
- `app.set_energy_budget` — Set an energy/carbon budget, refused on breach like a cost cap.
- `app.shadow` — Serve the primary model but dual-dispatch ``candidate_model`` for an offline diff. Returns the :class:`~vincio.providers.shadow.ShadowProvider` (read ``.observations`` / ``.diff()``); it also becomes the app's provider so every run is shadowed until removed.
- `app.swap_regression` — Synchronous :meth:`aswap_regression`.
- `app.use_bandit_router` — Route live traffic through a guarded online bandit over ``models``.
- `app.use_cascade` — Route runs through a cheap→strong model cascade at run time.
- `app.use_energy_accounting` — Turn on per-run energy & carbon accounting (opt-in).
- `app.use_kv_prefix_reuse` — Install a KV-prefix pool so cross-request stable-prefix reuse is tracked.
- `app.use_learned_budgets` — Install eval-tuned per-task budget allocations.
- `app.use_learned_compression` — Install a learned token-importance compressor on the compiler.
- `app.use_reputation_ledger` — Attach a cross-fleet reputation ledger over the federated round.
- `app.use_router` — Route each run to the cheapest / fastest / least-busy *capable* model.
- `app.use_semantic_cache` — Install a learned semantic cache so near-misses are served from cache.
- `app.use_semantic_context_scoring` — Score and select context by embedding cosine instead of lexical overlap.
- `app.watch_lifecycle` — Scan pinned models for sunset and (optionally) propose migrations off deprecated/retired/nearing-retirement ones. Returns ``{"alerts", "proposals"}``; defaults to the app's pinned models.

### Serving
_Expose it: MCP / A2A servers, realtime, the governed fabric, deploy, and the edge runtime._

- `app.add_mcp_from_registry` — Discover an MCP server from a registry and land its tools in the permissioned runtime — one governed call (the marketplace bridge).
- `app.add_mcp_server` — Connect to an MCP server and register its tools/resources/prompts.
- `app.agent_directory` — A governed, audited :class:`~vincio.registry.AgentDirectory` for this app.
- `app.deploy` — Canary-gate a prompt/policy candidate and deploy it only if it clears.
- `app.edge_runtime` — Build a bounded, in-process edge runtime that shares this app's rails.
- `app.mcp_app` — Bridge a consumed MCP server's UI resources onto the AG-UI channel.
- `app.realtime_session` — Open a voice/realtime session (returns a :class:`RealtimeSession`).
- `app.serve_a2a` — Expose a crew, a compiled graph, or this app over A2A.
- `app.serve_mcp` — Expose this app as an MCP server (returns an :class:`MCPServer`).

### Training
_Teach it: trace capture, dataset export, distillation, on-policy learning, local adaptation, federation, and skill acquisition._

- `app.adapt_locally` — Fit, gate, and (on a pass) install an on-device adapter — one call.
- `app.adopt_federated` — Aggregate a fleet's contributions, refit, gate, and adopt — one call.
- `app.contribute_federated` — Build this member's privacy-preserving contribution to a federated round.
- `app.cultivate` — Grow capability open-endedly: propose → attempt → verify → distill → promote.
- `app.distill` — Teacher → student distillation, gated on holding quality.
- `app.enable_training_capture` — Record the full output and cited evidence on every trace, so :meth:`export_training_set` can curate faithful, grounded fine-tuning data. Off by default (the span output stays truncated for cost)::
- `app.export_training_set` — Curate runs or captured traces into a grounded fine-tuning :class:`TrainingSet`.
- `app.federated_improvement` — The cross-org federated-improvement round, as a streaming controller.
- `app.learn` — On-policy reinforcement from verifiable rewards (RLVR).
- `app.local_adaptation` — The continual on-device adaptation loop, as a streaming controller.
- `app.use_local_adapter` — Apply (or remove) an on-device LoRA-class adapter on the base provider.

## Public API (559 public symbols)

Every introspectable name in `vincio.__all__` — the exact set Semantic Versioning applies to (the `__version__` value aside). Import every name from the top-level `vincio` package.

### Classes

- `A2ANegotiator(client, member_id, role=…)` — A negotiating :class:`Party` whose moves are made by a remote A2A agent.
- `AIBOM(**data)` — An AI bill of materials, serializable as CycloneDX 1.6 JSON.
- `ActionOutcome(**data)` — The result of one full perceive → gate → act → verify → undo cycle.
- `ActionPolicy(**data)` — The pre-gate rail: what is in scope and what needs approval.
- `AdaptationResult(**data)` — The outcome of one gated on-device adaptation cycle.
- `AdaptedProvider(base, adapter, embedder=…)` — Apply a :class:`LocalAdapter` to any base provider at generation time.
- `AdapterGate(metric=…, regression_threshold=…, require_significance=…, min_samples=…, alpha=…)` — No-regression gate for an on-device adapter, the model-swap gate's analog.
- `AdapterRegistry(directory=…)` — A versioned, reversible store of on-device adapters.
- `AdaptiveSampler(cases, sample, gate, metric=…, budget, seed_samples=…, confidence=…, weights=…)` — Decide a mean-aggregate gate with the fewest samples by allocating the budget to the highest-variance cases and stopping as soon as the verdict is certain.
- `AdmissionConfig(**data)` — How a counterparty's standing maps to a bounded exposure posture.
- `AdmissionDecision(**data)` — A bounded, offline-verifiable exposure posture for one counterparty.
- `AdmissionPolicy(config=…)` — A graduated-exposure policy over the standing the fabric already earns.
- `AdmissionVerification(**data)` — The (non-raising) outcome of verifying an admission decision offline.
- `AgentCredential(**data)` — A signed, verifiable claim an org makes about an agent.
- `AgentDirectory(allow_list=…, audit=…, principal=…)` — A governed, discoverable directory of agents across A2A / ACP / MCP.
- `AgentIdentity(keyring, name=…)` — A portable agent identity: a keyring, its document, and an accountable signer.
- `AgentRole(**data)` — A named role in a crew: who the agent is and what share it gets.
- `AlertManager(sinks=…)` — Evaluates :class:`AlertRule`\ s over a metric stream and dispatches alerts.
- `AlertRule(**data)` — One alerting rule over a metric stream.
- `AlertSink(*args, **kwargs)` — Base class for protocol classes.
- `AllowListGate(allow=…, deny=…, default_allow=…, action=…)` — A reachability allow-list for the agent fabric.
- `AnalysisAgent(app, budget=…, engine=…, propose_followups=…, max_followups=…)` — Plan → query → inspect → refine → synthesize, cited and budget-bounded.
- `AnalysisResult(**data)` — A bounded, multi-step analysis rendered as a **cited analytical narrative**.
- `AnnexIVBuilder(classifier=…)` — Render EU AI Act **Annex IV** technical documentation as a cited document.
- `ApprovalRecord(**data)` — A tool-approval decision made during a turn.
- `ArithmeticVerifier()` — Recomputes arithmetic equalities stated in an answer.
- `Assistant(app, user_id=…, tenant_id=…, session_id=…, memory_writeback=…, auto_approve=…, on_approval=…, feature=…)` — A multi-turn conversational session over a :class:`ContextApp`.
- `AssistantTurn(**data)` — The outcome of one conversational turn.
- `AssuranceCase(**data)` — A signed, content-bound assurance argument the platform keeps continuously valid.
- `AssuranceReport(**data)` — The content-bound outcome of re-checking a case against current evidence.
- `AttestationExchange(client, peer_id=…)` — A peer reached over A2A that an importer pulls signed artifacts from.
- `AttestationRevocation(**data)` — A signed, offline-verifiable withdrawal of a prior attestation by its hash.
- `AutoCurriculum(tasks, rails=…, governance=…, world_model=…, search=…, max_tasks=…)` — Propose the next frontier tasks, gated by rails and the governance verifier.
- `BatchRunner(backend, price_table=…, tracer=…, discount=…, poll_interval_s=…, timeout_s=…, clock=…)` — Submit a batch, poll it to completion, reconcile, and cost-track.
- `BehaviorEvent(**data)` — One observable step in an agent's trajectory.
- `BehaviorSpec(**data)` — A temporal-logic-lite property over an event trajectory, as plain data.
- `BenchmarkAdapter(tasks=…, fixture_path=…)` — Base contract for a leaderboard adapter.
- `BenchmarkDataset(**data)` — A pinned set of :class:`~vincio.evals.benchmarks.BenchmarkTask`s and its provenance tier ceiling.
- `BenchmarkRegistry(with_builtins=…)` — A niche-grouped catalog of :class:`BenchmarkSpec`s.
- `BenchmarkSpec(**data)` — One catalog entry: a benchmark, the adapter that scores it, and its provenance.
- `BenchmarkSuite(registry=…, concurrency=…, seed=…, checkpoint_dir=…)` — Run benchmarks over a model or app, deterministically and resumably.
- `BeneficiaryClaim(**data)` — One beneficiary's bounded claim on the poster's held capital.
- `BindingCandidate(**data)` — One ranked candidate for a capability binding, the decision's evidence.
- `BindingWeights(**data)` — How a candidate's signals combine into one ranking score.
- `Blackboard(event_bus=…)` — Versioned, author-attributed shared memory for agent teams.
- `BootstrapFinetune(evaluate_model, quality_metric=…, min_quality_ratio=…, gates=…, trainer=…, swap_gate=…, dedupe_embedder=…)` — Teacher → student distillation with a gated quality hold.
- `Budget(**data)` — Hard resource limits for a run (budgets, termination).
- `BudgetManager(ledger, events=…)` — Enforces :class:`CostBudget`/:class:`EnergyBudget`\ s and detects spend anomalies.
- `BundleRecord(**data)` — One governed, content-bound entry in the community index.
- `CalibrationExample(**data)` — One labelled near-miss observation used to calibrate the threshold.
- `CalibrationReport(**data)` — The verdict of :meth:`WorldModel.calibrate`, the model's planning weight.
- `CanaryRouter(primary, candidate, percent=…, candidate_model=…, score_fn=…, min_samples=…, window=…, regression_threshold=…, on_rollback=…, prompt_registry=…, prompt_name=…, events=…)` — Ramp a percentage of live traffic onto a candidate, with auto-rollback.
- `CanarySpec(**data)` — How a candidate is qualified before it is deployed live.
- `CapabilityBinder(directory, reputation=…, settlement_book=…, weights=…, principal=…)` — Resolves a capability-declaring saga step to a participant at dispatch time.
- `CapabilityBroker(secret=…, default_ttl_s=…)` — Mints and verifies :class:`CapabilityToken`\ s from the user's authority.
- `CapabilityToken(**data)` — An unforgeable, capability-scoped grant minted from the user's request.
- `CausalAttributor(app, dataset, factors, metric=…, aggregate=…, repeats=…, concurrency=…)` — Attribute a metric delta to the components a release changed, by Shapley counterfactual replay over the dataset.
- `CellCitation(**data)` — A reference to one source cell an answer rests on.
- `CellRef(**data)` — A reference to one source cell a series value came from.
- `Certificate(**data)` — A typed, content-bound, offline-verifiable proof over an answer.
- `CertificationReport(**data)` — The signed, content-bound certificate that an app is fit for production.
- `Chart(**data)` — A rendered chart, **content-bound and data-bound**.
- `ChartSpec(**data)` — A spec-driven chart definition: title, mark, channel encoding, the plotted columns, and the **values** it depicts (a projection of the source result onto the encoded columns). :meth:`to_vega_lite` renders it as a portable, embedded-data Vega-Lite v5 spec a consumer can render with any Vega-Lite runtime.
- `ChartType(*args, **kwds)` — The closed mark vocabulary a chart declares — the deterministic subset of Vega-Lite marks that also rasterizes cleanly through matplotlib.
- `Check(**data)` — One kernel's verdict on an answer.
- `Choreography(saga, participants, coordinator=…, store=…, audit=…, events=…, signer=…, binder=…, clock=…, raise_on_compensation_failure=…)` — Drives a :class:`~vincio.choreography.saga.Saga` across organizations.
- `CircuitBreaker(inner, failure_threshold=…, min_calls=…, window=…, latency_threshold_ms=…, cooldown_s=…, half_open_max=…, events=…, clock=…)` — Per-provider circuit breaker with half-open probing.
- `CitationContract(**data)` — Field/claim-level citation requirements for a cited report.
- `CitationVerifier(evidence=…)` — Checks every verifiable claim in an answer is entailed by cited evidence.
- `CitedReportBuilder(entailment=…, audit_log=…, tenant_id=…)` — Resolve citations, verify per-claim support, render a cited report.
- `CitedSeries(**data)` — A named numeric series bound to the source cells it was read from.
- `Claim(**data)` — A node in the assurance argument: a statement, its decomposition, its evidence.
- `ClaimStatus(**data)` — The re-derived verdict for one claim and its subtree.
- `CollateralLedger(**data)` — A poster's cross-pool rehypothecation view, a bounded re-use guard.
- `CollateralLedgerVerification(**data)` — The (non-raising) outcome of verifying a collateral ledger offline.
- `CollateralPool(**data)` — A counterparty's single posted stake backing many contracts, a margin account.
- `CollateralPoolVerification(**data)` — The (non-raising) outcome of verifying a collateral pool offline.
- `CommunityRegistry(allow_list=…, audit=…, signer=…, principal=…, require_signature=…, index=…)` — A governed, signed, audited index of community packs and skills.
- `CompletenessProof(**data)` — A signed, offline-verifiable completeness check over a liability attestation.
- `CompletenessVerification(**data)` — The (non-raising) outcome of verifying a completeness check offline.
- `ComplianceFramework(*args, **kwds)` — A governance framework whose controls Vincio maps onto.
- `ComplianceReport(**data)` — A coverage matrix across the mapped frameworks.
- `CompositeVerifier(verifiers)` — Runs an ordered set of verifiers and folds their checks into one certificate.
- `ComputerEnvironment(backend, app=…, policy=…, approve=…, auto_undo=…, max_steps=…)` — A grounded, verified, reversible computer-use action plane.
- `ComputerRun(**data)` — The outcome of driving a policy through the action plane to a goal.
- `ComputerTask(**data)` — A computer-use goal: a natural-language instruction plus a declarative end-state verifier and an action budget. The verifier reads the same :class:`~vincio.evals.environment.StateCheck` paths an environment oracle does, so a run's success is verifiable end-state, not turn-by-turn plausibility.
- `ConsentLedger(store=…, audit=…, default_allow=…)` — Records and checks consent, binding data to a purpose + lawful basis.
- `Constraint(text=…, **data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `ConstraintVerifier(constraints=…)` — Checks a candidate assignment satisfies a set of typed constraints.
- `ContainmentMonitor()` — Records capability exercises so containment can be proven after a run.
- `ContainmentReport(**data)` — The verdict of checking the containment invariant over a run.
- `ContentCapturePolicy(**data)` — Gate + redact prompt/completion content at the telemetry export boundary.
- `ContextApp(name=…, objective=…, output_schema=…, config=…, provider=…, model=…, budget=…, policies=…, prompt_spec=…)` — The top-level Vincio application: one object that compiles prompts, memory, retrieval, tools, schemas, and policies into validated, observable, model-ready context and runs the end-to-end pipeline.
- `ContextBudget(**data)` — A per-run context budget: the residency analogue of a dollar budget.
- `ContextCompactor(store=…, memory=…, owner_id=…, scope=…, summary_tokens=…, summarizer=…)` — Hierarchical, provenance-preserving compaction of cold run spans.
- `ContextGovernor(budget=…, decay=…, compactor=…, keep_recent_spans=…, decay_threshold=…, compact_batch=…)` — Per-run controller that holds a context budget across a long horizon.
- `ContinualAdaptation(app, policy=…, dataset=…, registry=…, embedder=…, base_model=…, trainer=…)` — Drive continual on-device adaptation as a streaming, gated loop.
- `ContinuousImprovementController(app, metrics=…, golden=…, registry=…, prompt_name=…, monitor=…, sustain=…, cooldown_s=…, eval_budget=…, quality_floor=…, reoptimize=…, gates=…, clock=…)` — Drive gated re-optimization / re-eval / rollback from live signals.
- `Contract(**data)` — A signed, audited, offline-verifiable agreement over typed terms.
- `ContractFulfillment(**data)` — Whether delivered work met the contract's terms, the enforcement verdict.
- `ContractTerms(**data)` — The typed, negotiated terms of an agreement.
- `ContractVerification(**data)` — The (non-raising) outcome of verifying a contract offline.
- `Contribution(**data)` — One member's privacy-preserving federated update, numeric, no raw traffic.
- `ContributionBuilder(embedder=…, privacy=…)` — Build a :class:`Contribution` from a member's local data, never its text.
- `ControllerDecision(**data)` — The record of one controller evaluation, stamped on the audit chain.
- `CorrelationClaim(**data)` — A stated correlation between two cited series, optionally asserting causation.
- `CorrelationVerifier(claims=…)` — Recomputes a correlation and refutes correlation-stated-as-causation.
- `CostAwareSelector(models, registry=…, quality_floor=…, events=…)` — Picks the cheapest capable model per action, escalating on low confidence.
- `CostBudget(**data)` — A spend limit on a scope, with an enforcement action on breach.
- `CostLedger(price_table=…, store=…, max_events=…)` — In-process append-only ledger of attributed cost events.
- `Counterexample(**data)` — A concrete, minimal state that violates an invariant.
- `CredentialVerification(**data)` — The (non-raising) outcome of verifying an agent credential offline.
- `CreditorRecovery(**data)` — One creditor's outcome in an :class:`InsolvencyResolution` waterfall.
- `Crew(name=…, process=…, blackboard=…, tracer=…, manager_provider=…, manager_model=…, max_rounds=…, concurrency=…, cost_tracker=…, cost_ledger=…)` — A multi-agent team that collaborates over a shared blackboard.
- `CrossOrgEngagement(app, buyer=…, seller=…, scope=…, coordinator=…)` — A purely-compositional facade threading the whole cross-org fabric in one call-path.
- `CultivationResult(**data)` — The content-bound, offline-verifiable outcome of a cultivation run.
- `Cultivator(app=…, curriculum, library=…, held_out=…, rails=…, governance=…, search=…, min_capability_gain=…, tolerance=…, prune=…, record=…)` — Drive the cultivation loop over a :class:`LearnedSkillLibrary`.
- `CurriculumProposal(**data)` — A content-bound, offline-verifiable curriculum round.
- `CurriculumTask(**data)` — A candidate objective: a deterministic environment plus its success oracle.
- `CustodyAttestation(**data)` — A signed, offline-verifiable proof-of-reserves over a poster's held capital.
- `CustodyAttestationVerification(**data)` — The (non-raising) outcome of verifying a custody attestation offline.
- `CycleReport(**data)` — What one cultivation cycle proposed, learned, promoted, and demoted.
- `DataCatalog(datasets=…)` — A named set of registered :class:`~vincio.data.Dataset`\s a query grounds against and executes over.
- `DataEncoder(delimiter=…, include_name=…, include_count=…, include_types=…, include_units=…, exemplars=…, max_rows=…)` — Render tabular data header-once in a compact, token-oriented form.
- `DataEngagement(app, dataset=…, question=…, analyst=…)` — A purely-compositional facade threading the whole data plane in one call-path.
- `DataEngagementSignature(**data)` — One party's signature over a data-engagement narrative's content hash.
- `DataEngagementVerification(**data)` — The (non-raising) outcome of verifying a data engagement offline.
- `DataNarrative(**data)` — A signed, content-bound, hash-chained narrative of a whole data engagement.
- `DataQualityRails(constraints=…, detect_anomalies=…, anomaly_threshold=…, anomaly_action=…, max_examples=…, pii_detector=…, secret_scanner=…, injection_detector=…)` — Screen tabular data deterministically against a set of column constraints, with optional numeric anomaly detection.
- `DataQualityReport(**data)` — The outcome of screening a dataset. ``allowed`` is false when any blocking rule fired; the violations carry the detail.
- `DataStage(**data)` — One step of a data engagement, bound into the narrative's hash chain.
- `Dataset(**data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `DatasetProfile(**data)` — A dataset's deterministic, fixed-size column profile.
- `Delegation(**data)` — A signed grant of bounded authority from one identity to another.
- `DelegationChain(**data)` — An ordered chain of delegations from a principal down to an acting agent.
- `DelegationChainVerification(**data)` — The (non-raising) outcome of verifying a delegation chain offline.
- `DelegationVerification(**data)` — The (non-raising) outcome of verifying one delegation offline.
- `DeployResult(**data)` — Outcome of a canary-gated prompt/policy deployment.
- `Discharge(**data)` — A signed, content-bound release of part of what a poster owes one creditor.
- `DischargeVerification(**data)` — The (non-raising) outcome of verifying a liability discharge offline.
- `DistributedCheckpointer(store=…, coordinator=…, owner=…, lease_ttl_s=…)` — A :class:`Checkpointer` that lease-guards and CAS-commits each super-step.
- `DocumentArtifact(**data)` — A rendered document: its bytes, format, and media type.
- `DocumentBuilder(audit_log=…, tenant_id=…)` — Render validated results into cited, contract-checked, audited documents.
- `DocumentContract(**data)` — The structural contract a generated document must satisfy.
- `DualPlaneExecutor(tool_runtime, broker=…, monitor=…, principal=…, approval=…, provider=…, model=…)` — Capability-secure executor separating the control and data planes.
- `EdgeEnvironment(**data)` — A report of the runtime the edge core is executing on.
- `EdgeManifest(**data)` — The static WASM-buildability certificate for the edge core.
- `EdgeParityReport(**data)` — The result of verifying the edge build is the same library, not a fork.
- `EdgeProfile(**data)` — A bounded resident-memory and latency profile for a constrained target.
- `EdgeRequest(**data)` — A self-contained context-engineering request for the edge runtime.
- `EdgeResult(**data)` — The outcome of one edge compile.
- `EdgeRuntime(profile=…, rails=…)` — A bounded, in-process context-engineering runtime for the edge.
- `EnergyBudget(**data)` — An energy/carbon limit on a scope, refused on breach.
- `EnergyEstimate(**data)` — A run (or call)'s estimated energy and carbon, with its breakdown.
- `EnergyIntensityTable(**data)` — Resolves a model + region into an energy/carbon estimate.
- `EnergyProfile(**data)` — Per-model energy intensity, in watt-hours per million tokens.
- `EnergyReport(**data)` — Estimated energy + carbon rolled up by dimension.
- `EngagementNarrative(**data)` — A signed, content-bound, hash-chained narrative of a whole cross-org engagement.
- `EngagementSignature(**data)` — One party's signature over an engagement narrative's content hash.
- `EngagementStage(**data)` — One step of a cross-org engagement, bound into the narrative's hash chain.
- `EngagementVerification(**data)` — The (non-raising) outcome of verifying an engagement narrative offline.
- `Environment(*args, **kwargs)` — The stateful-environment contract: ``reset`` / ``step`` / ``observe`` / ``verify``.
- `EnvironmentSimulator(max_steps=…)` — Drive an agent *policy* through an :class:`Environment` to a verified end state.
- `EquivocationProof(**data)` — A signed, offline-verifiable proof that a poster signed two conflicting liability roots.
- `EquivocationProofVerification(**data)` — The (non-raising) outcome of verifying a liability equivocation proof offline.
- `ErasureProof(**data)` — A signed, content-bound manifest of exactly what an erasure removed.
- `ErasureResult(**data)` — Outcome of a right-to-erasure-by-source sweep.
- `Escrow(**data)` — Posted collateral bound to a contract, held, released, or forfeited.
- `EscrowConfig(**data)` — How a breach's measured shortfall maps to a bounded forfeiture.
- `EscrowVerification(**data)` — The (non-raising) outcome of verifying an escrow offline.
- `EventCitation(**data)` — A reference to one source *event* cell a windowed answer rests on.
- `EventPattern(**data)` — A predicate that matches a :class:`BehaviorEvent`.
- `Evidence(**data)` — A platform verdict bound by hash to discharge one sub-claim.
- `EvidenceItem(**data)` — A provenance-aware unit of evidence (text, image, or table).
- `Example(**data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `ExperimentProposer(app, targets=…, eval_budget=…, golden_suite=…, gates=…)` — Rank where the system is weakest and schedule the highest-ROI experiment.
- `FRIAGenerator(classifier=…)` — Generate an Article 27 **fundamental-rights impact assessment** (FRIA).
- `FastEmbedEmbedder(model_name=…, dim=…, encode_fn=…, model=…, fallback=…)` — Local ONNX dense embedder via ``fastembed``.
- `FederatedContribution(**data)` — One organization's aggregated, source-bound contribution to a finding.
- `FederatedDataEngagement(app, query=…, coordinator=…, layer=…)` — A governed, compositional facade for analytics across organizations.
- `FederatedFinding(**data)` — A reconciled cross-org answer for one metric and one dimension group.
- `FederatedImprovement(app, policy=…, dataset=…, registry=…, embedder=…, base_model=…, reputation=…)` — Drive one gated, privacy-preserving federated round for the adopting member.
- `FederatedMember(org, app, table=…, layer=…, region=…, subject=…)` — One organization participating in a federated analytics engagement.
- `FederatedNarrative(**data)` — A signed, content-bound, hash-chained narrative of a federated engagement.
- `FederatedPolicy(**data)` — The opt-in contract for one gated federated-improvement round.
- `FederatedQuery(**data)` — The shape of one governed metric run across organizations.
- `FederatedRoundResult(**data)` — The outcome of one gated federated-improvement round.
- `FederatedSignature(**data)` — One party's signature over a federated narrative's content hash.
- `FederatedStage(**data)` — One step of a federated engagement, bound into the narrative's hash chain.
- `FederatedSubspace(**data)` — The fleet-consensus low-rank subspace distilled from a secure aggregation.
- `FederatedVerification(**data)` — The (non-raising) outcome of verifying a federated engagement offline.
- `FertilityTracker(model=…, baseline_language=…)` — Track tokens-per-word per language to surface the non-English token tax.
- `Figure(**data)` — A chart or table embedded in a cited report, **data-bound** to its source.
- `Flow(provider=…, model=…, name=…, output_schema=…, app=…, config=…)` — An immutable, fluent pipeline that lowers to one governed run packet.
- `ForecastClaim(**data)` — A stated projection from a declared deterministic forecast model.
- `ForecastVerifier(claims=…)` — Re-runs a declared deterministic forecast over the cited series and checks it.
- `FrontierEstimate(**data)` — Where a task sits relative to current competence.
- `GGUFProvider(model_path=…, llama=…, n_ctx=…, embedding=…, lora_path=…, lora_scale=…, **kwargs)` — Native in-process GGUF / llama.cpp provider with on-device embedding.
- `GatheredReputation(subject, visits, attestations, revocations, reputation, duplicates=…)` — A current prior assembled by pulling signed artifacts from a set of peers.
- `GoldenRegressionSuite(path=…, name=…)` — A held-out, *growing* golden regression set with per-case provenance.
- `GovernanceVerifier(invariants=…, audit_log=…, claim_generator=…)` — Proves governance invariants by exhaustive bounded model checking.
- `Grant(**data)` — A bounded grant of authority: the capabilities, budget, expiry, and audience.
- `GuardedBanditRouter(entries, bandit=…, safe_model=…, reward_fn=…, context_fn=…, epsilon=…, alpha=…, context_dim=…, seed=…, regret_budget=…, rollback_margin=…, store=…, app_name=…, events=…)` — A live routing bandit with a safety floor, regret tracking, and auto-rollback.
- `HTNDomain(**data)` — A library of operators and methods the planner decomposes against.
- `HealthAwareFailover(entries, guard_capabilities=…, registry=…)` — Failover chain that tries healthy providers first.
- `HistoryConsistencyProof(**data)` — A signed, offline-verifiable proof a poster's liability history is monotone over time.
- `HistoryConsistencyProofVerification(**data)` — The (non-raising) outcome of verifying a liability history-consistency proof offline.
- `HistoryConsistencyReport(**data)` — The outcome of walking a set of liability snapshots for cross-time monotonicity.
- `IdentityDocument(**data)` — A signed, content-bound description of an agent identity.
- `IdentityVerification(**data)` — The (non-raising) outcome of verifying an identity document offline.
- `ImageGenRequest(**data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `ImageProvider()` — Abstract image generation/editing provider.
- `ImprovementLoop(app, registry=…, tracker=…, metrics=…, weights=…, gates=…, max_cost_per_case=…, experiment=…, prompt_name=…, concurrency=…, optimizer=…, strategy=…, reflector=…, golden_suite=…)` — Runs the trace → dataset → eval → optimize → promote cycle on an app.
- `Incident(**data)` — A signed observation that a sub-claim no longer holds in production.
- `InclusionProof(**data)` — An offline-verifiable proof that one creditor's claim is in a liability attestation.
- `InclusionProofVerification(**data)` — The (non-raising) outcome of verifying a liability inclusion proof offline.
- `IndexedTraceStore(path=…, percentile_window=…)` — SQLite-backed, indexed trace + cost store with pre-aggregated rollups.
- `InsolvencyBreach(**data)` — A proven shortfall: the obligations owed exceed the reserves actually held.
- `InsolvencyResolution(**data)` — A signed, offline-verifiable resolution distributing reserves across ranked liabilities.
- `InsolvencyResolutionVerification(**data)` — The (non-raising) outcome of verifying an insolvency resolution offline.
- `Instruction(text=…, **data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `IntervalClaim(**data)` — A stated interval over a cited series.
- `IntervalVerifier(claims=…)` — Recomputes a stated confidence or prediction interval from the cited series.
- `Invariant(id, statement, category, variables, predicate, explain=…)` — A formal governance property checked over a bounded, typed state space.
- `InvariantResult(**data)` — The verdict of checking one :class:`Invariant` over its whole state space.
- `IssuePreference(**data)` — A party's preference over one numeric issue.
- `IssuerTrust(**data)` — The importer's resolved trust in one issuer, pinpointed, never silent.
- `JudgeCalibrator(judge, reflector=…, kappa_bins=…, trust_threshold=…, min_kappa_gain=…)` — Tune a :class:`~vincio.evals.judges.GEvalJudge`'s evaluation steps to maximize agreement with human labels, then leave the judge calibrated.
- `JudgeEnsemble(judges, aggregate=…, disagreement_threshold=…, name=…)` — A panel of judges scored together, with disagreement surfaced as uncertainty and the panel as a whole calibrated against human labels.
- `JudgeVerifier(judge, case=…, name=…)` — Score candidates with any :class:`~vincio.evals.judges.Judge` or :class:`~vincio.evals.ensemble.JudgeEnsemble`.
- `KVPrefixPool(kv_bytes_per_token=…, max_entries=…, max_resident_bytes=…)` — Bounded tracker of cross-request shared stable-prefix KV reuse.
- `KeyAuthorization(**data)` — An offline proof that a signing key descends from an identity's genesis key.
- `KeyPool(providers, rpm=…, tpm=…, breaker=…, labels=…, max_attempts=…, base_backoff_s=…, max_backoff_s=…, seed=…, events=…, clock=…)` — Round-robin pool over multiple keys/regions of one logical provider.
- `KeyRecord(**data)` — One public key in an identity's rotation history.
- `Keyring(document, seeds)` — Holds an identity's private keys and maintains its signed rotation chain.
- `LLMLinguaCompressor(scorer=…, min_keep_ratio=…, coarse_overshoot=…)` — Token-importance compressor (callable, drop-in for ``extractive_compress``).
- `LawfulBasis(*args, **kwds)` — GDPR Article 6(1) lawful bases for processing.
- `Leaderboard(**data)` — A ranked comparison of models over a shared benchmark set.
- `LearnedSemanticCache(embedder, policy=…, calibration=…, clock=…)` — Bounded, calibrated, auditable near-miss response cache.
- `LearnedSkill(**data)` — A verified, content-addressed, versioned, composable learned procedure.
- `LearnedSkillLibrary(skills=…)` — A content-addressed library of learned skills with versioning and dedup.
- `LearningResult(**data)` — The outcome of a :class:`TrajectoryOptimizer` run.
- `LiabilityAttestation(**data)` — A signed, offline-verifiable proof-of-liabilities over a poster's total obligations.
- `LiabilityAttestationVerification(**data)` — The (non-raising) outcome of verifying a liability attestation offline.
- `LiabilityLine(**data)` — One obligation owed, backing the poster's attested total liabilities.
- `LifecycleWatcher(registry=…, warn_within_days=…, events=…)` — Watch pinned models for sunset and propose migrations off them.
- `LineageRecord(**data)` — The full provenance chain for one source.
- `LocalAdaptationPolicy(**data)` — The opt-in contract for continual on-device adaptation.
- `LocalAdapter(**data)` — A versioned, content-addressed, portable LoRA-class adapter.
- `LocalLoRATrainer(embedder=…, rank=…, gate=…, scale=…, backend=…)` — Fit a :class:`LocalAdapter` on-device from a grounded training set.
- `LoopResult(**data)` — Outcome of one improvement-loop cycle, with full provenance.
- `MPCResult(**data)` — The outcome of driving a :class:`ModelPredictivePlanner` to a verified end.
- `MPCStep(**data)` — The record of one real, committed step of a model-predictive plan.
- `MatryoshkaEmbedder(inner, dimensions)` — Matryoshka (MRL) dimension truncation over any embedder.
- `MemberReputation(**data)` — One member's reputation snapshot, its track record as an auditable number.
- `MemoryEngine(store=…, write_policy=…, decay_lambda=…, min_confidence=…, graph_enabled=…, embedder=…, vector_weight=…, retention_weight=…, ttl_days=…, audit=…, consent_ledger=…, privacy_accountant=…, privacy_mechanism=…)` — Layered, guarded, decaying long-term memory with hybrid recall.
- `MemoryItem(**data)` — A scoped, scored, decaying memory.
- `MemoryScope(*args, **kwds)` — Enum where members are also (and must be) strings
- `MemoryType(*args, **kwds)` — Enum where members are also (and must be) strings
- `MerkleStep(**data)` — One step of an :class:`InclusionProof`'s authentication path.
- `Meter(contract_id, run_id=…)` — Accumulates the usage of work delivered under one contract.
- `MeterReading(**data)` — The deterministic roll-up of a meter's accrued usage for one contract.
- `MockImageProvider(size=…, default_model=…)` — Deterministic offline image provider.
- `MockScreen(app)` — Deterministic in-process screen over a :class:`ScreenApp`, no browser, no network. Tracks the current screen, typed field values, and durable flags, and re-derives a stable :class:`ScreenState` from them, so a run is reproducible and CI-golden. Supports exact snapshot restore as an undo fallback.
- `MockSpeechProvider(sample_rate=…)` — Deterministic offline TTS: a real WAV whose length scales with the text.
- `MockVideoProvider(default_model=…)` — Deterministic offline video provider.
- `ModelCard(**data)` — Machine-readable documentation for a single model.
- `ModelCascade(**data)` — An ordered cheap→strong model ladder for confidence-based escalation.
- `ModelPredictivePlanner(model, actions=…, goal_value=…, horizon=…, beam_width=…, max_real_steps=…, goal_bar=…, length_penalty=…, reward_weight=…, action_cost=…, cost_weight=…, require_calibrated=…)` — Plan by searching imagined rollouts under a :class:`WorldModel` (MPC).
- `ModelRegistry(profiles=…, version=…)` — A catalog of :class:`ModelProfile` keyed by exact model id.
- `MonitorVerdict(**data)` — The outcome of checking one event (or a whole trajectory).
- `MonotonicityBreach(**data)` — A creditor's obligation that shrank between two snapshots without a backing discharge.
- `Negotiation(buyer, seller, budget=…, signer=…, audit=…, events=…, clock=…)` — Drives a bounded alternating-offers bargain between a buyer and a seller.
- `NegotiationBudget(**data)` — The guaranteed-termination budget for a negotiation.
- `NegotiationPosition(**data)` — A party's private stance: per-issue preferences and a concession curve.
- `NegotiationResult(**data)` — The outcome of a bounded negotiation, a deal, or a partial no-deal.
- `NettingSet(**data)` — A content-bound, offline-verifiable multilateral clearing of a fleet's books.
- `NotebookSession(engagement, auto_display=…)` — An interactive, governed data-analysis session for notebooks and REPLs.
- `Objective(text=…, **data)` — What the application is trying to accomplish.
- `Offer(**data)` — One move in a negotiation: a proposal, an acceptance, or a walk-away.
- `OmissionBreach(**data)` — A creditor's proven claim the attested liabilities omit or under-state.
- `OpenAIFineTuneBackend(provider)` — Drives the OpenAI fine-tuning API over an :class:`OpenAIProvider`.
- `OutputContract(**data)` — The full output contract.
- `OutputSchema(name, json_schema, model=…)` — A named, provider-agnostic structured-output contract.
- `Pack(**data)` — A domain bundle: prompt config + schema + policies + evaluators + evals.
- `PlanRepairer(max_repairs=…, budget_shock_fraction=…)` — Repairs a running :class:`StepDAG` in place. Deterministic and offline.
- `PlannedStep(**data)` — One bounded, dependency-ordered step of the internal plan.
- `PluginInfo(**data)` — A discovered plugin entry point and its registration status.
- `PoisoningDetector(threshold=…, min_authority=…, min_provenance=…, classifier=…, injection_detector=…)` — Flag likely-poisoned retrieved evidence from authority/provenance signals.
- `PolicySet(**data)` — Deterministic per-run policies (policies).
- `PooledContract(**data)` — One contract a :class:`CollateralPool` backs, with its share and disposition.
- `PortableReputation(standings, verdicts, config, base=…, as_of=…, trust=…)` — An imported, evidence-weighted prior combined from several issuers' attestations.
- `Predict(sig, provider, model, temperature=…, prompt_spec=…, max_output_tokens=…)` — Execute a signature against a provider with full output validation.
- `PredictedStep(**data)` — The world model's prediction for one ``(observation, action)``.
- `PrivacyAccountant(default_budget=…, default_mechanism=…, orders=…, delta=…, audit=…, store=…)` — A composing, per-subject differential-privacy budget over the learning loop.
- `PrivacyBudget(**data)` — A per-subject (or default) ``(ε, δ)`` privacy ceiling.
- `PrivacyBudgetError(message, details=…, hint=…, docs_url=…)` — A learning step was refused because it would exceed a subject's DP budget.
- `PrivacyConfig(**data)` — How a contribution is made privacy-preserving before it leaves a member.
- `PrivacyDecision(**data)` — An explainable verdict on whether a proposed release fits the budget.
- `PrivacyMechanism(**data)` — One differentially-private release, as accounted against a budget.
- `PrivacyReport(**data)` — Per-subject DP budget roll-up, the privacy analogue of the cost report.
- `PrivacySpend(**data)` — One accounted privacy release for a subject, a row on the audit chain.
- `ProgramOp(**data)` — One whitelisted transform step over a list of record dicts.
- `ProgramProperty(**data)` — A declarative property a synthesized program must satisfy.
- `ProgramSpec(**data)` — The declaration of a verified transform: its ops and the properties it must hold.
- `PrometheusExporter(namespace=…)` — Scrape-friendly Prometheus metrics for the served plane.
- `PromptSpec(**data)` — Declarative prompt definition compiled to an AST.
- `ProvenanceManifest(**data)` — A C2PA-style content-provenance manifest for AI-generated output.
- `ProvenanceTier(*args, **kwds)` — How real a benchmark number is — ordered ``STATIC < RECORDED < LIVE``.
- `Purpose(*args, **kwds)` — Why personal data is processed (GDPR Art. 5(1)(b) purpose limitation).
- `QueryPlan(**data)` — A schema-grounded, read-only-verified query that has **not yet run**.
- `QueryResult(**data)` — A query's result, schema-bearing and **cell-level cited**.
- `Rail(**data)` — One programmable rail.
- `RealtimeSession(backend=…, config=…, tool_dispatcher=…)` — A bidirectional realtime session.
- `ReasoningAssessment(**data)` — Deterministic decision about how much reasoning a request warrants.
- `ReasoningController(policy=…, trace_cache=…)` — Pick a thinking effort + token budget per step from task + budget signals.
- `ReasoningDecision(**data)` — The record of one reasoning-effort pick, stamped on the trace.
- `ReasoningPass(**data)` — Observable receipt for one model pass, excluding private reasoning text.
- `ReasoningPlan(**data)` — Compact high-level plan; contains no model chain-of-thought.
- `ReasoningPolicy(**data)` — The effort policy: difficulty bands, guardrails, and reuse behavior.
- `ReasoningTrace(**data)` — One cached reasoning trace: how much thinking a warm prefix already cost.
- `ReasoningTraceCache(max_entries=…, max_resident_bytes=…)` — Bounded LRU of reasoning traces under a resident-memory budget.
- `ReasoningVerifier(*args, **kwargs)` — A pluggable, deterministic checker that turns an answer into checks.
- `Reconciliation(**data)` — Whether two parties' settlement records tie out, the dispute verdict.
- `ReflectiveOptimizer(evaluate_variant, weights=…, gates=…, max_cost_per_case=…, objectives=…, reflector=…, constraints=…, prefer=…)` — GEPA-style reflective prompt optimizer.
- `RelevanceDecay(**data)` — Exponential intra-run relevance decay (the memory recency model, per run).
- `RemoteParticipant(client, org_id)` — A choreography :class:`Participant` whose steps run in a remote A2A org.
- `ReputationAttestation(**data)` — A signed, offline-verifiable attestation of a counterparty's earned standing.
- `ReputationBundle(**data)` — The signed artifacts a peer holds about one subject, its reply to a query.
- `ReputationConfig(**data)` — How a member's gate track record maps to an aggregation weight.
- `ReputationError(message, details=…, hint=…, docs_url=…)` — A reputation operation could not proceed.
- `ReputationLedger(config=…, audit=…, events=…, store=…)` — A per-member, gate-earned reputation that weights federated aggregation.
- `ReputationReport(**data)` — Per-member reputation roll-up, alongside the cost and privacy reports.
- `ResearchAgent(app, budget=…, strategies=…, judge=…, min_support=…, require_citations=…)` — Search → read → reflect → verify → synthesize, cited and budget-bounded.
- `ResearchBudget(**data)` — Explicit breadth/depth/source/token bounds for one research run.
- `ResearchReport(**data)` — The cited, budgeted, eval-scored output of a research run.
- `ReserveLine(**data)` — One custodied holding backing the poster's proven reserves.
- `ResidencyPolicy(**data)` — Pin allowed provider regions and refuse egress to others.
- `Resolution(**data)` — A content-bound, offline-verifiable adjudication of a disputed contract.
- `RetrievalEvaluator(k_values=…)` — Score a retriever against a :class:`RetrievalGoldenSet` on the IR metrics.
- `RetrievalGoldenSet(**data)` — A fixed query set scored against a fixed corpus.
- `ReuseBreach(**data)` — A contract pledged across more than one pool, the same collateral, twice.
- `RewardModel(rewards, success_threshold=…, name=…)` — Compose verifiable rewards into one dense, confidence-weighted signal.
- `RewardVerifier(reward, name=…)` — Score candidates with any :class:`~vincio.optimize.rewards.VerifiableReward` or :class:`~vincio.optimize.rewards.RewardModel`.
- `RiskTierClassifier(purpose=…, domains=…, prohibited_practices=…, human_oversight=…, interacts_with_humans=…, generates_content=…)` — Place an app into the EU AI Act risk tiers from its declared profile.
- `RootCommitment(**data)` — A compact, signed digest of one liability attestation's root, for cross-creditor compare.
- `RootCommitmentVerification(**data)` — The (non-raising) outcome of verifying a liability root commitment offline.
- `RootConsistencyReport(**data)` — The outcome of comparing a set of liability roots for cross-creditor non-equivocation.
- `Router(entries, strategy=…, registry=…, price_table=…, budget_usd=…, guard_capabilities=…, events=…)` — A registry-backed router: pick the cheapest / fastest / least-busy *capable* model per request, inside your own process and audit boundary.
- `RowStream(source, schema, name=…, source_id=…)` — A lazy, re-iterable, schema-bearing handle over an out-of-core row source.
- `RunConfig(**data)` — Per-run overrides (A2).
- `RunHandle(task)` — Handle to an in-flight run started by :meth:`ContextApp.submit`.
- `RunResult(**data)` — Result of a ContextApp run.
- `RunStore(dsn=…)` — Persist and query :class:`SuiteRun`s over SQLite (default) or Postgres.
- `RunStreamEvent(**data)` — Event emitted by the streaming run flow (``ContextApp.astream``).
- `RuntimeMonitor(specs)` — Checks a :class:`BehaviorSpec` set against a trajectory, step-by-step.
- `Saga(**data)` — A cross-org compensating workflow: an ordered list of steps.
- `SagaJournal(**data)` — The durable, resumable, offline-verifiable record of one saga run.
- `SagaResult(**data)` — The outcome of a cross-org saga run, completion, a clean unwind, or a pause.
- `SagaStep(**data)` — One step of a :class:`Saga`: a forward action and its compensation.
- `ScheduleResult(**data)` — The aggregate result of one scheduling pass.
- `SchemaRouter(default=…)` — Routes a run (or a piece of structured data) to one of several schemas.
- `SchemaVerifier(schema=…)` — Checks an answer structurally conforms to a JSON schema.
- `ScopedMemory(engine, scope, owner_id)` — Mem0-style handle bound to one owner: ``engine.for_user("u1")``.
- `ScreenApp(**data)` — A deterministic, in-process app a :class:`MockScreen` drives, the offline, WebArena / OSWorld-shaped harness: named screens, form fields, click-driven transitions, and effects that set durable flags.
- `ScreenState(**data)` — A perceived snapshot of the UI, the *observe* half of the loop.
- `SearchBudget(**data)` — Bounds one search: candidate cap, optional cost cap, optional deadline.
- `SearchResult(**data)` — The outcome of a search: the winner, every candidate, and why it stopped.
- `SecureAggregator(privacy=…, rank=…, allowed_regions=…, reputation=…)` — Merge masked contributions into a :class:`FederatedSubspace`, never seeing one.
- `SelfImprovementController(app, policy=…, dataset=…, golden=…, registry=…, prompt_name=…)` — Drive a :class:`SelfImprovementPolicy` as one streaming controller.
- `SelfImprovementPolicy(**data)` — One declarative, governed contract for continual self-improvement.
- `SemanticCacheGate(quality_floor=…, scorer=…)` — Gate a learned semantic cache on replayed cases before it ships.
- `SemanticCachePolicy(**data)` — Opt-in policy for the learned semantic cache.
- `SemanticGateCase(**data)` — One probe for the cache gate: a query and its live (reference) answer.
- `SemanticLayer(**data)` — Measures, dimensions, and derived columns defined once over one table.
- `Send(node, state=…, **data)` — Dynamic fan-out instruction for map-reduce super-steps.
- `SenioritySchedule(**data)` — A signed, offline-verifiable ranking of a poster's obligations into priority tranches.
- `SeniorityTranche(**data)` — One priority rank of a :class:`SenioritySchedule`, the creditors paid at that level.
- `SeniorityVerification(**data)` — The (non-raising) outcome of verifying a seniority schedule offline.
- `SetOffStatement(**data)` — A signed, offline-verifiable statement of the obligations running both ways.
- `SetOffVerification(**data)` — The (non-raising) outcome of verifying a set-off statement offline.
- `SettlementBook(owner, signer=…, audit=…, events=…, store=…, reputation=…, book_id=…)` — An org's durable, hash-chained, offline-verifiable ledger of settlements.
- `SettlementRecord(**data)` — A signed, offline-verifiable reconciliation of delivery against a contract.
- `SettlementReport(**data)` — Per-counterparty settlement roll-up, alongside the cost report.
- `ShadowProvider(primary, candidate, candidate_model=…, block=…, price_table=…, recorder=…, events=…, max_observations=…)` — Return the primary's answer; dual-dispatch the candidate for offline diff.
- `ShardedIndex(shards, router=…, max_concurrency=…)` — Routes writes across shards and merges parallel reads (Index protocol).
- `Shield(specs, mode=…, repair=…)` — Prevents a behavioural violation before the action executes.
- `ShieldDecision(**data)` — A shield's ruling on a proposed event.
- `Signature(**data)` — Base class for typed input → output signatures.
- `SignatureCheck(**data)` — Which key verified a signature and whether it was valid at a given time.
- `SkillProvenance(**data)` — Where a learned skill came from, the audit trail of its acquisition.
- `SkillSearch(beam_width=…, max_depth=…)` — Bounded, deterministic beam search that composes the skill library.
- `SkillStep(**data)` — One step of a learned procedure: a primitive action **or** a sub-skill call.
- `Solution(**data)` — The outcome of searching for (or retrieving) a procedure for a task.
- `SolvencyProof(**data)` — A signed, offline-verifiable proof-of-solvency over a poster's reserves and liabilities.
- `SolvencyProofVerification(**data)` — The (non-raising) outcome of verifying a solvency proof offline.
- `SpeechProvider()` — Helper class that provides a standard way to create an ABC using inheritance.
- `SpeechRequest(**data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `StabilityLevel(*args, **kwds)` — Stability contract for a public symbol.
- `StateGraph(name=…, state_schema=…, reducers=…, defaults=…)` — Build-time graph definition; ``compile()`` produces the runnable form.
- `StatisticalClaim(**data)` — Base of the analytical-claim family the statistical kernels certify.
- `StepBinding(**data)` — The resolved run-time binding for one capability step.
- `StepOutcome(**data)` — A participant's result for one dispatched step.
- `StepRecord(**data)` — One immutable, hash-chained entry in a :class:`SagaJournal`.
- `StepRequest(**data)` — The typed envelope dispatched to a participant for one step, the handoff.
- `StreamWindow(**data)` — A windowing policy over an unbounded event stream, carrying the streaming analogues of the data plane's batch primitives.
- `SubgraphScheduler(workers=…, store=…, coordinator=…, lease_ttl_s=…, budget=…, deadline_s=…, clock=…)` — Runs independent sub-graphs concurrently under a fair-share budget + SLA.
- `SubgraphTask(graph, input=…, id=…, thread_id=…, weight=…)` — One independent sub-graph to schedule.
- `SuiteReport(run, title=…, cite_failures=…)` — Render one :class:`SuiteRun` to Markdown / HTML / JSON / CSV / PDF.
- `SuiteRun(**data)` — A whole suite run: one model over a set of benchmarks at one tier.
- `SwapGate(app, metrics=…, quality_metric=…, gates=…, alpha=…, drift_threshold=…, behavior_threshold=…, repeats=…, flake_quarantine=…)` — Gate a model/provider change on replayed golden traces + an eval/cost/ latency/behavioral diff with statistical backing.
- `SwapVerdict(**data)` — PASS / FAIL verdict for promoting a model into the live path.
- `SynthesizedProgram(**data)` — A verified transform paired with the certificate proving its properties.
- `SystemCard(**data)` — Documentation for the whole system: model + retrieval + memory + safety.
- `TableEvidence(**data)` — A :class:`~vincio.data.Dataset` presented as first-class context evidence.
- `TaintedValue(value, label=…, sources=…)` — A value carried together with its :class:`TrustLabel` and provenance.
- `TaskType(*args, **kwds)` — Task taxonomy used by the input router.
- `TemporalVerifier()` — Checks date ordering and duration claims against a real calendar.
- `TestTimeSearch(generate, verifier=…, budget=…)` — Verifier-guided test-time search bounded by a :class:`SearchBudget`.
- `ThresholdCalibrator(target_precision=…, min_floor=…)` — Fit a calibrated acceptance threshold from labelled near-miss examples.
- `TimerService(graph, clock=…)` — Resumes due timers and delivers events for one compiled graph.
- `ToolClause(**data)` — One named pre- or post-condition over a tool call.
- `ToolContract(**data)` — Pre- and post-conditions checked against a tool's actual call and result.
- `ToolEnvironment(name, initial_state, tools, task, instructions=…)` — A deterministic, in-process environment whose world is a dict mutated by tools.
- `TrainingSet(**data)` — A curated, grounded fine-tuning corpus.
- `TrajectoryAdvantage(value_fn, include=…, max_players=…)` — Attribute a trajectory's outcome reward to the steps that earned it.
- `TrajectoryOptimizer(reward_model, policy=…, learning_rate=…, kl_max=…, iterations=…, group_normalize=…, min_reward_improvement=…)` — GRPO-style on-policy update over a deterministic policy, safety-gated.
- `Transition(**data)` — One recorded ``(observation, action) → next_observation`` step.
- `TrendClaim(**data)` — A stated linear trend over a cited series.
- `TrendVerifier(claims=…)` — Recomputes a stated linear trend and its goodness-of-fit from cited cells.
- `TrustConfig(**data)` — How the importer's trust in an issuer scales the evidence it contributes.
- `TrustLabel(*args, **kwds)` — A typed information-flow label on a value or context candidate.
- `TrustModel(assessments, config)` — The importer's bounded, transitive trust in each issuer, the Sybil-resistant kernel.
- `TwoStageIndex(embedder=…, coarse_dims=…, quantization=…, rerank_factor=…)` — Matryoshka + quantized coarse search, full-precision exact rerank.
- `UIAction(**data)` — A typed action bound to a target by a stable selector, not a coordinate.
- `UIElement(**data)` — A typed, addressable element grounded from the screen + accessibility tree.
- `UnderReservedBreach(**data)` — A proven-reserves shortfall: the pools pledge more than the custodian attests.
- `UnitVerifier()` — Checks unit conversions and refuses a dimensional mismatch.
- `UniversalReasoningEngine(app, policy=…)` — Adaptive reasoning for every provider, including non-reasoning models.
- `UniversalReasoningPolicy(**data)` — Adaptive-depth, web, pass-count and token/cost guardrails.
- `UniversalReasoningResult(**data)` — Final normal run plus the provider-neutral reasoning receipt.
- `UsageEvent(**data)` — One unit of delivered usage accrued against a contract.
- `UserInput(**data)` — Structured task input.
- `VerifiableReward()` — Base contract: map a :class:`RewardSample` to a :class:`RewardSignal`.
- `VerificationContext(**data)` — The grounding a verifier may consult while certifying an answer.
- `VerificationReport(**data)` — The verdict of a governance-verification pass over all invariants.
- `VerifiedAnswer(**data)` — An answer paired with the certificate a deterministic verifier produced.
- `Verifier(*args, **kwargs)` — Scores a candidate answer or trajectory. Reuse an existing critic via the adapters in this module rather than implementing this directly.
- `VerifierScore(**data)` — A verifier's verdict on one candidate: a value, a confidence, a reason.
- `VideoGenRequest(**data)` — !!! abstract "Usage Documentation" [Models](../concepts/models.md)
- `VideoProvider()` — Abstract video generation/editing provider.
- `VincioConfig(**data)` — Top-level project configuration.
- `VincioDeprecationWarning(*args, **kwargs)` — Emitted when a deprecated Vincio API is used.
- `VincioError(message, details=…, hint=…, docs_url=…)` — Base class for all Vincio errors.
- `VincioExperimentalWarning(*args, **kwargs)` — Emitted on first use of an :func:`experimental` API.
- `Violation(**data)` — A single property breach pinned to the event that caused it.
- `VoiceAgent(app, backend=…, config=…, research=…, memory_os=…, rails=…, owner_id=…, research_tool=…, **backend_kwargs)` — A grounded, remembering, guarded voice session over a :class:`ContextApp`.
- `WaterfallTranche(**data)` — The per-tranche distribution summary of an :class:`InsolvencyResolution`.
- `WindowedQueryResult(**data)` — A governed query's result over one closed window, **event-level cited**.
- `WorkerPoolBackend(workers=…, store=…, coordinator=…, lease_ttl_s=…)` — In-process reference distributed executor, lock-free, durable, fan-out.
- `Workflow(name, tracer=…, approval_fn=…)` — A deterministic, resumable DAG of steps.
- `WorldModel(transitions=…)` — A deterministic, offline-learned dynamics model of a tool environment.

### Functions

- `InputField(desc=…, default=…, **kwargs)` — Declare a signature input field.
- `OutputField(desc=…, **kwargs)` — Declare a signature output field.
- `admit(subject, reputation=…, ledger=…, standing=…, config=…)` — Decide a counterparty's admitted exposure from its standing.
- `analyze_dataset(objective, data, table=…, budget=…, engine=…, injection_detector=…, screen=…, extra_questions=…)` — Run a bounded, multi-step analysis over a dataset and return a cited analytical narrative — the offline, deterministic core of the data-analysis agent.
- `arbitrate(records, contract_id=…, arbiter=…, verifier=…, verify_with=…)` — Adjudicate a disputed contract from the records its parties submit.
- `assurance_regression_gate(before, after)` — Block a build when a previously-discharged claim is no longer discharged.
- `attest_custody(poster, reserves, custodian=…, as_of=…)` — Attest a poster's proven reserves into an (unsigned) :class:`CustodyAttestation`.
- `attest_liabilities(poster, liabilities, attestor=…, as_of=…, prior=…)` — Attest a poster's total obligations into an (unsigned) :class:`LiabilityAttestation`.
- `attest_reputation(records, subject, issuer=…, resolutions=…, config=…, verifier=…, horizon_days=…, note=…, verify_with=…)` — Issue an attestation of ``subject``'s earned standing from signed records.
- `attestation_a2a_server(book, revocations=…, attestations=…, config=…, name=…, url=…, description=…, tracer=…, token_validator=…, audit=…)` — Expose an org's settlement book as a queryable attestation peer over A2A.
- `attribute_regression(app, dataset, factors, metric=…, aggregate=…, repeats=…)` — Attribute a metric regression to the changed ``factors`` by Shapley counterfactual replay, the convenience entry point behind a failing gate.
- `available_packs()` — Names of all packs that can be loaded (built-in + installed plugins + registered).
- `build_finetune_backend(provider)` — Build the right fine-tune backend for a provider instance.
- `build_retail_environment(task_id=…)` — A τ-bench-style retail world: orders mutated by tools, verified by end state.
- `build_seniority_schedule(poster, tranches, as_of=…)` — Rank a poster's obligations into a sealed, unsigned :class:`SenioritySchedule`.
- `build_set_off_statement(poster, creditor, owed_usd, owing_usd, references=…, as_of=…)` — Collapse the mutual obligations between a poster and one creditor into a statement.
- `build_trust_model(attestations, base=…, config=…, attestation_config=…, verifier=…, verify_with=…)` — Build the importer's bounded, transitive trust over a set of issuers.
- `build_web_checkout()` — A deterministic, in-process checkout app and its goal, the offline, WebArena / OSWorld-shaped reference scenario.
- `buyer_position(max_price_usd, ideal_price_usd=…, max_sla_seconds, ideal_sla_seconds=…, min_quality=…, ideal_quality=…, weights=…, concession=…, min_utility=…)` — Build a buyer position: wants low price, fast SLA, high quality.
- `certify(case, signer=…, residual_risks=…, provenance=…, as_of=…)` — Build a :class:`CertificationReport` from a checked assurance case.
- `chat(provider=…, model=…, name=…, tools=…, writes=…, approve=…, web=…, user_id=…, tenant_id=…, session_id=…, memory_writeback=…, on_approval=…, role=…, objective=…, rules=…, app=…, config=…)` — Open a multi-turn, session-aware chat in one expression.
- `check_completeness(liabilities, claims, verifier=…, as_of=…)` — Fold a set of creditor claims against a liability attestation into a completeness check.
- `check_history_consistency(attestations, discharges=…, verifier=…)` — Walk a set of liability snapshots for cross-time monotonicity (no debt silently dropped).
- `check_root_consistency(attestations, verifier=…)` — Compare a set of liability attestations for cross-creditor root non-equivocation.
- `choreography_a2a_server(handlers, org_id=…, name=…, url=…, description=…, tracer=…, token_validator=…, audit=…)` — Expose a local org's choreography handlers over A2A.
- `combine_attestations(attestations, subject=…, config=…, verifier=…, base=…, allow_self=…, revocations=…, as_of=…, trust=…, trust_config=…, verify_with=…)` — Combine several issuers' attestations into one bounded, evidence-weighted prior.
- `compose(*steps, name=…, tracer=…)` — Compose steps left to right: ``compose(a, b) == compose(a) | b``.
- `default_model_registry()` — Process-wide registry, seeded from the built-in catalog plus the ``VINCIO_MODEL_REGISTRY`` overlay (if set). Constructed lazily and cached.
- `default_verifiers()` — The default offline kernel set behind ``app.verify_reasoning``.
- `deprecated(since, removed_in, alternative=…)` — Mark a function or class as deprecated.
- `did_from_public_key(public_key)` — Derive the self-certifying DID for an Ed25519 public key.
- `discharge_liability(poster, creditor, amount_usd, as_of=…, note=…)` — Build an (unsigned) :class:`Discharge` releasing part of what ``poster`` owes ``creditor``.
- `discover_plugins(groups=…, entry_points=…)` — List installed Vincio plugins without registering them.
- `draw_pool(pool, record, config=…)` — Settle one backed contract against a settlement record (draw or release).
- `edge_environment()` — Detect the current runtime and report its edge-relevant capabilities.
- `edge_manifest()` — Certify that the edge core imports no native/optional dependency.
- `enable_rich_reprs()` — Attach ``_repr_html_`` / ``_repr_markdown_`` to the core and data-plane types.
- `evaluation(dataset=…, metrics=…, gates=…, provider=…, model=…, name=…, role=…, objective=…, rules=…, app=…, config=…)` — Build an offline evaluation in one expression.
- `experimental(since, note=…)` — Mark a function or class as experimental (no stability guarantee).
- `extractor(schema, provider=…, model=…, name=…, role=…, objective=…, rules=…, app=…, config=…)` — Build a typed structured-extraction task from a schema in one expression.
- `gather_reputation(subject, peers, directory=…, principal=…, config=…, verifier=…, base=…, allow_self=…, held_attestations=…, held_revocations=…, as_of=…, trust=…, trust_config=…, max_peers=…, audit=…, record_audit=…, verify_with=…)` — Pull signed attestations and revocations from a bounded set of peers.
- `generate_chart(result, type=…, x=…, y=…, color=…, title=…, renderer=…, signer=…, infer_type=…)` — Turn a cited query result into a **content-bound, data-bound** chart.
- `generate_redline(original, revised, format=…, title=…)` — Generate a tracked-change redline between two texts.
- `guard_collateral(pools, poster=…, held=…, custody=…, solvency=…, verifier=…, verify_with=…)` — Fold a counterparty's collateral pools into a bounded, offline-verifiable re-use guard.
- `installed_plugins()` — All installed Vincio plugins across every group (alias for discovery).
- `is_vincio_did(did)` — Whether ``did`` is a well-formed ``did:vincio:ed25519`` identifier.
- `is_wasm_runtime()` — True when running on a WASM target (Emscripten/Pyodide or WASI).
- `key_fingerprint(public_key)` — A short, stable key id (``k<16 hex>``) for a public key, used as ``kid``.
- `library_capability(library, tasks, search=…)` — Fraction of *tasks* the library solves by applying an existing skill.
- `load_benchmark(name, **kwargs)` — Construct a benchmark adapter by name.
- `load_config(path=…, overrides=…)` — Load configuration from a file (or discover it), env vars, and overrides.
- `load_pack(name)` — Load a pack by name (built-in modules import lazily; installed plugin packs register via the ``vincio.packs`` entry-point group on first miss).
- `load_plugins(groups=…, entry_points=…)` — Register every compatible installed plugin into its registry.
- `make_finetune_backend(provider)` — Build the right fine-tune backend for a provider instance.
- `make_retail_environment(task_id=…)` — A τ-bench-style retail world: orders mutated by tools, verified by end state.
- `make_web_checkout()` — A deterministic, in-process checkout app and its goal, the offline, WebArena / OSWorld-shaped reference scenario.
- `model_swap_regression(app, dataset, baseline_model=…, candidate_model, metrics=…, quality_metric=…, alpha=…, repeats=…, flake_quarantine=…, flake_threshold=…, slice_prefix=…)` — Swap only the model on a fixed dataset and report a statistically grounded regression analysis (the body of ``vincio eval regress``).
- `negotiation_a2a_server(party, name=…, url=…, description=…, tracer=…, token_validator=…, audit=…)` — Expose a local negotiating :class:`Party` over A2A.
- `net_books(books, owner=…, verifier=…, require_intact=…, verify_with=…)` — Net a fleet of :class:`~vincio.settlement.book.SettlementBook`\ s into one set.
- `net_settlements(records, owner=…, fleet=…, verifier=…, verify_with=…)` — Fold a fleet's settled contracts into a minimal cleared set of obligations.
- `notebook_session(app, dataset=…, question=…, analyst=…, auto_display=…, rich=…)` — Open a governed, notebook-native analysis session over *app*.
- `post_collateral_pool(contracts, poster=…, posted=…, decisions=…, fraction=…, config=…)` — Post one stake backing many contracts into an (unsigned) :class:`CollateralPool`.
- `post_escrow(contract, decision=…, fraction=…, amount=…, poster=…, beneficiary=…, config=…)` — Post collateral against a contract into an (unsigned) :class:`Escrow`.
- `prove_equivocation(first, second, verifier=…, first_creditor=…, second_creditor=…)` — Fold two conflicting liability attestations into a non-repudiable :class:`EquivocationProof`.
- `prove_solvency(custody, liabilities, poster=…, completeness=…, as_of=…, verifier=…)` — Fold a reserve proof against a liability proof into a proof-of-solvency.
- `provider_trainer(backend, registry=…, inherit_from=…, pricing=…, suffix=…, fmt=…, poll_interval_s=…, max_polls=…)` — Build an *executed* :data:`StudentTrainer` over a fine-tune backend.
- `public_key_from_did(did)` — Recover the Ed25519 public key embedded in a ``did:vincio:ed25519`` DID.
- `query_dataset(request, data, dialect=…, question=…, ops=…, table=…, max_rows=…, engine=…, injection_detector=…, screen_question=…)` — Plan → verify → execute → cite, in one call.
- `query_metric(request, data, layer, by=…, where=…, order_by=…, descending=…, limit=…, engine=…, max_rows=…, injection_detector=…, screen=…)` — Resolve a governed metric over *data* with *layer* and run it — the one-shot free function behind :meth:`SemanticLayer.query`.
- `rag(sources=…, provider=…, model=…, name=…, grounded=…, evaluators=…, role=…, objective=…, rules=…, output_schema=…, chunking=…, retrieval=…, app=…, config=…)` — Build a grounded-RAG question answerer in one expression.
- `reconcile(a, b, tolerance=…)` — Tie two independently-produced settlement records out against each other.
- `record_transitions(env, action_sequences, include_failures=…)` — Drive ``env`` through each action sequence, recording every tool step.
- `register_benchmark(spec, replace=…)` — Register a benchmark on the default registry — the public extension point.
- `resolve_insolvency(custody, liabilities, schedule=…, poster=…, completeness=…, solvency=…, set_off=…, as_of=…, verifier=…)` — Distribute a poster's proven reserves across its ranked liabilities into a resolution.
- `retrieval_regression(search_fn, golden, config, store=…, metrics=…, gates=…, top_k=…, alpha=…, min_delta=…, k_values=…)` — Evaluate ``config`` on ``golden``, record an artifact, and gate vs. baseline.
- `revoke_attestation(attestation, subject=…, issuer=…, replacement=…, reason=…)` — Issue a revocation withdrawing a prior attestation by its hash.
- `select_offer(results, buyer_position, reputation=…)` — Pick the best deal among competing sellers by reputation-weighted utility.
- `seller_position(min_price_usd, ideal_price_usd, min_sla_seconds=…, ideal_sla_seconds=…, max_quality=…, ideal_quality=…, weights=…, concession=…, min_utility=…)` — Build a seller position: wants high price, a loose SLA, a low quality floor.
- `serve_viewer(store, host=…, port=…)` — Start the served observability plane over ``store`` (opt-in, self-hosted).
- `set_off_from_records(poster, creditor, liabilities, records, as_of=…, verifier=…)` — Derive a set-off statement straight from the existing signed, content-bound artifacts.
- `settle_contract(contract, reading=…, cost_usd=…, latency_ms=…, quality=…, run_id=…, saga_id=…)` — Reconcile delivery against a contract into an (unsigned) settlement record.
- `settle_escrow(escrow, record, config=…)` — Resolve a posted escrow against a settlement record (release or forfeit).
- `settle_saga(result, contracts, run_id=…)` — Settle every contract a cross-org saga ran under, from its durable journal.
- `signature(spec, instructions=…, name=…)` — Build a Signature type from a DSPy-style string spec::
- `sleep_for(state, seconds, clock=…)` — Pause the graph for ``seconds`` of wall-clock time, durably.
- `sleep_until(state, when, clock=…)` — Pause the graph until ``when`` (a datetime or ISO string), durably.
- `stability_of(obj)` — Return the stability record for ``obj``.
- `statistical_verifiers()` — The four statistical kernels — trend, correlation, interval, forecast.
- `stream_aggregate(data, group_by, measures=…, max_groups=…)` — Group a stream by one or more columns and reduce measures over each group in a single bounded-memory pass.
- `synthesize(spec, examples, require=…)` — Verify ``spec``'s properties on ``examples`` and emit a proof-carrying program.
- `task_goal_value(checks)` — A goal-value function: the fraction of an environment task's checks an observation's state satisfies (the planner's default verifier).
- `tool_agent(tools=…, writes=…, approve=…, web=…, provider=…, model=…, name=…, role=…, objective=…, rules=…, app=…, config=…)` — Build an approval-gated tool-using agent in one expression.
- `verify_containment(events)` — Check ``untrusted ⇒ no unapproved capability`` over recorded events.
- `verify_edge_parity(request=…, profile=…)` — Prove the edge runtime is the server compiler under a profile, not a fork.
- `verify_erasure_proof(proof, signer=…)` — Verify a proof's content binding and (if present) its signature.
- `wait_for_event(state, name)` — Pause the graph until an event named ``name`` is delivered; return its payload.

### Values

- `API_VERSION` — str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

## Error catalog (103 codes)

Every error derives from `VincioError` with a stable `.code`, a `.remediation`, and a `.docs_url`. Branch on `.code`.

- `VINCIO_ERROR` — Vincio error. Catch-all base error. Inspect `.code`, `.message`, and `.details`; every Vincio failure derives from VincioError so one except clause covers the family.
- `CONFIG_ERROR` — Invalid configuration. Run `vincio config validate` to locate the offending field, and `vincio config migrate` if the file predates the current schema.
- `PROVIDER_ERROR` — Model provider failure. Check the provider's status and your network; wrap the provider in a FailoverChain or CircuitBreaker so a single backend cannot stall a run.
- `PROVIDER_AUTH` — Provider authentication failed. The API key is missing, wrong, or lacks scope. Set the standard env var (e.g. OPENAI_API_KEY) or `provider.api_keys` indirection in vincio.yaml, and confirm the key is active for the target model.
- `PROVIDER_RATE_LIMIT` — Provider rate limit. Back off and retry; the error is retryable and carries `retry_after_s`. Add a RateLimiter or KeyPool, or lower `performance.max_concurrency`.
- `PROVIDER_TIMEOUT` — Provider timed out. Raise `provider.timeout_s`, reduce the request size, or rely on the automatic retry; persistent timeouts indicate provider degradation, so fail over to a healthy model.
- `PROVIDER_UNAVAILABLE` — Provider unavailable. The backend is temporarily down (retryable). Configure `provider.fallback_models` so a FailoverChain routes around the outage.
- `PROVIDER_RESPONSE` — Malformed provider response. The provider returned an unparseable or contract-violating payload. Verify the model id is correct for the endpoint and that any OpenAI-compatible base URL implements the expected schema.
- `CIRCUIT_OPEN` — Circuit breaker open. The breaker tripped after repeated failures and is failing fast. Let it cool down, or provide a fallback model so the failover chain skips the unhealthy entry immediately.
- `BATCH_ERROR` — Batch API failure. A Batch submission/poll/reconciliation failed. Re-submit the batch or fall back to synchronous `run`; inspect `.details` for the provider job id.
- `FINETUNE_ERROR` — Fine-tune job failure. The distillation fine-tune could not be submitted or reached a failed/cancelled state. Check the training file format and the provider job status before re-running the flywheel.
- `CAPABILITY_MISMATCH` — Model capability mismatch. The routed model structurally cannot serve the request (see `.missing`, e.g. vision/tools/context). Escalate to a capable model rather than retrying; enable `guard_capabilities` on the router/failover chain.
- `MODEL_RETIRED` — Model retired. The pinned model is past its registry retirement date. Run `vincio providers lifecycle` for a migration proposal and repin to the successor model.
- `PROMPT_ERROR` — Prompt compilation error. The prompt spec is malformed. Run `vincio prompt lint` to surface the offending rule and location.
- `PROMPT_LINT` — Prompt lint failure. A blocking lint rule fired (see `.findings`). Fix the flagged sections or relax the rule; `vincio prompt lint` reports each finding with a hint.
- `PROMPT_BUDGET` — Prompt over token budget. The compiled prompt exceeds the token budget. Trim instructions/examples, raise `budget.max_input_tokens`, or enable context compression.
- `CONTEXT_ERROR` — Context compilation error. The context compiler could not assemble a packet. Inspect the source candidates and scoring configuration in `.details`.
- `CONTEXT_COMPILE` — Context compile failure. Candidate collection or packing failed. Check that sources are indexed and the embedder is reachable; review the excluded-context report.
- `BUDGET_EXCEEDED` — Token budget exceeded. Selected context exceeds the budget (`.used` vs `.limit`). Raise the token budget, lower `retrieval.top_k`, or enable compression/packing.
- `INPUT_ERROR` — Invalid input. The run input could not be normalized or classified. Provide non-empty text or a supported file type.
- `DOCUMENT_ERROR` — Document processing error. A document could not be parsed. Confirm the format is supported and the file is not corrupt; install the relevant extra (e.g. `vincio[pdf]`).
- `LOADER_ERROR` — Document loader error. No loader matched, or a loader failed. Register one with `register_loader`, or install the extra its format requires.
- `DATA_ERROR` — Tabular data error. A dataset could not be built, encoded, or decoded. Confirm the schema matches the data width and the column types are valid.
- `QUERY_ERROR` — Text-to-query error. A query could not be grounded, verified, or executed. Confirm the referenced tables and columns exist in the registered schema, that the dialect matches, and that the result stays within `max_rows`.
- `UNSAFE_QUERY` — Query refused as not read-only. A generated query was structurally refused before it ran because it was not provably read-only (a write, DDL, multiple statements, or an injection signal). Re-issue a single read-only `SELECT`; the read-only guard cannot be disabled.
- `ANALYSIS_ERROR` — Data-analysis error. The data-analysis agent had nothing to analyze. Register a dataset (or pass `dataset=`), and when the catalog holds more than one table pass `table=` to choose which one to analyze.
- `CHART_ERROR` — Chart generation error. A chart could not be built from the result. Confirm the result has rows and that any `x`/`y`/`color` you name are result columns; install `pip install "vincio[charts]"` for the matplotlib renderer (the dependency-free Vega-Lite renderer needs no extra).
- `SEMANTIC_LAYER_ERROR` — Semantic-layer definition or metric error. A semantic-layer definition or governed-metric request was invalid. Confirm names are unique, simple identifiers; that derived columns and ratio measures have no cycles; that each measure declares an aggregation or a numerator/denominator ratio; that referenced metrics and dimensions are defined and ground to the table's columns; and that a natural-language question names a defined metric.
- `RETRIEVAL_ERROR` — Retrieval failure. A retrieval backend errored. Verify the index exists and the vector store URL in `storage.vector` is reachable.
- `INDEX_ERROR` — Index failure. Building or querying an index failed. Rebuild with `vincio index build`, and confirm the embedder dimension matches the stored vectors.
- `LAGER_ERROR` — LAGER retrieval error. A lazy-graph-evidence operation could not proceed: retrieve() before ingest(), or an extracted object failing byte-exact re-derivation. Ingest documents first (`engine.ingest(docs)` / `app.use_lager()`); a re-derivation failure indicates the source text changed after ingest.
- `MEMORY_ERROR` — Memory engine error. A memory operation failed. Check the memory store URL and that the owner/scope arguments are supplied.
- `MEMORY_POLICY` — Memory policy violation. The write policy rejected this memory (`memory.write_policy`). Loosen the policy to `open`, or supply the required owner/consent metadata.
- `MEMORY_CONFLICT` — Memory conflict. A new memory contradicts an existing one. Use `MemoryEngine.correct()` to supersede it history-preservingly instead of overwriting.
- `WEB_ERROR` — Web operation error. A web browsing/search operation failed. Inspect `.details` for the URL or query; check connectivity and the backend's status.
- `WEB_SEARCH_ERROR` — Web search failed. The search backend returned no usable results page (network error, rate-limit/anomaly challenge, or unparseable markup). Retry later, slow the query rate, or inject a different `SearchBackend`.
- `WEB_FETCH_ERROR` — Web page fetch failed. The page could not be fetched or read (network error, non-success status, unsupported content type, or body over the byte ceiling). Check the URL, or raise `WebPolicy.max_page_bytes` deliberately.
- `WEB_POLICY_DENIED` — Web policy refused the operation. The `WebPolicy` blocked the search/fetch before any request left the process (domain, scheme, private host, robots.txt, or an exhausted budget). Relax the specific policy field deliberately, or raise the session budget.
- `TOOL_ERROR` — Tool execution error. A tool raised. Inspect `.tool` and the tool's own exception; make the tool defensive or wrap the call site.
- `TOOL_NOT_FOUND` — Tool not found. No tool with that name is registered. Register it with `app.add_tool`, and check for a typo against `app.enabled_tools`.
- `TOOL_PERMISSION` — Tool permission denied. The caller's role lacks permission for this tool. Grant the permission in the registry, or call with an authorized principal.
- `TOOL_VALIDATION` — Tool argument validation failed. The arguments do not match the tool's schema. Correct the call against the derived JSON Schema in `.details`.
- `TOOL_TIMEOUT` — Tool timed out. The tool exceeded its time limit. Raise the tool timeout, or make the tool faster/asynchronous.
- `TOOL_APPROVAL_REQUIRED` — Tool approval required. A write/side-effecting tool is gated behind human approval. Approve the pending call (e.g. `assistant.approve(...)`) or add it to an `auto_approve` allow-list.
- `SANDBOX_ERROR` — Sandbox isolation failure. The isolation backend is unavailable or too weak for the requested level. Install/configure a real backend, or lower the isolation requirement only if you trust the code.
- `COMPUTER_USE_ERROR` — Computer-use action plane failure. A computer-use backend could not be driven: a missing optional driver (install `pip install "vincio[computer-use]"`), an unaddressable target selector, or an exhausted action budget. Check the backend and the action's stable selector against the perceived screen state.
- `TOOL_CONTRACT_VIOLATION` — Tool call breached its contract. A tool declared pre/post-conditions and the actual call broke one: an argument failed a `requires` clause, or the result failed an `ensures` clause. Fix the arguments to meet the precondition, or treat a post-condition breach as a bug in the tool; the runtime refuses an out-of-contract result rather than returning it.
- `AGENT_ERROR` — Agent execution error. The agent loop failed. Inspect the trace span tree (`vincio trace show`) to find the failing step.
- `AGENT_STEP` — Agent step failed. A single plan step errored (see `.step_id`). The executor may repair the plan; if it recurs, narrow the step's tool or inputs.
- `AGENT_BUDGET_EXHAUSTED` — Agent budget exhausted. The agent hit its cost/token budget before finishing. Raise the budget or reduce the task scope.
- `AGENT_MAX_STEPS` — Agent step limit reached. The agent reached `max_steps` without converging. Raise `max_steps`, or decompose the task; inspect the trace for a loop.
- `GRAPH_ERROR` — Graph definition or execution error. The stateful graph is misconfigured or a node failed. Check channel reducers and that every edge target exists.
- `CHECKPOINT_CONFLICT` — Checkpoint version conflict. Another worker advanced the thread first (optimistic-concurrency loss). Re-acquire the lease and resume from the new head; this is non-fatal.
- `WORKFLOW_ERROR` — Workflow error. The deterministic workflow failed. Inspect the step graph and any compensation handlers.
- `WORKFLOW_STEP` — Workflow step failed. A workflow step raised (see `.step`). Add a retry or compensation, or fix the step's logic; resume from the last checkpoint.
- `OUTPUT_ERROR` — Structured output error. The model output failed contract handling. Review the schema and the raw text in `.details`.
- `OUTPUT_PARSE` — Output parse failure. The output is not valid JSON for the schema. Enable provider-native constrained decoding or bounded self-correction (`enable_self_correction`).
- `OUTPUT_SCHEMA` — Output schema validation failed. The parsed output violates the schema (see `.errors`). Tighten the prompt examples or enable structure-only repair.
- `OUTPUT_REPAIR_FORBIDDEN` — Output repair forbidden. Repair was disabled but the output needs it. Allow self-correction, or fix the prompt so the first attempt validates.
- `CITATION_INVALID` — Citation validation failed. A cited claim does not resolve to supporting evidence. Require citations and answer-only-from-sources, or relax the citation contract.
- `GENERATION_ERROR` — Document/media generation error. Rendering or a generation provider failed. Install the relevant extra (`vincio[gen-docx|gen-pdf|gen-pptx]`) and check the provider credentials.
- `DOCUMENT_CONTRACT` — Document contract violation. The rendered document violates its contract and formatting-only repair could not fix it (see `.violations`). Adjust the content or the TableSpec/structure requirements.
- `MEDIA_GENERATION` — Media generation failure. An image, video, or speech provider call failed. Verify the media provider credentials and that the requested model supports the modality.
- `EVAL_ERROR` — Evaluation error. An eval run failed. Check the dataset format and that every referenced metric/judge is registered.
- `DATASET_ERROR` — Dataset error. The dataset could not be loaded or is malformed. Validate the JSONL rows against the expected case schema.
- `GATE_FAILED` — Quality gate failed. A CI gate threshold was not met (see `.failures`). Fix the regression, or adjust the gate expression if the new baseline is intended.
- `BENCHMARK_ERROR` — Benchmark adapter error. A benchmark adapter failed to load or score. Confirm the task-set hash and that the recorded fixtures or live solver are wired correctly.
- `EVAL_SUITE_ERROR` — Evaluation-suite error. An open-evaluation-plane run failed. Check the benchmark id resolves in the registry and that its dataset, metric, and report format are valid.
- `TIER_VIOLATION` — Provenance-tier violation. A run executed under a lower provenance tier cannot be reported under a higher tier's label. Run the benchmark at a tier its dataset and solver support, or request the tier the inputs actually justify.
- `OPTIMIZATION_ERROR` — Optimization error. An optimization run failed. Check the dataset, fitness weights, and that the prompt spec is valid before retrying.
- `REWARD_ERROR` — Reward derivation error. A verifiable reward could not be derived from the sample. Provide the signal the reward needs (an environment verification, adapter gold, or judge inputs) before calling app.learn.
- `CACHE_ERROR` — Cache error. A cache backend failed. Verify the cache URL in `storage.cache`; an in-memory cache (`memory://`) always works as a fallback.
- `SECURITY_ERROR` — Security policy error. A security control failed or blocked the operation. Review the active rails and policy settings under `security`.
- `ACCESS_DENIED` — Access denied. The principal lacks rights for this resource. Grant the role/scope via the AccessController, or call with an authorized identity.
- `TENANT_ISOLATION` — Tenant isolation violation. A cross-tenant access was attempted, or a run is missing its tenant tag. Pass `tenant_id` on the run; keep `security.tenant_isolation` on.
- `INJECTION_DETECTED` — Prompt injection detected. Untrusted content carried instruction-like text. Keep `block_untrusted_instructions` on, quarantine the source, and review the injection finding in `.details`.
- `CONTAINMENT_BLOCKED` — Containment blocked an untrusted capability. An argument derived from untrusted data reached a write/external tool without authority. Mint a CapabilityToken from the user's request via CapabilityBroker (or route the call through the approval gate) before the side effect; the DualPlaneExecutor enforces this automatically.
- `PII_POLICY` — PII policy violation. Detected PII violates the active policy. Enable redaction (`redact_pii_in_context`), or add the locale pack the data requires.
- `EGRESS_BLOCKED` — Egress DLP blocked the request. The outbound request carried secrets or sensitive identifiers. Remove the leaked credential; set `security.egress_dlp: warn` only if the match is a false positive.
- `IDENTITY_VERIFICATION_FAILED` — Agent identity / delegation / credential failed verification. A DID, identity document, delegation chain, or credential did not verify from the bytes. Check `.details` for the failing artifact: a sub-delegation may amplify its parent's grant (only attenuation is allowed), a signature may not bind to its issuer DID, or a key may have been rotated/revoked. Re-issue the artifact with `app.identity(...)`.
- `GOVERNANCE_ERROR` — Governance/compliance error. A governance artifact (card/BOM/lineage) could not be produced. Check that the app has the required sources and metadata configured.
- `RESIDENCY_VIOLATION` — Data residency violation. The resolved provider region is not in `governance.allowed_regions` (see `.region`/`.allowed`). Pin the provider region or route to an in-jurisdiction model.
- `ERASURE_ERROR` — Erasure could not complete. A right-to-erasure-by-source operation did not complete atomically. Retry `app.erase_source(...)`; inspect which stores were swept in `.details`.
- `GOVERNANCE_INVARIANT_VIOLATED` — Governance invariant violated. The formal verifier found a counterexample to a governance invariant (containment/residency/budget/erasure). Inspect `.counterexamples` for the minimal violating state, or call `app.verify_governance()` without `raise_on_violation` to get the full VerificationReport.
- `PRIVACY_BUDGET_EXCEEDED` — Differential-privacy budget exceeded. A consolidation or learning round would push a subject's cumulative (ε, δ) past its PrivacyBudget. Raise the subject's epsilon, set `on_breach='downweight'` to admit a clipped-harder release, or refuse the step; inspect spent/remaining ε in `.details` and `app.privacy_report()`.
- `STORAGE_ERROR` — Storage backend error. A storage backend failed. Verify the URL/credentials for the relevant `storage.*` setting and that the schema is migrated.
- `SERVER_ERROR` — Server error. The HTTP API server hit an internal error. Check the server logs and that every served app file exposes a ContextApp as `app`.
- `AUTHENTICATION_ERROR` — Server authentication failed. The request's API key or JWT was missing or invalid. Send a valid credential matching `server.api_keys`/`server.jwt_secret`.
- `SKILL_ERROR` — Agent Skill error. A SKILL.md bundle could not be parsed or loaded. Validate the front matter and that referenced scripts exist.
- `OBSERVABILITY_ERROR` — Observability error. A tracing, recording, or replay operation failed. Inspect `.details` and confirm the trace/recording exists and is readable.
- `REPLAY_DIVERGENCE` — Recording no longer replays. Live code asked for an edge (a model call, tool output, or retrieval) absent from the recording, or the recording failed to load/verify. Re-record against the current code, or use `Replayer.branch(...)` to re-execute the changed suffix against the recorded prefix.
- `ENERGY_BUDGET_INVALID` — Energy budget misconfigured. Set an energy budget with at least one ceiling: pass `limit_wh` (watt-hours), `limit_co2e_grams` (grams CO₂e), or both to `app.set_energy_budget(...)`.
- `EDGE_ERROR` — Edge runtime request invalid or over profile. Give the `EdgeRequest` a `task` or `objective`; under `strict=True`, raise the `EdgeProfile`'s `max_resident_bytes` / `max_input_tokens` or trim the request's evidence so the packet fits the edge profile.
- `REASONING_VERIFICATION_ERROR` — Answer certificate did not check. A deterministic verifier refuted the answer (an arithmetic, unit, temporal, schema, constraint, or citation check failed) and `app.verify_reasoning(..., raise_on_refute=True)` was asked to raise. Inspect `VerifiedAnswer.certificate.refutations`, fix the refuted claim, or run with self-correction so the orchestrator repairs it.
- `BEHAVIOR_VIOLATION` — Agent trajectory violated a behavior spec. A `RuntimeMonitor` / `Shield` found a `BehaviorSpec` property breached: a forbidden action, a missing precondition (e.g. a write before approval, a claim before retrieval), or a violated invariant. Use a shield in `block`/`repair` mode to prevent the action, or correct the plan so the property holds.
- `PROGRAM_SYNTHESIS_FAILED` — Synthesized program failed verification. A `synthesize(...)` program failed to run on its examples or a declared property (schema, row-count, field-range) was refuted. Inspect `SynthesizedProgram.certificate.refutations`, fix the op pipeline or the property, and re-synthesize; a refuted program is never run.
- `NEGOTIATION_ERROR` — Negotiation could not proceed. Check the `NegotiationPosition` is coherent (the reservation must be no better for the party than its ideal) and the `NegotiationBudget` has positive `max_rounds`. A negotiation that runs out of rounds without a deal does not raise; it returns a partial NegotiationResult with `status='no_agreement'`.
- `CONTRACT_VIOLATION` — Contract failed verification or was breached. The contract's content hash did not recompute, a signature is missing or invalid, or delivered work breached the agreed price/SLA/quality (see `.breaches`). Re-verify with the signer both parties used, or renegotiate; use `contract.to_budget()` to enforce the terms up front.
- `CHOREOGRAPHY_ERROR` — Cross-org choreography could not proceed. Declare exactly one of `participant=` (static) or `capability=` (discovered) per `Saga` step; register a participant binding for every org a static step names; for a discovered step pass a governed `directory=` / `binder=` so the capability resolves to an allowed, reachable candidate at dispatch time. Give the saga at least one uniquely-named step and pass a `saga_id` that exists in the durable store when calling `resume`. A saga whose forward step fails does not raise; it compensates and returns a SagaResult with `status='compensated'`.
- `COMPENSATION_FAILED` — Saga could not unwind cleanly. A compensating step itself failed, leaving a half-completed cross-org transaction partially unwound (see `.failures`). Resume the saga to retry the outstanding compensations once the participant is reachable, or reconcile the residue manually; the journal pinpoints every compensation that did not complete.
- `SETTLEMENT_ERROR` — Settlement could not proceed. Meter non-negative usage, sign a settlement only as its buyer or seller, and supply the contract terms a saga's steps ran under when settling it. A settlement whose delivered work breaches the agreed terms does not raise; it reconciles to a SettlementRecord with `status='breached'` (see `.breaches`); re-verify a record or book with the signer the parties used.
- `CULTIVATION_ERROR` — Skill acquisition could not proceed. Give every `CurriculumTask` an `environment` factory before cultivating it, set exactly one of `action`/`skill` on a `SkillStep`, and ensure a skill's `requires` resolve to active library skills without a cycle. A proposed objective the rails or the governance verifier reject does not raise; it is pinpointed on the `CurriculumProposal` (`.refused`) and never attempted; re-verify a `LearnedSkill`, `LearnedSkillLibrary`, or `CultivationResult` with its own `verify()`.
- `ASSURANCE_ERROR` — Assurance case or certification could not proceed. Give every leaf `Claim` at least one `Evidence` item (or list the kinds it demands on `required_evidence`), bind each `Evidence` to an artifact that exposes a verifiable verdict (an eval gate, a `GovernanceVerifier` report, a reasoning `Certificate`, an audit log, an identity/delegation chain, or an AI-BOM), and reference an `Incident` only to a claim that exists in the case. A claim whose evidence is missing, stale, or falsified does not raise; it ispinpointed on the `AssuranceReport` and the case `holds` is False; re-verify an `AssuranceCase` or `CertificationReport` with its own `verify()`.

## Gotchas for generated code

- The DEFAULT provider is OpenAI. A bare `ContextApp(name=...)` needs a provider
  and key; to run with NO key, pass `provider=MockProvider()` explicitly (from
  `vincio.providers`). The mock auto-generates schema-valid output offline.
- `result.output` is a validated Pydantic instance only when `output_schema=` is
  set; otherwise read `result.raw_text`. Check `result.status` / `result.error`.
- Grounding is a policy: `app.set_policy("answer_only_from_sources", True)` plus
  an evaluator like `groundedness`. The `rag(...)` front door wires both.
- Async methods are the `a`-prefixed variants (`arun`, `astream`, `abatch`, …);
  the sync names wrap them and work with or without a running event loop.
- Write/side-effecting tools are denied by default and surfaced for approval;
  pass an `approval_required=` tool plus an approval callback / allow-list.
- The data plane uses app METHODS, not top-level functions: `app.register_dataset`,
  `app.query_data`, `app.analyze_data`, `app.generate_chart`, `app.data_catalog`.
- Heavy backends are extras: install `vincio[openai]`, `vincio[retrieval]`,
  `vincio[server]`, `vincio[charts]`, `vincio[docs]`, etc. as needed.
- The frozen public surface is exactly `vincio.__all__`; import from the top
  level. Subpackage paths are internal and may move.
