Skip to content

Integration Guide#

This guide explains how the diagrams are organized, how to read them, and how they map to the Serapeum source code.

See also: the Diagram Legend for notation and color coding.

Where the diagrams live#

All Mermaid source files are stored under docs/architecture/ in subfolders:

  • overview/: System context and component diagrams
  • class-diagrams/: Class hierarchies for LLMs, Tools, and Prompts
  • sequence-diagrams/: Common workflows
  • data-flow/: Data transformations through the system
  • state-machines/: Stateful lifecycles (tools, streaming)
  • deployment/: Integration and dependency graphs

The Diagrams page (Architecture → Diagrams) assembles these with snippet includes, so when you update any .mmd file, the page automatically reflects it.

How to read them#

  • System Context and Components provide the big picture. Start there.
  • Class diagrams show inheritance and key methods to understand extension points.
  • Sequence diagrams are best to follow runtime behavior in common scenarios.
  • Data flows trace how inputs become outputs.
  • State machines show lifecycle and error transitions.
  • Deployment and dependency diagrams show integration boundaries and layering.

Mapping to code#

Key modules in src/serapeum/ and their corresponding diagram nodes:

  • core.base.llms: BaseLLM interface and data models (Message, ChatResponse, CompletionResponse)
  • core.llms: LLM orchestration (LLM, FunctionCallingLLM, StructuredOutputLLM)
  • core.tools: Tool system (CallableTool and related models)
  • core.llms.orchestrators: Tool orchestration (ToolOrchestratingLLM)
  • core.prompts: Prompt templates (PromptTemplate, ChatPromptTemplate)
  • core.chat: Agent chat responses
  • ollama: Concrete Ollama backend

Use the class diagrams to locate classes and see which methods to implement or override when extending the framework (e.g., adding a new LLM backend implements BaseLLM/LLM behaviors per the Strategy pattern).

Design patterns#

  • Strategy: LLM backends implement a shared interface.
  • Adapter: Sync/async conversion for tools and calls.
  • Template Method: Prompt templates expose formatting hooks.
  • Factory: CallableTool creation from functions/models.
  • Decorator/Wrapper: StructuredOutputLLM wraps an LLM to produce validated outputs.

Streaming and async#

Both sync and async streaming paths are illustrated in the streaming-flow data flow and the streaming-states state machine. Use these to reason about buffering, parsing, and completion in both modes.

Making changes#

  • Update the relevant .mmd file under docs/architecture/...
  • Keep labels simple (avoid parentheses in node labels for flowcharts).
  • Prefer short node IDs and readable labels.
  • Validate changes by building the docs with mkdocs serve.