Diagrams

foundational_design_patterns/10_hitl/README.md

@@ -8,6 +8,29 @@ The core principle of HITL is to ensure that AI operates within ethical boundari
 
 HITL bridges the gap between fully autonomous AI systems and purely manual processes, combining the efficiency and scale of automation with the judgment, ethics, and accountability of human decision-making. Rather than viewing AI as a replacement for human workers, HITL positions AI as a tool that augments and enhances human capabilities. This augmentation can take various forms, from automating routine tasks to providing data-driven insights that inform human decisions. The end goal is to create a collaborative ecosystem where both humans and AI agents can leverage their distinct strengths to achieve outcomes that neither could accomplish alone.
 
+## Architecture
+
+```mermaid
+---
+title: Human-in-the-Loop — Content Approval
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Brief([content brief])
+    Pub([published])
+    Audit[(audit_log.json)]
+
+    Gen[LLM draft]
+    Draft[/draft/]
+    H{human review}
+
+    Brief --> Gen --> Draft --> H
+    H -- "approve" --> Pub
+    H -- "edit" --> Pub
+    H -- "reject" --> Gen
+    H -. "log decision" .-> Audit
+```
+
 ## Why Use This Pattern?
 
 Autonomous agents, while powerful, face fundamental limitations:

foundational_design_patterns/11_structured_outputs/README.md

@@ -6,6 +6,33 @@ The **Structured Outputs Pattern** treats schema-constrained output as a **core
 
 The pattern shifts validation from a brittle post-hoc step to a contract the model has to satisfy, surfacing malformed output as a typed validation error rather than a silent corruption downstream.
 
+## Architecture
+
+```mermaid
+---
+title: Structured Outputs — Schema-Enforced Extraction
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Inv([raw invoice text:<br/>'Vendor: Northwind…'])
+
+    subgraph naive ["naive path (anti-pattern)"]
+        N[prompt + regex parse]
+        Fail([runtime error:<br/>missing / wrong fields])
+        N --> Fail
+    end
+
+    subgraph typed ["schema-enforced path"]
+        S[[ExtractedInvoice<br/>Pydantic schema]]
+        LLM{{ChatOpenAI<br/>.with_structured_output}}
+        Valid([typed object:<br/>vendor · total · due_date])
+        S --> LLM --> Valid
+    end
+
+    Inv --> N
+    Inv --> S
+```
+
 ## How It Works
 
 1. **Declare the schema**: define the desired output as a Pydantic / TypeBox / Zod model. This is the single source of truth.

foundational_design_patterns/12_computer_use/README.md

@@ -2,6 +2,29 @@
 
 Browser/UI automation framing with explicit safety policy.
 
+## Architecture
+
+```mermaid
+---
+title: Computer Use — Screenshot · Think · Act · Observe
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Goal([find LLM info<br/>on Wikipedia])
+    Done([result])
+
+    subgraph loop ["control loop"]
+        Snap[/screenshot/]
+        Think[LLM reasoning]
+        Act[click · type · fetch]
+        Obs[/new page state/]
+        Snap --> Think --> Act --> Obs --> Snap
+    end
+
+    Goal --> Snap
+    Think -. "task complete" .-> Done
+```
+
 - `src/computer_use_basic.py`: screenshot-think-act-observe simulation on Wikipedia
 - `src/computer_use_advanced.py`: optional Playwright execution + safety controls
 

foundational_design_patterns/1_prompt_chain/README.md

@@ -14,6 +14,38 @@ Input → Step 1 (LLM/Logic) → Step 2 (LLM/Logic) → Step 3 (LLM/Logic) → F
         Output              Output               Output
 ```
 
+### Architecture
+
+```mermaid
+---
+title: Prompt Chain — Laptop Spec to JSON
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    In([raw text:<br/>'3.5 GHz octa-core,<br/>16GB RAM, 1TB NVMe'])
+    Out([JSON:<br/>cpu · memory · storage])
+
+    subgraph extract ["step 1 — extraction"]
+        P1[[prompt: spec extractor]]
+        L1{{ChatOpenAI}}
+        P1 --> L1
+    end
+
+    Mid[/plain-text specs/]
+
+    subgraph transform ["step 2 — transformation"]
+        P2[[prompt: JSON formatter]]
+        L2{{ChatOpenAI}}
+        P2 --> L2
+    end
+
+    In --> P1
+    L1 --> Mid --> P2
+    L2 --> Out
+```
+
+LCEL composition mirrors the diagram: `prompt | llm | parser` for each step, with the first step's output piped in as `{"specifications": extraction_chain}` to the second step's prompt ([`src/chain_prompt.py:107-130`](src/chain_prompt.py)). The intermediate plain-text extraction is **inspectable** — when the final JSON is wrong, you can tell whether extraction or formatting broke.
+
 Each step in the chain:
 1. **Receives input** from the previous step (or user)
 2. **Processes** the input through an LLM call or logic function

foundational_design_patterns/2_routing/README.md

@@ -4,6 +4,32 @@
 
 The **Routing Pattern** provides a standardized solution for building intelligent, context-aware agent systems by introducing conditional logic into an agent's operational framework.
 
+## Architecture
+
+```mermaid
+---
+title: Routing — Domain-Specific Handlers
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Q([user request])
+    R([response])
+
+    Cls{classifier<br/>LLM}
+
+    subgraph handlers ["specialist handlers"]
+        B[booking_handler]
+        I[info_handler]
+        U[unclear_handler]
+    end
+
+    Q --> Cls
+    Cls -- "booking" --> B
+    Cls -- "info" --> I
+    Cls -- "unclear" --> U
+    B & I & U --> R
+```
+
 ## How It Works
 
 The pattern operates through three key steps:

foundational_design_patterns/3_parallelization/README.md

@@ -4,6 +4,29 @@
 
 The **Parallelization Pattern** enables simultaneous execution of independent tasks within an agentic workflow, dramatically reducing total execution time by running operations concurrently rather than sequentially.
 
+## Architecture
+
+```mermaid
+---
+title: Parallelization — Concurrent LLM Chains
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Doc([document])
+    Out([unified output])
+
+    subgraph parallel ["RunnableParallel"]
+        S[summarize chain]
+        Q[question-gen chain]
+        K[key-terms chain]
+    end
+
+    Syn[[synthesize]]
+
+    Doc --> S & Q & K
+    S & Q & K --> Syn --> Out
+```
+
 ## Why Use This Pattern?
 
 Traditional sequential processing executes tasks one after another, even when those tasks don't depend on each other's outputs. This creates unnecessary bottlenecks, especially when waiting for external resources like API calls or database queries.

foundational_design_patterns/4_reflection/README.md

@@ -4,6 +4,31 @@
 
 The **Reflection Pattern** enables agentic systems to iteratively self-correct and refine their outputs through a structured feedback loop of generation, evaluation, and improvement, leading to significantly higher quality results.
 
+## Architecture
+
+```mermaid
+---
+title: Reflection — Producer · Critic · Reviser Loop
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Task([write factorial n])
+    Final([final code])
+
+    subgraph loop ["reflection loop"]
+        P[producer LLM]
+        Draft[/draft code/]
+        Cr[critic LLM]
+        Fb[/feedback/]
+        Rv[reviser LLM]
+        P --> Draft --> Cr --> Fb --> Rv
+        Rv -. "iterate" .-> Cr
+    end
+
+    Task --> P
+    Rv --> Final
+```
+
 ## Why Use This Pattern?
 
 LLMs can produce outputs that lack accuracy, miss nuances, or fail to fully satisfy complex requirements on the first attempt. While a single generation might be "good enough" for simple tasks, critical applications require outputs that are polished, accurate, and thoroughly vetted.

foundational_design_patterns/5_tool_use/README.md

@@ -4,6 +4,30 @@
 
 The **Tool Use Pattern** (also known as Function Calling) enables agentic systems to break out of the LLM's internal knowledge and interact with the external world through structured API calls, database queries, code execution, and real-world actions.
 
+## Architecture
+
+```mermaid
+---
+title: Tool Use — Support Triage with CRM and Weather
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Case([support case:<br/>CUST-1001 · Miami])
+    Resp([triage decision])
+
+    Agent{{create_agent}}
+
+    subgraph tools ["parallel tool calls"]
+        CRM[(CRM:<br/>tier · SLA)]
+        Wx[(Open-Meteo:<br/>weather)]
+    end
+
+    Case --> Agent
+    Agent --> CRM & Wx
+    CRM & Wx --> Agent
+    Agent --> Resp
+```
+
 ## Why Use This Pattern?
 
 LLMs are trained on static datasets with knowledge cutoffs, making them unable to:

foundational_design_patterns/6_planning/README.md

@@ -9,6 +9,31 @@ It’s useful when a user request requires coordination across tools, conditiona
 
 ---
 
+## Architecture
+
+```mermaid
+---
+title: Planning — Incident Response (Plan-and-Act)
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Inc([incident + context])
+    Done([resolved])
+
+    subgraph graph ["LangGraph StateGraph"]
+        Pl[planner_node]
+        Plan[/ordered actions/]
+        Ex[executor_node]
+        Rv{reviewer_node}
+        Pl --> Plan --> Ex --> Rv
+        Rv -- "next action" --> Ex
+        Rv -- "replan" --> Pl
+    end
+
+    Inc --> Pl
+    Rv -- "complete" --> Done
+```
+
 ## When to Use
 
 ### Use Planning when

foundational_design_patterns/7_multi_agent_collaboration/README.md

@@ -8,6 +8,36 @@ A useful analogy: even on a single computer, we break work into **multiple proce
 
 ---
 
+## Architecture
+
+```mermaid
+---
+title: Multi-Agent Collaboration — Research Report Pipeline
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Goal([research goal])
+    Out([final report])
+
+    subgraph orchestration ["orchestration"]
+        Pl[planner_agent]
+        Plan[/plan steps/]
+        Ex{executor_agent}
+        Pl --> Plan --> Ex
+    end
+
+    subgraph specialists ["specialist agents"]
+        R["research_agent<br/>arXiv · Tavily · Wiki"]
+        W[writer_agent]
+        Ed[editor_agent]
+    end
+
+    Goal --> Pl
+    Ex --> R & W & Ed
+    R & W & Ed -- "result" --> Ex
+    Ex --> Out
+```
+
 ## Why Use This Pattern?
 
 Single-agent systems often hit limits when tasks require:

foundational_design_patterns/8_react/README.md

@@ -6,6 +6,28 @@ The **ReAct Pattern** (Reasoning and Acting) is a synergistic approach that inte
 
 Unlike pure action-based agents that jump straight to tool use, or pure reasoning agents that only think without external interaction, ReAct combines both: the agent explicitly reasons about what to do, takes actions using tools, observes the results, and continues reasoning based on those observations.
 
+## Architecture
+
+```mermaid
+---
+title: ReAct — Reason · Act · Observe Loop
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Q([query])
+    F([final answer])
+
+    subgraph loop ["ReAct cycle"]
+        T[Thought<br/>reasoning trace]
+        A[Action<br/>tool call]
+        O[/Observation/]
+        T --> A --> O --> T
+    end
+
+    Q --> T
+    T -. "enough info" .-> F
+```
+
 ## Why Use This Pattern?
 
 Traditional approaches have limitations:

foundational_design_patterns/9_rag/README.md

@@ -6,6 +6,34 @@
 
 RAG combines the power of information retrieval systems with the generation capabilities of LLMs, creating a hybrid approach where the model answers questions based on retrieved context rather than pure memorization. This makes it particularly valuable for domain-specific applications, frequently updated information, and reducing hallucinations.
 
+## Architecture
+
+```mermaid
+---
+title: RAG — Hybrid Retrieval + Grounded Generation
+---
+%%{init: {'look':'handDrawn','theme':'base','themeVariables':{'background':'#f5ecd9','primaryColor':'#ede0bd','primaryBorderColor':'#6b4423','primaryTextColor':'#3e2723','lineColor':'#6b4423','clusterBkg':'#efe5cd','clusterBorder':'#c5b393','fontFamily':'Caveat, Patrick Hand, cursive'}}}%%
+flowchart LR
+    Q([password reset question])
+    Ans([grounded answer + sources])
+
+    subgraph retrieval ["retrieval"]
+        Idx[(support docs<br/>vector store)]
+        Ret[hybrid retriever<br/>BM25 + dense]
+        Ctx[/top-k chunks + citations/]
+        Idx -.-> Ret --> Ctx
+    end
+
+    subgraph generation ["generation"]
+        LLM{{ChatOpenAI}}
+    end
+
+    Q --> Ret
+    Ctx --> LLM
+    Q -. "+ question" .-> LLM
+    LLM --> Ans
+```
+
 ## Why Use This Pattern?
 
 Traditional LLM approaches have significant limitations: