feat: glossa-lab AI patterns — HF leaderboard, model profiles, LLM client, pacer v2, endpoint presets

Architecture (§21-27):
- HuggingFace Open LLM Leaderboard sync with bucket scoring
  (reasoning/conversational/longform) and 50+ model static fallback
- Model capability profiles with prefix-matching and ctx history trimmer
- Multi-provider LLM client with fallback waterfall + O-series translation
- AI Model Pacer v2: EMA utilisation, adaptive concurrency, image tokens
- Endpoint presets (vLLM/LM Studio/llama.cpp/OpenRouter/Groq etc.)
- Suggested profile generation from env/Ollama/BYOE
- Model intelligence REST endpoints on governance HTTP server

New files:
- src/specsmith/agent/hf_leaderboard.py
- src/specsmith/agent/model_profiles.py
- src/specsmith/agent/llm_client.py
- tests/test_ai_intelligence.py
- tests/test_ai_client.py

Updated: rate_limits.py, provider_registry.py, cli.py, governance_logic.py
Governance: REQ-263..REQ-281, TEST-263..TEST-281, ARCHITECTURE.md §21-27
Tests: 705 passed

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

docs/ARCHITECTURE.md

@@ -469,3 +469,127 @@ Kairos Settings pages that expose specsmith features via the governance REST API
 - Skills, Eval, Teams pages consume `GET /api/skills`, `GET /api/eval/suites`, `GET /api/teams`
 
 All pages use async health polling via `GovernanceClient.get_json()` and follow the monolith SettingsWidget pattern.
+
+## 21. HuggingFace Open LLM Leaderboard Integration
+
+Source: `src/specsmith/agent/hf_leaderboard.py`
+
+Syncs model benchmark data from the HuggingFace Datasets Server (`datasets-server.huggingface.co/rows?dataset=open-llm-leaderboard/contents`). Supports paginated fetch, exponential-backoff 429 handling with `RateLimit: t=` header parsing, optional HF API token (doubles rate limit to 1000 req/5min), and a static fallback of 50+ known models for offline operation.
+
+Background task runs 15 s after startup then every 24 h. Scores are persisted to `~/.specsmith/model_scores.json` under a `bucket_scores` key alongside existing role scores.
+
+Benchmarks mapped: IFEval, BBH, MATH Lvl 5, GPQA, MUSR, MMLU-PRO (HF field names → internal keys).
+
+REST endpoints exposed by governance server:
+- `GET /api/model-intel/scores` — all cached scores
+- `GET /api/model-intel/scores/{name}` — one model
+- `GET /api/model-intel/recommendations?bucket=reasoning` — top-10
+- `POST /api/model-intel/sync` — force re-sync
+- `POST /api/model-intel/test-hf` — connectivity + token probe
+
+CLI: `specsmith model-intel sync | scores | recommendations | test-hf`
+
+## 22. Bucket Scoring Engine
+
+Source: `src/specsmith/agent/hf_leaderboard.py` (`_compute_bucket_scores`)
+
+Three task-bucket scores computed from raw benchmark values (normalised 0–100):
+
+- **Reasoning** = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval
+- **Conversational** = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH
+- **Longform** = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO
+
+Ranked recommendation returns the top-10 models for a requested bucket. The engine merges HF-synced data with the existing `BASELINE_SCORES` so both cloud and local Ollama models appear in rankings.
+
+Base+org-prefix deduplication: `Qwen/Qwen3-14B` is stored under both its full name and `Qwen3-14B` so vLLM-style repo-ID model names match correctly.
+
+## 23. Model Capability Profiles
+
+Source: `src/specsmith/agent/model_profiles.py`
+
+Per-model capability descriptors resolved by prefix matching (longest key wins):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `max_tokens` | int | Max completion tokens to request |
+| `temperature` | float | Sampling temperature |
+| `ctx_budget` | int | Approx. chars of conversation history to keep |
+| `action_capable` | bool | Reliably produces structured actions/JSON |
+| `prompt_style` | str | `plain` \| `sections` \| `xml` |
+
+Covers 40+ models across Ollama (Mistral, Qwen, Llama, Gemma, Phi, DeepSeek), cloud (OpenAI o-series, Claude, Mistral API), and a `_DEFAULT` fallback.
+
+Context history trimmer (`trim_history`) summarises dropped turns into a compact `[Earlier conversation summary — N turns condensed]` assistant message to preserve research continuity.
+
+## 24. AI Model Pacer v2
+
+Source: `src/specsmith/rate_limits.py` (upgraded `ModelRateLimitScheduler`)
+
+Enhancements over the existing rolling-window scheduler:
+
+- **EMA utilisation tracking** — exponentially-weighted moving average of RPM/TPM utilisation (`alpha=0.25`) surfaced in `snapshot()`
+- **Adaptive concurrency** — `dynamic_concurrency` decreases on `on_rate_limit()`, restores after 120 s (incrementally, 60 s between steps)
+- **Retry-After parsing** — `parse_retry_after_seconds()` extracts `"try again in Xs"` from provider error strings; used when exponential backoff alone is insufficient
+- **Image token estimation** — `estimate_request_tokens()` accepts `image_count` and multiplies by a per-model `image_token_estimate` (default 4096)
+- **Pre-dispatch budget check** — `acquire()` blocks until RPM + TPM budgets allow dispatch; `release()` wakes waiting callers
+
+All operations are guarded by a single `threading.Condition` lock so the pacer is safe for concurrent agent sessions.
+
+## 25. Multi-Provider LLM Client with Fallback
+
+Source: `src/specsmith/agent/llm_client.py`
+
+Provider-agnostic chat client that tries a configurable ordered list of providers, falling back on 401/403/429/5xx. No optional packages required — uses `urllib` only.
+
+**LLMProvider ABC**: `name`, `key_name`, `default_model`, `is_configured()`, `chat()`.
+
+Concrete providers: `MistralProvider`, `OpenAIProvider`, `GoogleProvider`, `OllamaProvider`, `MockProvider` (test-only).
+
+**O-series translation**: OpenAI o1/o3/o4 models receive `max_completion_tokens` instead of `max_tokens` and their `system` messages are renamed to `developer`.
+
+**vLLM guided-JSON**: endpoints of type `byoe` or `huggingface` receive `guided_json` + `chat_template_kwargs: {enable_thinking: false}` when a JSON schema is provided.
+
+**Gemini parts extraction**: handles models that return answer text in `parts` rather than `content`.
+
+**JSON extraction helper** (`_extract_json`): tries direct parse → `\`\`\`json` fence → first balanced `{}` block before raising.
+
+Provider fallback decision: `_is_fallback_status(code)` returns True for 401, 403, 404, 408, 409, 425, 429, 5xx.
+
+## 26. Endpoint Preset Registry
+
+Source: `src/specsmith/agent/provider_registry.py` (`ENDPOINT_PRESETS`)
+
+Built-in connection presets for common local and hosted inference backends:
+
+| Preset | Base URL | Key needed |
+|---|---|---|
+| vLLM (local) | `http://localhost:8000/v1` | No |
+| LM Studio | `http://localhost:1234/v1` | No |
+| llama.cpp server | `http://localhost:8080/v1` | No |
+| OpenRouter | `https://openrouter.ai/api/v1` | Yes |
+| Together AI | `https://api.together.xyz/v1` | Yes |
+| Groq | `https://api.groq.com/openai/v1` | Yes |
+| Fireworks AI | `https://api.fireworks.ai/inference/v1` | Yes |
+| DeepInfra | `https://api.deepinfra.com/v1/openai` | Yes |
+| Perplexity | `https://api.perplexity.ai` | Yes |
+| Azure OpenAI | _(user-supplied)_ | Yes |
+
+Probe function enriches model list with `context_length` (from `max_model_len` on vLLM), `owner`, and `description` fields.
+
+CLI: `specsmith agent endpoint-presets`.
+
+## 27. Suggested Profile Generation
+
+Source: `src/specsmith/agent/provider_registry.py` (`suggest_profiles`)
+
+Generates a list of ready-to-add `ProviderEntry` suggestions by inspecting:
+
+1. Cloud API keys present in environment variables
+2. Ollama models currently installed (`/api/tags`)
+3. Custom BYOE endpoints in `providers.json`
+
+For each backend, role-tuned parameter sets (temperature, max_tokens) are proposed following the AEE bucket taxonomy: `reasoning`, `conversational`, `longform`.
+
+Suggestions are inert previews — the user calls `specsmith agent providers add` to persist.
+
+CLI: `specsmith agent suggest-profiles`.

docs/REQUIREMENTS.md

@@ -1803,3 +1803,136 @@ ame, command, and rgs fields derived from the description. The stub MUST be val
 - **Description:** The Kairos Agents > MCP servers list page MUST include a collapsible AI Builder card that accepts a natural-language server description, calls specsmith mcp generate <description> --json, displays the generated JSON stub, and offers an 'Add to ~/.specsmith/mcp.json' button that appends the stub to the user's MCP config file.
 - **Source:** ARCHITECTURE.md [Kairos Settings Extensions]
 - **Status:** implemented
+
+## 263. HuggingFace Open LLM Leaderboard Sync
+- **ID:** REQ-263
+- **Title:** HuggingFace Open LLM Leaderboard Sync
+- **Description:** specsmith MUST implement `src/specsmith/agent/hf_leaderboard.py` that fetches model benchmark data from the HuggingFace Datasets Server (`datasets-server.huggingface.co/rows?dataset=open-llm-leaderboard/contents`). The sync MUST be paginated (100 rows/page) and persist results to `~/.specsmith/model_scores.json` under a `bucket_scores` key.
+- **Source:** ARCHITECTURE.md §21 [HF-001]
+- **Status:** defined
+
+## 264. HF Leaderboard Rate-Limit Handling
+- **ID:** REQ-264
+- **Title:** HF Leaderboard Rate-Limit Handling
+- **Description:** The HF leaderboard sync MUST handle HTTP 429 with exponential-backoff retry (up to 4 attempts). It MUST parse the `RateLimit: "api";r=X;t=Y` header to extract the exact reset window and wait accordingly. A +1 s safety margin MUST be added to the `t=` value.
+- **Source:** ARCHITECTURE.md §21 [HF-002]
+- **Status:** defined
+
+## 265. HF API Token Support
+- **ID:** REQ-265
+- **Title:** HF API Token Support
+- **Description:** When `SPECSMITH_HF_TOKEN` or `hf_api_token` is configured, the HF sync MUST include an `Authorization: Bearer <token>` header. The CLI `specsmith model-intel test-hf` MUST validate the token via `huggingface.co/api/whoami-v2` and report whether the Datasets Server is reachable.
+- **Source:** ARCHITECTURE.md §21 [HF-003]
+- **Status:** defined
+
+## 266. HF Leaderboard Static Fallback
+- **ID:** REQ-266
+- **Title:** HF Leaderboard Static Fallback
+- **Description:** When HF is unreachable (network error, 5xx, or zero parseable rows), specsmith MUST load built-in static benchmark scores covering at least 40 models (OpenAI GPT-4o/mini, Claude 3.5 sonnet/haiku, Gemini 2.x, Mistral, Qwen, Llama, DeepSeek, Phi). The fallback MUST be transparent to callers.
+- **Source:** ARCHITECTURE.md §21 [HF-004]
+- **Status:** defined
+
+## 267. Bucket Scoring Engine
+- **ID:** REQ-267
+- **Title:** Bucket Scoring Engine
+- **Description:** specsmith MUST compute three task-bucket scores from raw benchmark values (0–100 scale): Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval; Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH; Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO. Scores MUST be rounded to 2 decimal places.
+- **Source:** ARCHITECTURE.md §22 [BKT-001]
+- **Status:** defined
+
+## 268. Model Intelligence Recommendations
+- **ID:** REQ-268
+- **Title:** Model Intelligence Recommendations
+- **Description:** `specsmith model-intel recommendations [--bucket reasoning|conversational|longform]` MUST return the top-10 models sorted by the requested bucket score. The governance HTTP server MUST expose `GET /api/model-intel/recommendations?bucket=<name>` returning the same data.
+- **Source:** ARCHITECTURE.md §22 [BKT-002]
+- **Status:** defined
+
+## 269. Model Intelligence CLI Commands
+- **ID:** REQ-269
+- **Title:** Model Intelligence CLI Commands
+- **Description:** specsmith MUST provide a `model-intel` CLI group with subcommands: `sync` (run HF sync), `scores [--model NAME]` (list/get cached scores), `recommendations [--bucket NAME]` (top-10 per bucket), `test-hf` (connectivity probe). All commands MUST support `--json` flag.
+- **Source:** ARCHITECTURE.md §21 [HF-005]
+- **Status:** defined
+
+## 270. Model Capability Profiles
+- **ID:** REQ-270
+- **Title:** Model Capability Profiles
+- **Description:** specsmith MUST implement `src/specsmith/agent/model_profiles.py` with a `ModelProfile` TypedDict containing `max_tokens`, `temperature`, `ctx_budget`, `action_capable`, `prompt_style` fields. A `get_profile(model)` function MUST resolve by prefix matching (longest key first) over ≥40 known models.
+- **Source:** ARCHITECTURE.md §23 [PRF-001]
+- **Status:** defined
+
+## 271. Context History Trimmer
+- **ID:** REQ-271
+- **Title:** Context History Trimmer
+- **Description:** `trim_history(messages, budget_chars)` in `model_profiles.py` MUST trim conversation history to fit within `budget_chars`. Oldest turns MUST be summarised into a compact `[Earlier conversation summary — N turns condensed]` assistant message rather than silently dropped. System messages MUST always be preserved.
+- **Source:** ARCHITECTURE.md §23 [PRF-002]
+- **Status:** defined
+
+## 272. AI Model Pacer EMA Utilisation
+- **ID:** REQ-272
+- **Title:** AI Model Pacer EMA Utilisation
+- **Description:** The `ModelRateLimitScheduler` MUST track RPM and TPM utilisation as exponentially-weighted moving averages (alpha=0.25) and expose them in `snapshot()` as `rpm_ema` and `tpm_ema` fields.
+- **Source:** ARCHITECTURE.md §24 [PCR-001]
+- **Status:** defined
+
+## 273. AI Model Pacer Adaptive Concurrency
+- **ID:** REQ-273
+- **Title:** AI Model Pacer Adaptive Concurrency
+- **Description:** `on_rate_limit(model, error, attempt)` MUST decrease `dynamic_concurrency` by 1 (minimum=1) and set `reduced_until` to now+120 s. Concurrency MUST restore incrementally (1 step per 60 s) once `reduced_until` has passed. The method MUST return a float delay for the caller to sleep.
+- **Source:** ARCHITECTURE.md §24 [PCR-002]
+- **Status:** defined
+
+## 274. AI Model Pacer Image Token Estimation
+- **ID:** REQ-274
+- **Title:** AI Model Pacer Image Token Estimation
+- **Description:** `estimate_request_tokens()` MUST accept an `image_count` parameter and include `image_count × image_token_estimate` tokens in the reservation. The default `image_token_estimate` MUST be 4096.
+- **Source:** ARCHITECTURE.md §24 [PCR-003]
+- **Status:** defined
+
+## 275. Multi-Provider LLM Client with Fallback
+- **ID:** REQ-275
+- **Title:** Multi-Provider LLM Client with Fallback
+- **Description:** specsmith MUST implement `src/specsmith/agent/llm_client.py` with a `LLMProvider` ABC and `LLMClient` that tries providers in order, falling back on HTTP 401/403/429/5xx. Concrete providers MUST cover Mistral, OpenAI, Google Gemini, and Ollama. A `MockProvider` MUST be available for tests.
+- **Source:** ARCHITECTURE.md §25 [LLM-001]
+- **Status:** defined
+
+## 276. LLM Client O-Series Translation
+- **ID:** REQ-276
+- **Title:** LLM Client O-Series Translation
+- **Description:** When the model name starts with `o1`, `o3`, or `o4`, or contains `-o1-`/`-o3-`/`-o4-`, the LLM client MUST use `max_completion_tokens` instead of `max_tokens`, force temperature to 1, and rename `system` role messages to `developer`.
+- **Source:** ARCHITECTURE.md §25 [LLM-002]
+- **Status:** defined
+
+## 277. LLM Client vLLM Guided-JSON Mode
+- **ID:** REQ-277
+- **Title:** LLM Client vLLM Guided-JSON Mode
+- **Description:** When a JSON schema is provided and the provider type is `byoe` or `huggingface`, the request MUST include `guided_json` and `chat_template_kwargs: {"enable_thinking": false}` to suppress chain-of-thought tokens and enforce structured output.
+- **Source:** ARCHITECTURE.md §25 [LLM-003]
+- **Status:** defined
+
+## 278. Endpoint Preset Registry
+- **ID:** REQ-278
+- **Title:** Endpoint Preset Registry
+- **Description:** `src/specsmith/agent/provider_registry.py` MUST export `ENDPOINT_PRESETS` — a list of built-in connection presets for at least: vLLM (localhost:8000), LM Studio (localhost:1234), llama.cpp (localhost:8080), OpenRouter, Together AI, Groq, Fireworks, DeepInfra, Perplexity, and Azure OpenAI. Each preset MUST include `id`, `label`, `base_url`, `endpoint_kind`, and `needs_key`.
+- **Source:** ARCHITECTURE.md §26 [PRE-001]
+- **Status:** defined
+
+## 279. Endpoint Probe Enriched Metadata
+- **ID:** REQ-279
+- **Title:** Endpoint Probe Enriched Metadata
+- **Description:** `probe_openai_compatible()` MUST return a `models_detail` list where each entry includes `id`, `owner`, `context_length` (from `max_model_len` on vLLM, `context_length` or `context_window` otherwise), and `description`. The cap MUST be 200 models.
+- **Source:** ARCHITECTURE.md §26 [PRE-002]
+- **Status:** defined
+
+## 280. Suggested Profile Generation
+- **ID:** REQ-280
+- **Title:** Suggested Profile Generation
+- **Description:** `specsmith agent suggest-profiles` MUST inspect available backends (cloud env vars, installed Ollama models, saved BYOE endpoints) and propose ready-to-add `ProviderEntry` suggestions with role-tuned temperature and max_tokens for the reasoning/conversational/longform AEE buckets. Suggestions MUST be inert (not auto-saved).
+- **Source:** ARCHITECTURE.md §27 [SGP-001]
+- **Status:** defined
+
+## 281. Kairos AI Settings Bucket Score Display
+- **ID:** REQ-281
+- **Title:** Kairos AI Settings Bucket Score Display
+- **Description:** The Kairos Agents > Providers settings page MUST display bucket scores (reasoning, conversational, longform) retrieved from `GET /api/model-intel/scores/{model}` for each configured provider. Scores MUST be shown as compact numeric badges. A Sync button MUST call `POST /api/model-intel/sync`.
+- **Source:** ARCHITECTURE.md §20–21 [KAI-001]
+- **Status:** defined