Skip to content

Contributing

Anjana Tiha edited this page Mar 31, 2026 · 4 revisions

Contributing

Development Setup

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 install

Project Structure

src/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.


Running Tests

# 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 -v

859 local · 385 HF Space · 1,244 total — all passing.

All tests must pass before submitting a pull request.


Test Strategy

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

Mock Strategy

# 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 classification

Code Standards

All code must meet production standard:

  • PEP 8 naming throughout (lower_case_with_underscores for functions, UPPER_CASE for constants, UpperCamelCase for 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_size not cs, is_confident not conf
  • 500-line limit for source files; 50-line limit for entry points (app.py, main.py)

File Size Limits

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

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

Pull Request Guidelines

  1. Fork the repository and create a feature branch
  2. Write tests first — all new code must have corresponding tests
  3. Ensure pytest passes with zero failures
  4. Ensure the web UI works: streamlit run app.py
  5. Update any affected documentation (README.md, DESIGN.md, wiki)
  6. Submit a pull request with a clear description of the change and its motivation

Reporting Issues

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:

  1. A clear description of the problem or feature request
  2. Steps to reproduce (for bugs)
  3. Your environment: OS, Python version, Ollama version
  4. Relevant error messages or logs

Open an issue →


Reporting Security Vulnerabilities

Do not open a public issue for security vulnerabilities. Email anjanatiha@gmail.com instead.

See SECURITY.md for the full policy.

Clone this wiki locally