# pgalko/bambooai architecture

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

- Interactive diagram: https://gitdiagram.com/pgalko/bambooai
- Repository: https://github.com/pgalko/bambooai

## Overview

##### Project Type and Purpose
- BambooAI is an open-source Python library plus optional web application that enables natural-language data analysis.
- It comprises a core “agent” library (bambooai/…), a sandboxed code execution service, connectors to external LLM providers and search APIs, an optional vector DB memory, and a Flask-based web UI.

##### File Structure
- Top-level:
- Dockerfile, docker-compose.yaml → containerized deployment
- bambooai/ → core library modules
- web_app/ → Flask application, API endpoints, static assets, HTML templates
- examples/, tests/ → sample datasets and unit tests
- LLM_CONFIG_sample.json, PROMPT_TEMPLATES_sample.yaml → configuration templates
- Core library packages:
- code_executor.py, executor_client.py → local vs remote code execution
- context_retrieval.py, qa_retrieval.py → semantic search & retrieval
- messages/ → prompt templates, message orchestration
- models/ → adapters for OpenAI, Gemini, Anthropic, local models, etc.
- storage_manager.py → vector DB (Pinecone) integration
- output_manager.py, web_output_manager.py → formatting results for CLI vs Web
- google_search.py → external web search tool
- Web UI:
- app.py → Flask entrypoint
- code_executor_api.py → sandboxed execution microservice
- static/, templates/ → frontend assets

##### README Insights
- Describes a multi-agent LLM workflow: Initiation → Task Routing → Dynamic Prompt Build → Debugging/Execution → Results/Memory
- Optional components: planning agent, vector DB, ontology integration, external search
- Deployment options: local pip, Docker, full repo
- Configuration driven by .env + LLM_CONFIG.json

##### Main Components and Their Relationships
a. Users and Interfaces
- Jupyter / CLI
- Web Browser → Web UI (Flask)
b. Core BambooAI Library
- Conversation Manager → orchestrates agents
- Agents: Expert Selector, Analyzer, Theorist, Planner, Code Generator, Error Corrector, Reviewer, Summarizer, Search Executor
c. External Services
- LLM Providers (OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek, local via Ollama/VLLM)
- Google Search API or Selenium
- Vector DB (Pinecone)
d. Code Execution Service
- Local sandbox or remote API (executor_client)
- Returns execution results or errors
e. Data Sources
- Local datasets (CSV, Parquet)
- Auxiliary datasets
- Dataframe Ontology (.ttl)
f. Storage & Logging
- Log Manager → JSON logs, rotation
- Storage Manager → vector DB put/get
g. Web Application
- Flask API endpoints → /converse, /execute
- Static assets → CSS, JS modules (UI controls, workflow map, PDF export)
- Templates → index.html

##### Architectural Patterns and Design Principles
- Modular multi-agent architecture – each agent handles a specific responsibility
- Layered separation: Interface (CLI/Web) → Orchestrator (Core Library) → Execution (Code Executor) → Persistence (Vector DB, Logs)
- Configuration-driven: LLM behavior, tools enabled via .env + JSON/YAML
- Plug-and-play adapters for new LLM providers or execution modes
- Containerized sandbox for secure code execution

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef core fill:#AED6F1,stroke:#21618C
    classDef ext fill:#A9DFBF,stroke:#196F3D
    classDef exec fill:#F5B7B1,stroke:#943126
    classDef web fill:#D2B4DE,stroke:#6C3483
    classDef store fill:#D5D8DC,stroke:#566573
    classDef ui fill:#FAD7A0,stroke:#B9770E

    User(("User")):::ui
    CLI["Jupyter / CLI"]:::ui
    AppAPI["Flask App API\n(/converse, /execute)"]:::web
    CoreLib["Core BambooAI Orchestrator"]:::core
    subgraph "Core Library Modules"
        BAMBI["bambooai/bambooai.py\n(Orchestrator Entrypoint)"]:::core
        ConversationManager["Conversation Manager"]:::core
        subgraph "Agents"
            ES["Expert Selector Agent"]:::core
            AN["Analyzer Agent"]:::core
            TH["Theorist Agent"]:::core
            PL["Planner Agent"]:::core
            CG["Code Generator Agent"]:::core
            EC["Error Corrector Agent"]:::core
            RV["Reviewer Agent"]:::core
            SM["Summarizer Agent"]:::core
            SQ["Search Executor Agent"]:::core
        end
        Messages["Message Orchestration &\nPrompt Templates"]:::core
        Models["LLM Provider Adapters"]:::core
        ContextRetrieval["Context Retrieval"]:::core
        QARetrieval["QA Retrieval"]:::core
        StorageManager["Vector DB Memory\n(Pinecone)"]:::store
        GoogleSearchConnector["External Search Connector"]:::ext
        LogManager["Logging Manager"]:::store
        OutputCLI["CLI Output Formatter"]:::core
        OutputWeb["Web Output Formatter"]:::core
        TemplateFormat["Template Formatting Utilities"]:::core
        Utils["General Utilities"]:::core
    end

    subgraph "Execution Sandbox"
        CodeExecutorLocal["Local Sandbox Executor"]:::exec
        RemoteExecutor["Remote Executor Client"]:::exec
    end

    subgraph "Web Application"
        AppAPI
        ExecAPI["Sandboxed Execution Microservice"]:::exec
        StaticAssets["Static Assets\n(CSS, JS, Images)"]:::web
        Templates["HTML Templates"]:::web
    end

    Config["Configuration Files\n(.env, JSON, YAML)"]:::store
    Datasets["Datasets (CSV, Parquet)"]:::store
    Ontology["Dataframe Ontology (.ttl)"]:::store
    LLMProviders["LLM Providers\n(OpenAI, Anthropic, etc.)"]:::ext
    VectorDB["Pinecone Vector DB"]:::ext
    Container["Docker &\nDocker Compose"]:::store
    Examples["Example Datasets"]:::store
    Tests["Unit Tests"]:::store

    User --> CLI
    User --> AppAPI
    CLI --> CoreLib
    AppAPI --> CoreLib
    CoreLib --> BAMBI
    BAMBI --> ConversationManager
    ConversationManager --> ES
    ConversationManager --> AN
    ConversationManager --> TH
    ConversationManager --> PL
    ConversationManager --> CG
    ConversationManager --> EC
    ConversationManager --> RV
    ConversationManager --> SM
    ConversationManager --> SQ

    CG --> CodeExecutorLocal
    CodeExecutorLocal --> CG

    ES --> LLMProviders
    AN --> LLMProviders
    TH --> LLMProviders
    PL --> LLMProviders
    SQ --> GoogleSearchConnector
    ES --> VectorDB
    AN --> VectorDB
    TH --> VectorDB
    ES --> Ontology
    PL --> Ontology

    BAMBI --> Messages
    BAMBI --> Models
    BAMBI --> ContextRetrieval
    BAMBI --> QARetrieval
    BAMBI --> StorageManager
    BAMBI --> GoogleSearchConnector
    BAMBI --> LogManager
    BAMBI --> OutputCLI
    BAMBI --> OutputWeb
    BAMBI --> TemplateFormat
    BAMBI --> Utils

    ContextRetrieval --> Datasets
    ContextRetrieval --> Ontology
    CodeExecutorLocal --> Datasets

    OutputCLI --> CLI
    OutputWeb --> AppAPI

    CoreLib --> Config
    AppAPI --> Config

    Container --> CoreLib
    Container --> CodeExecutorLocal
    Container --> AppAPI
    Container --> ExecAPI

    Examples --> Datasets
    Tests --> BAMBI

    click BAMBI "https://github.com/pgalko/bambooai/blob/main/bambooai/bambooai.py"
    click CodeExecutorLocal "https://github.com/pgalko/bambooai/blob/main/bambooai/code_executor.py"
    click RemoteExecutor "https://github.com/pgalko/bambooai/blob/main/bambooai/executor_client.py"
    click ContextRetrieval "https://github.com/pgalko/bambooai/blob/main/bambooai/context_retrieval.py"
    click QARetrieval "https://github.com/pgalko/bambooai/blob/main/bambooai/qa_retrieval.py"
    click Messages "https://github.com/pgalko/bambooai/tree/main/bambooai/messages/"
    click Models "https://github.com/pgalko/bambooai/tree/main/bambooai/models/"
    click StorageManager "https://github.com/pgalko/bambooai/blob/main/bambooai/storage_manager.py"
    click OutputCLI "https://github.com/pgalko/bambooai/blob/main/bambooai/output_manager.py"
    click OutputWeb "https://github.com/pgalko/bambooai/blob/main/bambooai/web_output_manager.py"
    click GoogleSearchConnector "https://github.com/pgalko/bambooai/blob/main/bambooai/google_search.py"
    click LogManager "https://github.com/pgalko/bambooai/blob/main/bambooai/log_manager.py"
    click TemplateFormat "https://github.com/pgalko/bambooai/blob/main/bambooai/template_formatting.py"
    click Utils "https://github.com/pgalko/bambooai/blob/main/bambooai/utils.py"
    click AppAPI "https://github.com/pgalko/bambooai/blob/main/web_app/app.py"
    click ExecAPI "https://github.com/pgalko/bambooai/blob/main/web_app/code_executor_api.py"
    click StaticAssets "https://github.com/pgalko/bambooai/tree/main/web_app/static/"
    click Templates "https://github.com/pgalko/bambooai/tree/main/web_app/templates/"
    click Ontology "https://github.com/pgalko/bambooai/tree/main/web_app/ontologies/"
    click Config "https://github.com/pgalko/bambooai/blob/main/LLM_CONFIG_sample.json"
    click Config "https://github.com/pgalko/bambooai/blob/main/PROMPT_TEMPLATES_sample.yaml"
    click Container "https://github.com/pgalko/bambooai/tree/main/Dockerfile"
    click Container "https://github.com/pgalko/bambooai/blob/main/docker-compose.yaml"
    click Examples "https://github.com/pgalko/bambooai/tree/main/examples/"
    click Tests "https://github.com/pgalko/bambooai/tree/main/tests/"

    class User,CLI ui
    class BAMBI,ConversationManager,ES,AN,TH,PL,CG,EC,RV,SM,SQ,Messages,Models,ContextRetrieval,QARetrieval,TemplateFormat,Utils core
    class StorageManager,LogManager,Config,Datasets,Ontology,Tests,Examples,Container store
    class LLMProviders,GoogleSearchConnector,VectorDB ext
    class CodeExecutorLocal,RemoteExecutor,ExecAPI exec
    class AppAPI,StaticAssets,Templates web
```
