# Copilot Instructions for `rag-kmk`

## Project Overview

- **rag-kmk** is an educational Python Retrieval-Augmented Generation (RAG) library.
- Main components:
  - `rag_kmk/`: Core library (document loader, text splitter, vector DB, chat flow)
  - `run.py`: Example runner (do not modify for features/bugfixes)
  - `tests/`: Pytest-based unit tests
  - `docs/`: Documentation
  - `chromaDB/`: Local persistent ChromaDB (default; in-memory support has been removed)
- Configuration is managed via `rag_kmk/config/config.yaml` and loaded through library helpers.

## Architecture & Data Flow

- **Knowledge Base Construction**: Documents are loaded and chunked, then indexed in ChromaDB (`rag_kmk.knowledge_base`, `rag_kmk.vector_db`).
- **LLM Integration**: Chat clients are built via `rag_kmk.chat_flow.llm_interface.build_chatBot`, supporting Gemini and fallback no-op clients.
- **Query Pipeline**: User queries are processed, relevant document chunks retrieved, and answers generated by the LLM.
- **Configurable**: All major behaviors (DB path, model, chunking, etc.) are set in YAML config, not hardcoded.

## Developer Workflow

- **Environment**: Use Conda (`conda create -n rag python=3.12 -y; conda activate rag`) and install dependencies via `pip install -r requirements.txt`.
- **Testing**: Run `pytest` on the `tests/` directory. Tests should import and exercise library code, not runner scripts.
- **Configuration**: Always load config from `rag_kmk/config/config.yaml` using library helpers. Never hardcode config in tests.
- **External Dependencies**: Mock/stub third-party SDKs (e.g., ChromaDB, LLM SDKs) in unit tests. Use environment variables for API keys.
- **Persistent DB only**: ChromaDB is persistent only. Ensure `vector_db.chromaDB_path` is set to a valid filesystem path in config.

## Project-Specific Conventions

- **No direct runner changes**: Do not add features or fix bugs in `run.py`; update library code only.
- **ABSOLUTE RULE:** Never modify `run.py` under any circumstance. This file is a stable example/entry-point and must remain unchanged by contributors, automated tools, or Copilot edits.
- **Minimal, idiomatic Python**: Prefer small, focused changes compatible with Python 3.8+.
- **Testing policy**: Each feature should have a happy-path and edge-case test. Avoid monkeypatching internal library code; mock only external dependencies.
- **Secrets**: Never commit API keys; use environment variables and placeholders.

## Examples

- **Unit test**: For a new function in `rag_kmk/`, create a fast, isolated test with external calls mocked.
- **Helper function**: Add with a docstring and corresponding test.
- **Usage snippet**: Show loading `tests/sample_documents/` and running a query in README or docs.

## Key Files & Directories

- `rag_kmk/`: Library code
- `rag_kmk/config/config.yaml`: Main config (must include vector_db.chromaDB_path)
- `tests/`: Unit tests
- `docs/`: Documentation
- `chromaDB/`: Persistent DB (add to `.gitignore`)
- `run.py`: Example runner (do not modify for features/bugs)

## Security

- Do not include API keys or private data in code or suggestions. Use environment variables and call out placeholders.
