How gvern/blackbird works
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.”