How gbaeke/pocketflow works
Project Type & Purpose
• Type: A hybrid CLI/library + microservice (Agent-to-Agent) application.
• Purpose: Generate structured tech documentation by orchestrating a serial workflow (validate → prepare → outline → research → write) using LLMs and web search.
Main Architectural Components
a. Client Layer
• CLI / direct Python invocation (python -m tech_doc_generator or library import)
• A2A Client (src/tech_doc_generator/a2a/client.py)
b. Agent Server Layer
• A2A Server (src/tech_doc_generator/a2a/server.py) running on Uvicorn (via uvicorn from requirements)
• Agent Executor (src/tech_doc_generator/agent_executor.py)
c. Core Workflow Layer
• Encapsulated Workflow Class (TechnologyDocumentGenerator in src/tech_doc_generator/utils/tech_doc_generator.py)
• Flow Orchestrator (src/tech_doc_generator/flow.py) implementing the serial execution pattern
• Nodes (src/tech_doc_generator/nodes.py):
• ValidateRequestNode
• PrepareDataNode
• CreateOutlineNode
• ResearchTechnologiesNode (AsyncParallelBatchNode)
• WriteDocumentNode
d. Utility & Integration Layer
• LLM Wrapper (src/tech_doc_generator/utils/call_llm.py) → OpenAI API
• Web Search Wrapper (src/tech_doc_generator/utils/search_web.py) → DuckDuckGo + BeautifulSoup4
• Validators (src/tech_doc_generator/validators.py)
• Constants & Exceptions (constants.py, exceptions.py)
e. External Services
• OpenAI API
• DuckDuckGo search engine (HTTP)
• Environment variables loader (python-dotenv)
Relationships & Data Flows
• User Request → CLI or A2A Client → A2A Server → Agent Executor
• Executor invokes TechnologyDocumentGenerator.invoke()
• Serial Flow:
1. ValidateRequestNode
2. PrepareDataNode
3. CreateOutlineNode → calls call_llm
4. ResearchTechnologiesNode → parallel calls to search_web and optionally call_llm
5. WriteDocumentNode → calls call_llm
• Final output → returned to client → printed or saved as Markdown
Architectural Patterns & Principles
• Serial Workflow Pattern for deterministic flow control
• Async Parallel Batch for research phase (improves throughput)
• Agent-to-Agent (A2A) for microservice decoupling
• Encapsulation via the TechnologyDocumentGenerator class
• Retry/Timeout Configuration per node (robustness)
• Clear labels: module path + responsibility (e.g., “CreateOutlineNode (calls OpenAI)”)