Hatchery — AI Agent Orchestration

# Install and run
pip install hatchery-ai
hatchery

# Dashboard at http://localhost:8000
# API docs at http://localhost:8000/docs

# Register an agent (Ollama, local LLM)
curl -X POST http://localhost:8000/api/agents \
  -H 'Content-Type: application/json' \
  -d '{"name":"scout","agent_type":"ollama","endpoint":"http://localhost:11434","config":{"model":"llama3"}}'

# Start chatting
curl -X POST http://localhost:8000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"AGENT_ID","message":"What can you do?"}'

# Or just open the dashboard and start typing.

What You Get

💬

Chat Interface

Talk to your agents directly from the dashboard. Conversation memory persists across sessions. Slash commands for everything. Thinking animation while agents process.

🤝

Agent-to-Agent Delegation

Agents delegate subtasks to other agents. Results flow back up the chain. Every delegation goes through the same trust governance. Full audit trail.

📊

Graduated Trust

Trust scores computed from real outcomes: 70% success rate + 30% volume. Agents earn autonomy through demonstrated competence. Irreversible actions always require human approval.

📋

4-Tier Approval System

Free actions auto-execute. Small actions get logged. Medium actions need approval. Big or irreversible actions require the Admiral. Trust scores can promote agents through tiers.

👤

Soul Files

Agent personalities loaded from markdown files. Write a persona, load it with one command. Five example personas included: researcher, writer, ops, code reviewer, project lead.

💰

Revenue P&L

Track income and expenses per revenue stream. Task compute costs auto-logged. P&L breakdowns by stream, source, and period. The organism funds itself.

🏆

Performance Scorecard

Six weighted metrics. Competitive compute allocation. Top scorers earn more resources. New agents get a 180-day runway. Monthly reviews with automatic rebalancing.

🔍

Full Audit Trail

Every action logged immutably. Who did what, when, at what cost, and who approved it. Queryable by entity type, actor, and time range.

Architecture

Chat Interface + Dashboard Single HTML file, vanilla JS, no build step │ FastAPI REST API /api/chat /api/tasks /api/agents /api/trust /api/revenue /api/scorecard │ Task Engine create → tier → approve → dispatch ← trust feedback loop → │ ┌───────────────┬──────────────────────┐ │ Adapters │ Governance (JSON) │ │ Ollama │ ComputeLedger │ │ Shell │ PerformanceScorecard│ │ Claude Code │ RevenueTracker │ │ HTTP │ │ ├───────────────┼──────────────────────┤ │ SQLite │ Soul Files (markdown)│ │ tasks, agents │ Agent personas │ │ runs, audit │ Loaded on demand │ │ chat_history │ │ └───────────────┴──────────────────────┘ Python 3.13+ · FastAPI · Pydantic · SQLite No external database. No Redis. No Docker required. Zero external dependencies beyond FastAPI.

Documentation & Guides

README

Full feature overview, install instructions, API reference, and architecture.

start here

Quickstart

From zero to chatting with an agent in 60 seconds. Register agents, send tasks, toggle trust.

getting started

v0.3.0 Release Notes

Chat interface, agent delegation, soul files, Ollama adapter. Full changelog.

changelog

SLOBSTAH Protocol

The governance spec. LOBSTER hierarchy, BARNACLE scoring, REEF budgets, and all the other acronyms.

protocol

Example Soul Files

Five agent personas ready to use: researcher, writer, ops, code reviewer, project lead.

templates

Package Config

Dependencies, build config, and project metadata. Python 3.13+, Apache 2.0.

reference

Dashboard Commands

/helpShow all commands

/agentsList registered agents

/trustShow trust scores

/healthPing agent endpoints

/statusSystem overview

/soulsLoad agents from soul files

/approve [id]Approve a pending task

/deny [id]Deny a pending task

/history clearClear chat history

API Reference

Method	Endpoint	Description
POST	/api/chat	Chat with an agent (auto-dispatch)
GET	/api/chat/history/{id}	Chat history per agent
POST	/api/tasks	Create a task
GET	/api/tasks	List tasks (filter by status, agent)
GET	/api/tasks/pending	Tasks awaiting approval
POST	/api/tasks/{id}/approve	Approve a task
POST	/api/tasks/{id}/deny	Deny with reason
POST	/api/agents	Register an agent
GET	/api/agents	List agents
POST	/api/agents/load-souls	Auto-register from soul files
GET	/api/trust	All agent trust scores
GET	/api/trust/{name}	Single agent trust detail
PATCH	/api/workspace	Config + trust mode toggle
GET	/api/ledger	Spending summary
GET	/api/revenue	Revenue P&L
GET	/api/scorecard	Performance standings
GET	/api/stats	Full dashboard payload
GET	/api/audit	Audit trail
GET	/api/health	Health check

interactive API docs at localhost:8000/docs after install

Soul File Format

# AGENT NAME -- Soul File ## Role or Title --- ## Constitution Write what the agent believes, values, and refuses. This becomes the system prompt. First person voice. The loader extracts the Constitution section and condenses it to ~1500 characters for the LLM context. I believe in [core principle]. ### What I Value **Accuracy.** [Why this matters to the agent.] **Clarity.** [How the agent approaches work.] ### What I Refuse I refuse to [hard boundary]. ### How I Work Give me [input] and I'll give you [output].

save as SOUL.md in a named directory. /souls loads them all.

Supported Agent Types

ollama

Local LLM inference via Ollama. Point at any Ollama instance on your network. Zero API costs, your hardware, your data.

endpoint: http://host:11434

shell

Execute shell commands. Task description becomes the command. Timeout protection, stdout/stderr capture.

endpoint: /bin/bash

claude_code

Claude Code CLI integration. Send tasks to Claude for code generation, analysis, and complex reasoning.

endpoint: claude

http

Any HTTP API endpoint. POST the task, get the response. Integrate with external services and custom agent backends.

endpoint: https://your-api.com