Example Projects

Five complete, runnable projects live in the public tuvl-io/examples repository. Each was built from a project-specification.md in its directory, passes tuvl validate with zero warnings, and runs with tuvl dev — clone one, point it at your Postgres, and make it yours.

Project	Difficulty	What it demonstrates
invoice-extraction-api	Easy	Raw invoice text → validated Postgres records: one Agent step with typed JSON output, a deterministic totals check, enum currencies, a secure tax id
knowledge-base-qa	Easy–Medium	RAG on the built-in rails — DataIngest/DataSearch over pgvector, cited answers, zero custom Python, a @tuvl/client demo script
content-moderation-pipeline	Medium	LLM classification, deterministic match: region routing, and group-gated human review — the submitter cannot approve their own content
mcp-research-agent	Medium–Complex	An AutonomousAgent driving an MCP fetch tool to a cited research brief, bounded by a token budget, with live loop progress over the SDK
kyc-onboarding	Complex	A supervised autonomous investigator (fail-closed LLM judge), policy RAG, compliance-gated approval, PII masking, versioned risk schemas

Together the five exercise every step kind and subsystem: all nine step kinds, RAG, spec.supervisor, HumanInTheLoop with auth.required_group, MCP over stdio, model versioning, secure: true masking, IAM scopes and groups, and the tuvl test framework with LLM-judge evaluations.

Running one

uv tool install "tuvl[standard]>=2026.2.6.1"
git clone https://github.com/tuvl-io/examples.git
cd examples/<project-name>
cp .env.example .env        # fill in DATABASE_URL, GEMINI_API_KEY, …
tuvl validate
tuvl dev                    # → http://localhost:8000 (+ /insight)

Per-project infrastructure needs (database, pgvector, API keys, MCP tooling) are catalogued in the repo's REQUIREMENTS.md. Contributions follow AGENTS.md — each project ships a specification a human or coding agent can implement unaided.