# biocypher/biochatter architecture

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

- Interactive diagram: https://gitdiagram.com/biocypher/biochatter
- Repository: https://github.com/biocypher/biochatter

## Overview

##### Project Type and Purpose
- BioChatter is an open-source, full-stack Python library (with optional UIs) designed to connect biomedical applications to conversational AI.
- It provides a generic backend (core “biochatter” package), pluggable LLM connectors, knowledge-graph/RAG support, and a living benchmark suite under “benchmark/”.

##### File Structure Analysis
- Top-level:
- configuration files (.gitignore, pyproject.toml, Docker Compose)
- benchmark/ – data, notebooks, test harness, results pipelines
- biochatter/ – the core library, subdivided into:
– api_agent/ (web + Python wrappers for external bio-tools)
– llm_connect/ (adapters for OpenAI, Anthropic, Gemini, etc.)
– rag_agent.py, vectorstore_agent.py, query_interaction.py, prompts.py, etc.
- docs/ – MkDocs source for user/developer guides and API reference
- scripts/, test/, .github/workflows – CI, publishing, and utility scripts
- Patterns:
- Modular plugin architecture (each LLM provider in its own module)
- Agent-based services (api_agent, rag_agent, selector_agent)
- Benchmark harness orchestrates loading datasets → calling core API → gathering/processing results

##### README Insights
- Core features: LLM integration, BioCypher KG connectivity, benchmarking framework, optional extras (xinference, podcast, streamlit).
- Mentions Ecosystem: separate frontends (“BioChatter Light”, “Next.js”), REST API server in other repos.

1. Client Layer
- CLI/scripts (scripts/)
- Optional UIs: Streamlit / BioChatter Light / Next.js
2. Core Library (“biochatter” package)
- QueryInteraction & SelectorAgent
- PromptManager (prompts.py)
- Agents:
- API Agents (biochatter/api_agent)
- RAG Agent (rag_agent.py) → uses VectorstoreAgent
- LLM Connectors (biochatter/llm_connect)
- Database Agent (database_agent.py)
3. Data & Storage
- BioCypher Knowledge Graph (external service)
- Vector Store (e.g., Milvus)
- Benchmark Data + Results (benchmark/data, benchmark/results)
4. External Services
- LLM Providers: OpenAI, Anthropic, Gemini, Ollama, Xinference, etc.
- Web APIs: BLAST, ONCOKB, other bio-tools
5. CI/CD & Docs
- GitHub Actions (ci.yaml, docs.yaml, publish.yaml)
- MkDocs
- Client → Core Library: “submit query / run benchmark”
- Core Library → PromptManager: “construct prompt”
- Core Library → LLM Connectors → LLM Providers: “LLM API call / response”
- Core Library → API Agents → Bio-tools / KG: “data retrieval”
- RAG Agent → VectorstoreAgent → Vector Store: “embedding search”
- Benchmark Harness → Core Library → Results → benchmark/results/processed
- CI/CD → Tests (test/) & Docs → Deployment
c. Architectural Patterns & Principles
- Plugin pattern for LLM/connectors (loose coupling)
- Agent pattern for chaining behaviors (api_agent, rag_agent, selector_agent)
- Layered architecture: Client → Service Layer → Data Layer → External
- Separation of concerns between core logic and benchmarking/visualization
d. Key Technologies / Frameworks
- Python modules & setuptools/poetry (pyproject.toml)
- pytest (tests, conftest.py)
- MkDocs + Material theme (docs/)
- Docker / Docker-Compose for optional deployment (docker-compose.yml, milvus-docker-compose.yml)
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        CLI["CLI / Scripts"]:::client
        Streamlit["Streamlit UI (optional)"]:::client
        Light["BioChatter Light UI"]:::client
        NextJS["Next.js UI"]:::client
    end

    %% Core Library
    subgraph "Core Library (biochatter)" 
        QI["QueryInteraction"]:::core
        SA["SelectorAgent"]:::core
        PM["PromptManager"]:::core
        subgraph "Agents"
            APIAG["API Agents"]:::core
            RAG["RAGAgent"]:::core
            VSA["VectorstoreAgent"]:::core
            DA["DatabaseAgent"]:::core
            KGAG["KG Agent"]:::core
        end
        subgraph "LLM Connectors"
            LLMC["LLM Connectors"]:::core
        end
        VSC["Vectorstore Client"]:::core
        Podcast["Podcast/TTS (optional)"]:::core
    end

    %% Data & Storage
    subgraph "Data & Storage"
        KGService["BioCypher KG"]:::external
        VectorStore["Vector Store"]:::external
    end

    %% Benchmark Suite
    subgraph "Benchmark Suite" 
        BD["Benchmark Data"]:::benchmark
        BH["Benchmark Harness"]:::benchmark
        BR["Processed Results"]:::benchmark
    end

    %% External Services
    subgraph "External Services"
        subgraph "LLM Providers"
            OpenAI["OpenAI"]:::external
            Anthropic["Anthropic"]:::external
            Gemini["Gemini"]:::external
            Ollama["Ollama"]:::external
            Xinference["Xinference"]:::external
        end
        subgraph "Web APIs / Bio-tools"
            BLAST["BLAST"]:::external
            ONCOKB["ONCOKB"]:::external
            OtherBio["Other Bio-tools"]:::external
        end
    end

    %% CI/CD & Docs
    subgraph "CI/CD & Docs"
        CI["GitHub Actions Workflows"]:::ci
        Docs["MkDocs Documentation"]:::ci
    end

    %% Connections
    CLI -->|"submit query/run benchmark"| QI
    CLI -->|runs| BH

    Streamlit -->|submit query| QI
    Light -->|submit query| QI
    NextJS -->|submit query| QI

    BH -->|load dataset| BD
    BD -->|dataset| BH
    BH -->|invoke core API| QI
    QI -->|return results| BH
    BH -->|produce| BR

    QI -->|"calls"| SA
    QI -->|"calls"| PM
    PM -->|"construct prompt"| LLMC
    LLMC -->|"LLM request/response"| OpenAI
    LLMC -->|"LLM request/response"| Anthropic
    LLMC -->|"LLM request/response"| Gemini
    LLMC -->|"LLM request/response"| Ollama
    LLMC -->|"LLM request/response"| Xinference

    QI -->|"uses"| APIAG
    APIAG -->|"data retrieval"| BLAST
    APIAG -->|"data retrieval"| ONCOKB
    APIAG -->|"data retrieval"| OtherBio
    APIAG -->|"KG query"| KGService

    RAG -->|"uses"| VSA
    VSA -->|"embedding search"| VectorStore

    QI -->|"may call"| RAG
    QI -->|"may call"| DA
    QI -->|"may call"| KGAG
    QI -->|"may call"| VSC
    QI -->|"may call"| Podcast

    CI -->|runs tests| BH
    CI -->|build docs| Docs

    %% Click Events
    click CLI "https://github.com/biocypher/biochatter/tree/main/scripts/"
    click QI "https://github.com/biocypher/biochatter/blob/main/biochatter/query_interaction.py"
    click SA "https://github.com/biocypher/biochatter/blob/main/biochatter/selector_agent.py"
    click PM "https://github.com/biocypher/biochatter/blob/main/biochatter/prompts.py"
    click APIAG "https://github.com/biocypher/biochatter/tree/main/biochatter/api_agent/"
    click RAG "https://github.com/biocypher/biochatter/blob/main/biochatter/rag_agent.py"
    click VSA "https://github.com/biocypher/biochatter/blob/main/biochatter/vectorstore_agent.py"
    click LLMC "https://github.com/biocypher/biochatter/tree/main/biochatter/llm_connect/"
    click DA "https://github.com/biocypher/biochatter/blob/main/biochatter/database_agent.py"
    click KGAG "https://github.com/biocypher/biochatter/blob/main/biochatter/kg_langgraph_agent.py"
    click VSC "https://github.com/biocypher/biochatter/blob/main/biochatter/vectorstore.py"
    click Podcast "https://github.com/biocypher/biochatter/blob/main/biochatter/podcast.py"
    click BD "https://github.com/biocypher/biochatter/tree/main/benchmark/data/"
    click BR "https://github.com/biocypher/biochatter/tree/main/benchmark/results/processed/"
    click CI "https://github.com/biocypher/biochatter/tree/main/.github/workflows/"
    click Docs "https://github.com/biocypher/biochatter/tree/main/docs/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef external fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef benchmark fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef client fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px;
```
