How mishanya-maestro/electionrag works
1. What this repo is
- This is a Russian-language legal-document RAG system for Belarusian нормативные правовые акты.
- The core purpose is to answer questions from a fixed corpus of laws using retrieval over indexed text plus an LLM.
2. Primary data source
- The canonical input corpus lives in data/*.txt and data/*_raw.txt.
- Each file corresponds to a specific legal act listed in README.md such as KONrb.txt, IZKrb.txt, SMIrb.txt, etc.
- The raw/clean split suggests a preprocessing boundary between source text normalization and downstream indexing.
3. Ingestion and text preparation
- src/parser.py, src/clean.py, src/ingest.py, and src/generate_fulltext.py form the document-prep pipeline.
- Their role is likely to parse legal text structure, clean formatting, split into searchable units, and materialize derived artifacts.
- src/check_sequence.py and src/validate_golden.py suggest integrity checks over article ordering and a validation pass against expected outputs.
4. Two indexing backends
- The repository persists retrieval data in chroma_db/ and chroma_db_new/, which are Chroma vector stores.
- It also contains fulltext.db, indicating a separate full-text search layer, likely SQLite-based.
- This implies a hybrid retrieval architecture: vector similarity for semantic search and keyword/full-text search for exact legal references.
5. Embedding layer
- src/embeddings.py is the boundary where text chunks are converted into vectors.
- Those embeddings feed the Chroma collections stored on disk, enabling semantic retrieval across the legal corpus.
6. Retrieval pipeline
- src/retrieval.py appears to orchestrate candidate selection from the indexed corpus.
- src/fts_index.py likely integrates the full-text index, while src/reranker.py refines initial hits into a better-ranked context set.
- The retrieval stage is probably the main decision point that combines semantic and lexical evidence before generation.
7. Answer generation
- src/generator.py is the generation boundary, taking retrieved context and producing the final answer.
- The README’s “Обычный” mode indicates a standard RAG flow: retrieval first, then LLM response grounded in the selected legal passages.
- The “Сравнение” mode implies the generator can also call the same LLM without retrieved context, for side-by-side comparison.
8. Web application layer
- src/flask_app.py exposes the system as a Flask web UI.
- Frontend assets live in src/static/ and src/templates/, with index.html and source.html defining the main views.
- src/static/app.js and styles.css provide client-side interaction and presentation, but the architecture remains server-rendered Flask with static assets.
9. Operational workflow
- The normal flow is: raw legal texts in data/ → preprocessing/cleaning → full-text and vector indexing → retrieval/reranking → LLM generation → UI display.
- The stored databases mean the app can run locally without reprocessing the corpus on every launch.
10. Evaluation and regression testing
- data/golden_eval.json is an evaluation fixture for expected retrieval or answer behavior.
- src/eval_retrieval.py and src/test.py indicate offline quality checks for retrieval behavior, likely used to compare index versions or tuning changes.
- This matters architecturally because the repo is not just an app; it also includes a measurement loop for retrieval quality.
11. Configuration and environment
- src/config.py centralizes runtime settings.
- The presence of .env suggests external configuration for model/API access or local paths.
- This separates deployment/runtime concerns from the indexing and app code.
12. Key architectural boundaries to draw
- Boundary 1: source documents vs derived search artifacts.
- Boundary 2: indexing layer vs online query-serving layer.
- Boundary 3: retrieval/reranking vs generation.
- Boundary 4: web UI vs backend search/LLM pipeline.
- Boundary 5: offline evaluation scripts vs production request handling.
13. What is persistent vs ephemeral
- Persistent: legal text files, Chroma stores, fulltext.db, and golden evaluation data.
- Ephemeral: Flask request handling, retrieval contexts, reranked candidate lists, and generated answers.
- The architecture is therefore data-driven and locally stateful rather than stateless cloud-native.
14. Overall system shape
- This repo is best understood as a local RAG application over a curated legal corpus, with dual retrieval backends and a Flask front end.
- The most important diagram elements are the corpus, preprocessing/indexing pipeline, Chroma + FTS stores, retrieval/reranking, LLM generation, and the comparison-oriented UI.
Main entry points: retrieval.py Retriever · ingest.py Ingest · embeddings.py Embeddings · flask_app.py Flask app
Components 24
Corpus & artifacts
Canonical legal texts and persisted derived search data.
- Raw laws · Source legal-act text files before normalization.
data - Clean laws · Processed legal-act texts used for downstream indexing.
data - Chroma store · Persisted semantic retrieval backend.
chroma_db - New Chroma · Alternative or rebuilt vector store for retrieval experiments.
chroma_db_new - FTS db · Persistent keyword/full-text retrieval layer.
fulltext.db
Document prep
Parsing, cleaning, validation, and index building.
- Parser · Parses legal documents into structured units.
src/parser.py - Cleaner · Cleans formatting and prepares text for indexing.
src/clean.py - Ingest · Drives document preparation and artifact creation.
src/ingest.py - Build FTS · Creates or refreshes the full-text search database.
src/generate_fulltext.py - Embeddings · Converts text chunks into vectors for Chroma.
src/embeddings.py - Seq check · Validates article and section ordering.
src/check_sequence.py - Storage · Shared database access boundary for on-disk indexes.
src/database.py
Query serving
Retrieval, ranking, generation, and application layer.
- FTS search · Queries the full-text index for exact legal matches.
src/fts_index.py - Retriever · Orchestrates candidate selection from vector and lexical sources.
src/retrieval.py - Reranker · Reorders retrieved passages into a better context set.
src/reranker.py - Generator · Produces grounded answers from retrieved context.
src/generator.py - Flask app · HTTP layer that serves the RAG experience.
src/flask_app.py - CLI · Command-line entry for local operations.
src/cli.py - Templates · Rendered HTML views for the main pages.
src/templates - Static UI · Client-side scripts and styles for the web UI.
src/static
Evaluation
Offline checks and regression fixtures.
- Golden data · Expected outputs used for regression checking.
data/golden_eval.json - Eval retrieval · Measures retrieval quality against golden cases.
src/eval_retrieval.py - Validate golden · Validates outputs against golden expectations.
src/validate_golden.py - Test harness · Additional repository-level quality checks.
src/test.py
Connections 24
- Raw laws → Parser: source text · Raw legal acts are parsed into structured content.
- Parser → Cleaner: structured text · Parsed documents are normalized for indexing.
- Cleaner → Ingest: normalized docs · Cleaned text is prepared for ingestion.
- Ingest → Embeddings: chunks · Prepared chunks are embedded for semantic search.
- Ingest → Build FTS: documents · Prepared documents are materialized into full-text artifacts.
- Embeddings → Chroma store: vectors · Embeddings are persisted to the vector store.
- Embeddings → New Chroma: vectors · Alternative vector index is also populated.
- Build FTS → FTS db: index data · Full-text search structures are written to SQLite.
- Seq check → Ingest: integrity · Sequence validation guards the preparation pipeline.
- Storage → Chroma store: storage access · Shared persistence layer reads and writes the vector store.
- Storage → FTS db: storage access · Shared persistence layer accesses the full-text database.
- FTS search → FTS db: query · Lexical search runs against the full-text index.
- Retriever → Chroma store: semantic search · Retriever pulls candidates from the vector store.
- Retriever → FTS search: lexical search · Retriever combines keyword evidence from FTS.
- Retriever → Reranker: candidates · Initial hits are refined by the reranker.
- Reranker → Generator: context · Ranked passages are passed into answer generation.
- Generator → Flask app: answer · Generated responses are returned through the web app.
- Flask app → Templates: render · Server-side views are rendered for the UI.
- Flask app → Static UI: assets · Frontend scripts and styles support interaction.
- CLI → Ingest: ops · CLI entrypoint can run indexing and maintenance tasks.
- Eval retrieval → Retriever: measure · Retrieval quality is assessed offline.
- Validate golden → Golden data: compare · Golden fixture drives regression validation.
- Test harness → Generator: check · Repository tests exercise the generation path.
- Test harness → Retriever: check · Repository tests also exercise retrieval behavior.