# gvern/blackbird architecture

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

- Interactive diagram: https://gitdiagram.com/gvern/blackbird
- Repository: https://github.com/gvern/blackbird

## Overview

##### Project Type & Purpose
- Blackbird is a modular, local conversational-agent platform written in Python.
- It orchestrates multiple specialized agents (legal assistant, tech helper, etc.) via YAML configs, loads local LLMs through the Ollama CLI, stores conversational memory, and exposes both a CLI (Rich-enhanced) and optional Streamlit UI.

##### Key Architectural Components
a. Frontends
- CLI (frontend/cli.py + main.py using Rich)
- Streamlit UI (frontend/streamlit_app.py)
b. Core Logic
- Agent Manager (core/agent_manager.py) – loads agent configs, routes requests
- Local Model Wrapper (core/local_model.py) – encapsulates Ollama interactions
- Memory Store (core/memory.py) – appends & retrieves conversation history
c. Agents
- Directory per agent under agents/ (demo_agent, legal_assistant, tech_helper)
- Each with a config.yaml defining prompts, tools, memory settings
- Shared helper code in agents/tools.py (tool invocation abstractions)
d. Configuration
- Global settings (config/settings.yaml)
- Per-agent configs (agents/*/config.yaml)
e. External Services & Resources
- Ollama CLI / Ollama LLM engine (external process)
- Local GGUF model files (models/ – gitignored)
f. Tests
- Unit tests (tests/test_llm.py, test_ollama.py, test_rich.py) validating core wrappers

##### Relationships & Data Flow
1. User → Frontend (CLI or Streamlit)
2. Frontend → Agent Manager: “Which agent? What user input?”
3. Agent Manager
- Loads YAML config → instantiates agent pipeline
- Queries Memory for context
- Calls Local Model Wrapper to produce a response
- Updates Memory with user & assistant turns
4. Agent Manager → Frontend: delivers the response
5. Local Model Wrapper ↔ Ollama CLI: spawns subprocess/API calls to LLM
6. Memory persists in local files or in-memory structures (depending on config)

##### Architectural Patterns & Principles
- Plugin Pattern: each agent is a pluggable sub-directory with its own config and specialized tools
- Separation of Concerns:
- Presentation (CLI/UI)
- Orchestration (Agent Manager)
- Model abstraction (Local Model)
- Persistence (Memory)
- Config-Driven Behavior: YAML configs drive prompt templates, tool selection, memory policies
- Extensibility: Add a new agent by dropping a folder under agents/ with a config.yaml

##### Final Advice
- Iterate: start with the big picture, then drill down into the agent plug-in pattern.
- The goal is clarity on “who does what,” “where configs live,” and “how the LLM is invoked.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        CLI_frontend["CLI Frontend<br/>(Rich)"]:::frontend
        CLI_entry["CLI Entrypoint<br/>(main.py)"]:::frontend
        Streamlit["Streamlit UI"]:::frontend
    end

    %% Core Logic Layer
    subgraph "Core Logic"
        Agent_manager["Agent Manager"]:::core
        Local_model["Local Model Wrapper"]:::core
        Memory_store["Memory Store"]:::core
    end

    %% Agents Plugins
    subgraph "Agents Plugins"
        Demo_agent["Demo Agent<br/>config.yaml"]:::agent
        Legal_agent["Legal Assistant Agent<br/>config.yaml"]:::agent
        Tech_agent["Tech Helper Agent<br/>config.yaml"]:::agent
        Tools["Shared Agent Tools"]:::agent
    end

    %% Configuration
    Global_config["Global Configuration<br/>(settings.yaml)"]:::config

    %% External Service
    Ollama["Ollama CLI / LLM Engine"]:::external

    %% Tests
    subgraph "Unit Tests"
        Test_llm["test_llm.py"]:::test
        Test_ollama["test_ollama.py"]:::test
        Test_rich["test_rich.py"]:::test
    end

    %% Connections
    User -->|uses| CLI_frontend
    User -->|uses| Streamlit
    CLI_frontend -->|invokes| CLI_entry
    CLI_frontend -->|sends input to| Agent_manager
    Streamlit -->|sends input to| Agent_manager

    Agent_manager -->|loads config from| Global_config
    Agent_manager -->|loads per-agent config| Demo_agent
    Agent_manager -->|loads per-agent config| Legal_agent
    Agent_manager -->|loads per-agent config| Tech_agent
    Agent_manager -->|routes to tools| Tools

    Agent_manager -->|queries| Memory_store
    Memory_store -->|returns history| Agent_manager

    Agent_manager -->|requests completion| Local_model
    Local_model -->|spawns subprocess| Ollama
    Ollama -->|returns response| Local_model

    Local_model -->|response| Agent_manager
    Agent_manager -->|updates| Memory_store

    Agent_manager -->|sends response to| CLI_frontend
    Agent_manager -->|sends response to| Streamlit
    CLI_frontend -->|displays| User
    Streamlit -->|displays| User

    %% Click Events
    click CLI_frontend "https://github.com/gvern/blackbird/blob/main/frontend/cli.py"
    click CLI_entry "https://github.com/gvern/blackbird/blob/main/main.py"
    click Streamlit "https://github.com/gvern/blackbird/blob/main/frontend/streamlit_app.py"
    click Agent_manager "https://github.com/gvern/blackbird/blob/main/core/agent_manager.py"
    click Local_model "https://github.com/gvern/blackbird/blob/main/core/local_model.py"
    click Memory_store "https://github.com/gvern/blackbird/blob/main/core/memory.py"
    click Global_config "https://github.com/gvern/blackbird/blob/main/config/settings.yaml"
    click Demo_agent "https://github.com/gvern/blackbird/blob/main/agents/demo_agent/config.yaml"
    click Legal_agent "https://github.com/gvern/blackbird/blob/main/agents/legal_assistant/config.yaml"
    click Tech_agent "https://github.com/gvern/blackbird/blob/main/agents/tech_helper/config.yaml"
    click Tools "https://github.com/gvern/blackbird/blob/main/agents/tools.py"
    click Test_llm "https://github.com/gvern/blackbird/blob/main/tests/test_llm.py"
    click Test_ollama "https://github.com/gvern/blackbird/blob/main/tests/test_ollama.py"
    click Test_rich "https://github.com/gvern/blackbird/blob/main/tests/test_rich.py"

    %% Styles
    classDef user fill:#FFFFFF,stroke:#000000,stroke-width:1px
    classDef frontend fill:#C6E5B1,stroke:#333,stroke-width:1px
    classDef core fill:#9EC1CF,stroke:#333,stroke-width:1px
    classDef agent fill:#FDD692,stroke:#333,stroke-width:1px
    classDef config fill:#F4B183,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef test fill:#D7D3E3,stroke:#333,stroke-width:1px
```
