Metadata-Version: 2.4
Name: modulatio
Version: 1.0.0
Summary: Multi-model agent framework with plan-mode orchestration, integrated TUI, and team-state working memory.
Project-URL: Homepage, https://github.com/ModulatioAI/modulatio
Project-URL: Repository, https://github.com/ModulatioAI/modulatio
Project-URL: Issues, https://github.com/ModulatioAI/modulatio/issues
Project-URL: Changelog, https://github.com/ModulatioAI/modulatio/blob/main/CHANGELOG.md
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,llm,multi-agent,orchestration,plan-mode,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: ddgs>=9.0
Requires-Dist: fastembed>=0.3
Requires-Dist: httpx>=0.27
Requires-Dist: lancedb>=0.13
Requires-Dist: litellm>=1.50
Requires-Dist: orjson>=3
Requires-Dist: packaging>=23
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic>=2.8
Requires-Dist: pyperclip>=1.8
Requires-Dist: python-dotenv>=1.0
Requires-Dist: textual>=0.80
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: httpx2>=2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.6; extra == 'dev'
Provides-Extra: export
Requires-Dist: pypandoc-binary>=1.13; extra == 'export'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: uvicorn>=0.29; extra == 'web'
Description-Content-Type: text/markdown

# Modulatio

**A multi-model agent framework for running long, high-stakes projects with real quality control.**

Modulatio orchestrates teams of LLM agents — each on its own model and provider — through plan-mode execution with a real quality gate. Designed for work that takes more than one prompt: long-form drafting, small-business loops, multi-step research, codebase work, anything where output quality matters.

> [!WARNING]
> **v1.0.0 — the 1.0 line, and still beta software.** v1.0.0b1 opened this line with the **standalone Leader harness** present; 1.0 makes it *trustworthy*. It is now **bounded** — one absolute wall over the Leader's whole chat loop and every dispatch inside it, abortable shells, and a durable **per-task tool-call budget** that yields to QC instead of spinning; **observable** — a live **capability card** built from the production authority descriptors, a conformance matrix that runs the *real* gate across every surface × backend × tool-origin × autonomy-mode cell, and one coordinator that asks **once per call**; and **careful about which successes it claims** — code deliverables are *executed* (wheel built in a sandbox, installed into a pristine network-off environment, entry point probed, component imported, suite run from a disposable clone), component shape is **sealed before any producer writes code**, and the pytest gate is honest about what it can vouch for: the engine picks the targets, strips collection hooks and runs the suite under containment, and a MISSING wrapper result means no outcome whatever the exit status said — but the suite is the deliverable's own and runs in one interpreter with the code it judges, so a reported success is evidence rather than an attestation, while a recovered failure binds. **One fact in that gate is no longer producer-authored:** the shipped component's source is watched from outside the interpreter, and a credit for a file the kernel never saw opened is withdrawn — it refutes a false load, it does not attest an honest one, and the report says so. **There is no stable release and this version number does not imply one** — 1.0 is the line, not a promise. Install plainly: `pip install "modulatio[web]"`. Builds on **v1.0.0b1** (the 1.0 line opens) and the WebOS line before it. See the [CHANGELOG](CHANGELOG.md) for the full delta and the [roadmap](https://modulatio.ai/roadmap/) for what's next. Read the [Beta calibration](https://modulatio.ai/v0-1-0-beta/) page before serious work. Bug reports + discussions welcome on the [issues tab](https://github.com/ModulatioAI/modulatio/issues) and [discussions](https://github.com/ModulatioAI/modulatio/discussions).

**Requires Python 3.12+.**

---

## Quick install

```bash
git clone https://github.com/ModulatioAI/modulatio.git ~/modulatio
cd ~/modulatio
uv venv && uv pip install -e ".[dev]"
modulatio setup
```

Full install with troubleshooting at <https://modulatio.ai/getting-started/install/>.

> **Linux clipboard.** The TUI's copy/paste (Ctrl+C / Ctrl+V) reaches the OS clipboard through a system backend — `xclip` or `wl-clipboard`. `modulatio setup` detects it and offers to install it; or `sudo apt install xclip` (Debian/Ubuntu) / `wl-clipboard` (Wayland). macOS and Windows work out of the box. Without a backend, Ctrl+C still copies via OSC 52 (terminal-dependent) and Ctrl+V paste is unavailable.

> **Why 3.12+?** One of the dependencies (`lancedb`, `fastembed`, or `litellm` depending on platform) hasn't published a wheel for older Pythons and falls back to a source build that often fails. If your `python3` is 3.11 or older, point the venv at `/usr/bin/python3.12` explicitly.

---

## Documentation

Full documentation lives at **<https://modulatio.ai>**.

- **[Overview](https://modulatio.ai/overview/)** — what Modulatio is, who it's for, the orchestration model.
- **[v0.1.0 Beta calibration](https://modulatio.ai/v0-1-0-beta/)** — what the engine does well, what it does NOT do yet. Read before serious work.
- **[Getting Started](https://modulatio.ai/getting-started/install/)** — install, run the setup wizard, ship your first plan.
- **[Concepts](https://modulatio.ai/concepts/concepts/)** — the mental model: vault, project, plan, agent, skill, standard.
- **[Architecture deep-dives](https://modulatio.ai/architecture/working-memory/)** — five-layer working memory, skill system, assembly + review-ledger, sandbox, audit trails.
- **[CLI reference](https://modulatio.ai/reference/cli/)** — every command, every flag.
- **[Roadmap](https://modulatio.ai/roadmap/)** — what's shipping next, what's planned beyond.

---

## What Modulatio does

- **Multi-model routing per agent.** Each agent (Leader, QC, every producer) runs on its own configured provider + model. Pick a fast/cheap model for routine work and a stronger one for the gate-class seats — native to the architecture, not an afterthought. Each seat can also carry an ordered list of **fallback models**: if its model is unavailable (rate limit, auth, 5xx), the engine warns and restarts the whole task on the next backup — never a mid-task switch.
- **Subscription seats — bring your own Claude or GPT-5.5.** Beyond API keys, a seat can run on a subscription you already pay for. **Clay** runs any seat through your **Claude Code** subscription (`claude -p`, the official harness — your subscription, never a metered key); **GPT-5.5** runs through your **OpenAI Codex** subscription (the ChatGPT backend). Both reach the model through the vendor's own harness, are confined like any other seat, and are additive to the existing API-key paths. A confined kickoff seat (producer/QC) is held to a fixed set of non-process tools with customizations disabled — it can't spawn a hidden crew or escape its sandbox — while the interactive Leader lane keeps its full loadout.
- **Configure everything from the TUI.** A Configuration tab wires up providers, models, API keys, and agents without touching a config file: pick a provider and a model and base_url / auth / model-id auto-fill — you type only a key. Catalogs thirteen providers (OpenRouter, Ollama Cloud, xAI, Anthropic, OpenAI, NVIDIA, Google, three locals, custom — plus two subscription seats: GPT-5.5 via OpenAI Codex, and Claude via Clay) with free-tier models honestly caveated. A **Providers & keys** manager lists each provider's keys (by label, never the value) to add or remove; add and remove models and agents. Only the **Leader** is required — a QC verifier and producers are optional, so you can run a solo Leader or a full swarm. Subscription models that reason (GPT-5.5/Codex) expose a **reasoning-effort** picker (xhigh/high/medium/low).
- **Key-pool — your own keys, pooled by default.** A provider's keys form one shared floating pool: every model on it rotates across the keys (so a swarm of producers spreads load instead of hammering one rate-limited key) and a `429` fails over to the next. Need a budget? **Pin** a key to a model — it then serves only that model and leaves the pool, so its spend stays isolated (the provider meters per key; distinct keys become your accounting buckets). Modulatio meters by key, not in the router. Pool *your own* legit keys; never throwaway accounts. See the [key-pool doc](https://modulatio.ai/architecture/key-pool/).
- **Talk to the Leader.** Beyond batch kickoffs, the Leader is an agent you converse with — ask him to answer, analyze, fetch the web, author a skill, inspect the team's own configuration, or *run a job* and command the producer swarm, all in one lane, streaming back live. The conversation rides the **model's full context window** by default, so a long thread isn't compressed away (cap it lower from SETTINGS for cost control). Drive the thread with commands — **`/new`** archives the conversation aside (kept, never deleted) and starts fresh, **`/editor`** composes a message in your `$EDITOR`, **`/models`** opens the picker — and **ESC** interrupts him mid-thought, cleanly, at the next step.
- **The Leader works solo, too.** Beyond commanding the swarm, the Leader can pair with you directly as a standalone coding agent — read, edit, and **run** files in a folder you point it at with **`/work <path>`** (`pytest`, builds, `git`). It's confined by default to its own per-project workspace — a *structural* cheat-guard, it physically can't touch the team's deliverables — and widening it to a real folder is an explicit, scoped approval (once / session / always / deny; **`/rp`** revokes everything). Two separate grant classes guard that folder: the `/work` approval covers **reading and editing**; **running** commands there is its own, separately prompted approval — a path grant never confers exec (**sandbox-required, fail-closed** for anything it runs). Turn it loose *within bounds* with autonomy modes — **`/yolo`** (auto-grant capabilities), **`/goal`** (delegate judgment), **`/yolo-goal`** (both) — while one fence holds through every mode: **crossing into a new folder always needs your `/work` approval.**
- **The WebOS — the whole thing in your browser.** Opt in with `pip install "modulatio[web]"`, run `modulatio-api`, and browse: the TUI's layout rendered as a web app over the *same* engine seams — no parallel data paths. The **Console** carries the terminal's anatomy faithfully (status lamps, LEADER / MOD SQUAD flip, the live activity TV, the run telemetry rail, and a composer where `/kickoff … /end` is the only job trigger), plus nine pages that **act** — a button for every verb — a **read/write CONFIG tab** (models, agents, services, folders, projects, settings, with a write-only key manager), and a **Teams-style cron scheduler** in the JT Library (date + time, recurring, count/until stop rules the daemon holds fail-closed). The telemetry rail carries the run's **tokens in / out** and the Leader's **autonomy pill**; approvals run the engine's own permission gate (once / session / always / deny, durable grants); the run stream replays across reconnects. Two print-flavored **Feng-Web themes** — **Atelier** (thin ink on a field you choose) and **Vellum** (invertible greyscale) — switch with `F2`. The frontend is hand-authored vanilla ES modules: no framework, no build step, no runtime JS dependency. It **binds loopback by default**; LAN exposure requires a bearer token and a `Host` allowlist, secrets never cross the boundary, and the Leader's permission asks land as a **fail-closed** modal. See the [WebOS doc](https://modulatio.ai/reference/webos/).
- **Diagnostics you can send in one step.** Crashes, handled failures, and a `doctor` read are captured to local **logs** (each kind named in its file), browsable in a `LOGS` tab or via `modulatio logs` — review one and **send it to the team** as a GitHub issue. Capture-always, submit-on-consent: nothing is auto-filed, and every log is auto-redacted (secrets, tokens, `Authorization` headers) and shown to you before it's sent.
- **Many projects, one install.** A single install runs more than one line of work. Switch the active project from the CLI (`modulatio project list` / `project use <code>`) or a **PROJECTS** tab (browse, **switch**, **create**, **delete**); switching is live and in-place, disabled while a job runs. Your **team carries install-wide** — the same agents and models everywhere — while each project keeps its own memory, deliverables, tickets, and history. Creating a project seeds your team into it in one click; deleting one **backs it up first** and is guarded against the obvious accidents.
- **Clean install lifecycle — `modulatio repair` and `modulatio uninstall`.** Repair a broken setup (rebuild missing presets/agents, recreate a missing vault or project, clear configuration in tiers) or remove Modulatio entirely with named choices (settings, project folders, deliverables, pandoc) and a `--pristine` full reset. Your own data is **backed up before removal**, and a vault Modulatio didn't create — your own notes folder — is **never auto-deleted**, even under `--pristine`.
- **Quality control as a first-class subsystem.** Three-layer TQM (universal axes × per-artifact-kind standards × per-team overrides). QC reviews every artifact; rejects route back to producers in GENERATE / EDIT / DIFF mode.
- **QC-as-fixer (on by default).** Cheap, fast producers generate the bulk of the work; the smarter QC reviews it and *patches only the errors* — the cost of a cheap model with the quality of a strong one (speculative decoding, applied to agents). When a producer can't clear the bar, QC authors the fix from its own findings and the task completes — and at a goal's end, if work is still missing, QC **produces the missing pieces itself** (in dependency order, from each task's brief) rather than shipping a goal with a hole in it. Bundled default standards give QC a real bar from a cold start. Opt out with `MODULATIO_QC_FIXER=0`.
- **The team finishes even when a seat dies.** A crashed or unloaded local model is recognized as an availability failure: the seat's fallback chain engages, its retries back off instead of burning a budget against a dead endpoint in a second, and the seat is cooled out of the dispatch pool so it stops attracting tasks while it's down. Its work routes to the QC backstop, and the run lands a real deliverable instead of wedging. And the **floor's telemetry rail is live** — you watch the run's task progress, QC tally, context load, and each producer's current move in real time, instead of reading tea leaves.
- **Product Quality Report.** Every run ships an advisory note (`.docx`) in the project lead's own voice — what it stands behind and what it recommends you double-check. Honest caveats, never a gate: reservations the swarm can't resolve are surfaced here, never block the work or open a ticket.
- **Finished products, delivered — one folder per job.** Producers write Markdown; the lead's tagged deliverables render to `.docx`, human-named from the document title, into a **per-job folder** under `~/Documents/Modulatio/<project>/` (named from the job and date, with a hex tiebreaker only on collision) so each run keeps its own products instead of overwriting the last. The Product Quality Report ships inside the same folder. When a renderer isn't installed, products ship as Markdown with a note rather than failing.
- **A research library the team reuses, not re-buys.** The project folder is the **durable layer** — research notes and finished products persist across runs, and producers are **prejudiced toward reuse**: mine the team canvas and prior-run artifacts first, cite a still-fresh grounded note as-is, and re-fetch only the gaps (or a note past its 30-day freshness). Cross-run reuse is measured in the audit trail. So a project that runs the same class of job repeatedly gets *cheaper*, not just faster.
- **Fan the work by context size, not a guess.** When a wide research goal would overload one producer, the engine splits the oversized gather into the **fewest size-bounded chunks** that each fit a producer's window — size decides whether to cut, the model only picks the cut lines, and a task that fits stays whole. No fixed topic-count cap, no one seat inheriting the whole scope and riding the compression bands. Tunable via `MODULATIO_TASK_CONTEXT_CAP_PCT`.
- **Assemble the product, not just the document.** A multi-piece deliverable is joined by a **family of assemblers** chosen by the artifact's kind — `document` (ordered text), `code` (preserve the file tree + generate a wiring index), `data` (a real JSON/CSV merge), `media` (image/audio/video/bundle via a local compositor). The producer emits a small *plan* (a manifest); the **engine** owns the join, so unit bytes never round-trip through the model and a large deliverable can't truncate. Underneath, a **content-addressed review-ledger** lets QC verify a finished deliverable by its *marks* (each unit passed, bytes unchanged, the set matches the dependency graph) instead of re-reading the whole thing into a blown budget. Every family now has a **deterministic containment oracle** — a provably-correct assembly passes QC *cheaply*, without the bytes ever re-entering the model: `document`/`data` structurally, `code` by static wiring checks, a `media` `bundle` by exact byte equality; a lossy `video`/`audio`/`image` composite honestly falls back to the full review rather than claim a proof it can't back. See [Assembly + the review-ledger](https://modulatio.ai/architecture/assembly/).
- **Code deliverables are executed before they're called done.** Beyond checking the text, the engine *runs* the product: it builds a wheel in a sandbox, validates the metadata, installs it into a pristine network-off environment, then probes the entry point, imports the declared component, and runs the suite from a disposable clone. The rollup is typed — `OK` / `PRODUCT_FAILED` / `ENGINE_UNAVAILABLE`, with the origin stated — so an undeclared dependency fails **by name** and a deliverable the engine can't execute never ships clean.
- **The test gate separates "it ran" from "it ran the right thing."** Every engine-run pytest goes through the engine's own isolated wrapper, so a suite that reports success without the wrapper finishing produced **no outcome at all** and clamps RED — exit status is never mistaken for evidence. Whether the suite actually *loaded the shipped component* is observed too, but stays **advisory**, because that observation shares an interpreter with producer code and can be influenced by it. Hard verdicts settle before the advisory is written, so a failing report never claims the suite passed.
- **Component shape is sealed before anyone writes code.** After planning and before dispatch the engine derives and *seals* each component's contract — import name, distribution name, source layout — and renders it into every producer, QC, and Leader prompt. Ambiguity is refused up front rather than discovered in the deliverable, and a component the Python schema doesn't claim runs explicitly unbound instead of being silently counted as conforming.
- **A storming seat can't burn your budget.** Every task carries a durable tool-call budget consumed under one serializable authority — denied, errored, cache-hit, and replayed calls all count, and it survives crashes and concurrent writers. Trip it and the task yields a typed outcome straight to QC-as-fixer instead of spinning; a seat can't loop on tools any more than it can loop on retries.
- **See exactly what the team may do, on every surface.** `modulatio doctor` renders a **capability card** built from the production authority descriptors themselves — not a hand-maintained table that drifts. A conformance matrix exercises the *real* permission gate across operator surface × execution backend × tool origin × autonomy mode, with set-equality completeness, so a new tool or surface can't be added without showing up in it. One authorization coordinator asks **once per call** over a single atomic bundle, and architectural parity gaps are *declared* rather than papered over.
- **Verify the whole deliverable, not just the parts.** A declared **`DeliverableSpec`** (per-part floor, required structure, title) is carried from the job template into the run, and the engine checks the *assembled whole* against it — giving the verifier real eyes (an engine-extracted structural *digest* + a readable text *twin*, never binary bytes the model can't read), binding the per-part floor at produce-time (on the assembler's real part set, never a front-matter page), generating the framing (title + table of contents), and normalizing part numbering to a clean 1..N. Every move is a per-family dispatch — document-first, every other family a graceful no-op — so it stays product- and agent-agnostic. See [Deliverable fidelity](https://modulatio.ai/architecture/deliverable-fidelity/).
- **Outside services on the team — the SERVICES pool.** Configure outside APIs (image, video, speech, research, or any custom service) in the Config tab's **SERVICES** section — from a shipped catalog (OpenAI Images, Tavily, ElevenLabs, Luma — beta-flagged) or as a custom service with an **operator-pinned base URL**. Producers get capability tools (`generate_image`, `generate_video` — submit-then-poll under a wall cap, `generate_speech`, `research_search`) plus a generic `api_call` whose paths are relative to the pinned base — **the model can never choose a host**. Keys ride the same numbered-slot pool provider keys use, are injected at the adapter layer, and never enter agent context or results; binary outputs land in the artifacts tree and come back as filenames. When more than one service backs a capability, you pick the default — ambiguity never guesses with your money.
- **Metered tools, gated before they spend.** Every built-in tool is free-local and unmetered; a service tool is metered by default (`cost_class: paid-cloud`; a free-tier service opts out), and the Comptroller gates each metered call before it spends — fail-closed on a missing budget (`paid_cloud_escalations_per_day`, per project), per-task + daily caps, idempotent (a retry of the identical call replays free), narrow params (a tool's schema-declared options pass; URL-shaped names and URL-like values never do). `modulatio doctor` flags keyless services and metered services with no budget before a run. No SaaS lock-in: every provider is optional and swappable.
- **MCP servers — bring outside tools onto the team.** Modulatio is an **MCP client**: plug in a Model Context Protocol server (a local `stdio` subprocess or a remote `http` endpoint) with `modulatio mcp add-stdio` / `add-http`, and its tools become first-class Modulatio tools. The Leader can call them (each gated once/session/always the first time, or run a read-only server **trusted** for zero clicks); a producer gets a specific MCP tool only when a skill's loadout names it. It's a fourth capability provider on the *same* control plane as the built-ins and the SERVICES pool — the tool registry, the write-only key vault, the permission gate, the spend comptroller. Opt-in `[mcp]` extra keeps the base install lean. Secrets never enter agent context or results, and a bad server degrades to an honest "unavailable" instead of crashing a run. See the [MCP doc](https://modulatio.ai/reference/mcp/).
- **Job Templates — setup that sticks.** For work you do more than once, the Leader can codify a **Job Template**: its own interview, parameter schema, and output contract for that *class* of job — domain-agnostic (a single report, an N-piece anthology, a per-competitor brief are all the same primitive over a generic output cardinality). Bind it to a concrete answer set and it runs headless on a schedule — every cron job is a bound template, validated when you add it, never failing at 3am. The team notices when you keep running the same kind of job (or redo one) and offers to template it: the setup-side mirror of skill self-codification.
- **A producer is a model endpoint that learns.** No fixed roles and no skills to assign — give a producer an LLM and tag what it's good at; the team composes the skills each task needs from a shared, **git-versioned** library at run-time, and routing never blocks on a capability gap. When the same defect keeps recurring, the team **codifies** the correction into durable skill guidance that cheap producers load next time — and it learns the other direction too: when the smart QC keeps *rescuing* a producer by writing the fix it couldn't, the team codifies that recurring **technique** (project-local, flagged as a non-independent fix worth a spot-check), so the cheap producer learns to do it itself. It gets quietly better at the work you give it.
- **Plan-mode end-to-end.** Leader is a conversational partner, plan is the unit of execution, daemon-driven async, Telegram approvals, full audit trail.
- **Open architecture.** Your data, your vault, your providers, your models. No SaaS, no per-instance subscription.

---

## Project structure

```
modulatio/
├── src/modulatio/    # Source — agents, runners, daemon, TUI, CLI, WebOS
├── tests/            # Pytest suite (5,598 tests)
├── scripts/          # Build / release scripts
└── pyproject.toml    # Package metadata + deps
```

Documentation lives in its own repo (the [Modulatio docs site](https://github.com/ModulatioAI/modulatio-site)) so it can be deployed to <https://modulatio.ai> independently of code releases.

---

## License

[Apache License, Version 2.0](LICENSE). Relicensed from AGPL-3.0-or-later prior to v0.1.0.

---

## Contributing

Issues and pull requests welcome at <https://github.com/ModulatioAI/modulatio>. See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide. Three GitHub issue templates are wired (Bug report / Regression / Feature request) plus a labelset for severity / component / status / regression — file issues using the templates so the labels apply correctly.

Contributions are accepted under the project's Apache-2.0 license (see [LICENSE](LICENSE)). By submitting a contribution, you affirm you have the right to do so under those terms.
