How frostyotter/words-calculator works
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.