PinelliaChill/Operant

Operant – a local AI‑agent platform for multi‑model collaboration

What it is – Operant is a Python‑based framework that lets a single user run several large‑language‑model (LLM) agents on their own machine and have them cooperate on complex programming tasks. It provides a command‑line tool, a web UI, a TUI (Textual) and a desktop client (Tauri) that all talk to the same local FastAPI service.

Key ideas

Feature	What it does
Multi‑agent collaboration	You can define roles (planner, coder, reviewer, etc.) each backed by its own LLM. Agents are organised in a workflow graph with 14 node types (agents, tools, scripts, conditions, loops, approvals, etc.) and can pass messages only to the agents that need them, keeping context small.
Safety‑first approvals	Operations that affect the host system are classified as allowed, needs approval, or blocked. A “judge” model can automatically approve low‑risk actions, while higher‑risk steps require manual confirmation. Hard‑blocked actions are never auto‑approved.
Memory & experience reuse	Run‑time data, past task logs and curated knowledge are stored in a local “memory” system. Candidates can be reviewed, versioned, and promoted to reusable Skills that other projects can import.
Plugin‑able extensions	The core is split into model adapters, agent execution, tool invocation, memory, and UI. Plugins (e.g., extra memory back‑ends, tool providers) are loaded explicitly and run under macOS sandbox‑exec or a trusted in‑process mode.
Local‑only, user‑centric	All state lives under .operant/ on the user’s computer. Model calls go to any OpenAI‑compatible API you configure (self‑hosted, OpenAI, Anthropic, etc.). No cloud service is required.

Typical workflow

1. Install – clone the v0.1.0‑beta.2 tag, install Python 3.10+ with uv, and run operant init.
2. Add a model – point OPERANT_BASE_URL and OPERANT_API_KEY at your own API, discover models, and create a model profile.
3. Create roles – assign a system prompt to each role (e.g., “read code and explain it”).
4. Start a session – run a read‑only task to verify connectivity, or launch a full workflow where a planner creates a plan, a coder edits files (via Docker), and a reviewer approves changes.
5. Use the UI – open http://127.0.0.1:8000/web for the built‑in web UI, or run the React GUI (npm ci && npm run dev) for a richer experience.

Current status – The project is in beta (Beta 2). macOS arm64 and Ubuntu 24.04 have been validated for the core, TUI, and private cross‑device linking. Docker execution, Linux third‑party sandboxing, and public‑internet deployment are not yet verified.

License – PolyForm Non‑commercial 1.0.0 (free for non‑commercial use; commercial use requires a separate agreement).

---

Bottom line – Operant is a locally hosted, extensible AI‑agent orchestration system aimed at developers who want multiple LLMs to cooperate on code‑heavy tasks while keeping data, approvals, and tool access under tight user control.