Skip to content

tuvl

A lightweight, local-first workflow orchestration engine for AI-powered business automation.

Early stable release

tuvl 2026.3.1.0 is production-ready: the API and YAML schemas are stable and versioned. As an early release in the stable line it is still maturing quickly, so expect additive improvements between versions.

Pronounced "Thoo-val" (തൂവൽ) in Malayalam means a feather. It refers specifically to the soft feathers or plumage of a bird.

What is tuvl?

tuvl is a modular workflow engine that bridges the gap between deterministic code and probabilistic AI. It enables you to build complex business workflows using YAML-defined playbooks, with LLMs and traditional Python functions as interchangeable logic units.

workflows/onboarding.yaml
kind: "Workflow"
version: "v1"
metadata:
  name: "candidate_onboarding"
  description: "AI-powered candidate vetting workflow"

spec:
  steps:
    - id: "save_draft"
      kind: "Functional"
      runner: "db_save"

    - id: "ai_vetting"
      kind: "Agent"
      agent:
        model: "ollama/llama3"
        prompt: |
          Evaluate this candidate: {{ full_name }}
          Experience: {{ experience_years }} years
      routes:
        senior: "fast_track"
        needs_review: "manual_review"

Key Features

  • Local-First

    Run entirely on your infrastructure with Ollama for LLM inference. No data leaves your network.

  • YAML-Driven Workflows

    Define complex business logic in readable YAML files. No more scattered code.

  • AI as a Function

    Use LLMs as interchangeable logic units with structured JSON outputs and automatic routing.

  • Autonomous Agents

    Beyond a single call: an AutonomousAgent step runs a bounded tool-calling loop — the model picks from your declared tools until it emits a declared outcome, capped by max_iterations and token_budget.

    Autonomous agents

  • Agent Supervisor

    An optional per-workflow watcher observes each autonomous run live and can pause, steer, or abort it mid-loop — deterministic rules or an LLM judge — with an operator API and a live Insight dashboard.

    Supervise agents

  • Dynamic Models

    Define data models in YAML and get SQLModel classes, Pydantic schemas, and CRUD APIs automatically.

  • Flexible Routing

    Branch workflows based on node outputs, AI decisions, or custom conditions.

  • Auto-Generated APIs

    Every workflow becomes an HTTP endpoint. Every model gets CRUD operations.

  • Insight Developer Portal

    Browser-based UI for editing workflows, managing models, testing with Spectrum, and configuring IAM — all in dev mode.

    Explore the portal

Quick Example

nodes/onboarding.py
from typing import Any
from tuvl_engine.nodes.base import node
from tuvl_engine.repositories.registry import get_repository

@node("db_save")
async def db_save(ctx: dict[str, Any]) -> dict[str, Any]:
    """Save a candidate to the database."""
    session = ctx["_session"]
    repo = get_repository("Candidate", session)

    candidate = await repo.add({
        "email": ctx["email"],
        "full_name": ctx["full_name"],
        "experience_years": ctx.get("experience_years", 0),
    })

    ctx["id"] = str(candidate.id)
    return ctx

Architecture & Data Flow

flowchart TD
    subgraph Configuration
        YAML[YAML Definitions] -->|load_all_configs| Reg[In-Memory Registries]
    end

    subgraph Transport Layer
        Reg -->|Mount Endpoints| REST[FastAPI REST Server]
        Reg -->|Mount Services| GRPC[gRPC Server]
    end

    Client([Clients]) -->|HTTP/JSON| REST
    Client -->|HTTP/2 Protobuf| GRPC

    subgraph Security: Authentication & Authorization
        REST --> Auth[Biscuit Token Auth<br>Verify Crypto Signature]
        GRPC --> Auth
        Auth -->|Extract Identity| AuthZ[IAM Scope Guard<br>Enforce Model/Route Scopes]
    end

    AuthZ -->|Workflow Route| Engine{WorkflowEngine.run}
    AuthZ -->|Auto-Generated CRUD| UoW[Workflow Unit of Work<br>Pydantic-Validated CRUD]

    subgraph Execution & Integrations
        Engine -->|ModelOp| UoW
        UoW -->|SQLModel Object Mapper| PG[(PostgreSQL)]
        Engine -->|Agent| LLM[LiteLLM Any Provider]
        Engine -->|AutonomousAgent| Loop[Bounded Tool-Calling Loop]
        Loop -->|LLM + declared tools| LLM
        Sup[Agent Supervisor<br>pause · steer · abort] -.watches.-> Loop
        Engine -->|DataSearch| RAG[(pgvector RAG)]
        Engine -->|Functional| Nodes[Custom Python Nodes]
        Engine -->|MCP| MCP[MCP Tools]
        Engine -->|APICall| ExtAPI[External APIs]
    end

AI Agent Instructions

TUVL is fully compatible with AI coding agents. To empower your AI agent with complete knowledge of the TUVL declarative schema, YAML logic, and custom python nodes, provide it with our official agent instructions:

Place these files directly in the root of your project workspace to align your AI assistant with the TUVL framework. New projects created with tuvl init already include them. For the full workflow — scaffolding, prompting, validating, and testing generated config — see Build with Coding Agents.

Getting Started

Ready to build your first workflow?

Get Started View Examples

License

tuvl is open source software licensed under the MIT license.