Mullm - Multi-Agent Learning and Labor Management

A distributed system for orchestrating multiple AI agents with event-driven architecture, CQRS patterns, and real-time projections.

Architecture Overview

Mullm is built using Domain-Driven Design (DDD) principles with:

• Event Sourcing for state management
• CQRS for command/query separation
• Saga Pattern for distributed transactions
• Event-Driven Architecture with NATS messaging
• Read Model Projections for real-time dashboards

Services

Core Services

• Orchestrator: Command handling, domain logic, and event publishing
• Projector: Read model projections and query handling
• Web: FastAPI/Jinja dashboard for monitoring and control

Agents

• Shell Agent: Command execution and system operations
• Browser Host Agent: Web automation and browser control

Quick Start

# Start Mullm core/rag and nlp2dsl when ../nlp2dsl is present
make up

# View logs
make logs

# Stop services
make down

make up uses PROFILES="core rag" by default and also manages ../nlp2dsl for the AI dialogue loop. Use NLP2DSL=0 make up to run only Mullm, or override profiles with PROFILES="core rag nlp2dsl" make up.

Development

Prerequisites

• Docker & Docker Compose
• Python 3.11+
• PostgreSQL 15+
• NATS Server

Local Development

# Setup environment
cp .env.example .env

# Start infrastructure
docker compose --profile core up postgres nats -d

# Install dependencies
pip install -r services/orchestrator/requirements.txt
pip install -r services/projector/requirements.txt
pip install -r services/web/requirements.txt

# Run services locally
# Ports from .env: MULLM_ORCHESTRATOR_HOST_PORT, MULLM_PROJECTOR_HOST_PORT, MULLM_WEB_HOST_PORT
uvicorn app.main:app --app-dir services/orchestrator --host 0.0.0.0 --port ${MULLM_ORCHESTRATOR_HOST_PORT:-8001}
uvicorn app.main:app --app-dir services/projector --host 0.0.0.0 --port ${MULLM_PROJECTOR_HOST_PORT:-8002}
ORCHESTRATOR_URL=${ORCHESTRATOR_URL} PROJECTOR_URL=${PROJECTOR_URL} \
  uvicorn app.main:app --app-dir services/web --host 0.0.0.0 --port ${MULLM_WEB_PORT:-3000}

API Documentation

Host ports are configured in .env (see .env.example). Defaults:

Service	URL
Web UI	${WEB_URL} → http://localhost:3003
Orchestrator	${ORCHESTRATOR_URL} → http://localhost:8001
Projector	${PROJECTOR_URL} → http://localhost:8002
Postgres	localhost:${MULLM_POSTGRES_HOST_PORT} (5433)
NATS monitor	http://localhost:`${MULLM_NATS_MONITOR_HOST_PORT}`

Orchestrator API

• POST /api/commands - Submit commands
• GET /api/queries - Execute queries
• GET /health - Health check

Projector API

• GET /projections/tasks - Task board view
• GET /projections/agents - Agent fleet status
• GET /projections/workflows - Workflow versions

Domain Model

Aggregates

• Task: Represents work units with state transitions
• Agent: AI agents with capabilities and status
• Workflow: Multi-step processes with orchestration logic

Events

• TaskCreated, TaskAssigned, TaskCompleted
• AgentRegistered, AgentStatusChanged
• WorkflowStarted, WorkflowStepCompleted

Workspace UI (panel operacyjny)

http://localhost:3003/ — cockpit: Chat + Tasks + Context + Files (nie tylko dashboard).

• Natural language → draft zadania → Utwórz / Uruchom / Kolejka
• Drag-and-drop plików → RAG + kontekst sesji
• Live feed + zdarzenia sesji

Szczegóły: docs/workspace-ui.md. Stary widok tabel: /dashboard.

Monitoring

Ports from .env: MULLM_NATS_MONITOR_HOST_PORT, MULLM_POSTGRES_HOST_PORT, MULLM_REDIS_HOST_PORT.

RAG Fabric (Sprint 6 MVP)

Wymaga w .env (patrz .env.example):

• OPENROUTER_API_KEY — embeddings + opcjonalne odpowiedzi /ask
• LLM_MODEL — model chat (np. openrouter/deepseek/deepseek-v4-pro)
• EMBEDDING_MODEL — opcjonalnie (domyślnie openai/text-embedding-3-small)

Po RegisterResource orchestrator automatycznie indeksuje treść (RAG_AUTO_INGEST=true).

• POST /api/rag/search — wyszukiwanie (embedding + FTS fallback)
• POST /api/rag/ask — odpowiedź LLM na podstawie chunków
• POST /api/rag/ingest/{resource_id} — ręczny re-ingest
• GET /projections/rag/documents — stan indeksu

docker compose --profile rag up -d

Access Fabric (Sprint 4–5 MVP)

• URI: mullm://localfs/..., mullm://http/...
• Rejestr zasobów: POST /api/access/resources/register
• Transport: POST /api/access/resources/transfer
• Probe/fetch: POST /api/access/probe, /fetch

docker compose --profile access up -d

Evolution control plane (Sprint 7–9 MVP)

System opisuje sam siebie i kontroluje zmiany:

• catalog/ — domeny, event schemas, capabilities, services, policies
• Policy engine — reguły przed ProposePlugin, aktywacją workflow (manifest, approval, metryki)
• Evaluation engine — evolution_metrics po CompleteTask / FailTask
• Experiment manager — shadow workflow (ShadowWorkflowVersion)
• API: GET /api/catalog/graph, GET /api/evolution/metrics

Szczegóły: docs/roadmap-90d.md

docker compose --profile core up -d      # orchestrator + projector + agents
docker compose --profile evolution up -d # + eventstoredb (dual write)
docker compose --profile full up -d        # cały stack (+ placeholdery access/rag)

Event store

EVENT_STORE_BACKEND	Opis
postgres (default)	Tabela events w Postgres
eventstoredb	Tylko EventStoreDB (EVENTSTORE_URL)
dual	Zapis do Postgres + mirror do EventStoreDB

pip install -r services/orchestrator/requirements-esdb.txt

Tests

./scripts/test.sh
# lub
PYTHONPATH=services/orchestrator pytest tests/ -q

Testy integracyjne z Postgres (wymaga docker compose up postgres -d):

MULLM_INTEGRATION=1 pytest tests/test_integration_postgres.py -v

API (orchestrator)

Endpoint	Opis
POST /api/commands	Ogólny envelope CQRS
POST /api/commands/tasks	CreateTask (auto_assign, shell_command)
POST /api/commands/approvals/*	Approval gate
POST /api/commands/plugins/*	Plugin lifecycle
POST /api/commands/workflows/versions/*	Wersjonowanie workflow

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes with tests
4. Submit a pull request

License

Licensed under Apache-2.0.