Engine (@tedos/engine)

@tedos/engine is the last-mile execution engine: it turns AI models into implemented, reliable solutions for each client. The model is interchangeable; the value is everything around it — evals, guardrails, a human gate, connectors, and deliberation.

The thesis in one line: the model is swappable; the moat is the reliability layer that wraps it.

Design principles

• Service outside, product inside. The client buys an implementation; the core is reusable so each delivery is cheaper than the last.
• Outside the Claude API layer. The engine only knows an LLMProvider interface. The default is an open-source model (Ollama / vLLM); any API is "just another provider."
• The flow leads, the model adds craft. A fixed playbook (the expert) defines the plan, not the model; the model drafts/classifies inside bounded steps.
• Reliability is the product. Evals + retries + guardrails + a human gate are what take a vertical from ~25% to ~95% consistency.
• The human decides what matters. High-risk actions (send, charge) pass through a human gate; decisions can be deliberated in a council.

Layer view

                         client OBJECTIVE
                                │
                     ┌──────────▼───────────┐
                     │     ORCHESTRATOR     │  the flow controls the agents
                     └──┬───────┬───────┬───┘
            plan ───────┘       │       └──────── reliability + observability
                                │
          ┌──────────────┬──────┴─────────┬──────────────────┐
          ▼              ▼                ▼                  ▼
     connector tool   content          council          (human gate)
                      (model + evals)  (deliberation)
          │              │                │
   ┌──────▼──────┐  ┌────▼─────┐    ┌─────▼──────┐
   │ CONNECTORS  │  │ PROVIDER │    │   ROLES    │
   │ crm·whatsapp│  │ (model)  │    │ (council)  │
   │ ·invoices   │  │ oss/mock │    │            │
   └─────────────┘  └──────────┘    └────────────┘

  VERTICAL (marketing | accounting) = playbook + connectors + evals + prompt
  HTTP API + a pg-boss-style QUEUE wrap it all

Modules (single responsibility)

Module	Role
provider.ts	The model boundary — LLMProvider + an OpenAI-compatible provider (Ollama/vLLM) + a deterministic MockProvider. No Anthropic SDK.
providerSelect.ts	Picks the provider by environment (real model when configured; mock otherwise).
orchestrator.ts	The heart — walks the playbook, runs each step (connector / content / council), applies retries, evals, guardrails, and the gate, computes reliability. Vertical- and model-agnostic.
planner.ts	Takes the vertical's playbook and validates each step points to a real tool. Does not use the model.
evaluator.ts	Scores text against criteria (0..1 + failures) — defines "correct".
reliability.ts	PII guardrail, the human-gate predicate, checkpoints, retries.
observability.ts	A tracer — structured trace (events + summary).
roles.ts	Roles as runtime objects (systemPrompt, allowed connectors, model).
council.ts	A council / board-meeting node — deliberate → opinions + consensus + minutes.

Hybrid model

The same vertical runs in three modes — only the LLMProvider changes:

• local — Ollama, $0 inference, data at home.
• hosted — your own vLLM in the cloud (OpenAI-compatible).
• mock — deterministic, no network.

Connectors (product, not workflow)

The engine ships tenant-aware connectors — CRM, WhatsApp (Meta / 360dialog), Google, HubSpot, GitHub, invoices. Each tenant connects their own accounts via a 3-legged OAuth flow (in apps/api, the control plane), and the engine acts with their tokens, read from an encrypted-per-tenant credential vault. "Your Claude is yours, your data is yours" — only the (encrypted) tokens are stored, never the client's content.

Connectors are product, never dev-workflow

The tenant connectors operate on the client's systems. They are never routed through the dev-workflow git-mechanics, and the dev-workflow tooling is never routed through a tenant connector. See Build & workflow → kit ↔ engine boundary.

Where it fits

The engine is the substrate for the future per-client assistant (Layer 4 of Data, memory & assistant): the assistant is retrieval over the SoR

• memory through this engine — no new engine is built.