How tathadn/parallel-multi-agent-codegen works
1. What this repo is
A Python-based, LLM-driven code generation system that turns a natural-language request into a planned set of code artifacts, generates them in parallel, integrates the outputs, then reviews and tests the result before returning a final package.
2. Main runtime entrypoint
app.py is the user-facing Streamlit application. It likely serves as the control panel for submitting requests and visualizing pipeline progress, DAG state, timings, and generated artifacts. The rest of the repository is the backend workflow that Streamlit drives.
3. Core architecture: stateful agent pipeline
The system centers on a shared typed state in models/state.py. That state carries the user request, the plan, the task DAG, produced artifacts, review/test results, logs, timing, and iteration counters. Every agent reads from and writes to this shared state, so the architecture is not request/response RPC style; it is a state machine over a single evolving workflow object.
4. Planning and decomposition layer
The pipeline starts with a Planner agent, then the Orchestrator transforms that plan into a DAG of implementation tasks. The key architectural choice is dependency-aware decomposition: files/modules that can be built independently are separated into parallel nodes, while import or schema dependencies become edges in the graph.
5. Parallel code generation layer
agents/coder.py is the concurrent worker layer. Multiple coder agents run in parallel using asyncio, each responsible for one DAG node or grouped module set. This is the main scalability boundary in the system: all independent nodes are dispatched simultaneously, reducing end-to-end latency compared with a sequential agent chain.
6. Merge and validation layer
agents/integrator.py reconciles the parallel outputs into a coherent codebase, resolving interface mismatches and import conflicts introduced by concurrent generation. After integration, agents/reviewer.py scores or critiques the result, and agents/tester.py generates/runs tests. The README indicates a revision loop: failing review/test outcomes can send only the affected DAG nodes back for regeneration rather than rebuilding everything.
7. Workflow engine
graph/pipeline.py is the orchestration definition, and the repository uses LangGraph to express conditional transitions between phases. This makes the pipeline a graph of states rather than a fixed linear script, which is important for the revision loop and for routing based on review/test outcomes.
8. LLM and tracing boundary
agents/llm_utils.py is the shared API boundary to Anthropic’s native SDK. The README highlights prompt caching via cache_control={"type": "ephemeral"} and LangSmith tracing through @traceable. This means all agent calls share one LLM transport layer, one tracing strategy, and one place for caching/cost behavior.
9. Prompting and role separation
prompts/ stores the system prompts/templates for each role. The architecture depends on role specialization: orchestrator, planner, coder, integrator, reviewer, and tester each have distinct prompt contracts and output shapes. That separation is important because the system’s correctness depends on structured outputs, not free-form chat.
10. Sandboxed execution boundary
sandbox/Dockerfile defines an isolated environment for test execution. That indicates a safety boundary between generated code and the host machine: tests run in a containerized sandbox rather than directly on the developer’s machine.
11. Testing strategy for the repo itself
The tests/ folder is focused on infrastructure correctness rather than generated-code correctness. There are tests for models, pipeline routing, LLM JSON parsing, and agent behavior using mocked LLM calls. So the repository’s own test suite validates orchestration logic, DAG scheduling, and agent contracts without requiring real Anthropic traffic.
12. Architectural summary for diagramming
If you draw this repo, the main boxes are: UI (app.py) → shared state (models/state.py) → orchestrated pipeline (graph/pipeline.py) → role-based agents (agents/*) → sandboxed testing (sandbox/) → final output and revision loop. The key data flow is request → plan → DAG → parallel worker artifacts → integration → review/test → optional targeted regeneration → final result.
Main entry points: pipeline.py Pipeline graph · state.py Workflow state · coder.py Coder pool · test_agents.py Agent tests
Components 17
UI
User-facing request submission and progress view
- Streamlit app · User interface for submitting requests and viewing pipeline progress
app.py
Core flow
Shared state and orchestration of the generation pipeline
- Workflow state · Shared evolving state carrying plan, DAG, artifacts, logs, timings, and iterations
models/state.py - Pipeline graph · LangGraph orchestration and conditional routing between phases
graph/pipeline.py
Agents
Role-specialized LLM workers and support code
- Planner · Converts the request into a structured implementation plan
agents/planner.py - Orchestrator · Transforms the plan into dependency-aware implementation tasks
agents/orchestrator.py - Coder pool · Concurrent workers that generate code for DAG nodes or module groups
agents/coder.py - Integrator · Reconciles parallel outputs into a coherent codebase
agents/integrator.py - Reviewer · Evaluates generated code and detects quality or contract issues
agents/reviewer.py - Tester · Creates and runs tests against the integrated result
agents/tester.py - LLM utils · Shared Anthropic SDK wrapper, caching, and tracing support
agents/llm_utils.py - Prompts · Role-specific prompt templates and output contracts
prompts
Runtime
Execution and validation boundaries
- Sandbox · Containerized environment for isolated test execution
sandbox/Dockerfile
Tests
Repository-level correctness checks
- Model tests · Checks the typed state and related models
tests/test_models.py - Pipeline tests · Validates orchestration and routing behavior
tests/test_pipeline.py - LLM tests · Exercises JSON parsing and LLM utility behavior with mocks
tests/test_llm_utils.py - Agent tests · Verifies agent contracts and behaviors with mocked model calls
tests/test_agents.py - Test fixtures · Shared pytest fixtures and test setup
tests/conftest.py
Connections 29
- Streamlit app → Workflow state: writes request · UI populates the shared workflow state
- Streamlit app → Pipeline graph: starts flow · Streamlit drives the orchestration pipeline
- Pipeline graph → Planner: route · Initial stage sends the request to planning
- Planner → LLM utils: calls LLM · Planner uses the shared model transport layer
- Planner → Prompts: uses prompts · Planner consumes role-specific prompt templates
- Planner → Workflow state: updates plan · Planner writes the structured plan into shared state
- Pipeline graph → Orchestrator: route · Planned work is transformed into a dependency graph
- Orchestrator → Workflow state: builds DAG · Orchestrator stores tasks and dependencies in state
- Orchestrator → Coder pool: dispatches tasks · Independent nodes are scheduled for concurrent generation
- Coder pool → LLM utils: calls LLM · Parallel workers use the shared LLM API boundary
- Coder pool → Prompts: uses prompts · Coder behavior is driven by role-specific templates
- Coder pool → Workflow state: emits artifacts · Generated code and metadata are accumulated in shared state
- Pipeline graph → Integrator: route · Parallel outputs are merged after generation
- Integrator → Workflow state: merges outputs · Integrator reconciles artifacts and updates state
- Pipeline graph → Reviewer: route · Integrated code is reviewed for correctness and quality
- Reviewer → Workflow state: scores result · Review findings and issues are written back to state
- Pipeline graph → Tester: route · Tests are generated or executed after review
- Tester → Sandbox: runs in · Testing happens inside an isolated container boundary
- Tester → Workflow state: records results · Test outcomes and failures are captured in state
- Pipeline graph → Coder pool: revise subset · Failed review or test outcomes can target only affected nodes for regeneration
- Model tests → Workflow state: verifies · Model tests validate the shared typed state
- Pipeline tests → Pipeline graph: verifies · Pipeline tests validate routing and orchestration logic
- LLM tests → LLM utils: verifies · LLM utility tests check parsing and transport behavior
- Agent tests → Planner: verifies · Agent tests cover role contracts and mocked execution
- Agent tests → Orchestrator: verifies · Agent tests cover decomposition and orchestration behavior
- Agent tests → Coder pool: verifies · Agent tests cover worker behavior and concurrency paths
- Agent tests → Integrator: verifies · Agent tests cover merge behavior and output reconciliation
- Test fixtures → Model tests: supports · Shared fixtures support repository tests
- Test fixtures → Agent tests: supports · Shared fixtures support mocked agent tests