vincio 3.28.0

Vincio: the context engineering platform for AI applications. Compiles prompts, memory, retrieval, tools, schemas, and policies into optimized, validated, observable model-ready context packets.

The scarce resource is not the model. It is the context you feed it.

---

Vincio is a Python platform for building context-engineered AI applications. It compiles prompts, memory, retrieval, tools, schemas, and policies into optimized, testable, observable, provider-neutral context packets — then validates and evaluates every output.

Most frameworks help you call a model. Vincio governs the boundary between your application state and the model: what evidence is selected, how it is scored and budgeted, how it is rendered for cache reuse, and how the result is validated, measured, and traced. Named for Leonardo da Vinci — engineering and craft in equal measure.

Raw Input → Normalization → Objective Detection → Memory Selection
→ Retrieval Planning → Evidence Retrieval → Ranking + Distillation
→ Tool Planning → Context Compilation → Model Execution
→ Parsing + Validation → Evaluation + Guardrails → Trace + Learning Loop

Contents

Why Vincio · Install · Quickstart · Features · Benchmarks · Comparison · Use cases · CLI · Architecture · Roadmap · Documentation

Why Vincio

Teams ship a prompt, watch it work, then spend months fighting everything around it: context that overflows the window, retrieved chunks that contradict each other, outputs that fail to parse, silent quality regressions, untraceable costs, and prompt-injection risk. These are not model problems — they are context problems.

Vincio treats context as a compiled artifact with a clear contract:

• Deterministic where it matters. Security, permissions, and validation are enforced in code — never gated on model output. The same input compiles to the same packet.
• Measured, not asserted. Every run is traced and costed; every change can be gated by an eval suite before it ships.
• Provider-neutral. OpenAI, Anthropic, Google, Mistral, any OpenAI-compatible endpoint, or a deterministic offline mock — behind one interface.
• One coherent model from input to output, instead of a bag of loosely-coupled utilities.

Install

pip install vincio                  # core — runs fully offline with the mock provider
pip install "vincio[openai]"        # + OpenAI provider
pip install "vincio[anthropic]"     # + Anthropic provider
pip install "vincio[chroma]"        # + a vector store (also: pinecone, lancedb, postgres,
                                    #   weaviate, milvus, elasticsearch, opensearch, vespa)
pip install "vincio[realtime]"      # + voice/realtime sessions (OpenAI Realtime, Gemini Live)
pip install "vincio[langchain]"     # + framework interop export (also: llamaindex, haystack, dspy)
pip install "vincio[snowflake]"     # + a warehouse connector (also: bigquery)
pip install "vincio[all]"           # every optional integration

Python 3.11+. Core dependencies are just pydantic, httpx, pyyaml, and typing-extensions; every heavy integration (vector stores, OCR, server, OpenTelemetry, …) is an opt-in extra.

Quickstart

from vincio import ContextApp

app = ContextApp(name="docs_qa")
app.add_source("docs", path="./docs", retrieval="hybrid")
app.set_policy("answer_only_from_sources", True)

result = app.run("How do I configure SSO?")
print(result.output)      # the grounded answer
print(result.citations)   # evidence the answer actually cited
print(result.trace_id)    # every run produces a full trace
print(result.cost_usd)    # …and a cost

No API key? It runs offline out of the box on a deterministic mock provider that emits schema-valid output — so your whole pipeline (retrieval, validation, evals, traces) runs for real in CI.

Typed output

from pydantic import BaseModel
from vincio import ContextApp

class TicketClassification(BaseModel):
    label: str
    confidence: float
    reason: str

app = ContextApp(name="triage", output_schema=TicketClassification)
result = app.run("The dashboard crashes after login")

result.output.label        # → a validated TicketClassification instance

Agents with tools and memory

app = ContextApp(name="support_refunds", output_schema=RefundDecision)
app.add_memory(scope="user", strategy="semantic")
app.add_tool("billing_lookup", permissions=["billing:read"])
app.add_tool("refund_create", permissions=["billing:write"], approval_required=True)

agent = app.agent(max_steps=6)
result = agent.run("Customer asks for a refund on invoice INV-123.")

Multi-agent crews and durable graphs

from vincio.agents import interrupt

crew = app.crew(members=[
    {"name": "researcher", "goal": "gather the numbers", "keywords": ["find"]},
    {"name": "writer", "goal": "draft the recommendation"},
])
result = crew.run("Explain the Q3 refund trend")   # bounded, traced, blackboard-shared

graph = app.graph("review")                        # checkpointed in your own store
graph.add_node("analyze", analyze)
graph.add_node("approve", lambda s: {"ok": interrupt(s, "proceed?")})
graph.add_edge("analyze", "approve")
flow = graph.compile()
paused = flow.invoke({"doc": "msa.pdf"})           # pauses at the human gate
done = flow.resume(paused.thread_id, value=True)   # later — even after a restart

Reliability as a guarantee

from vincio import Signature, InputField, OutputField

class Triage(Signature):
    """Classify a support ticket."""
    ticket: str = InputField(desc="the raw ticket text")
    label: str = OutputField(desc="bug | billing | feature | other")
    confidence: float = OutputField()

result = app.predictor(Triage)(ticket="The export button 500s")  # typed + validated

app.add_rail(name="no_leaks", kind="safety", detectors=["pii", "secrets"], action="redact")
app.add_rail(name="on_topic", kind="topic", direction="input", blocked_topics=["legal advice"])
app.enable_self_correction(max_cycles=2, max_cost_usd=0.05)      # facts never invented
app.add_output_schema(BugReport, keywords=["bug", "crash"])       # multi-schema routing

async for event in app.astream("Extract the invoice"):
    if event.type == "partial_output" and event.valid_prefix is False:
        break   # streaming validation: stop paying for a doomed answer

Evaluation as a gate

from vincio.evals import Dataset, EvalRunner

dataset = Dataset.load("golden/support_triage.jsonl")
report = EvalRunner(app).run(dataset)
report.print_summary()     # groundedness, citation accuracy, schema validity, cost — with CI exit codes

Self-improvement as a contract

from vincio.optimize import SelfImprovementPolicy

# One declarative policy composes scheduling, autonomous proposal, online updates,
# meta-optimization, active-learning labels, and canary-gated promotion/rollback.
controller = app.self_improvement(SelfImprovementPolicy(), dataset=golden)
async for ev in controller.astream():
    print(ev.phase, ev.reason)   # observe → proposal → meta → canary → promote/rollback

# Promote a candidate live only if it clears a no-regression canary verdict.
app.deploy(candidate, dataset=golden)

# On-policy reinforcement from verifiable rewards: improve a policy from the
# task-success oracle and benchmark scorers, behind a KL clamp + no-regression gate.
from vincio.optimize import OracleReward, RewardModel
result = app.learn(tasks, reward=RewardModel([OracleReward()]))
result.promoted, result.reward_delta, result.kl_to_reference

Interoperate: MCP, A2A, Skills

# Consume an MCP server — its tools run through the permissioned, sandboxed,
# audited runtime; its resources become cited evidence.
app.add_mcp_server("weather", command=["python", "weather_server.py"])

# Load portable SKILL.md procedural knowledge (progressive disclosure).
app.add_skill("skills/pdf-invoice")

# Expose your app over the protocols — one ContextApp, both consumer and provider.
mcp_server = app.serve_mcp()                       # serve tools/resources/prompts
a2a_server = app.serve_a2a(crew, name="research")  # Agent Card + task lifecycle

# One portable reasoning knob across providers (thinking tokens are billed).
from vincio.core.types import RunConfig
app.run("Plan the migration", config=RunConfig(reasoning_effort="high"))

Features

Vincio is organized into composable subsystems. Use the high-level ContextApp runtime, or reach for any engine directly. Everything below is implemented, tested offline, and documented.

Subsystem	What it does
Prompt compiler	Typed prompt ASTs with ${variables}, lint rules, cache-aware stable-prefix layout, versioning, hashing, diffing, variant generation.
Context compiler	Scores every candidate (relevance, novelty, authority, freshness, provenance, token cost, leakage risk), deduplicates, resolves conflicts, compresses, and packs to a token budget — with an excluded-context report explaining every omission. Image, table, video, and text evidence are first-class candidates in one scored packet, with modality-aware token cost and slim packets that materialize() cross-process from a content-addressed evidence store. Video clips are sampled and segmented into typed evidence whose time range is preserved through to the citation, so a clip-grounded answer points at the moment it came from.
Retrieval (RAG)	BM25 + dense + learned-sparse (SPLADE-style) + late-interaction (ColBERT-style MaxSim with PLAID-style compression) fused in one weighted RRF; query understanding (HyDE, multi-query, decomposition, step-back); sentence-window, parent-document/auto-merging, and contextual chunking; GraphRAG with community summaries and global/local routing; live indexes (upsert/TTL/migrations); entity-graph, multi-hop, and reasoning retrieval; Matryoshka (MRL) dimension truncation, contextual (Voyage context-3) and unified text+image multimodal (Cohere v4 / Voyage) embedders behind one build_embedder; a structured FilterSpec (eq/in/range/and/or) that pushes down to each backend's native filter with tenant scope enforced in the engine.
Memory	Layered (session → episodic → semantic → tenant → graph) with a guarded write pipeline, confidence decay, contradiction resolution, and privacy scoping; remember/recall personalization over user/agent/session/team scopes, hybrid vector+graph recall, episodic→semantic consolidation with provenance, TTL + importance-weighted retention, audited GDPR-style edit/forget/export/erase, and a CI-gated memory eval harness. Memory is bi-temporal (valid_from/valid_to + as-of recall, correct() that preserves history) with per-memory ACLs and a TEAM scope.
Tools	Permissioned registry (RBAC scopes + ABAC rules), schema derivation from type hints, a resource-limited sandbox (timeout, output caps, scrubbed env, POSIX CPU/memory/fd setrlimit), reliability scoring, idempotent write-action guardrails with approval callbacks; computer-use and provider-native hosted tools behind a pluggable IsolationBackend (container / microVM / gVisor / WASM).
Agents	Bounded DAG execution with planners (direct / static / dynamic / ReAct / plan-and-execute / hierarchical HTN), critics, validators, human gates, and hard budget enforcement; in-place plan repair (re-bind / substitute / reorder / drop on a tool failure, contradiction, or budget shock — recorded as a trajectory event, not a restart); cost-aware action selection that reads ModelRegistry pricing and the live budget to spend the cheapest capable model per step, escalating only on low confidence; a budgeted, citation-gated deep-research agent (app.research) that loops search → read → reflect → verify → synthesize into a cited report; a self-editing memory OS (app.enable_memory_os) exposing memory ops as audited tools with a context-pressure pager.
Orchestration	Multi-agent crews — roles, delegation, and a shared versioned blackboard — with per-agent budget shares and guaranteed termination; durable stateful graphs with checkpoints on your storage, resume, edit-and-resume, and time-travel forks; first-class human-in-the-loop interrupts; a declarative compose/pipe API with streaming node events. A distributed durable-execution backend runs the same graph/workflow across a worker pool with a TTL lease + checkpoint-version CAS so two workers never double-execute a step, with BSP parallel super-steps, a Send map-reduce primitive, and LangGraph / OpenAI Agents SDK / Ray / Temporal export adapters. A work-stealing sub-graph scheduler runs independent sub-graphs concurrently across the pool under one fair-share budget with an SLA deadline that returns a partial result, and durable timers (sleep_until / wait_for_event) pause a graph for a delay, a webhook, or an approval — surviving a restart without holding a worker.
Workflows	Deterministic DAGs with retries, branching, parallelism, compensation, and approval gates that pause the run and resume without re-executing finished steps.
Structured output	Pydantic output contracts, provider-native constrained decoding with strict schema sanitization (robust-parser fallback everywhere else), streaming validation with mid-stream early abort, DSPy-style typed signatures (Signature / Predict) that feed the optimizer, bounded self-correcting loops with cost ceilings, multi-schema routing by task or content, and principled repair that fixes structure only — never invents facts.
Evaluation	Golden JSONL datasets, 30+ task / grounding / quality / safety / conversational / trajectory & tool-use / retrieval / operational metrics, deterministic / model / G-Eval judges with calibration, synthetic dataset generation with provenance, red-teaming judged by the security detectors, experiment tracking with statistical significance, regression gates, and baseline-diff reports — plus a pytest plugin (assert_eval / assert_grounded, packet/trace snapshots). A stateful-environment harness (Environment reset/step/observe/verify with a task-success oracle) scores the verifiable end state of a mutable world, and nine agentic benchmark adapters (SWE-bench Verified, τ-bench/τ²-bench, GAIA, WebArena, BFCL, AgentBench, ToolBench, LiveCodeBench, MMLU-Pro) run inside VincioBench behind one contract — replayed offline or solved live, scored either way by the benchmark's own scorer. A retrieval-eval harness (recall@k / nDCG / MRR / context-precision) records versioned index-regression artifacts keyed on (embedder, chunker, corpus hash) and gates a regression on the same significance test as a model swap. When a gate does regress, a CausalAttributor attributes the drop to the component that caused it (prompt / retrieval / model / budget) by Shapley counterfactual replay — so a failure names its cause instead of just its score — and an AdaptiveSampler spends the eval budget where the variance is, converging a noisy gate on the same verdict as the exhaustive run for far fewer samples.
Agentic eval & continuous quality	Score how a run reached its answer: trajectory & tool-use metrics over a Trajectory projected from any crew / graph / trace (no re-instrumentation); a deterministic multi-turn Simulator; online evaluation on a sampled slice of live traffic (restart-safe, worker-aggregatable, off the hot path); drift detection — score, embedding-distribution, KS / PSI / MMD distributional, and a streaming CUSUM changepoint — raising a drift.detected event; human annotation with Cohen's-κ judge calibration; judge ensembles (JudgeEnsemble) that turn a panel's disagreement into an uncertainty signal — flagging split cases for review and earning CI-gating weight only once the panel's κ against human labels clears the bar; production A/B with cost + significance per variant. Every metric doubles as a runtime guardrail (add_metric_rail) and optimizer fitness term.
Optimization & the closed loop	One continuous, reproducible cycle — trace → dataset → eval → optimize → promote (ImprovementLoop / vincio loop run): production traces become datasets, the gated optimizer searches, and the winner lands in the prompt registry tagged, eval-linked, applied live, and audited — with safety-gated promotion that blocks any candidate regressing schema validity or safety. Plus grounded auto-memory from runs, eval-driven retrieval feedback, cost/quality Pareto frontiers with knee-point selection, and learned per-task budget allocation.
Self-improvement	One declarative SelfImprovementPolicy composes scheduling, autonomous proposal, online updates, meta-optimization (learned fitness weights + successive-halving), active-learning label acquisition, and canary/rollback; app.self_improvement(policy).astream() drives the organs as one streaming controller — observe → proposal → meta → reeval → canary → promote/rollback. app.deploy promotes a prompt/policy live only on a no-regression canary verdict — an offline gated comparison or a live-traffic canary that ramps a fraction of real runs and auto-rolls-back a regression. Every promotion passes the same significance + safety + golden gates.
Reflective optimization & the flywheel	A GEPA-style ReflectiveOptimizer that reads eval failures, reflects on why a prompt lost, and proposes targeted edits, evolving a Pareto frontier under a hard rollout budget (plus MIPRO joint instruction+example proposal); a distillation flywheel (app.export_training_set / vincio distill) that curates grounded production traces into provider-ready fine-tuning JSONL and gates a cheaper student into the routing cascade only when it holds quality, with executed fine-tune jobs (OpenAI/Gemini/Anthropic); learned prompt compression (LLMLinguaCompressor) as a faithfulness-gated compiler pass; and reflective calibration of the optimizer's own LLM judge against κ-validated labels.
On-policy reinforcement (RLVR)	The learning loop closed on a policy, not just a prompt. A RewardModel turns the signals the platform already computes — the stateful-environment task-success oracle, the nine benchmark scorers, and a judge ensemble whose disagreement down-weights itself — into a verifiable reward; a TrajectoryAdvantage assigns step-level credit by Shapley counterfactual replay (the same kernel as causal regression attribution); and a GRPO-style TrajectoryOptimizer (app.learn) runs a group-relative update behind a KL-to-reference clamp and a monotonic no-regression gate — the served policy never regresses the baseline reward — emitting a fine-tune job through the existing flywheel under the same canary verdict a prompt deploy produces. The offline path runs a deterministic mock policy so the optimizer's math is fully tested without a GPU.
Test-time compute & reasoning	Thinking budgets and parallel search as a first-class, budgeted dimension of the run. A ReasoningController (app.use_reasoning_controller) sets thinking effort and a thinking-token budget per step from the task classification and the live budget, under a hard reasoning-token ceiling so a hard task cannot silently exhaust the run; a warm thinking prefix in the byte-budgeted ReasoningTraceCache steps the effort down. TestTimeSearch (app.test_time_search) runs verifier-guided best-of-N, self-consistency, and beam search over tool-use trajectories — scored by the platform's existing judge ensembles and verifiable rewards through one Verifier protocol (a split panel's disagreement lowers its confidence) — and early-exits the instant the verifier clears the bar or the majority is locked, bounded by a candidate / cost / deadline budget.
Long-horizon context engineering	Million-token, multi-day, multi-session runs stay bounded where naïve accumulation rots quality and blows the budget. A per-run ContextGovernor (app.use_context_governor) holds a ContextBudget — live tokens, residency, and KV-cache footprint — the way the cost report holds a dollar budget, and surfaces it via app.context_budget_report(). RelevanceDecay applies the memory subsystem's decay within a single run so stale spans lose weight before they crowd out fresh signal, surfaced in the excluded-context report. A provenance-preserving ContextCompactor folds cold spans into hierarchical summaries in the memory OS and pages their full text back on demand from the content-addressed store — so detail is moved, never lost. A horizon-scaling SLO holds quality and footprint bounded as a run grows 10×.
World-model / simulation-based planning	An agent that learns a model of its tools and plans against it — searching imagined rollouts before acting, so a wrong move costs a simulated step, not a live one. A WorldModel is fit offline from recorded reset/step Transitions (record_transitions); it learns each tool's parameterized effect under a learned precondition, so it predicts a refund fails on a processing order but succeeds on a cancelled one — and generalizes a cancel it only ever saw on one order to another. A CalibrationReport (WorldModel.calibrate) earns the model planning weight only once its predictions track the real environment within tolerance, the way a judge ensemble earns gating weight. A ModelPredictivePlanner searches imagined rollouts with the test-time-search beam, commits the best first action, observes, and re-plans — and at a fixed action budget matches or beats reactive planning, opening a vault a one-step planner is trapped short of.
Causal record-replay debugger	A past run becomes something you can step, inspect, and branch — not a one-shot you can only read about. A Recorder captures every non-deterministic edge of a run — model responses, tool outputs, retrieval hits, the negotiated capabilities, and the clock/seed — keyed to its trace spans into a portable, content-addressed, verifiable Recording. A deterministic Replayer serves each edge back so a recorded run replays byte-for-byte (the recording, not the live provider, drives the run), with a step/inspect surface over the span tree and a Divergence report the moment live code no longer matches. Branch-and-edit (BranchEdit) forks a recording, changes an edge or the input, and re-executes only the affected suffix while the unchanged prefix is still served from the recording — so a fix is validated against the exact failing run.
Learned semantic cache & near-miss KV reuse	Exact-match caching serves a byte-identical request for free; this serves the rung above it — a request that is semantically equivalent (not byte-identical) to a recent one, answered straight from cache. A LearnedSemanticCache (app.use_semantic_cache) serves a near-miss only above a calibrated acceptance threshold: a ThresholdCalibrator fits the bar from labelled trace pairs so accepted near-misses clear a precision target — and falls back to off rather than guess when the target is unreachable, so the cache never serves below the bar. Every accepted hit is auditable and reversible, and a SemanticCacheGate catches a drifted cache with the same eval-replay no-regression check that gates a model swap. A KVPrefixPool (app.use_kv_prefix_reuse) reuses a shared stable-prefix KV footprint across a family of requests that share a head, reporting the serving-engine KV the shared head avoids recomputing. Savings surface as $0-billed calls in the cost report and via app.semantic_cache_report(); both layers stay under the resident-memory budget, held by a hit-quality SLO (an accepted near-miss is at-least-as-good as a live answer at a fixed budget).
On-device fine-tuning & continual local adaptation	The flywheel turns traces into hosted fine-tune jobs and the in-process GGUF provider runs a model air-gapped; this closes the loop with local adaptation — the model improving on its own traffic with no hosted training round-trip. A LocalLoRATrainer fits a parameter-efficient, low-rank LocalAdapter on-device from the flywheel's grounded dataset — pure-Python and deterministic by default, with a NativeLoRABackend hook for a real GGUF/LoRA. An AdaptedProvider applies it to any provider (the in-process model, the mock, a hosted endpoint) so an in-distribution request is answered the way it was taught while everything else falls through to the base model unchanged — the adapter is bounded, never reshaping traffic it has not seen. A ContinualAdaptation loop (app.adapt_locally / app.local_adaptation) promotes a new adapter version only when the locally-adapted model is at-least-as-good as its base on a held-out set — the same no-regression gate a hosted fine-tune job clears — and an AdapterRegistry versions every adapter and rolls it back on regression. Apply or unload one live with app.use_local_adapter; the run never leaves the process, held by a no-regression SLO.
Federated / cross-org self-improvement	The platform learns from its own traffic within one trust boundary three ways; this adds the rung that lets a fleet improve together without sharing the raw traffic. Each member builds a numeric, raw-text-free Contribution — the clipped, masked subspace scatter of its local adapter geometry, never a prompt or a response — behind the consent ledger (TRAINING purpose) and the residency posture (app.contribute_federated). A SecureAggregator merges the fleet's contributions into a shared FederatedSubspace: the pairwise masks cancel exactly, so the aggregator recovers the fleet geometry without ever seeing one member's update, refuses a round below the k-anonymity contributor floor, and supports a differential-privacy Gaussian mechanism via PrivacyConfig. The adopting member re-fits its own adapter against the shared subspace (app.adopt_federated / app.federated_improvement) — the fleet's geometry, the member's own grounded answers — and adopts it only when at-least-as-good as its base on a held-out set, the same no-regression gate a local promotion clears, versioned in the AdapterRegistry and rolled back on regression. Only numeric, masked, bounded-sensitivity aggregates ever cross a trust boundary; held by a privacy SLO and a no-regression SLO.
Differential-privacy memory & training	A federated round bounds one member's per-round influence; this adds the end-to-end privacy accountant the platform lacked — a per-subject (ε, δ) budget that composes every memory consolidation and learning round a subject's data touches and refuses once it is spent. app.use_privacy_accountant(...) attaches a Rényi/moments PrivacyAccountant that tracks the cumulative (ε, δ) a subject has spent (composing across rounds far more tightly than naively summing each step), and a PrivacyBudget gates a learning step the way the cost report gates a dollar: a consolidation or contribution that would exceed the budget is refused (a hard cap) or down-weighted (clipped harder so its sensitivity, and so its privacy cost, fits). It wires into memory consolidation and federated contributions automatically, and app.privacy_report() rolls up each subject's spent / remaining ε next to the cost report — every spend and refusal on the hash-chained audit log, so the guarantee is a mechanical, auditable number, not a policy doc — see the differential-privacy guide.
Cross-fleet reputation & weighting	A federated round merges every member with equal weight; this adds a per-member reputation that discounts an unreliable or adversarial member's pull on the shared consensus — earned only from how each contribution fared against the no-regression gate, never from raw traffic. app.use_reputation_ledger(...) attaches a ReputationLedger that keeps each member's reliability as a Beta-Bernoulli posterior over gate outcomes (a robust generalization of the existing reliability scoring): a newcomer earns the benefit of the doubt from a prior, a repeatedly-regressing member decays toward a floor, a reformed member recovers. The SecureAggregator weights a member's contribution by its reputation before distilling the consensus subspace — folded in before the secure-aggregation masks so they still cancel exactly — so a regressor is discounted without being singled out. The discount is bounded and reversible: a weight never leaves [floor, 1] (only lowering pull, never zeroing it or bypassing the quality bar), and adoption still clears the same no-regression and canary gates a local promotion does. Every update lands on the signed audit chain and replays from it (ReputationLedger.from_audit), and app.reputation_report() rolls up each member's standing next to the cost and privacy reports; held by a discount-the-regressor SLO and a no-regression SLO.
Energy & carbon accounting	The cost report makes a run's dollar spend an auditable number; this adds the sustainability figure beside it — a per-run energy (watt-hours) and carbon (grams CO₂e) estimate, on the same cost-report surface, never a new plane. app.use_energy_accounting(...) turns it on; every run then accrues a deterministic estimate from its own token accounting against a per-model intensity (by tier, from the ModelRegistry) and a per-region grid factor — result.energy_wh / result.co2e_grams, with app.energy_report(...) rolling it up by model/tenant/feature on the same attributed events the cost report uses. It is budgeted like a dollar: app.set_energy_budget(...) sets an energy or carbon envelope and a run that would exceed it is refused the way a hard cost cap refuses spend. And it is auditable and offline — the estimate is computed in-process from a built-in intensity table (no external service), and both the per-run number and every refusal land on the hash-chained audit log, so the sustainability figure is mechanical, not a claim.
Edge / WASM in-process runtime	"Runs in your process" extends to a WASM process. The dependency-free core — the prompt and context compilers, the vectorized scorer with its pure-Python fallback, the deterministic rails, and the offline-first evidence path — runs at the edge and in the browser through a thin in-process boundary. An EdgeRuntime (app.edge_runtime()) turns an EdgeRequest into a bounded, slim packet and a rendered prompt with no provider, network, filesystem, or caller-owned event loop — the same compile → score → rail → pack pipeline, offline. An EdgeProfile bounds the compiled packet's resident footprint and token window for a constrained target; the footprint stays under the cap as the candidate corpus grows 10×, held by the same slimming + eviction the server's resident-memory budget uses. The deterministic rails run unchanged, so a secret leaking from evidence into the assembled context is refused at the edge exactly as on the server. It is parity, not a fork: verify_edge_parity proves an edge compile is byte-identical to a direct server compile over the same inputs, and edge_manifest statically certifies the core imports nothing native (NumPy stays behind its guarded fallback), so the edge build is WASM-buildable and a capability can never silently diverge between server and edge — held by an edge-scaling SLO and exercised by the same offline test suite.
Observability	Every run yields a full trace span tree with sessions, threaded runs, user feedback, and eval scores on spans; JSONL and OpenTelemetry exporters (GenAI semantic conventions, including agentic spans); a local viewer (TUI + self-contained static HTML export + visual trace diff); traces become eval datasets in one command; a versioned prompt registry with tags, diffs, rollback, and eval links; per-run cost tracking. A served, self-hosted observability & alerting plane — an indexed trace/cost store with rollups, a stdlib dashboard (serve_viewer), and a rule engine (threshold / EWMA-anomaly / SRE burn-rate) over webhook/Slack/PagerDuty/Prometheus sinks — replaces O(n) JSONL scans, with prompt/completion content off by default at the export boundary.
Security	Deterministic PII / secret detection and redaction (with non-English locale packs for France/Germany/Spain/India/Singapore/Brazil/UK), prompt-injection defense, authority/provenance RAG-poisoning detection on retrieved evidence, and provable injection containment — a typed TrustLabel and TaintedValue that propagate taint from untrusted documents, a DualPlaneExecutor whose privileged planner sees only schema-validated extractions, and unforgeable CapabilityTokens minted from the user's request so an injected instruction provably cannot escalate to an unauthorized side effect; programmable input/output rails (topic / format / safety / custom) in the deterministic policy engine, RBAC / ABAC, tenant isolation, and a hash-chained, signed Merkle-checkpointed audit log with offline tamper verification (vincio audit verify) — all documented in a threat model and shipped with SBOM + SLSA provenance attestations.
Governance & compliance	Evidence generated from the running system, as files you own: machine-readable model & system cards, a compliance coverage matrix across OWASP LLM Top 10 (2025) / OWASP Agentic / NIST AI RMF / MITRE ATLAS / ISO IEC 42001 backed by red-team and eval evidence, an AI-BOM with SHA-256 model-hash verification, EU AI Act synthetic-content marking (media-aware, optionally signed + verifiable), an EU AI Act conformity pack (risk-tier + cited Annex IV + Article 27 FRIA), provable erasure (app.erase_source emits a signed, content-bound ErasureProof over the exact removed-id set across indexes, memory, and generated artifacts, anchored to the audit chain's Merkle root and verifiable offline), a ConsentLedger binding data to a GDPR purpose + lawful basis that access and recall enforce, data lineage, data-residency-aware egress refusal, formal invariant verification (app.verify_governance proves containment, residency, the budget cap, and the erasure-proof binding hold across their whole bounded, typed state space ahead of any run — a deterministic, offline, content-hashed verdict on the audit chain that returns a minimal counterexample on violation), and the non-English token tax surfaced per language/tenant — see the governance guide and the verification guide.
Documents & media out (generation)	The deliverable comes out under the same guarantees as text in. A DocumentBuilder renders a validated result into cited DOCX/PDF/PPTX/HTML/Markdown, structurally validated against a DocumentContract with formatting-only repair, plus template/form filling and tracked-change redlines. A CitedReportBuilder resolves [E1] markers to footnotes + a bibliography with sentence-level citation coverage and per-claim entailment. Image generation/editing, TTS, and video generation/editing (Sora / Veo / a generic adapter) are first-class output modalities where every asset is C2PA-provenance-stamped, budget-metered, and audited. Inputs get richer too: OCR auto-fallback for scanned PDFs, audio transcript ingestion, video understanding (deterministic frame sampling + temporal segmentation into time-stamped, citable evidence), new-format loaders (PPTX/EPUB/RTF/ODT/Parquet/mbox), a real-parser HTML/JSON/YAML path, and offline forms/KYC extraction — see the generation guide and the video guide.
Storage	Pluggable metadata (in-memory / SQLite / Postgres, async-first with a psycopg3 pool), blob, analytics (DuckDB), vector (Qdrant / pgvector / Chroma / Pinecone / LanceDB / Weaviate / Milvus / Elasticsearch / OpenSearch / Vespa behind one build_vector_index factory), and graph (Neo4j) backends. Redis-backed shared state + a first-class vincio serve keep multi-worker deployments coherent.
Providers	OpenAI (Chat Completions + Responses API), Anthropic, Google, Mistral, any OpenAI-compatible endpoint (with hosted-gateway presets: groq, together, fireworks, openrouter, deepseek, perplexity, xai, nvidia), enterprise endpoints (AWS Bedrock SigV4, Google Vertex, Azure OpenAI) behind a pluggable AuthStrategy in the same registry, and a deterministic offline mock — all async-first with sync wrappers, pooled transport, retries, and capability-aware failover, with in-flight request coalescing. A data-driven ModelRegistry (capabilities, pricing, lifecycle) is the single source the cost table, capability guards, and rotation read from. Unified reasoning control (reasoning_effort / thinking budget) maps across OpenAI/Anthropic/Gemini, with thinking tokens recorded and billed. Opt-in voice/realtime sessions (OpenAI Realtime, Gemini Live) via vincio.realtime. Batteries-included local neural models (fastembed, SPLADE, ColBERT, a cross-encoder, and a llama.cpp GGUF in-process provider) give air-gapped/edge deployments true offline inference behind the same interfaces.
Protocols & interoperability	Speaks the standards in-process: MCP client and server (stdio / Streamable HTTP / in-process) — MCP tools run through the permissioned, sandboxed, audited, budgeted runtime; resources become cited evidence. A2A agent-to-agent — expose a crew/graph as an Agent Card + task lifecycle, and reach remote agents as bounded, traced crew delegates. Agent Skills — SKILL.md with progressive disclosure, bundled scripts as sandboxed tools. A governed agent fabric (AgentDirectory over A2A Agent Cards, AGNTCY/ACP, and the MCP Registry) resolves agents behind an AllowListGate, every resolution an audited access decision; the same gate governs a signed community pack & skill registry and a one-call MCP-server marketplace bridge that lands a discovered server's tools in the permissioned runtime. Generative UI streams a run as AG-UI events so an interactive frontend inherits the run's provenance, budget, and audit. MCP Apps land the spec's newer surface in that same channel: a server's ui:// UI resource is surfaced as a governed mcp.ui AG-UI event (app.mcp_app(...) / MCPAppBridge) — untrusted-external provenance, token-metered against the run budget, audited — and a typed elicitation request (ElicitationGate) for mid-call user input is gated by the same approval + rail machinery a write tool passes, so an accepted value is screened and tainted untrusted. Protocol-version negotiation and a stateless-core transport mode keep a peer pinned to an older stable revision interoperable.
Agent negotiation & contracting	Bounded negotiation and contracting between agents in a multi-org crew, in the same governed, audited, budgeted runtime — never a hosted marketplace. A Negotiation runs a typed offer/counter-offer bargain between a buyer and a seller party with guaranteed termination (the analogue of a bounded crew round): a deal when the parties' acceptable regions overlap, a clean no-deal when they do not, a partial result on a deadline. The agreement is a typed Contract over price / SLA / scope / quality that both parties sign, that verify checks offline from the bytes alone (a tampered term or forged signature is caught), and that to_budget / check (app.enforce_contract) enforce like any other budget. The counterparty's ReputationLedger standing weights its offers, so a repeatedly-regressing agent is discounted without being singled out (a bounded, reversible risk premium), and select_offer picks the reputation-weighted best deal among competing sellers; a breached contract debits the seller, closing the loop. The bargain runs offline against deterministic local parties or over the A2A fabric against a remote counterparty (A2ANegotiator / app.serve_negotiation) byte-for-byte the same, every outcome on the hash-chained audit log (app.negotiate) — see the negotiation guide.
Cross-org workflow choreography	The durable work agents coordinate once they can negotiate and contract: a long-running, compensating workflow spanning more than one organization's agent fabric — the choreography analogue of the in-process durable graph, now crossing trust boundaries. A Saga is an ordered list of steps, each dispatching a typed StepRequest to a participant org under a negotiated Contract and declaring the compensation that undoes it; a Choreography (app.choreograph) drives it with per-org self-governance — the coordinator audits the dispatched handoff on its own chain while each Participant runs and audits the step on its own, so no shared control plane crosses a trust boundary, only the typed contract and the audited handoff. The SagaJournal is checkpointed to the metadata store after every step, so a saga survives a restart — a fresh engine resumes it by id and never re-runs a completed step (app.resume_choreography) — and is hash-chained, so verify() recomputes it offline and catches any tampered record. A forward step that fails, raises, or breaches its step contract triggers deterministic compensation of the completed steps in reverse order, so a half-completed cross-org transaction unwinds cleanly. A LocalParticipant runs an org's handlers in-process and a RemoteParticipant / app.serve_choreography dispatches a step to a remote org over the A2A fabric, byte-for-byte the same — see the choreography guide.
Agent-to-agent settlement & metering	Closing the books on contracted cross-org work — a metered, auditable settlement record reconciling delivery against a negotiated Contract, the way a run closes its cost report; never a payment rail, only a verifiable ledger of what was owed and delivered. A Meter accrues the usage of delivered work against the agreed price as a saga's steps complete — each unit a UsageEvent attributed to the contract and the run — into a deterministic, total-preserving MeterReading (the cross-org analogue of the cost report). A SettlementRecord reconciles that delivery against the agreed price / SLA / quality into a typed, signed, offline-verifiable record: both parties sign one reconciliation hash binding the economic facts, verify checks it from the bytes alone (a tampered figure or forged signature is caught), and reconcile ties two orgs' independently-produced records out — a dispute is pinpointed, not merely flagged. A SettlementBook keeps an org's durable, hash-chained ledger of those records — the settlement analogue of the SagaJournal — that verifys offline and reports per counterparty; settle_contract settles one contract and settle_saga settles every contract a saga ran under, straight from its journal (app.meter / app.settle / app.settle_saga / app.use_settlement_book). Closing the books also closes the reputation loop: a settled overrun or shortfall debits the seller, so reliability earned in delivery weights the next negotiation — see the settlement guide.
Cross-org workflow discovery & dynamic choreography	The next reach once cross-org sagas are negotiated, contracted, and settled: who runs each step, resolved at run time rather than wired by org id. A saga step declares the capability it needs (capability="transcription") and the engine resolves the participant at dispatch time from the governed AgentDirectory (app.choreograph(..., directory=)) — so a choreography binds the best-available counterparty for each step, never a hosted matching service. A CapabilityBinder ranks the candidates that advertise the capability: among those the directory's allow-list permits and that are reachable, it prefers the one whose ReputationLedger standing and prior SettlementBook record best fit the step's Contract (a regressing vendor is discounted without being singled out; ties break deterministically), and records the decision as a StepBinding on the saga journal (result.bindings). Discovery changes who, never how: every candidate's governed resolution is audited (agent_resolve), the binding lands on the coordinator's chain (choreography_bind), a capability no allowed, reachable candidate advertises is refused rather than dropped, and the bound step is contract-enforced, compensated at the org it was bound to, durable across a restart, and dispatched over the A2A fabric byte-for-byte the same as a statically-wired one — see the choreography guide.
Cross-org settlement netting & multilateral clearing	The reach once settlements are signed, reconciled, and reputation-closing: netting them. An org is often both a buyer and a seller across a web of contracts; net_settlements / net_books fold a fleet's many bilateral SettlementBook balances into a single minimal set of net obligations, so the books close once — a library-side clearing calculation, never a hosted clearing house or a payment rail. Each settled contract is a directed payable (the buyer owes the seller the agreed price for the scope); the directed obligations aggregate per pair, collapse to one BilateralNet figure per counterparty, and clear to the minimal set of NetObligation transfers — at most N − 1 for N parties, net-debtors paying net-creditors, deterministically. The resulting NettingSet is content-bound and offline-verifiable the way a record is: verify recomputes the netting hash from the bytes alone, confirms the **NetPosition**s balance to zero, and confirms the cleared transfers reproduce every position. Netting reads only signed, hash-chained records and asserts nothing it cannot recompute — a tampered source record is refused, and two books that disagree on a contract are pinpointed as a NettingDispute, excluded rather than silently absorbed (app.clear_settlements / book.net()) — see the settlement guide.
Cross-org dispute resolution & arbitration	The reach once a disagreement is pinpointed: resolving it. Each party submits its signed SettlementRecords for the disputed contract and the deterministic arbitrate (app.arbitrate / book.arbitrate) decides which figure stands — reading only the existing signed records and asserting nothing it cannot recompute, a library-side protocol, never a hosted arbitration service or a court of record. The decision rests on verifiable evidence: a reconciliation hash both the buyer and the seller signed (each on their own record, co-signing one figure exactly as reconcile describes) is mutually corroborated and upheld; a unilateral claim contradicting it is rejected and its claimant pinpointed; a single uncontested figure stands on its own; and when neither side's figure is corroborated the dispute is honestly left unresolved rather than decided by fiat. Unlike netting, which refuses to clear over a tampered book, arbitration is the venue where a bad claim is adjudicated: a tampered or forged claim is marked inadmissible and pinpointed (ClaimVerdict), never silently dropped. The resulting Resolution is content-bound and offline-verifiable the way a record is: verify recomputes the resolution hash from the bytes alone and re-derives the whole decision from the recorded claims, so a flipped verdict is caught even after re-sealing and two arbiters compute the same co-signable hash. A settled dispute also closes the reputation loop: the party whose claim did not stand is debited, so a bad-faith revision weights the next negotiation — see the settlement guide.
Performance	End-to-end streaming (astream + SSE) with incremental partial-JSON output and genuine provider token deltas, concurrent retrieval/memory/tool fan-out with cancellation propagation and hard latency deadlines, content-addressed compile/chunk/embedding caches, and zero-copy (slim) context packets. The compile hot path is single-pass and allocation-light: a vectorized candidate scorer (NumPy-optional, pure-Python fallback), a compiled-prompt render program and a warm candidate arena that reuse the stable prefix and prepared candidate set so a warm compile is dominated by scoring not allocation, streaming-first compilation that emits the prefix before scoring, speculative retrieval prefetch that warms the query embedding from the task classification, and a per-app resident-memory budget held by slim packets and evidence eviction. Quantized two-stage retrieval, a sub-millisecond warm compile, and a footprint regression gate — all held by CI-gated VincioBench performance budgets.
Cost & reliability (FinOps)	Production-traffic resilience in-process, not a proxy hop: batch execution at ~50% cost (OpenAI Batch + Anthropic Message Batches + Google/Vertex batch), circuit breaking + health-aware failover and key pooling with RPM+TPM rate limiting, runtime model cascades (start cheap, escalate on low confidence), cost attribution by tenant/feature with enforced budget SLOs (cap / degrade / queue-to-batch + cost.anomaly), provider-aware prompt caching with TTL choice and cache-hit telemetry, and incremental (content-hash) + sharded indexing at scale.
Provider/model rotation & swap regression	The migration safety net for the riskiest production change. A registry-backed Router picks the cheapest / fastest / least-busy capable model per request. A SwapGate replays golden traces and runs an eval + cost + latency + behavioral diff with statistical significance, PASS/FAILing the swap; model-swap regression swaps only the model and reports per-metric significance, the cost/latency trade, and the worst-regressed slices, with flake quarantine. A shadow provider and a capped canary qualify a candidate on live traffic with automatic rollback, and a lifecycle watcher proposes migrations off deprecated models.
Connectors	Pluggable data connectors — web, GitHub, SQL, S3, GCS, Notion, Confluence, Slack, Jira, Linear, Google Drive, SharePoint, Salesforce, Zendesk, BigQuery, Snowflake, plus custom via register_connector — feeding the document engine with full provenance: app.add_source("kb", connector=connect("github", repo="acme/handbook")). The REST connectors ride the core httpx dependency; all accept an injected client so they round-trip offline.
Plugins & ecosystem	An entry-point plugin contract (vincio plugins list) so third-party providers, embedders, stores, connectors, chunkers, rerankers, judges, metrics, and packs register themselves on install, gated by a versioned plugin API; a signed, allow-list-gated, audited CommunityRegistry of opt-in domain packs and SKILL.md bundles (content-bound SHA-256 + HMAC/Ed25519 signatures, resolution as an audited access decision); and an MCP-server marketplace bridge (app.add_mcp_from_registry) that discovers a server from a registry, governs reachability, and lands its tools in the permissioned runtime in one call.
Use-case coverage & verticals	Go from primitives to a working app in one file. Vertical packs (healthcare / ediscovery / kyc / customer_support / code_review) preconfigure retrieval, scoped memory, deterministic rails, domain metrics, a data-residency posture, and a golden eval set in one use_pack, on top of the existing pack contract. A higher-level Assistant layer over ContextApp threads turns into a session, carries multi-turn state via memory write-back, and gates write tools behind an approval — a chat product in a few lines. An end-to-end VoiceAgent wires a realtime session to the deep-research agent, the memory OS, and the rails, so a spoken assistant inherits the same grounding, budget, and audit guarantees. A cookbook of task-shaped recipes (contract redlining, incident triage, data-room Q&A, multimodal RAG over slides/PDFs) ships as runnable, offline-gated examples.
Integrations & DX	LangChain + LlamaIndex + Haystack + DSPy interop (vincio.interop) for tools, retrievers, loaders, embedders, components, and compiled DSPy modules — both directions, duck-typed from_* (no heavy import); hosted rerankers/embedders (Cohere/Jina/Voyage, httpx-only) behind build_reranker/build_embedder; opt-in domain packs (support, engineering, finance, legal) via app.use_pack(...); vincio init templates (rag/agent/eval) with a typed vincio.yaml JSON Schema for editor completion; notebook reprs (enable_rich_reprs) and an interactive vincio tui inspector.
Stability & guarantees	Semantic Versioning on a frozen public surface (vincio.__all__) with a mechanical deprecation policy (@deprecated / stability_of); published performance & quality SLOs held by at-least-as-strict VincioBench budgets; CycloneDX SBOM + SLSA build-provenance attestations on every release.
A trustworthy surface	The public API is held to the same bar as the internals. Every VincioError carries a stable .code, a .remediation hint, and a .docs_url from a completeness-gated, internationalizable error catalog. The package ships py.typed with a CI-enforced mypy --strict ladder, and a docstring-coverage gate keeps every public symbol documented. vincio.yaml files migrate forward automatically (vincio config migrate, in-memory upgrade on load), and vincio doctor reports any deprecated API a project still uses — its replacement and removal version straight from stability_of.

Every extension point — providers, metrics, chunkers, rerankers, judges, validators, tools — accepts your own implementation via a registry.

Benchmarks

VincioBench ships in benchmarks/ and runs fully offline (deterministic provider + deterministic metrics) so results are reproducible. Each family compares the Vincio pipeline against a naive baseline. Representative results on the bundled reference corpus:

Family	Metric	Vincio	Naive baseline
Context compression	evidence tokens for the same task	216	1,175 (stuff-everything)
	→ token reduction	−81.6%	—
Output recovery	malformed model outputs successfully parsed	5 / 5	3 / 5 (json.loads)
Security	prompt-injection detection rate	100%	—
	injection false-positive rate	0%	—
	PII coverage	100%	—
Containment	injection escalation rate (adversarial corpus)	0	—
Governance proof	invariants proven across their state space (containment · residency · budget · erasure)	4 / 4	—
Edge / WASM	edge compile vs server compile (same inputs) · resident footprint under cap at 10× corpus · native imports on the core path	byte-identical · held · 0	—
MCP Apps	server UI surfaced through AG-UI (provenance · budget-refused · audited) · elicited secret refused · spec-revision negotiated	pass	—
Negotiation	bargain terminates within budget · no-overlap ends in no-deal · contract verifies offline · tamper caught · regressor discounted · A2A parity	pass	unbounded haggle / unverifiable deal
Choreography	cross-org saga completes in order · failure compensates in reverse · contract breach compensates · journal resumes after restart · journal verifies offline · tamper caught · per-org chains	pass	dangling half-done transaction
Discovery	capability binds best-ranked allowed candidate · unlisted/unreachable never bound · no-candidate refused · binding audited · compensated at bound org · durable resume re-binds pending only · A2A parity	pass	discovery bypassing governance
Retrieval	recall@3 / MRR (known-answer corpus)	1.00 / 1.00	—
	per-mode recall@3 (sparse · late-interaction · PLAID · hybrid_full)	1.00 each	—
Memory	preference recall · contradiction supersede · tenant isolation	pass	—
Tools	runtime overhead, p50	0.02 ms	—
Agents	adversarial infinite-loop model	bounded (budget)	unbounded
Orchestration	crew over-budget termination · delegation recorded	pass	—
	graph interrupt→resume and fork-replay vs straight run	identical state	—
	plan repair recovers a tool failure / contradiction / budget shock	pass	restart / dead-end
	cost-aware action selection vs always-strong	−57%	always-strong
	parallel sub-graph speedup over serial (4 workers)	4.0×	1× (serial)
	durable timer survives restart → resumes when due	pass	timer lost
Evals	metric agreement on labeled examples	100%	—
	red-team detector coverage · guarded attack success	100% · 0%	naive target: 85% attacks succeed
	A/B significance (real shift detected / null ignored)	pass	—
Reliability	invalid output detected mid-stream → tokens saved	98%	0% (validate at end)
	self-correction recovery rate (bounded cycles)	3 / 3	—
	rail catch rate · false positives on clean text	100% · 0	—
	schema routing / classification accuracy	100%	—
Closed loop	loop promotion fires · deterministic · gates block regressions	pass	—
	grounded facts written · ungrounded excluded	pass	—
	Pareto front excludes dominated · knee balanced · learned budgets promote	pass	—
Cost & reliability	prompt-cache hit rate · cost-attribution accuracy	72% · 100%	—
	cascade savings vs always-strong (escalate on low confidence)	−70%	—
	canary auto-rolls-back under load → serves primary after	pass	serves the regression
Rotation & swap	router picks cheapest capable · capability guard skips incapable failover	pass	routes to incapable/pricier
	swap gate blocks a regression · passes a safe swap (significance)	pass	swap on one noisy run
Governance	card/AI-BOM completeness · framework-mapping coverage	pass · 79%	—
	erasure correctness (removed = lineage) · audited · proof verifies	pass	—
	multilingual PII recall · RAG-poisoning detection (FP rate)	100% · 100% (0%)	English-only

Honest by design. These numbers come from a small, synthetic offline corpus and are meant to demonstrate the mechanisms, not to be quoted as universal gains. The context-compression hypothesis (a 20–40% reduction target) is measured per run, and VincioBench reports whether it was met on your data. Run python benchmarks/vinciobench.py against your own corpus — and trust only what that prints. See benchmarks/README.md.

How Vincio compares

Each ecosystem below is broad and capable in its own focus area. The table reflects built-in, in-library capabilities — not what is reachable by bolting on a separate product or SaaS.

Capability	Vincio	LangChain	LlamaIndex	DSPy	Ragas
Scored, budgeted context compiler	✅	➖	➖	❌	❌
Typed prompt AST + lint + cache layout	✅	❌	❌	➖	❌
Hybrid (BM25 + dense) RAG	✅	✅	✅	❌	❌
Sparse + late-interaction + GraphRAG in one fusion	✅	➖	➖	❌	❌
Layered memory (decay, conflicts, scopes, bi-temporal)	✅	➖	➖	❌	❌
Permissioned tool registry (RBAC/ABAC)	✅	❌	❌	❌	❌
Bounded agents + deterministic workflows	✅	✅	➖	➖	❌
Durable graphs (checkpoint / resume / time-travel) + bounded crews	✅	➖	❌	❌	❌
Structured output + structure-only repair	✅	➖	➖	✅	❌
Built-in evals + CI gates	✅	➖	➖	➖	✅
pytest assertions + red-teaming + synthetic data	✅	❌	❌	❌	➖
Eval-driven optimization (gated promotion)	✅	❌	❌	✅	❌
Native tracing + cost, no account needed	✅	➖	➖	❌	❌
Sessions, feedback, prompt registry, trace viewer in-process	✅	➖	❌	❌	❌
Deterministic security (PII / injection / audit)	✅	❌	❌	❌	❌
MCP client and server + A2A + Agent Skills	✅	➖	➖	➖	❌
In-process FinOps: batch · circuit-break · cascades · cost attribution + budgets	✅	❌	❌	❌	❌
Capability-aware rotation + gated swap regression	✅	➖	❌	❌	❌
Governance evidence: cards · framework mapping · AI-BOM · provable erasure · residency	✅	❌	❌	❌	❌

_{✅ first-class in-library · ➖ partial or via a separate add-on/SaaS · ❌ not a focus. Ecosystems evolve. Vincio is built to interoperate — it speaks MCP (client and server), A2A, and Agent Skills in-process, vincio.interop brings LangChain, LlamaIndex, Haystack, and DSPy tools, retrievers, loaders, embedders, components, and compiled modules in (and hands Vincio's back), first-party connectors and an entry-point plugin system meet your data and tools where they live, and you can point at any OpenAI-compatible model and the vector store you already run. See the migration guides, the integrations guide, and the in-depth write-ups in docs/comparisons/.}

Use cases

You want to…	Reach for	Example
Classify and route support tickets into typed labels	typed output	01_support_triage.py
Answer questions over your docs with real citations	hybrid RAG + grounding policy	02_document_qa.py
Review contracts clause-by-clause	end-to-end context app	03_contract_review.py
Extract structured fields from invoices	structured extraction + F1 eval	04_invoice_extraction.py
Build a research agent with bounded budgets	ReAct agent + tools	05_research_agent.py
Automate a CRM agent with approval-gated writes	memory + permissioned tools	06_crm_agent.py
Ask questions over a codebase	code-aware chunking + import graph	07_codebase_qa.py
Analyze spreadsheets with schema awareness	table chunking + quality checks	08_spreadsheet_analysis.py
Gate quality in CI	datasets, gates, baseline diff	09_eval_pipeline.py
Tune prompts/context against an eval suite	optimization + gated promotion	10_optimization_run.py
Stream answers token-by-token through the full pipeline	astream + partial-JSON + compile caches	11_streaming_performance.py
Push retrieval quality with the full toolkit	sparse+late-interaction fusion, HyDE, auto-merge, GraphRAG, connectors	12_advanced_rag.py
Personalize an app with governed memory	scoped remember/recall, consolidation, hygiene, memory evals	13_memory_personalization.py
Evaluate, test, and observe without a platform	quality metrics, synthetic data, red-teaming, experiments, prompt registry, sessions + trace viewer	14_evaluation_observability.py
Run a multi-agent team with roles and delegation	crews + shared blackboard + budget guarantees	15_multi_agent_crew.py
Build an interruptible, auditable, resumable process	durable graphs + human gates + time-travel	16_durable_graph.py
Guarantee output shape and guard every generation	signatures, constrained decoding, streaming validation, rails, self-correction, schema routing	17_reliable_structured_output.py
Improve the app from its own production traffic	the closed loop: traces→dataset→eval→optimize→promote, auto-memory, retrieval feedback, Pareto, learned budgets	18_closed_loop.py
Reuse LangChain/LlamaIndex assets and any OpenAI-compatible model	framework interop + provider/vector-store breadth	19_framework_interop.py
Configure an app for a domain in one line	opt-in domain packs (support/engineering/finance/legal)	20_domain_pack.py
Govern PII, injection, access, and audit integrity	deterministic security primitives + tamper-evident audit	21_security_governance.py
Use MCP servers as tools/resources, or expose your app as one	MCP client + server	22_mcp_tools_and_resources.py
Surface a server's UI and govern a mid-call input request	MCP Apps over AG-UI + elicitation gated by approval + rails	66_mcp_apps_and_elicitation.py
Negotiate a price/SLA/scope contract between agents	bounded negotiation + signed contract + reputation-weighted, over A2A	67_agent_negotiation_and_contracting.py
Run a durable, compensating workflow across organizations	cross-org saga + reverse-order compensation + restart-survivable journal, over A2A	68_cross_org_workflow_choreography.py
Bind the best counterparty for a saga step at run time	capability discovery over the governed directory, reputation/settlement-ranked, governance-preserving	70_cross_org_workflow_discovery.py
Resolve a cross-org dispute over which figure stands	deterministic arbitration over signed records — co-signed upheld, contradicting claim rejected, content-bound Resolution verifies offline	72_cross_org_dispute_arbitration.py
Expose a crew over A2A and delegate across vendor agents	A2A agent card + task lifecycle + remote delegate	23_a2a_delegation.py
Drop in portable SKILL.md knowledge with budgeting	Agent Skills + progressive disclosure	24_agent_skills.py
Control reasoning effort across providers with honest cost	unified reasoning control + Responses API	25_reasoning_control.py
Score agents over their trajectory and live traffic	trajectory & tool-use metrics, multi-turn simulator, online eval + drift, annotation, A/B	26_agentic_eval.py
Survive outages and account for every dollar at scale	batch execution, circuit breaking + failover, key pooling, model cascades, cost attribution + budgets, prompt caching, sharded indexing	27_cost_and_reliability.py
Optimize prompts reflectively and distill traces into a cheaper model	GEPA/MIPRO reflective optimizer, distillation flywheel, learned compression, optimizer-judge calibration	28_reflective_optimization.py
Shrink embeddings, retrieve across text+image, and add stores	Matryoshka truncation, contextual & multimodal embedders, new vector stores, layout-aware extraction, voice/realtime	29_multimodal_retrieval.py
Generate compliance evidence and satisfy a data-erasure request	model/system cards, framework mapping, AI-BOM, lineage + erasure, residency, multilingual PII	30_governance_compliance.py
Prove the governance invariants hold ahead of any run	app.verify_governance / GovernanceVerifier — bounded model checking of containment/residency/budget/erasure with a minimal counterexample on violation	63_governance_invariant_verification.py
Enforce the honest, fast spine	hard budgets, the ModelRegistry, semantic scoring, cancellation, significance-gated promotion + replay	31_honest_fast_spine.py
Rotate providers/models safely	router, SwapGate, swap regression with quarantine, shadow + canary, lifecycle migrations	32_swap_regression.py
Let documents and images flow out under the same guarantees	DocumentBuilder + DocumentContract, CitedReportBuilder, redlines, image/TTS with C2PA, richer inputs, EU AI Act pack	33_documents_and_media_out.py
Run a self-improving loop with agentic capabilities	online controller, GEPA reflector, experiment proposer, golden non-regression guard, deep-research agent, memory OS, computer-use + isolation	34_self_improving_loop_and_agents.py
Work with the multimodal-native packet and capability facades	facades, multimodal packet + cross-process materialize, structured FilterSpec pushdown + tenant scope, typed event catalog, enterprise endpoints, egress DLP + signed audit chain	35_multimodal_packet_and_facades.py
Scale out across workers, train a cheaper model, and serve a dashboard	distributed durable execution (lease/CAS + worker pool + Send map-reduce), swap-gated distillation, served observability + burn-rate alerting, quantized two-stage retrieval, in-process GGUF	36_distributed_scale_and_finetune.py
Score on the leaderboards, govern a fabric, and stream a UI	stateful-environment eval with a task-success oracle, the nine benchmark adapters, retrieval-eval + index regression, the AgentDirectory under an AllowListGate, AG-UI streaming	37_benchmarks_and_agent_fabric.py
Run continual self-improvement and prove a data-erasure request	one SelfImprovementPolicy (streaming proposal→meta→canary→promote/rollback), canary-gated app.deploy, signed & verifiable ErasureProof, a GDPR ConsentLedger, bi-temporal memory	38_self_improvement_and_erasure.py
Plan deeper, recover from failure, and schedule fairly at scale	HTN hierarchical planning, in-place plan repair, cost-aware action selection, parallel sub-graph scheduling, durable timers	40_orchestrator_planner_depth.py
Meet teams where their data and tools live	first-party connectors (Jira/Linear/Drive/SharePoint/Salesforce/Zendesk/BigQuery/Snowflake), the entry-point plugin system, a signed community pack/skill registry, Haystack + DSPy interop, the MCP-server marketplace bridge	41_ecosystem_and_integration.py
Configure a regulated domain in one line	full-stack vertical packs (healthcare/e-discovery/KYC-AML/support/code-review) with retrieval, memory, rails, metrics, residency, and a golden set	42_vertical_packs.py
Build a multi-turn chat product	the Assistant — session threading, memory write-back, tool approvals	43_assistant.py
Ship a grounded, guarded voice assistant	the VoiceAgent — realtime wired to deep research, the memory OS, and rails	44_voice_agent.py
Follow a task-shaped recipe	the cookbook — contract redlining, incident triage, data-room Q&A, multimodal RAG over slides/PDFs	45 · 46 · 47 · 48
Spend test-time compute where it pays off	the ReasoningController (auto effort under a hard token ceiling), reasoning-trace caching, and verifier-guided TestTimeSearch (best-of-N / self-consistency / beam) with early-exit	53_test_time_compute.py

All examples in examples/ run fully offline with no API keys. Point them at a real model with environment variables:

export VINCIO_PROVIDER=openai VINCIO_MODEL=gpt-5.2-mini OPENAI_API_KEY=sk-...
cd examples && python 02_document_qa.py

Command line

vincio init my-project --template rag  # scaffold config + app + golden set (minimal|rag|agent|eval)
vincio config schema --output vincio.schema.json  # typed JSON Schema for editor completion
vincio config migrate            # upgrade vincio.yaml to the current schema (--check for CI)
vincio doctor                    # report deprecated-API usage and config schema drift
vincio packs list                # opt-in domain packs (support/engineering/finance/legal)
vincio tui                       # interactive inspector for runs, traces, and memory
vincio run app.py --input "..."  # run an app
vincio eval run golden.jsonl     # run an eval suite (with CI gates and baseline compare)
vincio eval dataset golden.jsonl --min-feedback 0.5  # curate traces into a dataset
vincio prompt lint prompts/      # lint prompt specs
vincio prompt push prompts/support.yaml --tag production  # version a prompt
vincio trace view trace_123      # TUI trace tree with scores + feedback
vincio trace export trace_123    # self-contained static HTML (also --session)
vincio trace diff a b --html diff.html  # visual side-by-side diff
vincio optimize run --target groundedness
vincio optimize reflective --app app.py --dataset golden.jsonl  # GEPA-style reflective optimization
vincio loop run --app app.py --min-feedback 0.5 --gate groundedness=">= 0.8"  # one closed-loop cycle
vincio distill --traces-dir .vincio/traces --output train.jsonl  # grounded fine-tuning JSONL
vincio index build ./docs        # build a retrieval index
vincio memory recall "answer style" --user u1  # scored hybrid recall
vincio audit verify              # verify the audit-log hash chain offline
vincio mcp serve app.py          # expose an app as an MCP server (stdio)
vincio serve --app app.py        # launch the HTTP API (health/readiness/metrics)

A FastAPI server (API-key + JWT auth, real-token SSE streaming, /v1/health/ready and Prometheus /v1/metrics) is launched with vincio serve --app app.py or built with from vincio.server import create_app — see docs/reference/api.md. For horizontal scale, point your process manager at it and configure server.redis_url so rate-limit and idempotency state stays coherent across workers.

Architecture

                         ┌──────────────────────────────────────────────┐
   user input  ─────────▶│  Input engine   normalize · classify · scope  │
                         └───────────────┬──────────────────────────────┘
                                         ▼
        ┌──────────────┐        ┌────────────────┐        ┌──────────────┐
        │   Memory     │───────▶│    CONTEXT     │◀───────│  Retrieval   │
        │  L0…L5       │        │   COMPILER     │        │  hybrid RAG  │
        └──────────────┘        │ score·dedupe·  │        └──────────────┘
        ┌──────────────┐        │ conflict·      │        ┌──────────────┐
        │    Tools     │───────▶│ compress·budget│◀───────│   Prompt     │
        │ permissioned │        └───────┬────────┘        │  compiler    │
        └──────────────┘                ▼                 └──────────────┘
                              ┌────────────────────┐
                              │   Model execution  │   provider-neutral
                              └─────────┬──────────┘
                                        ▼
                    ┌─────────────────────────────────────────┐
                    │ Output validation · Evals · Security ·   │
                    │ Trace + cost · Memory write-back         │
                    └─────────────────────────────────────────┘

The public surface is organized into lazy capability facades (app.runs / .knowledge / .governance / .optimization / .serving / .training) over async-first stores and a typed, versioned event catalog. See AGENTS.md for the package layout and docs/concepts/ for a tour of each engine.

Roadmap

Every subsystem above is implemented, tested offline, documented, and demonstrated by a runnable example. The public API is frozen under Semantic Versioning with a mechanical deprecation policy; performance and quality targets are published as SLOs and gated by VincioBench; the threat model is documented with offline audit-chain verification and a resource-limited tool sandbox; and releases ship a CycloneDX SBOM with SLSA provenance attestations.

New capabilities are added without breaking working code: each one sits behind a new entry point or an opt-in extra. Vincio adopts the ecosystem's standards — the MCP, A2A, and Agent Skills protocols, and the OWASP LLM / OWASP Agentic / NIST AI RMF / MITRE ATLAS governance frameworks — in your process; it never becomes a hosted service to do so.

See ROADMAP.md for what ships today, what is planned next, and what is intentionally out of scope.

Vincio is, and stays, a library. The building blocks for production operation (audit chain, retention, tenant isolation, RBAC/ABAC, a server) ship in the package for you to deploy on your own infrastructure. Hosted services and managed control planes are not part of this project.

Documentation

• Getting started — install, your first app, offline development
• Concepts — context packets · prompt compiler · memory · retrieval · agents & workflows · evaluation · observability
• Guides — build a RAG app · build a chat product (the Assistant) · vertical packs · cookbook recipes · connect data sources · extend with plugins · structured output · generate documents & media · video understanding & generation · reliability & guardrails · add tools · orchestrate multi-agent systems · run evals · test LLM apps · optimize · close the loop · performance & streaming · edge / WASM runtime · cost, reliability & scale · integrations
• Agentic evaluation & continuous quality — trajectory metrics, simulator, online eval, drift & annotation
• Protocols & interoperability — MCP client + server · A2A agent-to-agent · Agent Skills · reasoning control & Responses API · voice & realtime
• Migrating — coming from LangChain · LlamaIndex · Ragas · Mem0
• Reference — API · API index · CLI · config · errors · typing · API stability & deprecation policy · performance & quality SLOs
• Security & governance — threat model · security policy · governance & compliance · differential privacy
• Comparisons — LangChain · LlamaIndex · RAGatouille · Mem0 · CrewAI · OpenAI Agents SDK · DSPy · Pydantic AI · Guardrails AI · NeMo Guardrails · Ragas · LiteLLM / gateways

Contributing

Contributions are welcome. The test suite runs fully offline and must stay green:

pip install -e ".[dev]"
python -m pytest tests/ -q     # 1929 tests, no network or API keys required
ruff check vincio/ tests/
mypy vincio

See AGENTS.md for the codebase layout and engineering conventions.

License

Apache License 2.0 © Vincio Contributors.