# spandan7724/songbird architecture

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

- Interactive diagram: https://gitdiagram.com/spandan7724/songbird
- Repository: https://github.com/spandan7724/songbird

## Overview

##### Project type and purpose
- Songbird is a terminal-first AI coding companion CLI tool written in Python. It orchestrates user conversations, invokes LLM providers, runs “professional” development tools (file operations, search, shell, todos), and persists session memory.

##### Top-level components (per the file tree and README)
- CLI Layer (`songbird/cli.py`, `songbird/commands/…`, `songbird/cli_utils.py`)
- Core Orchestrator (`songbird/orchestrator.py`, `songbird/core/…`)
- Agent & Planning (`songbird/agent/…`)
- LLM Adapter & Providers (`songbird/llm/…`)
- Tools Framework (`songbird/tools/…`)
- Memory & Persistence (`songbird/memory/…`)
- Configuration (`songbird/config/…`)
- UI Layer (`songbird/ui/…`)
- Prompts (`songbird/prompts/agent.txt`)
- Model Discovery (`songbird/discovery/…`)

##### Key interactions and data flows
- User types a command or natural-language prompt → CLI Layer parses & dispatches to Orchestrator.
- Orchestrator invokes the Agent Core, which:
- Classifies the message (`message_classifier.py`)
- Updates the conversation plan (`plan_manager.py`, `planning.py`)
- Possibly calls external Tools via the Tool Runner.
- When a natural-language turn requires LLM intelligence:
- Agent calls the unified LLM interface (`llm/unified_interface.py`)
- LLM interface selects an active provider (OpenAI, Gemini, Copilot, Ollama, etc.) using session managers (`aiohttp_session_manager.py`, `http_session_manager.py`) and provider adapters (`copilot_provider.py`, `litellm_adapter.py`).
- The external LLM returns a response.
- Tool invocation:
- Agent or CLI issues a tool call → Tool Registry (`tool_registry.py`) → Tool Runner (`tool_runner.py`) → Specific tool modules (`file_operations.py`, `grep_tool.py`, `shell_exec.py`, `todo_manager.py`, etc.)
- Tools operate on the local filesystem or shell and return results.
- Memory system:
- Every turn is recorded in History Manager (`memory/history_manager.py`).
- Memory Manager (`memory/manager.py`, `optimized_manager.py`) persists sessions per repository.
- UI Layer (`ui/ui_layer.py`) formats and streams output back to the terminal using Rich.

##### Architectural patterns and principles
- Layered modular architecture separating:
- Presentation (CLI/UI)
- Orchestration & Agent logic
- LLM abstraction
- Tools execution
- Memory persistence
- Configuration & discovery
- Plugin-style tool registry for extensibility.
- Unified adapter pattern for multiple LLM providers.
- Transactional/atomic multi-file operations with rollback.
- Event loop & signal handling for responsive CLI interactions.

##### Detailed capture of essential elements
- Interactions between sub-components (e.g., Agent → Plan Manager → Message Classifier).
- That tool calls are mediated via the Tool Registry and Runner.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"types command/prompt"| CLI

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Layer\n(songbird/cli.py)"]:::core
        CLI_UTILS["CLI Utils\n(songbird/cli_utils.py)"]:::core
        COMMANDS["Commands\n(songbird/commands/)"]:::core
    end
    CLI --> CLI_UTILS
    CLI --> COMMANDS

    %% Configuration
    CONFIG["Config Loader\n(songbird/config/config_manager.py)"]:::config
    MAPPING["Provider Mapping\n(songbird/config/provider_mapping.toml)"]:::config
    LOADER["Mapping Loader\n(songbird/config/mapping_loader.py)"]:::config
    CLI --> CONFIG
    CONFIG --> LOADER
    CONFIG --> MAPPING
    CONFIG --> ORCH

    %% Orchestrator
    subgraph "Core Orchestrator"
        ORCH["Orchestrator\n(songbird/orchestrator.py)"]:::core
        EVENT_LOOP["Event Loop Manager\n(songbird/core/event_loop_manager.py)"]:::core
        SIGNAL["Signal Handler\n(songbird/core/signal_handler.py)"]:::core
        PATCH["Loop Cleanup Patch\n(songbird/core/loop_cleanup_patch.py)"]:::core
    end
    CLI --> ORCH
    ORCH --> EVENT_LOOP
    ORCH --> SIGNAL
    ORCH --> PATCH
    ORCH --> AGENT

    %% Agent & Planning
    subgraph "Agent & Planning"
        AGENT["Agent Core\n(songbird/agent/agent_core.py)"]:::core
        CLASSIFIER["Message Classifier\n(songbird/agent/message_classifier.py)"]:::core
        PLAN_MGR["Plan Manager\n(songbird/agent/plan_manager.py)"]:::core
        PLANNING["Planning\n(songbird/agent/planning.py)"]:::core
    end
    ORCH --> AGENT
    AGENT --> CLASSIFIER
    AGENT --> PLAN_MGR
    PLAN_MGR --> PLANNING

    %% Model Discovery
    DISCOVERY["Model Discovery\n(songbird/discovery/model_discovery.py)"]:::core
    AGENT --> DISCOVERY

    %% LLM Adapter & Providers
    subgraph "LLM Adapter & Providers"
        LLM_IF["Unified Interface\n(songbird/llm/unified_interface.py)"]:::core
        PROVIDERS["Providers\n(songbird/llm/providers.py)"]:::core
        AIOSESSION["AIOHTTP Session\n(songbird/llm/aiohttp_session_manager.py)"]:::core
        HTTPSESSION["HTTP Session\n(songbird/llm/http_session_manager.py)"]:::core
        COPILOT["Copilot Provider\n(songbird/llm/copilot_provider.py)"]:::core
        LITELLM["LiteLLM Adapter\n(songbird/llm/litellm_adapter.py)"]:::core
        TYPES["Types\n(songbird/llm/types.py)"]:::core
        OPENAI["OpenAI"]:::external
        GEMINI["Gemini"]:::external
        COPILOT_EXT["Copilot"]:::external
        OLLAMA["Ollama"]:::external
    end
    AGENT --> LLM_IF
    LLM_IF --> PROVIDERS
    PROVIDERS --> AIOSESSION
    PROVIDERS --> HTTPSESSION
    PROVIDERS --> COPILOT
    PROVIDERS --> LITELLM
    PROVIDERS --> TYPES
    PROVIDERS --> OPENAI
    PROVIDERS --> GEMINI
    PROVIDERS --> COPILOT_EXT
    PROVIDERS --> OLLAMA

    %% Tools Framework
    subgraph "Tools Framework"
        TOOL_REG["Tool Registry\n(songbird/tools/tool_registry.py)"]:::tool
        TOOL_RUN["Tool Runner\n(songbird/tools/tool_runner.py)"]:::tool
        FILE_OP["File Ops\n(songbird/tools/file_operations.py)"]:::tool
        FILE_SEARCH["File Search\n(songbird/tools/file_search.py)"]:::tool
        GREP["Grep\n(songbird/tools/grep_tool.py)"]:::tool
        SHELL["Shell Exec\n(songbird/tools/shell_exec.py)"]:::tool
        TODO_MGR["Todo Manager\n(songbird/tools/todo_manager.py)"]:::tool
        TODO_TOOLS["Todo Tools\n(songbird/tools/todo_tools.py)"]:::tool
        LS["LS Tool\n(songbird/tools/ls_tool.py)"]:::tool
        TREE["Tree Tool\n(songbird/tools/tree_tool.py)"]:::tool
        MULTIEDIT["Multi-Edit\n(songbird/tools/multiedit_tool.py)"]:::tool
        GLOB["Glob Tool\n(songbird/tools/glob_tool.py)"]:::tool
        SEM_CONF["Semantic Config\n(songbird/tools/semantic_config.py)"]:::tool
        SEM_MATCH["Semantic Matcher\n(songbird/tools/semantic_matcher.py)"]:::tool
        EXECUTOR["Executor\n(songbird/tools/executor.py)"]:::tool
    end
    AGENT --> TOOL_REG
    TOOL_REG --> TOOL_RUN
    TOOL_RUN --> FILE_OP
    TOOL_RUN --> FILE_SEARCH
    TOOL_RUN --> GREP
    TOOL_RUN --> SHELL
    TOOL_RUN --> TODO_MGR
    TOOL_RUN --> TODO_TOOLS
    TOOL_RUN --> LS
    TOOL_RUN --> TREE
    TOOL_RUN --> MULTIEDIT
    TOOL_RUN --> GLOB
    TOOL_RUN --> SEM_CONF
    TOOL_RUN --> SEM_MATCH
    TOOL_RUN --> EXECUTOR

    %% Memory & Persistence
    subgraph "Memory & Persistence"
        HISTORY["History Manager\n(songbird/memory/history_manager.py)"]:::pers
        MEM_MGR["Memory Manager\n(songbird/memory/manager.py)"]:::pers
        OPT_MGR["Optimized Manager\n(songbird/memory/optimized_manager.py)"]:::pers
        MODELS["Models\n(songbird/memory/models.py)"]:::pers
        STORAGE["Session Storage\n(JSON files)"]:::pers
    end
    ORCH --> HISTORY
    ORCH --> MEM_MGR
    MEM_MGR --> OPT_MGR
    MEM_MGR --> MODELS
    MEM_MGR --> STORAGE

    %% UI Layer
    subgraph "UI Layer"
        UI["UI Layer\n(songbird/ui/ui_layer.py)"]:::ui
        DATA_XFER["Data Transfer\n(songbird/ui/data_transfer.py)"]:::ui
    end
    AGENT --> UI
    UI --> DATA_XFER
    UI --> User

    %% Prompts
    PROMPTS["Agent Prompts\n(songbird/prompts/agent.txt)"]:::config
    AGENT --> PROMPTS

    %% Styling
    classDef core fill:#D0E1F9,stroke:#333,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef tool fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef pers fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef config fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef ui fill:#E1D5E7,stroke:#333,stroke-width:1px

    %% Click events
    click CLI "https://github.com/spandan7724/songbird/blob/main/songbird/cli.py"
    click CLI_UTILS "https://github.com/spandan7724/songbird/blob/main/songbird/cli_utils.py"
    click COMMANDS "https://github.com/spandan7724/songbird/tree/main/songbird/commands/"
    click CONFIG "https://github.com/spandan7724/songbird/blob/main/songbird/config/config_manager.py"
    click LOADER "https://github.com/spandan7724/songbird/blob/main/songbird/config/mapping_loader.py"
    click MAPPING "https://github.com/spandan7724/songbird/blob/main/songbird/config/provider_mapping.toml"
    click ORCH "https://github.com/spandan7724/songbird/blob/main/songbird/orchestrator.py"
    click EVENT_LOOP "https://github.com/spandan7724/songbird/blob/main/songbird/core/event_loop_manager.py"
    click SIGNAL "https://github.com/spandan7724/songbird/blob/main/songbird/core/signal_handler.py"
    click PATCH "https://github.com/spandan7724/songbird/blob/main/songbird/core/loop_cleanup_patch.py"
    click AGENT "https://github.com/spandan7724/songbird/blob/main/songbird/agent/agent_core.py"
    click CLASSIFIER "https://github.com/spandan7724/songbird/blob/main/songbird/agent/message_classifier.py"
    click PLAN_MGR "https://github.com/spandan7724/songbird/blob/main/songbird/agent/plan_manager.py"
    click PLANNING "https://github.com/spandan7724/songbird/blob/main/songbird/agent/planning.py"
    click DISCOVERY "https://github.com/spandan7724/songbird/blob/main/songbird/discovery/model_discovery.py"
    click LLM_IF "https://github.com/spandan7724/songbird/blob/main/songbird/llm/unified_interface.py"
    click PROVIDERS "https://github.com/spandan7724/songbird/blob/main/songbird/llm/providers.py"
    click AIOSESSION "https://github.com/spandan7724/songbird/blob/main/songbird/llm/aiohttp_session_manager.py"
    click HTTPSESSION "https://github.com/spandan7724/songbird/blob/main/songbird/llm/http_session_manager.py"
    click COPILOT "https://github.com/spandan7724/songbird/blob/main/songbird/llm/copilot_provider.py"
    click LITELLM "https://github.com/spandan7724/songbird/blob/main/songbird/llm/litellm_adapter.py"
    click TYPES "https://github.com/spandan7724/songbird/blob/main/songbird/llm/types.py"
    click TOOL_REG "https://github.com/spandan7724/songbird/blob/main/songbird/tools/tool_registry.py"
    click TOOL_RUN "https://github.com/spandan7724/songbird/blob/main/songbird/tools/tool_runner.py"
    click FILE_OP "https://github.com/spandan7724/songbird/blob/main/songbird/tools/file_operations.py"
    click FILE_SEARCH "https://github.com/spandan7724/songbird/blob/main/songbird/tools/file_search.py"
    click GREP "https://github.com/spandan7724/songbird/blob/main/songbird/tools/grep_tool.py"
    click SHELL "https://github.com/spandan7724/songbird/blob/main/songbird/tools/shell_exec.py"
    click TODO_MGR "https://github.com/spandan7724/songbird/blob/main/songbird/tools/todo_manager.py"
    click TODO_TOOLS "https://github.com/spandan7724/songbird/blob/main/songbird/tools/todo_tools.py"
    click LS "https://github.com/spandan7724/songbird/blob/main/songbird/tools/ls_tool.py"
    click TREE "https://github.com/spandan7724/songbird/blob/main/songbird/tools/tree_tool.py"
    click MULTIEDIT "https://github.com/spandan7724/songbird/blob/main/songbird/tools/multiedit_tool.py"
    click GLOB "https://github.com/spandan7724/songbird/blob/main/songbird/tools/glob_tool.py"
    click SEM_CONF "https://github.com/spandan7724/songbird/blob/main/songbird/tools/semantic_config.py"
    click SEM_MATCH "https://github.com/spandan7724/songbird/blob/main/songbird/tools/semantic_matcher.py"
    click EXECUTOR "https://github.com/spandan7724/songbird/blob/main/songbird/tools/executor.py"
    click HISTORY "https://github.com/spandan7724/songbird/blob/main/songbird/memory/history_manager.py"
    click MEM_MGR "https://github.com/spandan7724/songbird/blob/main/songbird/memory/manager.py"
    click OPT_MGR "https://github.com/spandan7724/songbird/blob/main/songbird/memory/optimized_manager.py"
    click MODELS "https://github.com/spandan7724/songbird/blob/main/songbird/memory/models.py"
    click UI "https://github.com/spandan7724/songbird/blob/main/songbird/ui/ui_layer.py"
    click DATA_XFER "https://github.com/spandan7724/songbird/blob/main/songbird/ui/data_transfer.py"
    click PROMPTS "https://github.com/spandan7724/songbird/blob/main/songbird/prompts/agent.txt"
```
