How neverdecel/coderag works
1. Repository shape
- This is a small Python 3.11+ application centered on a reusable coderag package, with thin entrypoints for a terminal CLI, a Streamlit UI, and background indexing/monitoring tasks.
- The project is local-first: the main persistent artifact is a FAISS index file on disk, not a remote database service.
2. Core domain boundary: coderag/
- coderag/ contains the reusable engine for retrieval-augmented code assistance.
- The main internal responsibilities are separated into configuration, embeddings, vector indexing, semantic search, and file monitoring.
- This package is the architectural center; the UI, scripts, and tests all depend on it.
3. Configuration layer
- coderag/config.py likely loads environment-driven settings such as the watched source directory, OpenAI model names, embedding dimension, and FAISS index path.
- example.env, README.md, and requirements.txt show that runtime behavior is configured externally rather than hardcoded.
4. Embedding and model boundary
- coderag/embeddings.py is the boundary to OpenAI’s embedding API.
- The system converts code text into vectors using the configured embedding model, which is the foundation for semantic retrieval.
- The README also implies GPT/chat models are used for the response-generation side of the RAG flow, though the exact orchestration likely lives elsewhere.
5. Indexing/storage subsystem
- coderag/index.py owns FAISS vector index operations and persistence.
- The index is the local storage layer for embeddings plus associated metadata, enabling fast similarity lookup without a separate vector database service.
- tests/test_faiss.py and tests/test_index.py indicate this is a major correctness boundary.
6. Search/retrieval subsystem
- coderag/search.py performs semantic search over the FAISS index.
- Query text is embedded, matched against the stored vectors, and returns the most relevant code context.
- This is the retrieval half of RAG and is likely consumed by both the CLI and the UI.
7. Real-time update subsystem
- coderag/monitor.py handles filesystem watching, probably using Watchdog as the README suggests.
- The monitor keeps the local index in sync with changes in the watched code directory, making indexing incremental rather than purely batch-oriented.
- scripts/run_monitor.py appears to be a utility for running this subsystem directly.
8. RAG orchestration
- prompt_flow.py is the likely orchestration boundary that combines retrieval output with an LLM prompt for final answers.
- The data flow is: user question → search over FAISS → retrieved code snippets/context → chat model prompt → generated response.
- This file probably sits above the lower-level package modules and coordinates end-to-end assistant behavior.
9. User-facing entrypoints
- app.py is the Streamlit frontend, giving a conversational interface over the same retrieval engine.
- main.py is the backend runner that starts indexing and monitoring, so the app can work against a live-updating index.
- coderag/cli.py and the advertised coderag-cli command expose the same functionality in terminal form.
10. Operational scripts
- scripts/initialize_index.py is a one-shot bootstrap path for creating the initial FAISS index from a codebase.
- scripts/run_monitor.py is a long-running operational script for keeping the index updated.
- These scripts separate setup/maintenance flows from the normal app entrypoints.
11. Testing and quality boundary
- tests/test_search.py, tests/test_index.py, and tests/test_faiss.py focus on the retrieval stack rather than the UI.
- .github/workflows/ci-tests.yml and .pre-commit-config.yaml show that CI and local code quality checks are part of the repository’s engineering workflow.
12. High-level data flow
- Source files in WATCHED_DIR are observed, converted into embeddings, stored in the FAISS index, and then queried by user requests.
- The retrieval result is fed into a prompt flow that prepares context for an OpenAI chat model.
- The system therefore has two main runtime paths: background indexing/monitoring and foreground query/response generation.
13. Important architecture boundaries to diagram
- External services: OpenAI embeddings/chat APIs.
- Local persistence: FAISS index file and metadata on disk.
- Long-running infrastructure: filesystem monitor/indexer process.
- Presentation layers: Streamlit UI and CLI, both consuming the same shared package logic.
Main entry points: index.py Index · search.py Search · config.py Config · prompt_flow.py Prompt flow
Components 15
Core package
Reusable retrieval and monitoring engine.
- Config · Loads runtime settings and environment-driven paths/models.
coderag/config.py - Embeddings · Converts code and queries into vectors via the embedding API.
coderag/embeddings.py - Index · Builds, updates, and persists the local vector index.
coderag/index.py - Search · Runs semantic lookup over the stored vectors and metadata.
coderag/search.py - Monitor · Watches the source tree and incrementally updates the index.
coderag/monitor.py
Interfaces
User-facing entrypoints and orchestration.
- Prompt flow · Coordinates retrieval and prompt construction for final answers.
prompt_flow.py - CLI · Command-line interface over the shared retrieval engine.
coderag/cli.py - Streamlit app · Interactive frontend for asking questions against the codebase.
app.py - Runner · Starts the background indexing and monitoring workflow.
main.py
Operations
Scripts for bootstrap and long-running sync.
- Init index · One-shot script to create the initial index from source code.
scripts/initialize_index.py - Run monitor · Long-running script for keeping the index updated.
scripts/run_monitor.py
Quality
Tests and CI coverage of core flows.
- Tests · Covers retrieval, indexing, and FAISS integration behavior.
tests
External boundaries
Model APIs and local persistence.
- OpenAI embeds · External embedding service used to vectorize code and queries.
- OpenAI chat · Generates the final assistant response from retrieved context.
- FAISS index · On-disk vector index and associated metadata storage.
Connections 20
- Config → Embeddings: model settings · Provides embedding model and API configuration.
- Config → Index: storage settings · Provides index path and embedding dimensions.
- Config → Search: runtime settings · Configures retrieval behavior and limits.
- Config → Monitor: watch settings · Provides watched directory and sync options.
- Embeddings → OpenAI embeds: calls · Uses the embedding API to encode text.
- Index → FAISS index: persists to · Stores and loads the local vector index.
- Search → Embeddings: embed query · Turns user queries into vectors before lookup.
- Search → Index: reads · Queries the indexed vectors and metadata.
- Monitor → Index: updates · Keeps the index in sync with file changes.
- Prompt flow → Search: retrieves · Pulls relevant code context for a question.
- Prompt flow → OpenAI chat: generates · Sends retrieved context to the chat model.
- CLI → Prompt flow: drives · Uses the shared RAG orchestration for terminal queries.
- Streamlit app → Prompt flow: drives · Uses the same orchestration from the UI.
- Runner → Monitor: starts · Launches the background filesystem watcher.
- Init index → Index: bootstraps · Creates the initial local index from source files.
- Init index → Embeddings: embeds · Vectorizes the initial corpus during bootstrap.
- Run monitor → Monitor: runs · Executes the monitoring loop as a standalone process.
- Tests → Index: verifies · Covers index correctness and persistence behavior.
- Tests → Search: verifies · Covers semantic retrieval behavior.
- Tests → FAISS index: verifies · Checks FAISS integration and storage semantics.