Repository navigation
Contributing
For end-user installation (Docker or local Python), see the Installation wiki page.
git clone https://github.com/anjanatiha/Retrieval-Augmented-Generation-RAG-Agent.git
cd Retrieval-Augmented-Generation-RAG-Agent
python3.11 -m venv rag_env_311
source rag_env_311/bin/activate
pip install -r requirements.txt
pip install -e ".[dev]" # pytest, pre-commit, xlwt
# Install pre-commit hooks (runs automatically before every git commit)
pre-commit installsrc/rag/ ← Core RAG system (4 classes + modules)
src/ui/ ← Streamlit UI modules
src/cli/ ← Terminal interface
tests/ ← Local test suite (859 tests)
huggingface/ ← HF Space deployment + mirror test suite (385 tests)
See Architecture for a full breakdown of responsibilities.
# All local tests
pytest
# With coverage report
pytest --cov=src --cov-report=term-missing
# HF Space tests
cd huggingface && pytest
# Single file
pytest tests/test_vector_store.py -v859 local · 385 HF Space · 1,244 total — all passing.
All tests must pass before submitting a pull request.
Tests are written in the same pass as the code — not after. Every new feature or bug fix must include tests.
| Test type | What it covers |
|---|---|
| Unit | Single method in isolation with mocked dependencies |
| Functional | Method with real libraries (e.g. PyMuPDF, openpyxl) |
| Integration | Full pipeline with multiple components |
| Regression | Specific bugs or edge cases that were previously broken |
| Boundary | Minimum and maximum valid inputs |
| Negative | Invalid inputs and error paths |
| Parametrized | Multiple input combinations in a single test |
# Always mock — these require external services or slow I/O:
ollama.embed → {'embeddings': [[0.1, 0.2, ...]]}
ollama.chat → {'message': {'content': 'mock response'}}
chromadb → chromadb.EphemeralClient() (or MagicMock for pipeline tests)
requests.get → MagicMock with .content, .headers, .raise_for_status()
# Never mock — test with real libraries:
fitz (PyMuPDF), python-docx, openpyxl, xlrd, python-pptx, BeautifulSoup4
BM25Okapi, cosine similarity, chunk truncation, query classificationAll code must meet production standard:
-
PEP 8 naming throughout (
lower_case_with_underscoresfor functions,UPPER_CASEfor constants,UpperCamelCasefor classes) - Google-style docstrings on every public class, every public method, and every private method with non-obvious logic
- Type hints on all function signatures
- Comments explain WHY, not what the code is doing
-
Plain English names —
chunk_sizenotcs,is_confidentnotconf -
500-line limit for source files; 50-line limit for entry points (
app.py,main.py)
| File type | Limit | Action if exceeded |
|---|---|---|
| Source files | 500 lines | Split along a clear conceptual boundary immediately |
Entry points (app.py, main.py) |
50 lines | Move excess to a handler or runner module |
| Test files | 500 lines (soft) | Split by class or concern |
Pre-commit hooks run automatically before every git commit. They enforce:
| Hook | What it checks |
|---|---|
trailing-whitespace |
Removes trailing spaces |
end-of-file-fixer |
Ensures files end with a newline |
check-yaml / check-json / check-toml
|
Validates config file syntax |
isort |
Keeps imports sorted (black profile, 120-char line length) |
flake8 |
Catches syntax errors and undefined names (--select=E9,F63,F7,F82) |
Run them manually on all files:
pre-commit run --all-files- Fork the repository and create a feature branch
- Write tests first — all new code must have corresponding tests
- Ensure
pytestpasses with zero failures - Ensure the web UI works:
streamlit run app.py - Update any affected documentation (README.md, DESIGN.md, wiki)
- Submit a pull request with a clear description of the change and its motivation
Use the issue templates when opening a GitHub issue — they will prompt you for the right information automatically.
- Bug Report — for unexpected behavior or errors
- Feature Request — for new ideas or improvements
Please include:
- A clear description of the problem or feature request
- Steps to reproduce (for bugs)
- Your environment: OS, Python version, Ollama version
- Relevant error messages or logs
Do not open a public issue for security vulnerabilities. Email anjanatiha@gmail.com instead.
See SECURITY.md for the full policy.