vincio 7.7.0

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

Vincio is a Python platform for building AI applications that you can trust in production. It takes everything that goes into a model (prompts, memory, retrieved evidence, tools, schemas, and policies) and compiles it into an optimized, validated, observable context packet; then it checks, measures, and traces everything that comes out. Named for Leonardo da Vinci, it pairs engineering and craft in equal measure.

Most libraries help you call a model. Vincio governs the boundary between your application and the model: what evidence is selected, how it is scored and budgeted, how the result is validated, and what it cost. It runs on your model of choice across every major provider, with batching, caching, failover, and cost tracking built in.

Try it in 30 seconds, no install: open the quickstart notebook in Google Colab — one pip install, runs offline on the bundled mock provider, no API key required.

Contents

Install · Quickstart · The one-line front door · What you can build · Providers · Features · Benchmarks · How Vincio compares · Examples · CLI · Architecture · Docs

Install

pip install vincio                  # core (dependency-light: 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, postgres, …)
pip install "vincio[server]"        # + the FastAPI server (vincio serve)
pip install "vincio[all]"           # every optional integration

Python 3.11+. Every heavy integration (vector stores, OCR, server, OpenTelemetry, charts, …) is an opt-in extra; the core stays small and runs offline.

Quickstart

from vincio import ContextApp

# Configure a provider (the default is OpenAI — set a provider + key, or pass one explicitly).
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?")
print(result.output)      # the grounded answer
print(result.citations)   # the evidence it actually cited
print(result.trace_id)    # every run produces a full trace
print(result.cost_usd)    # …and a cost

Run it offline — no key, no network. Pass the bundled deterministic mock; it auto-generates schema-valid output, so the whole pipeline runs in dev and CI for real:

from vincio.providers import MockProvider
app = ContextApp(name="docs_qa", provider=MockProvider(), model="mock-1")

Set VINCIO_PROVIDER + the matching key in the environment (or pass provider=/model=) to point the same code at OpenAI, Anthropic, Google, Mistral, a local model, or any OpenAI-compatible gateway.

The one-line front door

For the five jobs you reach for most, the vincio.tasks namespace is one expression each — a task-shaped constructor with sane governed defaults that lowers to the exact same governed run as the verbose builder path (retrieval, grounding, validation, rails, budgets, tracing, and the audit chain all apply unchanged). .app is the escape hatch to every deep method.

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

rag("./docs").ask("How do I configure SSO?")          # grounded RAG Q&A, cited and eval-scored
extractor(Ticket).extract("I was charged twice")      # typed structured extraction
tool_agent(writes=[create_ticket]).run(task)          # an approval-gated tool agent
evaluation(dataset, gates={"groundedness": ">= 0.8"}).run()   # an offline eval
chat().send("What's my refund window?")               # a multi-turn assistant

# …or thread the whole pipeline fluently — the Vincio answer to LCEL:
Flow(provider=p, model=m).retrieve("./docs").ground().evaluate("groundedness").run(question)

These are @experimental while their shape settles. See examples/00_one_liners.py and the ergonomic-surface concept for how each one-liner maps to the deep methods it composes.

What you can build

Typed output you can rely on: declare a Pydantic schema, get a validated instance back:

from pydantic import BaseModel
from vincio import ContextApp
from vincio.providers import MockProvider

class Triage(BaseModel):
    label: str
    confidence: float

# (provider=MockProvider() runs this offline; use a real provider in production)
app = ContextApp(name="triage", provider=MockProvider(), model="mock-1", output_schema=Triage)
app.run("The dashboard crashes after login").output.label   # → a validated Triage

Agents with tools, memory, and hard budgets: permissioned tools, approval-gated writes, and a loop that cannot run away:

app = ContextApp(name="support", output_schema=RefundDecision)
app.add_memory(scope="user", strategy="semantic")
app.add_tool(lookup_order, permissions=["orders:read"])
app.add_tool(issue_refund, permissions=["refunds:write"], approval_required=True)
app.run("Refund my duplicate charge")

A real backend service you can copy: examples/applications/ ships a FastAPI grounded-RAG service, a ticket-triage API, a structured-extraction service, and a CLI research agent — each runnable fully offline. See Examples.

Providers & models

Vincio calls real models in production. One interface routes to every major provider, with the model-operations layer (reasoning control, half-cost batch, caching, failover, cost tracking) built in. The deterministic mock is a development convenience, not the product: pass it to build and test the whole pipeline with no key and no cost before you point it at a real model.

# point an app at a real model (or set VINCIO_PROVIDER / the API key in the environment)
app = ContextApp(name="docs_qa", provider="openai", model="gpt-4o-mini")

Features

Everything below is implemented, tested offline, and demonstrated by a runnable example. Use the high-level ContextApp, or reach for any engine directly.

Benchmarks

Vincio's benchmark platform has three tracks under one honesty contract: every number carries a provenance tier that says, structurally, how real it is — so you never have to guess whether a figure is LIVE, STATIC/FABRICATED, or a self-measurement. One command drives all three: vincio bench model | uplift | feature. The map is benchmarks/PROVENANCE.md; the machine-readable source of truth is benchmarks/manifest.json.

Every track supports LIVE (the real thing runs end to end) and an offline MOCKUP. Tiers: L Live (a live model, or the real competitor library on this machine — reported, never gated), R Recorded (a hash-pinned replay, gates CI), S Static/Mockup (offline, reproducible, gates CI — model scores saturate by design). A lower tier can never print a higher tier's label. A separate internal VincioBench gate keeps the library's own mechanisms honest and CI-gates the deterministic core of all three tracks.

Track 1 — Model: public benchmarks, tier-honest

vincio bench model scores a model (or a model version) on the standard public benchmarks — one pluggable contract, 29 benchmarks across 10 niches, an enforced provenance tier on every number. In-process, offline-first, never a hosted leaderboard.

vincio bench list                                   # the whole platform at a glance
vincio bench model all --tier static                # every benchmark, offline (Tier-S), gates CI
python benchmarks/eval_live.py --provider anthropic --model claude-opus-4-8 \
    --benchmarks knowledge.mmlu reasoning.gsm8k --tier live --dataset-dir ./datasets

Run live over real official dataset slices (OpenRouter, 2026-07-01, small n — a capability demo, reported not gated): gpt-5.4-mini scored 0.90 on a 20-item GSM8K slice and 0.60 on a 15-item MMLU slice; gemini-3.5-flash 0.70 / 0.93. The engine refuses to let a fabricated fixture print a Recorded or Live label — a Tier-S mechanism check can never masquerade as a Tier-L score. Concept: docs/concepts/open-evaluation-plane.md; guide: docs/guides/run-benchmark-suite.md.

Track 3 — Feature: a Vincio feature vs a competitor library _{· run vincio bench feature}

vincio bench feature runs a Vincio feature head-to-head against the actual competitor library a team would otherwise use — measured live on this machine across retrieval, tokenization, output repair, prompt safety, tabular encoding, context assembly, layered memory, and chunking. A missing competitor is reported skipped, never fabricated; the deterministic quality metric (not wall-clock) gates CI. Representative real results (Apple Silicon, Python 3.13; ratios are the portable signal): Vincio BM25 retrieval matches rank_bm25's recall at ~12× the speed; layered memory returns the current fact after a contradicting update at precision 1.0 vs 0.5 for a naive keyword store; tabular encoding uses ~70% fewer tokens than json.dumps. The richer offline driver with a few extra micro-benchmarks is competitive.py.

Track 2 — Uplift: the same model, through Vincio vs direct _{· run vincio bench uplift}

vincio bench uplift runs each benchmark twice by the identical scorer — the model's direct answer vs its Vincio-routed answer — and reports the per-benchmark delta (grounding, injection containment, long-context needle recall, output validity); the mockup deltas gate CI. The extended live-model driver quality_uplift.py measures the same on real models across 15 company-specific policy questions a model cannot know from pretraining. Measured live against current state-of-the-art models (4 models × 2 runs = 240 live calls, OpenRouter, July 2026):

VincioBench: the internal gate _{· not one of the three tracks}

vinciobench.py is not a competitive claim and not one of the three tracks: it is the deterministic mechanism / regression gate that gates CI, and it also gates the deterministic core of all three tracks (families.bench_tracks.*). Its families assert that each engine still works on a bundled synthetic corpus, so a regression fails the build. The scores saturate by design (a small corpus built to exercise each mechanism), which proves the mechanism is intact, not real-world performance. The credible performance evidence is the three tracks above at their Live tier (Track 1/2 with a model key, Track 3 with a real competitor installed).

How Vincio compares

Each ecosystem below is strong in its focus area. This reflects built-in, in-library capability, not what's reachable by adding a separate product or SaaS.

Examples

A three-tier on-ramp in examples/ — start in the browser, learn each subsystem, then copy a real backend. Every tier runs fully offline on the bundled mock and points at a real model with one env var; each is gated in CI so it can never drift.

1 · Notebooks — start in the browser

Six Google Colab-ready notebooks (examples/notebooks/), one pip install and no setup:

Notebook	Open in Colab
Quickstart
RAG
Agents & tools
Evaluation
Data analysis
Notebook-native analysis

2 · Feature tours — one program per subsystem

Twenty complete, heavily-commented programs (00–20); each runs offline and teaches a whole theme end to end — the entire data & analytics plane is one tour (13). Highlights (full index in examples/README.md):

3 · Applications — real-world backends

Small, production-shaped apps to copy (examples/applications/): a FastAPI grounded-RAG service, a ticket-triage API (typed output + scoped memory + an approval-gated tool), a structured-extraction service (self-correcting), and a no-framework CLI research agent. Each FastAPI app splits an offline-testable core.py from a thin FastAPI main.py.

cd examples && python 01_quickstart.py            # offline, no keys
export VINCIO_PROVIDER=openai OPENAI_API_KEY=sk-... && python 01_quickstart.py   # against a real model
pip install "vincio[server]" && cd examples/applications/rag_service && uvicorn main:app --reload

Command line

vincio init my-project --template rag   # scaffold config + app + golden set
vincio run app.py --input "..."         # run an app
vincio eval run golden.jsonl            # run an eval suite with CI gates + baseline compare
vincio bench list                       # the benchmark platform: model / uplift / feature tracks
vincio bench feature                    # a Vincio feature vs a competitor library (LIVE)
vincio bench model knowledge.mmlu       # a model on a public benchmark, tier-honest, offline
vincio trace view trace_123             # TUI trace tree with scores + feedback
vincio loop run --app app.py --gate groundedness=">= 0.8"   # one closed-loop cycle
vincio docs check                       # gate the docs graph (links, coverage, llms.txt freshness)
vincio audit verify                     # verify the audit-log hash chain offline
vincio mcp serve app.py                 # expose an app as an MCP server
vincio serve --app app.py               # launch the HTTP API (health/readiness/metrics)

The full CLI is in the CLI reference. vincio serve launches a FastAPI server (API-key + JWT auth, SSE streaming, Prometheus metrics); from vincio.server import create_app embeds it.

Architecture

One coherent pipeline from raw input to traced, validated result: the input engine normalizes and scopes the request; memory, retrieval, tools, and the prompt compiler all feed the context compiler, which scores, deduplicates, resolves conflicts, compresses, and budgets; the model runs provider-neutral; and every output is validated, evaluated, secured, traced, costed, and written back to memory.

See AGENTS.md for the package layout and docs/concepts/ for a tour of each engine.

Status

Vincio is feature-complete and in long-term support. 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; releases ship a CycloneDX SBOM with SLSA provenance. New capabilities are added behind opt-in extras, never by breaking working code. The ROADMAP.md records what ships today, and upgrade notes are in MIGRATION.md.

Vincio is, and stays, a library. The building blocks for production (audit chain, retention, tenant isolation, RBAC/ABAC, a server) ship in the package for you to deploy on your own infrastructure. There is no hosted service.

Documentation

The documentation index maps every guide, concept, and reference page in a reading order; the learning path is a staged route from your first app to the full platform. Highlights:

• Getting started: install, your first app, offline development
• Concepts: context packets · prompt compiler · memory · retrieval · context anchors · agents & workflows · evaluation · observability
• Guides: build a RAG app · structured output · add tools · analyze data · orchestrate multi-agent systems · run evals · close the loop · performance & streaming · integrations
• Protocols: MCP client + server · A2A · Agent Skills · reasoning control
• Migrating: from LangChain · LlamaIndex · Ragas
• Security & governance: threat model · security policy · governance & compliance
• Reference: API · capability map · CLI · config · SLOs · stability & deprecation
• Comparisons: LangChain · LlamaIndex · DSPy · CrewAI · Ragas · and more

Contributing

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

pip install -e ".[dev]"
python -m pytest -q          # the full offline suite — 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.