# frostyotter/words-calculator architecture

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

- Interactive diagram: https://gitdiagram.com/frostyotter/words-calculator
- Repository: https://github.com/frostyotter/words-calculator

## Overview

##### Project type and purpose
- This is a data-driven, full-stack Python application with a Streamlit front end.
- Purpose: provide an interactive word-analogy calculator by performing vector arithmetic on word embeddings drawn from multiple sources (local and cloud-based).

##### File structure
- Top level:
- data/20k-english-words.txt – source vocabulary for pre-computations
- pyproject.toml, requirements.txt, .python-version – build and environment config
- .gitignore, uv.lock – VCS and lockfile
- src/ directory groups concerns:
- main.py – Streamlit app entry (Presentation layer)
- ── ingest_data_to_db.py, pre_compute_embeddings.py – batch tools that load data, compute embeddings and populate the database
- ── models.py, embeddings_db.py – Data layer (ORM or direct SQL access, caching of computed embeddings)
- ── *embeddings*.py & gemini_api_service.py – Adapter modules for each embedding provider (GloVe, SBERT, OpenAI, Azure OpenAI, Cohere, Gemini)
- prompts.yaml – parameterize any prompt templates or model settings

##### Key insights from README
- Stacks used: Python 3.x, Streamlit (UI), NumPy, Gensim, PyYAML, Loguru, plus SDKs for Cohere, OpenAI, Azure OpenAI, etc.
- Workflow: user enters analogy expression → application obtains or fetches vectors → computes analogy → retrieves nearest neighbors → renders results

##### Detail and boundaries
- Config inputs (.env, prompts.yaml) feeding into adapters and orchestrator.
- “Batch Ingestion” pipeline as a separate path into the DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User (Browser)"]:::external
        UI["Streamlit UI"]:::internal
        Orchestrator["App Orchestrator & Analogy Engine"]:::internal
    end

    %% Application Logic
    subgraph "Application Logic"
        direction TB
        subgraph "Local Model Loaders" 
            direction TB
            GloVe["GloVe Loader"]:::internal
            SBERT["SBERT Loader"]:::internal
        end
        subgraph "Cloud Embedding Adapters"
            direction TB
            OpenAIAdapter["OpenAI Adapter"]:::internal
            AzureAdapter["Azure OpenAI Adapter"]:::internal
            CohereAdapter["Cohere Adapter"]:::internal
            GeminiAdapter["Gemini Adapter"]:::internal
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Models["Data Models / ORM"]:::internal
        DB[(Embeddings DB)]:::datastore
    end

    %% Batch Tools
    subgraph "Batch Ingestion & Pre-compute" 
        direction TB
        IngestTool["Ingest Data to DB"]:::batch
        PreCompute["Pre-compute Embeddings"]:::batch
        SourceData["20k-English Words"]:::batch
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        Prompts["prompts.yaml"]:::batch
        PyProject["pyproject.toml"]:::batch
        Requirements["requirements.txt"]:::batch
        PyVersion[".python-version"]:::batch
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        OpenAI["OpenAI API"]:::external
        AzureAPI["Azure OpenAI API"]:::external
        Cohere["Cohere API"]:::external
        Gemini["Gemini API"]:::external
    end

    %% Connections
    User -->|uses| UI
    UI -->|submits analogy| Orchestrator
    Orchestrator -->|load vector| GloVe
    Orchestrator -->|load vector| SBERT
    Orchestrator -->|request embedding| OpenAIAdapter
    Orchestrator -->|request embedding| AzureAdapter
    Orchestrator -->|request embedding| CohereAdapter
    Orchestrator -->|request embedding| GeminiAdapter

    GloVe -->|vector| Orchestrator
    SBERT -->|vector| Orchestrator

    OpenAIAdapter -->|API call| OpenAI
    AzureAdapter -->|API call| AzureAPI
    CohereAdapter -->|API call| Cohere
    GeminiAdapter -->|API call| Gemini

    OpenAI -->|vector| OpenAIAdapter
    AzureAPI -->|vector| AzureAdapter
    Cohere -->|vector| CohereAdapter
    Gemini -->|vector| GeminiAdapter

    %% Cache in DB
    OpenAIAdapter -->|cache vector| DB
    AzureAdapter -->|cache vector| DB
    CohereAdapter -->|cache vector| DB
    GeminiAdapter -->|cache vector| DB

    %% Analogy & Nearest Neighbor
    Orchestrator -->|compute analogy| Models
    Models -->|query NN| DB
    DB -->|results| Models
    Models -->|results| Orchestrator
    Orchestrator -->|render results| UI

    %% Batch pipeline
    SourceData --> IngestTool
    IngestTool --> PreCompute
    PreCompute --> DB

    %% Configuration usage
    Prompts --> Orchestrator
    Prompts --> OpenAIAdapter
    Prompts --> AzureAdapter
    Prompts --> CohereAdapter
    Prompts --> GeminiAdapter

    PyProject --> Orchestrator
    Requirements --> Orchestrator
    PyVersion --> Orchestrator

    %% Click Events
    click Orchestrator "https://github.com/frostyotter/words-calculator/blob/main/src/main.py"
    click Models "https://github.com/frostyotter/words-calculator/blob/main/src/models.py"
    click DB "https://github.com/frostyotter/words-calculator/blob/main/src/embeddings_db.py"
    click IngestTool "https://github.com/frostyotter/words-calculator/blob/main/src/ingest_data_to_db.py"
    click PreCompute "https://github.com/frostyotter/words-calculator/blob/main/src/pre_compute_embeddings.py"
    click GloVe "https://github.com/frostyotter/words-calculator/blob/main/src/glove_embeddings.py"
    click SBERT "https://github.com/frostyotter/words-calculator/blob/main/src/sbert_embeddings.py"
    click OpenAIAdapter "https://github.com/frostyotter/words-calculator/blob/main/src/openai_embeddings.py"
    click AzureAdapter "https://github.com/frostyotter/words-calculator/blob/main/src/azure_openai_embeddings.py"
    click CohereAdapter "https://github.com/frostyotter/words-calculator/blob/main/src/cohere_embeddings.py"
    click GeminiAdapter "https://github.com/frostyotter/words-calculator/blob/main/src/gemini_api_service.py"
    click Prompts "https://github.com/frostyotter/words-calculator/blob/main/src/prompts.yaml"
    click SourceData "https://github.com/frostyotter/words-calculator/blob/main/data/20k-english-words.txt"
    click PyProject "https://github.com/frostyotter/words-calculator/blob/main/pyproject.toml"
    click Requirements "https://github.com/frostyotter/words-calculator/blob/main/requirements.txt"
    click PyVersion "https://github.com/frostyotter/words-calculator/blob/main/.python-version"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef batch fill:#FFE0B2,stroke:#e65100,color:#e65100
    classDef datastore fill:#C8E6C9,stroke:#2e7d32,color:#2e7d32
    classDef external fill:#E0E0E0,stroke:#616161,color:#424242
```
