vincio 5.6.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, pgvector, …)
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

Three suites ship in benchmarks/, all reproducible on your own machine. Every number is measured live from both sides; a missing competitor is reported as skipped, never assumed.

Head-to-head vs. real libraries

competitive.py runs Vincio against the actual library a team would otherwise use (Apple Silicon, Python 3.13; ratios are the portable signal, not wall-clock).

Orchestrator uplift: the same model, through Vincio

quality_uplift.py measures what routing a model through Vincio adds versus calling it directly, against real models on 15 company-specific policy questions a model cannot know from pretraining (4 models × 3 runs = 360 live calls, OpenRouter, June 2026).

VincioBench: the internal regression suite

vinciobench.py is not a competitive claim: it is the deterministic mechanism suite that gates CI. 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 two sections above.

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

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

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

2 · Feature tours — one program per subsystem

Twenty-three complete, heavily-commented programs; each runs offline and teaches a whole theme end to end. 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 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 on the 5.x surface. 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 forward plan — a scheduled data & analytics extension line (real-time shipped; federated, forecasting/causal verifiers, notebook-native next) — is in ROADMAP.md; upgrades 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 · 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          # 6421 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.