# mcherukara/calms architecture

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

- Interactive diagram: https://gitdiagram.com/mcherukara/calms
- Repository: https://github.com/mcherukara/calms

## Overview

##### Project type and purpose
- CALMS is a retrieval- and tool-augmented large language model application tailored for scientific workflows.
- It consists of a backend Python service (chat_app.py + llms.py + utility modules) exposing a web‐based UI for interactive chat, a document ingestion pipeline (web_scraper → DOC_STORE), and integration with external APIs (OpenAI, Materials Project).

##### File structure
- Top-level code:
- chat_app.py – main web service / UI entrypoint
- llms.py – wrappers for OpenAI or HuggingFace LLM calls
- dfrac_tools.py, params.py – tool-support, configuration
- tokenizer/… – local tokenizer resources for HF models
- Data layer:
- DOC_STORE/… – raw text files organized by source, pre-computed embedding store
- Ingestion pipeline:
- web_scraper/… – scripts to scrape and populate DOC_STORE
- Auxiliary code:
- ops_demo/… – demo utilities
- dev_tests_and_results/… – testing and experiments
- Config & dependencies:
- requirements_H100.txt, requirements.txt – Python packages
- LICENSE, README.md

##### README for additional insights
- CALMS supports two operation modes:
- --openai: calls OpenAI endpoints (requires API key)
- --hf: runs open-source models (Vicuna, requires GPU)
- First-run requires embedding computation over DOC_STORE (init_docs in params.py).
- UI exposed via HTTP on configurable ports.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Web Browser"]:::ui
    ChatApp["Chat Application Server\n(chat_app.py)"]:::backend
    Retrieval["Retrieval Engine & Embedding Store\n(DOC_STORE/)"]:::data
    subgraph "LLM Execution Layer"
        OpenAI["OpenAI API"]:::external
        HF["HuggingFace Inference\n(on-prem GPU)"]:::backend
        Tokenizer["Tokenizer Resources\n(tokenizer/vicuna-13b-v1.5-16k/)"]:::backend
    end
    Tools["Tool Modules\n(dfrac_tools.py)"]:::backend
    Demo["Auxiliary Demo Tools\n(ops_demo/)"]:::backend
    Ingestion["Ingestion Pipeline\n(web_scraper/)"]:::offline
    Config["Configuration Store\n(params.py)"]:::config
    Requirements["Dependency Specifications\n(requirements*.txt)"]:::config
    Baseline["Baseline Prompt Examples\n(baseline_questions.txt)"]:::config
    Legacy["Legacy Notebooks & Scripts\n(old_scripts/)"]:::offline
    Tests["Testing & Experimental Code\n(dev_tests_and_results/)"]:::offline
    Materials["Materials Project API"]:::external

    User -->|HTTP Request| ChatApp
    ChatApp -->|vector query| Retrieval
    Retrieval -->|top-k contexts| ChatApp
    ChatApp -->|prompt + context| OpenAI
    ChatApp -->|prompt + context| HF
    HF -->|uses| Tokenizer
    ChatApp -->|invoke| Tools
    Tools -->|results| ChatApp
    ChatApp -->|demo utilities| Demo
    Ingestion -->|populates embeddings| Retrieval
    Config --> ChatApp
    Config --> Ingestion
    Config --> OpenAI
    Config --> HF
    Requirements -.-> ChatApp
    Requirements -.-> Ingestion
    Requirements -.-> HF
    Baseline --> ChatApp
    Legacy --> ChatApp
    Tests -.-> ChatApp
    Tests -.-> Ingestion
    ChatApp -->|external data| Materials

    classDef ui fill:#b2f2bb,stroke:#333
    classDef backend fill:#a5d8ff,stroke:#333
    classDef data fill:#c3fae8,stroke:#333
    classDef offline fill:#ffd8a8,stroke:#333
    classDef config fill:#eebefa,stroke:#333
    classDef external fill:#d3d3d3,stroke:#333

    click ChatApp "https://github.com/mcherukara/calms/blob/main/chat_app.py"
    click llm "https://github.com/mcherukara/calms/blob/main/llms.py"
    click Tokenizer "https://github.com/mcherukara/calms/tree/main/tokenizer/vicuna-13b-v1.5-16k/"
    click Tools "https://github.com/mcherukara/calms/blob/main/dfrac_tools.py"
    click Demo "https://github.com/mcherukara/calms/tree/main/ops_demo/"
    click Config "https://github.com/mcherukara/calms/blob/main/params.py"
    click Ingestion "https://github.com/mcherukara/calms/tree/main/web_scraper/"
    click Retrieval "https://github.com/mcherukara/calms/tree/main/DOC_STORE/"
    click Tests "https://github.com/mcherukara/calms/tree/main/dev_tests_and_results/"
    click Requirements "https://github.com/mcherukara/calms/blob/main/requirements.txt"
    click Requirements "https://github.com/mcherukara/calms/blob/main/requirements_H100.txt"
    click Baseline "https://github.com/mcherukara/calms/blob/main/baseline_questions.txt"
    click Legacy "https://github.com/mcherukara/calms/tree/main/old_scripts/"
```
