# doncamilom/bollama architecture

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

- Interactive diagram: https://gitdiagram.com/doncamilom/bollama
- Repository: https://github.com/doncamilom/bollama

## Overview

##### Project type and purpose
- BOLLaMa is a Python-based AI‐powered chatbot for Bayesian optimization of chemical reactions.
- It bundles a command‐line + web UI (via Gradio), an LLM interface (OpenAI API), a Bayesian optimization engine, domain tools, and optional graph‐based chemistry libraries.

##### File structure
Top-level
- app.py – main entrypoint; launches Gradio app and wires user input → backend.
- data/ – CSV of example reaction data used by tools or demos.
- pyproject.toml, setup.cfg, setup.py – packaging, dependencies, version.
- docs/ – Sphinx documentation with conf.py, makefile, rst pages.
- .github/workflows/ci.yml, tox.ini – CI/CD and testing configuration.

src/bollama/
- __init__.py – package initializer
- LLMInterface.py – abstraction over OpenAI (or other) calls
- agents.py – high‐level agents that orchestrate LLM prompts + tool calls
- bopt.py – Bayesian optimization engine that selects next experiment
- tools.py – domain‐specific utilities (e.g., graph construction via Graphein, data parsing)

tests/
- conftest.py – pytest fixtures for unit/integration tests

##### Key architectural insights from README
- UI: Gradio-based web interface launched by app.py
- External services: OpenAI API (requires API key)
- Optional libraries: graphein (molecular graphs), gradio (UI)
- Data: example CSV, but real usage is interactive, no persistent DB

##### Main components and interactions
a. User Interface layer
– Gradio Web App (app.py)
– Assets: logos, images, static CSS (if any)
b. Application layer
– Input preprocessor (clean user text)
– LLM Interface → sends prompts to OpenAI → receives completions
– Agents orchestrator → decides when to call optimization or tools
– Tools library → data loaders, graph constructors, helper functions
c. Optimization layer
– Bayesian Optimization module (bopt.py) → proposes new reaction conditions
d. Data layer
– Local CSV (data/additives_reactions.csv) used for demos or benchmarking
e. External services
– OpenAI API
– (Optional) Graphein for graph embeddings
f. CI/CD
– GitHub Actions (ci.yml) runs tests, linting

##### Architectural patterns and design principles
- Modular layering: clear separation of UI, orchestration (agents), business logic (optimization), utility tools.
- Dependency injection: app.py wires together LLMInterface, agents, bopt, tools.
- Stateless service: each user session is ephemeral; no persistent database.
- Plugin-style extensibility: you could swap out LLM backend or optimization algorithm by replacing interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::actor

    subgraph "UI Layer"
        UI["Gradio Web UI (app.py)"]:::ui
        Assets["Static Assets (assets/)"]:::ui
    end

    subgraph "Application Layer"
        IP["Input Processor"]:::orchestration
        Agents["Agents Orchestrator (agents.py)"]:::orchestration
        LLM["LLM Interface (LLMInterface.py)"]:::orchestration
        Tools["Domain Tools Library (tools.py)"]:::orchestration
        Init["Package Initialization (__init__.py)"]:::orchestration
    end

    subgraph "Optimization Layer"
        BOpt["Bayesian Optimization Engine (bopt.py)"]:::optimization
    end

    subgraph "Data Layer"
        Data["Example Reaction Data (additives_reactions.csv)"]:::data
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Graphein["Graphein Library"]:::external
    end

    subgraph "Infrastructure"
        CI["CI/CD Workflow (ci.yml)"]:::infra
        Tests["Testing Fixtures (conftest.py)"]:::infra
        Docs["Documentation (docs/)"]:::infra
        PYT["pyproject.toml"]:::infra
        CFG["setup.cfg"]:::infra
        SETUP["setup.py"]:::infra
        TOX["tox.ini"]:::infra
    end

    User --> UI
    UI --> IP
    IP --> Agents
    Agents --> LLM
    Agents --> BOpt
    Agents --> Tools
    LLM --> OpenAI
    Tools --> Graphein
    Data --> Tools
    BOpt --> Agents
    Agents --> UI
    UI --> User

    click UI "https://github.com/doncamilom/bollama/blob/main/app.py"
    click Assets "https://github.com/doncamilom/bollama/tree/main/assets/"
    click Data "https://github.com/doncamilom/bollama/blob/main/data/additives_reactions.csv"
    click LLM "https://github.com/doncamilom/bollama/blob/main/src/bollama/LLMInterface.py"
    click Agents "https://github.com/doncamilom/bollama/blob/main/src/bollama/agents.py"
    click BOpt "https://github.com/doncamilom/bollama/blob/main/src/bollama/bopt.py"
    click Tools "https://github.com/doncamilom/bollama/blob/main/src/bollama/tools.py"
    click Init "https://github.com/doncamilom/bollama/blob/main/src/bollama/__init__.py"
    click CI "https://github.com/doncamilom/bollama/blob/main/.github/workflows/ci.yml"
    click Tests "https://github.com/doncamilom/bollama/blob/main/tests/conftest.py"
    click Docs "https://github.com/doncamilom/bollama/tree/main/docs/"
    click PYT "https://github.com/doncamilom/bollama/blob/main/pyproject.toml"
    click CFG "https://github.com/doncamilom/bollama/blob/main/setup.cfg"
    click SETUP "https://github.com/doncamilom/bollama/blob/main/setup.py"
    click TOX "https://github.com/doncamilom/bollama/blob/main/tox.ini"

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef orchestration fill:#90EE90,stroke:#333,stroke-width:1px
    classDef optimization fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef infra fill:#F5DEB3,stroke:#333,stroke-width:1px
    classDef actor fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
