AGENTS.md

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