# AGENTS.md

This file provides guidance to agents when working with code in this repository.

## Build/Test Commands
- Run all tests: `python test_implementation.py`
- Start API server: `uvicorn compact_ai_model.api.main:app --host 0.0.0.0 --port 8000`
- Train model: `python compact_ai_model/training/train.py`
- Docker deployment: `docker-compose up`

## Non-Obvious Project Patterns

### Custom Tokenizer Implementation
- Uses `SimpleTokenizer` class that hashes words with `hash(word) % vocab_size` - not a real tokenizer
- Only suitable for demonstration; replace with proper tokenizer (HuggingFace, etc.) for production

### API Reasoning Parameters
- `reasoning_depth` accepts: "adaptive", "simple", "complex", or integer values
- `early_stop_threshold` controls when thinking stops (default 0.85)
- `thinking_visualization` returns confidence scores and path information

### Model Architecture Gotchas
- Hierarchical thinking paths operate at different abstraction levels (0=low-level details, 1=patterns, 2=concepts)
- Early stopping uses task-specific thresholds learned from input complexity
- Memory compression includes reconstruction loss for training stability
- Path specialization adds path-ID based bias to reasoning paths

### Environment Variables Required
- `MODEL_SIZE`: "tiny", "small", "medium" (affects model dimensions and layers)
- `API_HOST` and `API_PORT`: Must be set for proper API binding
- `MODEL_CHECKPOINT`: Path to .bin checkpoint file for loading trained weights

### Docker Configuration
- Health check endpoint: `/health` (returns JSON with model_loaded status)
- Volumes mount: `./checkpoints:/app/checkpoints` and `./data:/app/data`
- Default CMD runs API with `--host 0.0.0.0 --port 8000`

### Training Requirements
- Data directory structure: `checkpoints/` and `data/` must exist
- Sample data created via `create_sample_data()` uses simple Q&A templates
- Mixed precision training enabled by default with gradient accumulation