Skip to content

tuvl

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

Stable release

tuvl 1.0.1 is production-ready: the API and YAML schemas are stable and versioned under SemVer — breaking changes bump the major version.

Try it live — no install

Run any example in a throwaway browser sandbox at try.tuvl.online. Pick an example, get a private live instance with the Insight editor, and explore the workflows hands-on — each sandbox resets automatically after a few minutes.

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"
      mode: "completion"
      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 Agent step in mode: autonomous 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

  • Artifacts

    Prompts, steering, skills, guardrails, hooks, and MCP server configs as named, versioned, typed assets — referenced from YAML via artifact://name[@version] and sourced from project files, DB uploads, or sha256-pinned external packs.

    Artifacts

  • 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 completion| LLM[LiteLLM Any Provider]
        Engine -->|Agent autonomous| 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.