An Autonomous AI Engineering Organization as a Service — give it a prompt and it plans, builds, tests, and deploys a full-stack application using a hierarchy of specialised AI agents governed by a deterministic state machine.
"LLMs generate ideas. Systems enforce reality."
The system uses a Deterministic Orchestration Engine where LLMs are replaceable workers operating under a strict state machine. Agents never talk to each other directly — all communication flows through a structured Project State Object.
| Agent | Role |
|---|---|
| CPO | Top-level product strategist; assigns teams to projects |
| Manager | Breaks down prompts into actionable tasks |
| Architect | Generates OpenAPI specs, DB schemas, tech-stack contracts |
| Backend | Implements FastAPI services (iterative agentic loop) |
| Frontend | Implements Next.js / React UI (iterative agentic loop) |
| QA | Validates code quality and runs tests |
| DevOps | Docker & deployment configuration |
| Dynamic | Dynamically created specialist agents |
- Contract-First — No code is written until the API schema is defined.
- No Agent-to-Agent Chat — Prevents infinite loops and hallucinated agreements.
- Iterative Agentic Loop — Worker agents write files, run commands, read errors, and self-fix in a sandboxed loop (max 15 iterations, tool-repetition detection, timeout guards).
- Human-in-the-Loop (HITL) — Optional approval gates for risky operations.
- Python 3.11+
- Node.js 18+ & npm
- Docker (for Qdrant vector DB)
- An OpenAI API key (or Anthropic / Gemini)
pip install poetry
poetry installCreate a .env file in the project root:
OPENAI_API_KEY=sk-...
# Optional
ANTHROPIC_API_KEY=...
GEMINI_API_KEY=...
DEFAULT_MODEL=gpt-4o
# Infrastructure
DATABASE_URL=sqlite:///./factory.db
QDRANT_URL=http://127.0.0.1:6333
QDRANT_COLLECTION=project_documents
EMBEDDING_MODEL=text-embedding-3-small
# Observability (optional)
WANDB_API_KEY=... # Enables Weave tracing
DEBUG_MODE=truedocker compose -f docker-compose.dev.yml up -d# Development (auto-reload)
poetry run uvicorn factory.server.api:app --port 8005 --reload
# Production
poetry run uvicorn factory.server.api:app --port 8005cd web
npm install
npm run devOpen http://localhost:5173 in your browser.
# Automated end-to-end run
poetry run python scripts/verify_live_api.py# Run the latest generated project automatically
./scripts/run_latest.sh
# Or manually
poetry run python output/<project_folder>/backend/main.py├── src/factory/ # Core Python package
│ ├── agents/ # Specialised AI agents
│ │ ├── base.py # Agent base class
│ │ ├── cpo.py # Chief Product Officer
│ │ ├── manager.py # Task breakdown
│ │ ├── architect.py # Contracts & schemas
│ │ ├── backend.py # FastAPI code generation
│ │ ├── frontend.py # React/Next.js code generation
│ │ ├── qa.py # Quality assurance
│ │ ├── devops.py # Docker & deployment
│ │ └── dynamic.py # Dynamically created agents
│ ├── core/ # Config, logging, DAG engine, tool registry
│ ├── db/ # SQLAlchemy models, Alembic migrations
│ ├── llm/ # LLM client (Instructor + Weave), agentic loop
│ ├── models/ # Pydantic domain models
│ ├── repositories/ # Data-access layer
│ ├── server/ # FastAPI app & REST/WebSocket routes
│ │ └── routes/ # companies, projects, workflows, tools, etc.
│ ├── services/ # LLM service, RAG service, memory, security
│ └── tools/ # Tool system
│ ├── human_loop.py # Human-in-the-loop gates
│ └── native/ # Shell, files, network, RAG, automation
├── web/ # React + TypeScript frontend (Vite)
│ └── src/
│ ├── components/ # Dashboard, Kanban, Workflow, Terminal, etc.
│ └── pages/ # AgentsPage, WorkflowPage, IntegrationsPage
├── docs/plans/ # Design docs & implementation plans
├── scripts/ # Utility & verification scripts
├── output/ # Generated project artifacts
├── docker-compose.dev.yml # Qdrant vector DB
├── pyproject.toml # Python dependencies (Poetry)
└── COMMANDS.md # Quick-reference command guide
| Technology | Purpose |
|---|---|
| Python 3.11+ | Core language |
| FastAPI | REST API & WebSocket server |
| SQLAlchemy + Alembic | Database ORM & migrations |
| Pydantic | Data validation & settings |
| LiteLLM | Unified LLM gateway (OpenAI, Anthropic, Gemini) |
| Instructor | Structured LLM outputs (guaranteed valid JSON) |
| Weave | LLM call observability & tracing |
| Qdrant | Vector database for RAG memory |
| Technology | Purpose |
|---|---|
| React 19 + TypeScript | UI framework |
| Vite | Build tooling |
| Tailwind CSS | Styling |
| React Flow | Workflow/DAG visualisation |
| Monaco Editor | In-browser code viewer |
| Framer Motion | Animations |
The FastAPI server exposes RESTful endpoints under http://localhost:8005:
| Route Prefix | Description |
|---|---|
/companies |
Company / organisation CRUD |
/projects |
Project lifecycle management |
/groups |
Agent group management |
/individuals |
Individual agent instances |
/workflows |
Workflow definitions & executions |
/executions |
Execution tracking & graph |
/tools |
Tool registry & management |
/documents |
RAG document upload & search |
/llm |
LLM profile configuration |
/playground |
Interactive agent playground |
/agent-chat |
Agent chat interface |
/users |
User management |
Real-time events are streamed via WebSocket.
| Phase | Status | Description |
|---|---|---|
| 0 — Tracer Bullet | Complete | Prove orchestration loop with mock agents |
| 1 — MVP Core | Complete | Real agent hierarchy, async pipeline, project generation |
| 2 — Enhanced AI | Complete | Instructor, Weave, Qdrant RAG, tool system |
| 3 — Agentic Loop | Complete | Iterative write, run, fix loop for worker agents |
| 4 — Glass Factory | Complete | React Flow workflow visualiser, Monaco code studio |
| 5 — HITL & Persistence | Complete | Human-in-the-loop gates, execution persistence |
| 6 — Self-Healing & Reliability | Complete | Reliability Layer background scheduler, token budget circuit breaker, exponential backoff retries |
| 7 — Governance & Real Tools | Complete | COSTAR system prompts, Pydantic Instructor LLM retries, n8n tool bridge, same-origin static preview engine |
| 8 — Enterprise | In Progress | Multi-tenant governance, team collaboration, custom model fine-tuning |
See docs/plans/ and docs/walkthroughs/ for detailed design documents.
# Run tests
poetry run pytest
# Lint
ruff check src/factory
# Type check
mypy src/factory --ignore-missing-imports
# Clean caches
./scripts/clean.sh
# Initialize / reset database
poetry run python scripts/init_db.py
# Monitor agent activity (separate terminal)
tail -f src/factory/logs/app.logThis project is proprietary. All rights reserved.