# AI & LLM Integration Standards

This document defines how LLM calls and AI features must be implemented within GramPilot.

## 1. Centralized Provider
- **Never** make raw `requests.post` calls to Ollama or OpenRouter directly in business logic.
- **Always** use the centralized `GramAddict.core.llm_provider.query_llm` or `query_telepathic_llm` wrappers. This ensures consistent timeout handling, logging, and fallback logic.

## 2. Determinism over Creativity
- GramPilot uses LLMs for *structural classification*, not creative writing.
- **Always** force structured JSON outputs (`format_json=True`).
- **Always** set `temperature=0.0` to ensure deterministic, repeatable classifications of the UI.

## 3. Resource Hygiene (VRAM)
- Local LLMs (via Ollama) consume massive VRAM.
- Always implement the `keep_alive: 0` pattern (via `unload_ollama_models`) during bot shutdown or catastrophic crashes in the `finally` block to prevent GPU memory fragmentation.

## 4. The Resolution Cascade
- The LLM is the **last resort** (Level 3).
- Always try CPU Fast-Paths (Level 1) and Qdrant Vector Similarity (Level 2) before waking up an LLM.
- If an LLM is used, its result must be cached in Qdrant to ensure it is never called twice for the same UI state.

## 5. Benchmark Guard (Safety Pre-Checks)
- **Model Validation:** The `check_model_benchmarks` function in `benchmark_guard.py` enforces a strict quality gate before the bot even starts.
- **Scoring System:** It checks the configured models against `benchmarks/data/llm_benchmarks.json`.
  - **< 50 Score:** Critical Failure. The agent will hallucinate and compromise account safety. The bot warns the user not to run unattended.
  - **< 80 Score:** Sub-Standard. The model might occasionally fail at precise XML structural parsing (`TelepathicScore`) or persona-matching (`ResonanceScore`).
- **Purpose:** Because FSD (Full Self-Driving) relies heavily on structural AI fallback, running untested small parameter models (like an un-tuned 1B model) can lead to infinite loops or incorrect clicks. The Benchmark Guard ensures only capable models (like `qwen3.5:latest` or `llama3.2-vision`) are trusted for autonomous navigation.
