| # Repository Guidelines |
|
|
| ## Project Structure & Module Organization |
| `main.py` is the FastAPI entrypoint and serves the web UI from `templates/index.html` and `static/style.css`. `ingest.py` handles document loading, chunking, metadata, and Chroma ingestion. `retrieve.py` handles retrieval, context expansion, and query-time helpers. `config.py` centralizes paths and environment-driven settings. `prompt.py` contains prompt-building logic. Test data and evaluation inputs live in `tests/`, currently with `tests/eval_question.json`. |
|
|
| ## Build, Test, and Development Commands |
| - `cd rabbook && ../venv/bin/python main.py`: run the FastAPI app locally. |
| - `cd rabbook && ../venv/bin/python ingest.py`: rebuild the vector store and chunk registry from `data/`. |
| - `cd rabbook && ../venv/bin/python -m py_compile main.py ingest.py retrieve.py config.py prompt.py`: quick syntax validation. |
| - `cd rabbook && ../venv/bin/python -m pip install -r requirements.txt`: install dependencies into the shared virtual environment. |
|
|
| Use `RABBOOK_PORT=6001 ../venv/bin/python main.py` if you need to override the default port. |
|
|
| ## Coding Style & Naming Conventions |
| Follow PEP 8 with 4-space indentation. Keep functions small and linear; favor obvious control flow over heavy abstraction. Use `snake_case` for functions, variables, and module-level settings. Keep metadata keys stable and explicit, for example `document_id`, `chunk_index`, and `chunk_id`. Prefer direct helper names such as `load_chunk_registry()` over generic names like `process_data()`. |
|
|
| Code in this repository should optimize for fast review, not maximum cleverness. Keep the main flow simple and easy to explain. Prefer readable step-by-step logic over layered abstraction, and only add helper functions when they remove real confusion. Use explicit names like `paragraphs`, `current_chunk_text`, and `chunk_registry`; avoid vague names like `data`, `items`, or `parts`. If a function needs a long explanation, simplify it. |
|
|
| Keep complexity concentrated in one well-named place instead of spreading it across many helpers. Choose the simpler implementation unless extra complexity provides a clear benefit. Strong defaults in `config.py` are preferred over long parameter lists. Comments should be rare and only clarify non-obvious logic; clear naming should do most of the work. |
|
|
| When comments are needed, explain the intent or tradeoff, not the syntax. Good comments describe why a block exists, for example why context windows use the chunk registry or why semantic overlap keeps trailing units. Avoid comments that only restate obvious code like variable assignment or loop mechanics. |
|
|
| ## Testing Guidelines |
| There is no full automated test suite yet. Before opening a PR, run the `py_compile` check above and smoke-test the main flows: |
| - ingest a sample `.pdf` or `.txt` |
| - ask at least one question through the UI |
| - verify `chunk_registry.json` updates when documents are added |
|
|
| When adding tests, place them under `tests/` and name files `test_<feature>.py`. |
|
|
| ## Commit & Pull Request Guidelines |
| Recent commits use concise, imperative summaries, for example: `Enhance configuration and retrieval functionality by adding chunk registry management`. Keep that style. PRs should include: |
| - a short problem/solution summary |
| - affected files or modules |
| - manual verification steps |
| - screenshots for UI changes |
|
|
| ## Security & Configuration Tips |
| Store secrets in `.env`, never in source files. Do not commit `.env`, `chroma_db/`, uploaded documents, or local cache files. Rotate API keys immediately if they are exposed in logs, screenshots, or chat transcripts. |
|
|
