How pvmodayil/agentic-pcb-design-assistant works
This repository implements a Python-based, agentic PCB design automation system centered on a deterministic, checkpointed workflow rather than a free-form chat application.
High-level shape
The architecture is split into four main layers:
1. Entry / orchestration layer
- src/main.py
- src/orchestrator/
- src/protocols/input_protocol.py
2. Agent core
- src/core/
- src/agents/
3. Tool execution layer
- src/tools/
- src/infrastructure/
- MCP integration via src/core/mcp_server_builder.py
4. Configuration and artifacts
- config/
- src/models/
- outputs/
The system is built around a PCB-specific agent framework, with the concrete domain example in this repo being a coupled microstrip design agent.
---
Main subsystems
1) Application entry and orchestration
src/main.py is the runtime entry point. It likely loads configuration, constructs the agent stack, and starts the workflow. The src/orchestrator/ package suggests there is a coordination boundary between:
• user input / task request
• agent state initialization
• repeated tool-usage / reasoning cycles
• checkpoint updates
• final result emission
The protocols/input_protocol.py file implies the system expects structured input contracts rather than arbitrary text blobs. This is an important diagram boundary: input normalization happens before agent execution.
2) Core agent framework
The src/core/ package contains the reusable framework pieces that all domain agents depend on:
• pcb_agent.py: abstract base agent with workflow control
• data_models.py: Pydantic models for checkpoints, actions, results, and state
• memory_manager.py: conversation / context retention and summarization
• message_builder.py: prompt/message assembly
• llm_model.py: LLM integration and model configuration
• settings.py: configuration loading
• tool_registry.py: centralized tool registration and invocation
• mcp_server_builder.py: wrapper for connecting to MCP tools
This layer is the control plane of the system. It manages state, checkpoints, and tool selection, while staying independent of any one PCB task.
3) Domain-specific agents
src/agents/coupled_microstrip_agent.py is the concrete agent implementation in the repository. It appears to specialize the generic PCB agent framework for a coupled microstrip design workflow.
This specialization likely binds:
• domain-specific checkpoints
• the correct tool set
• domain prompts / reasoning constraints
• domain result formatting
So in a diagram, this should be shown as a concrete agent instance built on top of the generic PCB agent base.
4) Tooling and computation layer
The src/tools/ package contains the actual computational capabilities exposed to the agent:
• bem_field_solver_simulator.py
• coupled_microstrip_parameter_optimizer_tool.py
These tools are likely invoked by the agent through the tool registry, and they represent the main computational boundary of the system.
The repository also includes:
• src/models/coupled_microstrip_impedance_predictor_ann.onnx
That ONNX model is an embedded local ML artifact and should be drawn as a local inference dependency used by the microstrip-related tooling or prediction pipeline.
5) External tool integration via MCP
The README states the system integrates with external tools via MCP servers, both local and remote. The code structure supports that through:
• src/core/mcp_server_builder.py
• config/tool_config/*.yaml
This indicates the agent can call:
• local stdio-based MCP servers
• remote SSE/HTTP-based MCP servers
This is a key architectural boundary: the core agent does not directly depend on every external tool implementation. Instead, it accesses them through an MCP abstraction.
6) State, memory, and checkpointing
A major design feature is checkpoint-based workflow management. The relevant pieces are:
• src/core/data_models.py
• src/core/memory_manager.py
• docs/adr/checkpointing.md
This means the workflow is not a single linear run. It is a stateful process with:
• pending checkpoints
• validation of progress
• accumulated intermediate results
• recovery / continuation support
In a diagram, this is the main persistence/state boundary.
---
Primary data flow
A typical execution path looks like this:
1. Configuration load
- YAML under config/ defines agent behavior, LLM settings, and tool wiring.
2. Request intake
- Structured input arrives via the input protocol and is passed into the orchestrator / main entry point.
3. Agent construction
- The system builds a concrete agent, such as the coupled microstrip agent, using the core PCB agent base and the selected tool set.
4. State initialization
- Checkpoints, memory, and run state are initialized from the core data models.
5. Reasoning and tool selection
- The LLM-backed agent formulates actions using prompt/message construction and memory context.
6. Tool execution
- The tool registry dispatches to local tools or MCP-connected external tools.
- Some tools may use the ONNX model or simulator/optimizer components.
7. Checkpoint update
- Results are validated and written back into the checkpoint/state model.
- The memory manager may summarize older context to keep the workflow bounded.
8. Final output
- Completed results are stored or emitted, with outputs likely landing under outputs/.
---
Important architectural boundaries
Control plane vs execution plane
• Control plane: core/, orchestrator/, checkpoint models, memory, prompt/message construction.
• Execution plane: tools/, MCP-connected services, ONNX model inference, simulators, optimizers.
This is one of the most important boundaries in the repo.
Generic framework vs domain specialization
• Generic reusable agent machinery lives in src/core/.
• Concrete PCB tasks live in src/agents/ and src/tools/.
This separation makes it possible to add new PCB agents without rewriting the workflow engine.
Internal tools vs external services
• Internal tools are implemented directly in Python under src/tools/.
• External capabilities are wrapped via MCP in mcp_server_builder.py.
This keeps the agent’s tool API stable even if the underlying service is local or remote.
Short-term context vs long-running state
• Short-term context is handled by the memory manager.
• Long-running progress is represented by checkpoints and data models.
This distinction is central to how the workflow survives multi-step design tasks.
---
Configuration and runtime assets
The config/ directory is significant to the architecture:
• config/llm_config.yaml — LLM/model selection and settings
• config/agent_config/coupled_microstrip_agent.yaml — domain agent setup
• config/tool_config/bem_field_solver_simulator.yaml
• config/tool_config/coupled_microstrip_parameter_optimizer.yaml
These files suggest the system is designed to be configuration-driven, where agent behavior and tool exposure can be changed without code changes.
The outputs/ directory is the likely sink for generated artifacts, reports, intermediate results, or simulation outputs.
---
What to draw in an architecture diagram
If you are diagramming this repo, the most accurate top-level picture is:
• A Python application entry point
• Feeding an orchestrator
• Which constructs a PCB agent framework instance
• That agent uses:
- LLM integration
- memory and checkpoint state
- tool registry
- MCP connectors
• Tools then call:
- local simulators/optimizers
- remote MCP services
- embedded ONNX inference
• Results flow back through checkpoints and memory into final outputs
---
Notable repo-specific observations
• The README describes the project as “agentic PCB design automation,” and the source tree confirms a specific domain agent for coupled microstrip work.
• The architecture emphasizes deterministic workflow control over autonomous free-form agent behavior.
• The presence of docs/adr/checkpointing.md indicates checkpointing is not incidental; it is a first-class architectural decision.
• The config/ layout suggests the repo is intended to be reconfigured for different agents/tools, even though the included implementation is centered on one PCB domain.
Main entry points: pcb_agent.py PCB agent · orchestrator Orchestrator · tool_registry.py Tool registry · coupled_microstrip_agent.py Coupled agent
Components 18
Entry & orchestration
Runtime entry, request normalization, and workflow coordination.
- Main · Application startup and top-level runtime wiring.
src/main.py - Orchestrator · Coordinates request intake, agent execution, and checkpointed run flow.
src/orchestrator - Input protocol · Structured input schema for incoming tasks.
src/protocols/input_protocol.py
Agent core
Reusable PCB agent control plane: state, prompts, LLM, and tool dispatch.
- PCB agent · Abstract workflow engine for deterministic agent execution.
src/core/pcb_agent.py - State models · Checkpoints, actions, results, and run state definitions.
src/core/data_models.py - Memory · Context retention and summarization for long-running runs.
src/core/memory_manager.py - Prompt builder · Builds LLM-facing prompts and messages from state and context.
src/core/message_builder.py - LLM model · LLM integration and model configuration wrapper.
src/core/llm_model.py - Tool registry · Registers tools and routes agent actions to executors.
src/core/tool_registry.py - MCP bridge · Constructs connections to local and remote MCP tool servers.
src/core/mcp_server_builder.py - Coupled agent · Concrete PCB agent for coupled microstrip design workflows.
src/agents/coupled_microstrip_agent.py
Execution layer
Domain computation tools, embedded models, and external tool connectivity.
- BEM solver · Field solver / simulator used by the agent for electromagnetic analysis.
src/tools/bem_field_solver_simulator.py - Optimizer · Parameter optimization tool for coupled microstrip design.
src/tools/coupled_microstrip_parameter_optimizer_tool.py - ANN model · Embedded impedance predictor used by the microstrip tooling pipeline.
src/models/coupled_microstrip_impedance_predictor_ann.onnx
Config & artifacts
Configuration inputs and generated outputs.
- Agent config · Domain agent configuration for coupled microstrip execution.
config/agent_config/coupled_microstrip_agent.yaml - LLM config · Model selection and LLM runtime settings.
config/llm_config.yaml - Tool configs · Configuration for simulator and optimizer tool wiring.
config/tool_config - Outputs · Generated reports, intermediate results, and final artifacts.
outputs
Connections 19
- Main → Orchestrator: starts · Runtime entry hands off execution to orchestration.
- Main → LLM config: loads · Startup reads model/runtime configuration.
- Orchestrator → Input protocol: normalizes · Structured request input is validated before execution.
- Orchestrator → Coupled agent: constructs · Builds the concrete domain agent for the task.
- Coupled agent → PCB agent: extends · Domain agent specializes the reusable PCB workflow engine.
- Coupled agent → Agent config: uses · Domain behavior is driven by configuration.
- Coupled agent → Tool registry: invokes · Agent actions are dispatched through the registry.
- PCB agent → State models: tracks · Workflow state and checkpoints are represented by data models.
- PCB agent → Memory: updates · Agent maintains bounded conversational context.
- PCB agent → Prompt builder: builds · Prompt and message construction for each reasoning step.
- PCB agent → LLM model: queries · LLM-backed reasoning and action selection.
- Tool registry → BEM solver: dispatches · Registry routes calls to local simulation tooling.
- Tool registry → Optimizer: dispatches · Registry routes calls to optimization tooling.
- Tool registry → MCP bridge: bridges · Registry can connect to tools exposed over MCP.
- MCP bridge → Tool configs: loads · MCP connections are configured from tool YAML.
- BEM solver → ANN model: uses · Simulation/prediction pipeline may depend on local ML inference.
- Optimizer → ANN model: uses · Optimization can incorporate the embedded predictor.
- State models → Outputs: persists · Checkpointed results and final artifacts are written out.
- Orchestrator → Outputs: emits · Completed runs produce output artifacts.