vincio 7.10.0

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 output is validated, and what it cost. It compiles everything that goes into a model (prompts, memory, retrieved evidence, tools, schemas, policies) into an optimized, provenance-aware context packet, then checks, measures, and traces everything that comes out. Named for Leonardo da Vinci — engineering and craft in equal measure.

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

Contents · Install · Quickstart · One-line front door · Providers · Features · Live performance · How it 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

app = ContextApp(name="docs_qa", provider="openai", model="gpt-4o-mini")
app.add_source("docs", path="./docs", retrieval="hybrid")   # index a folder
app.set_policy("answer_only_from_sources", True)            # ground answers in evidence

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

Run the whole pipeline offline — no key, no network. Pass the bundled deterministic mock; it auto-generates schema-valid output, so retrieval, validation, evals, traces, and cost all run 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, vincio.tasks is one expression each — a task-shaped constructor with 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, cited, eval-scored RAG
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 with CI gates
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)

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

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

app = ContextApp(name="triage", provider=MockProvider(), model="mock-1", output_schema=Triage)
app.run("The dashboard crashes after login").output.label   # → a validated Triage

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")

Providers & models

Vincio calls real models in production. One ModelProvider 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 — pass it to build and test the whole pipeline with no key and no cost, then point the same code at a real model.

Features

One governed runtime, nine layers. Use the high-level ContextApp, or reach for any of 559 public symbols directly under one frozen API contract.

Live performance

Vincio's claims are measured, not asserted — and the numbers below are all live. The feature head-to-head runs on your machine against the real competitor library; the model uplift is a dated run against real models. Honest losses are shown too: where a specialist wins, we say so.

Feature vs. the library you'd otherwise reach for — reproduce with one command, python benchmarks/bench.py feature, which runs against whatever competitor libraries are installed (a missing one is reported skipped, never fabricated):

The same model, called directly vs. routed through Vincio — on private-knowledge questions a model cannot answer from pretraining, retrieval + grounding turn a near-useless direct call (which either abstains or hallucinates) into a cited, correct answer at a fraction of the cost per correct answer:

Reasoning quality is measured separately from retrieval quality. On a small, reviewed Tier-L set, the non-reasoning Llama 3.2 3B model moved from 0/4 direct to 3/4 through Vincio: all three stable math/logic/multi-step answers passed deterministic verification; on the current-fact case Vincio verified two web snapshots but withheld the model's unsupported final claim instead of counting the refusal as correct. A companion model-native routing run classified 5/5 Spanish, Japanese, Arabic, Swahili and Chinese requests correctly for language, task/depth and web intent. Sample sizes are deliberately shown:

Reproduce the two arms with benchmarks/reasoning_uplift_live.py and benchmarks/reasoning_multilingual_live.py. The dated, machine-readable summary is in benchmarks/reference/live_snapshot.json.

Two more dated live runs (reproduce with the script in each): LAGER reaches a multi-hop bridge that shares zero words with the query — 100% vs classic top-k RAG's 75% at ~8× fewer input tokens/call (benchmarks/lager_uplift_live.py). Context anchors hold a globally-binding rule that pure per-query RAG drops — 100% vs 50% at ~3× fewer tokens than pasting every file (benchmarks/rag_anchor_uplift_live.py). Web search answers post-cutoff facts the model gets wrong — 2/3 fresh vs 0/3 direct (benchmarks/web_uplift_live.py).

vincio bench feature          # a Vincio feature vs a competitor library — LIVE, on your machine
vincio bench uplift           # the same model, Vincio-routed vs direct (live with a key; Tier-S offline)
vincio bench model mmlu       # a model on a public benchmark (29 across 10 niches)

How Vincio compares

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

Ecosystems evolve, and Vincio is built to interoperate: vincio.interop brings LangChain, LlamaIndex, Haystack, and DSPy assets in (and hands Vincio's back). In-depth write-ups in docs/comparisons/.

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.

• Notebooks — six Colab-ready notebooks, one pip install, no setup: Quickstart · RAG · Agents · Evaluation · Data analysis
• Feature tours — one focused, runnable program per subsystem, each a syntax-and-best-practice walkthrough (quickstart, retrieval, memory, agents, structured output, evaluation, security & governance, the data plane, LAGER, context anchors, and more). Full index in examples/README.md.
• Applications — production-shaped backends to copy: a FastAPI grounded-RAG service, a ticket-triage API, a structured-extraction service, and a no-framework CLI research agent.

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 feature                    # a Vincio feature vs a competitor library — LIVE
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 web search "…"                   # governed web search / read / crawl
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 (27 command groups) 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 (API_VERSION 5.0, decoupled from the release version) 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. 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.

• Start — getting started · context packets · the prompt & context compiler
• Build — RAG app · structured output · add tools · memory · context anchors · LAGER · web search
• Evaluate & improve — run evals · benchmark suite · close the loop · performance
• Orchestrate & interop — orchestrate agents · MCP · A2A · Agent Skills
• Data & analytics — analyze data · the data plane concepts
• Secure & govern — threat model · security policy · governance & compliance · verified reasoning
• Reference — API · capability map · CLI · config · SLOs · stability
• Migrating — from LangChain · LlamaIndex · Ragas · Mem0

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, TESTING.md for the testing model, and CONTRIBUTING.md for the workflow.

License

Apache License 2.0 © Vincio Contributors.