ZeroERP

Zero Human ERP — autonomous AI agent management system that operates an ERP with minimal human intervention.

A FastAPI gateway accepts tasks, a LangGraph "Manager" graph decomposes them into subtasks, and per-agent "Worker" subgraphs execute tools with guardrails (Budget → ACL → HITL). State is checkpointed to Postgres so human-in-the-loop interrupts can be resumed.

Architecture

Hexagonal / Ports & Adapters. Import direction is one-way: adapters → application → domain.

src/
  domain/           # pure business: models, value_objects, services, ports
  application/      # use cases, DTOs, LangGraph graphs/nodes, guardrail chain
  adapters/         # concrete infra: api (FastAPI), persistence, llm, tools, tracing
  config/           # Settings (pydantic-settings) + structlog config
  bootstrap.py      # composition root — wires all concretes together

Graph Topology

• Manager graph — classify_intent → decompose_task → assign_agents → dispatch_worker → … → aggregate_results → finalize
• Worker subgraph — plan → execute (GuardedToolNode) → review → fix_loop → report_back
• Guardrails — Chain of Responsibility: Budget → ACL → HITL

Requirements

• Docker & Docker Compose
• Python 3.11+
• uv package manager

Getting Started

# Install dependencies
make install

# Copy and fill in environment variables
cp .env.example .env

# Start Postgres and API
make up

# Run migrations
make migrate

# Seed agents and tools
make seed

Common Commands

make up               # Start API + Postgres (Docker)
make down             # Stop containers
make logs             # Tail API logs

make migrate          # Run alembic upgrade head (in container)
make migrate-local    # Run alembic upgrade head (local venv)
make migration MSG='describe change'  # Autogenerate new revision

make seed             # Seed tools + agents
make seed-agents      # Seed agents only

make test             # Full pytest run
make test-unit        # Unit tests only
make test-integration # Integration tests (needs Postgres)
make test-e2e         # E2E tests

make lint             # ruff check
make fmt              # ruff format + autofix

Environment Variables

Copy .env.example to .env and configure:

Variable	Description
OPENAI_API_KEY	OpenAI API key
POSTGRES_URL	Postgres connection string
API_KEY	API key for authenticating requests
LANGSMITH_API_KEY	LangSmith tracing (optional)

API Authentication

All mutating endpoints require the X-API-Key header matching API_KEY in settings. The /health endpoint is open.

Adding a New Tool

1. Create src/adapters/tools/<domain>/<name>.py with a @tool-decorated async function
2. Add entry to seeds/tools_seed.yaml with handler_ref = "adapters.tools.<domain>.<name>:<func>"
3. Grant permissions in seeds/agents_seed.yaml
4. Run make seed

Odoo Integration

To create an API key in Odoo:

Settings → Enable Two-Factor / API Key → Administrator → Security → API Key

License

MIT