# gixgosu/multiagentworkshop architecture

> Architecture diagram of the GitHub repository gixgosu/multiagentworkshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gixgosu/multiagentworkshop
- Repository: https://github.com/gixgosu/multiagentworkshop

## Overview

##### Project Type & Purpose
- This repository contains two proof-of-concept multi-agent AI systems:
- Canary Swarm: A nine-agent RAG security testing framework that generates canary tokens, runs adversarial probes, detects leaks, scores risk, and produces reports.
- DM Squad: A five-agent D&D campaign generator producing stateful, table-ready session documents with consistent lore, balanced encounters, and branching narrative.
- Both systems use Python (3.8+), LangGraph for orchestration, and LLM APIs (OpenAI or Claude) to power agent logic.

##### File Structure
Top-level layout:
- README.md – Workshop overview and architecture summary
- canary_swarm/ – Code, notebooks, reports, and run scripts for Canary Swarm
- dnd_dm_squad/ – Code, prompts, and run script for DM Squad
- docs/ – Workshop summary HTML
Key sub-structures:
- canary_swarm/src/canary_swarm – Nine agent modules, schemas, graphs, runner scripts
- dnd_dm_squad/dnd_graph – Graph implementation & state management for five agents
- prompts/ (in both) – Markdown prompt templates per agent
- .ipynb notebooks (research and demo workflows)
- requirements.txt & .env.example – Dependency and environment configuration

##### Extract Architectural Insights from the README
- Multi-agent orchestration patterns: Pipeline, Supervisor (Orchestrator), Committee, Event-Driven
- Agents are highly specialized; flows are observable and modular
- Outputs: JSONL logs, JSON reports (Canary Swarm) and Markdown session docs (DM Squad)
- External dependencies: LLM APIs, optional RAG knowledge bases, dotenv config

##### Diagramming the System
- Orchestrator (central coordinator)
- Agent clusters:
– Canary Swarm agents (9 modules)
– DM Squad agents (5 modules)
- Code modules: Graph builders, prompt handlers, schemas
- Runner scripts (python –m canary_swarm.run, main.py)
- External LLM service (OpenAI/Claude)
- Data stores/files: JSONL logs, JSON reports, Markdown outputs
- Notebook interfaces (Jupyter) for research workflows
- Orchestrator → Agent X (task dispatch)
- Agent → Agent (data or state passed in pipeline)
- Agent → External LLM API (invoke LLM, receive response)
- Agent → Local storage (write logs, reports, markdown)
- Runner script → Orchestrator (kick off workflow)
c. Architectural Patterns & Principles
- Pipeline pattern: sequential agent workflows (e.g., in run_research.py)
- Supervisor pattern: Orchestrator assigns subtasks and awaits completions
- Event-driven: Agents trigger downstream agents on output events
- Modularity & Observability: each agent’s input/output is logged
- Stateless vs. Stateful: Canary Swarm is batch/stateless; DM Squad maintains state across sessions
d. Technologies, Frameworks & Libraries
- Core: Python 3.8+, LangGraph
- LLM integration: langchain-core, langchain-openai, dotenv
- Security: Python secrets module (Canary Swarm)
- Notebook support: Jupyter (.ipynb)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services and Data Stores
    ExternalLLM["External LLM API (OpenAI/Claude)"]:::cloud
    JSONLLogs["JSONL Logs"]:::cylinder
    JSONReports["JSON Reports"]:::cylinder
    MDOutputs["Markdown Session Docs"]:::document
    JupyterNotebook["Jupyter Notebooks (.ipynb)"]:::document

    %% Canary Swarm Subgraph
    subgraph "Canary Swarm"
        direction TB
        CS_Run["Orchestrator & Runner (run.py)"]:::core
        CS_Rsch_Run["Research Workflow Runner (run_research.py)"]:::core
        CS_Diff_Run["Differentiation Runner (run_differentiation.py)"]:::core
        CS_Notebook_Run["Notebook Compilation Runner (run_notebook_compilation.py)"]:::core
        CS_Graph["Graph Builder (graph.py)"]:::core
        CS_ResGraph["Research Graph (research_graph.py)"]:::core
        CS_DiffGraph["Differentiation Graph (differentiation_graph.py)"]:::core
        CS_NotebookGraph["Notebook Graph (notebook_graph.py)"]:::core

        CS_Agents["Agents Module (agents.py)"]:::agent
        CS_ResAgents["Research Agents (research_agents.py)"]:::agent
        CS_DiffAgents["Differentiation Agents (differentiation_agents.py)"]:::agent
        CS_SrcVerAgent["Source Verification Agent"]:::agent
        CS_NotebookAgents["Notebook Agents (notebook_agents.py)"]:::agent
        CS_NotebookCitationAgent["Notebook Citation Agent"]:::agent
        CS_Prompts["Prompt Templates Handler (prompts.py)"]:::agent
        CS_Schema["Data Schemas (schema.py)"]:::agent
    end

    %% DM Squad Subgraph
    subgraph "DM Squad"
        direction TB
        DM_Main["Orchestrator & CLI (main.py)"]:::core
        DM_Graph["Graph Implementation (dnd_graph/graph.py)"]:::core
        DM_State["Stateful Manager (state.py)"]:::core
        DM_LLM["LLM Integration Module (llm.py)"]:::agent
        DM_Nodes["Agent Nodes Definitions (nodes.py)"]:::agent
        DM_PromptsModule["Graph Prompt Templates (prompts.py)"]:::agent
        DM_MarkdownPrompts["Markdown Prompt Files (*.md)"]:::agent
    end

    %% Connections - Canary Swarm Flows
    CS_Run -->|"invokes"| CS_Graph
    CS_Rsch_Run -->|"invokes"| CS_ResGraph
    CS_Diff_Run -->|"invokes"| CS_DiffGraph
    CS_Notebook_Run -->|"invokes"| CS_NotebookGraph

    CS_Graph -->|"builds pipeline"| CS_Agents
    CS_ResGraph -->|"builds research pipeline"| CS_ResAgents
    CS_DiffGraph -->|"builds differentiation pipeline"| CS_DiffAgents
    CS_NotebookGraph -->|"builds notebook pipeline"| CS_NotebookAgents

    CS_Agents -->|"uses prompts"| CS_Prompts
    CS_Agents -->|"uses schema"| CS_Schema
    CS_ResAgents -->|"task dispatch"| CS_SrcVerAgent
    CS_NotebookAgents -->|"task dispatch"| CS_NotebookCitationAgent

    CS_ResAgents -->|"call"| ExternalLLM
    CS_DiffAgents -->|"call"| ExternalLLM
    CS_NotebookAgents -->|"call"| ExternalLLM

    CS_ResAgents -->|"log JSONL"| JSONLLogs
    CS_DiffAgents -->|"log JSONL"| JSONLLogs
    CS_SrcVerAgent -->|"write JSON Report"| JSONReports
    CS_NotebookCitationAgent -->|"write JSON Report"| JSONReports

    CS_Notebook_Run -->|"output notebooks"| JupyterNotebook

    %% Connections - DM Squad Flows
    DM_Main -->|"initializes"| DM_Graph
    DM_Graph -->|"manages state"| DM_State
    DM_Graph -->|"dispatch nodes"| DM_Nodes
    DM_Nodes -->|"use prompts"| DM_PromptsModule
    DM_Nodes -->|"call"| ExternalLLM
    DM_Nodes -->|"generate markdown"| MDOutputs
    DM_Main -->|"reads prompts"| DM_MarkdownPrompts

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:2px
    classDef agent fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10,stroke-width:2px
    classDef cylinder fill:#FFF2CC,stroke:#BF9000,color:#BF6000,stroke-width:2px
    classDef cloud fill:#E3F2FD,stroke:#1976D2,color:#1976D2,stroke-width:2px,stroke-dasharray: 5 5
    classDef document fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A,stroke-width:2px

    %% Click Events - Canary Swarm
    click CS_Run "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/run.py"
    click CS_Rsch_Run "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/run_research.py"
    click CS_Diff_Run "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/run_differentiation.py"
    click CS_Notebook_Run "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/run_notebook_compilation.py"
    click CS_Graph "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/graph.py"
    click CS_ResGraph "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/research_graph.py"
    click CS_DiffGraph "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/differentiation_graph.py"
    click CS_NotebookGraph "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/notebook_graph.py"
    click CS_Agents "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/agents.py"
    click CS_ResAgents "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/research_agents.py"
    click CS_DiffAgents "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/differentiation_agents.py"
    click CS_SrcVerAgent "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/source_verification_agent.py"
    click CS_NotebookAgents "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/notebook_agents.py"
    click CS_NotebookCitationAgent "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/notebook_citation_agent.py"
    click CS_Prompts "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/prompts.py"
    click CS_Schema "https://github.com/gixgosu/multiagentworkshop/blob/master/canary_swarm/src/canary_swarm/schema.py"

    %% Click Events - DM Squad
    click DM_Main "https://github.com/gixgosu/multiagentworkshop/blob/master/dnd_dm_squad/main.py"
    click DM_Graph "https://github.com/gixgosu/multiagentworkshop/blob/master/dnd_dm_squad/dnd_graph/graph.py"
    click DM_State "https://github.com/gixgosu/multiagentworkshop/blob/master/dnd_dm_squad/dnd_graph/state.py"
    click DM_LLM "https://github.com/gixgosu/multiagentworkshop/blob/master/dnd_dm_squad/dnd_graph/llm.py"
    click DM_Nodes "https://github.com/gixgosu/multiagentworkshop/blob/master/dnd_dm_squad/dnd_graph/nodes.py"
    click DM_PromptsModule "https://github.com/gixgosu/multiagentworkshop/blob/master/dnd_dm_squad/dnd_graph/prompts.py"
    click DM_MarkdownPrompts "https://github.com/gixgosu/multiagentworkshop/tree/master/dnd_dm_squad/prompts/"
```
