Выбрать ветку (тег)
Найти файл
Клонировать
README.md 
inclusion: always

Medical RAG System - Master Steering Guide

Context-aware guidance for AI assistants working on the medical-rag-system project.

Core Principles

  • KISS: Simplest solution that solves the current requirement
  • YAGNI: Abstract only when pattern appears twice in real usage
  • DRY: Extract to function/class on third repetition
  • Type Safety: Strict type hints on all public signatures
  • Single Responsibility: One class, one reason to change
  • Dependency Injection: Pass dependencies via constructor
  • Meaningful Comments: Explain "why", not "how"

Context-Aware Steering Files

Specialized guides auto-load based on file paths:

File Pattern Steering File Focus Areas
**/*.py architecture-and-code-quality.md SOLID, GoF patterns, error handling, GPU memory
**/*.py medical-rag-development-guide.md venv, .env config, project structure
**/graph/**/*.py airllm-integration-guide.md 4-bit quantization, prompt engineering, OOM handling
**/storage/**/*.py qdrant-best-practices.md On-disk mode, batch ops, vector normalization

Technology Stack

Component Technology Configuration
Language Python 3.10+ venv required, strict typing
LLM AirLLM (Llama-3-8B, Mistral-7B, Phi-2) 4-bit quantization
Vector DB Qdrant On-disk mode
Graph DB FalkorDB Local instance
Embeddings Sentence Transformers (multilingual-e5-small) CPU/GPU
API FastAPI Async endpoints

Project Structure

src/
├── parsers/        # PDF extraction (PyMuPDF)
├── embeddings/     # Text vectorization
├── pipelines/      # RAG orchestration
├── graph/          # Entity/relation extraction (AirLLM)
├── storage/        # Qdrant operations
├── api/            # FastAPI endpoints
├── memory/         # GPU/RAM management
├── utils/          # Shared utilities
└── config/         # .env loading

tests/
├── unit/           # Component tests
├── property/       # PBT correctness tests
└── integration/    # End-to-end tests

data/               # Qdrant on-disk storage
logs/               # Application logs
Clinic/             # 26 medical PDFs (source data)

Critical Constraints (GPU 4-8GB)

ALWAYS enforce these rules:

  1. 4-bit quantization for all AirLLM model loading
  2. Clear GPU cache after each batch: torch.cuda.empty_cache()
  3. On-disk storage for Qdrant (no in-memory mode)
  4. Batch processing with configurable sizes (default: 10 documents)
  5. Memory checks before loading models or large datasets

Code Generation Checklist

Before writing ANY code, verify:

  • Virtual environment active (.venv\Scripts\activate on Windows)
  • Relevant steering files reviewed for target file path
  • Configuration uses .env variables (NEVER hardcode paths/credentials)
  • Type hints present on all function signatures
  • GPU resources explicitly managed (load/unload/cache clearing)
  • Error handling includes logging with context
  • New dependencies added to requirements.txt
  • Follows SOLID principles (especially SRP and DIP)

Common Commands

# Virtual environment (Windows)
.venv\Scripts\activate

# Dependencies
pip install -r requirements.txt

# Testing
pytest tests/ -v                    # All tests
pytest tests/unit/ -v               # Unit tests only
pytest tests/property/ -v           # Property-based tests

# Type checking
mypy src/

# Code quality
flake8 src/
black src/ --check

Long-Running Services

NEVER execute directly - instruct user to run manually:

  • Qdrant server: docker run -p 6333:6333 qdrant/qdrant
  • FastAPI server: uvicorn src.api.main:app --reload
  • Any command with --watch or --dev flags

Error Handling Patterns

# GPU OOM
try:
    result = model.generate(prompt)
except torch.cuda.OutOfMemoryError:
    torch.cuda.empty_cache()
    # Reduce batch size or use smaller model
    
# Qdrant connection
try:
    client.search(collection_name, query_vector)
except Exception as e:
    logger.error(f"Qdrant search failed: {e}", extra={"collection": collection_name})
    # Fallback or retry logic

Troubleshooting Quick Reference

Symptom Root Cause Solution
torch.cuda.OutOfMemoryError GPU exhausted Reduce batch size, verify 4-bit quantization, clear cache
ConnectionRefusedError (Qdrant) Service not running Start Qdrant: docker run -p 6333:6333 qdrant/qdrant
ModuleNotFoundError venv not active or deps missing Activate venv, run pip install -r requirements.txt
mypy type errors Missing type hints Add annotations to function signatures
Slow inference Full precision model Verify compression='4bit' in AirLLM config

Reference Documentation

AI Assistant Guidelines

When working on this project:

  1. Read relevant steering files before generating code for specific paths
  2. Ask clarifying questions if requirements are ambiguous (inputs/outputs/edge cases)
  3. Propose architecture (sequence diagrams, class interactions) before implementation
  4. Explain complex patterns - state "why" you chose a specific approach
  5. Validate constraints - always check GPU memory limits and batch sizes
  6. Test incrementally - suggest running tests after each component
  7. Document decisions - add comments explaining non-obvious choices