refactor: remove airllm references from docs, docstrings, and README (#486)

Co-authored-by: Kimi Agent <kimi@timmy.local>
Co-committed-by: Kimi Agent <kimi@timmy.local>

README.md

@@ -82,7 +82,6 @@ cp .env.example .env
 | `OLLAMA_MODEL` | `qwen3:30b` | Primary model for reasoning and tool calling. Fallback: `llama3.1:8b-instruct` |
 | `DEBUG` | `false` | Enable `/docs` and `/redoc` |
 | `TIMMY_MODEL_BACKEND` | `ollama` | `ollama` \| `airllm` \| `auto` |
-| `AIRLLM_MODEL_SIZE` | `70b` | `8b` \| `70b` \| `405b` |
 | `L402_HMAC_SECRET` | *(default — change in prod)* | HMAC signing key for macaroons |
 | `L402_MACAROON_SECRET` | *(default — change in prod)* | Macaroon secret |
 | `LIGHTNING_BACKEND` | `mock` | `mock` (production-ready) \| `lnd` (scaffolded, not yet functional) |
@@ -177,7 +176,6 @@ timmy chat "Explain self-custody" --backend airllm --model-size 70b
 Or set once in `.env`:
 ```bash
 TIMMY_MODEL_BACKEND=auto
-AIRLLM_MODEL_SIZE=70b
 ```
 
 | Flag  | Parameters  | RAM needed |

TEST_COVERAGE_ANALYSIS.md

@@ -111,7 +111,7 @@ pytest: error: unrecognized arguments: -n --dist worksteal
 ### 4a. Missing Error-Path Testing
 
 Many modules have happy-path tests but lack coverage for:
-- **Graceful degradation paths**: The architecture mandates graceful degradation when Ollama/Redis/AirLLM are unavailable, but most fallback paths are untested (e.g., `cascade.py` lines 563–655)
+- **Graceful degradation paths**: The architecture mandates graceful degradation when Ollama/Redis are unavailable, but most fallback paths are untested (e.g., `cascade.py` lines 563–655)
 - **`brain/client.py`**: Only 14.8% covered — connection failures, retries, and error handling are untested
 - **`infrastructure/error_capture.py`**: 0% — the error capture system itself has no tests
 

docs/AUDIT_REPORT.md

@@ -63,11 +63,11 @@ $ python -m pytest -q
 ## 2. Feature-by-Feature Audit
 
 ### 2.1 Timmy Agent
-**Claimed**: Agno-powered conversational agent backed by Ollama, AirLLM for 70B-405B models, SQLite memory
+**Claimed**: Agno-powered conversational agent backed by Ollama, SQLite memory
 **Verdict: REAL & FUNCTIONAL**
 
 - `src/timmy/agent.py` (79 lines): Creates a genuine `agno.Agent` with Ollama model, SQLite persistence, tools, and system prompt
-- Backend selection (`backends.py`) implements real Ollama/AirLLM switching with Apple Silicon detection
+- Backend selection (`backends.py`) implements real Ollama switching with Apple Silicon detection
 - CLI (`cli.py`) provides working `timmy chat`, `timmy think`, `timmy status` commands
 - Approval workflow (`approvals.py`) implements real human-in-the-loop with SQLite-backed state
 - Briefing system (`briefing.py`) generates real scheduled briefings

docs/REFACTORING_PLAN.md

@@ -100,7 +100,7 @@ Bitcoin Lightning economics. No cloud AI.
   make install && make dev  →  http://localhost:8000
 
 ## What's Here
-  - Timmy Agent (Ollama/AirLLM)
+  - Timmy Agent (Ollama)
   - Mission Control Dashboard (FastAPI + HTMX)
   - Swarm Coordinator (multi-agent auctions)
   - Lightning Payments (L402 gating)

docs/SECURITY.md

@@ -6,7 +6,7 @@ This document outlines the security architecture, threat model, and recent audit
 
 Timmy Time is built on the principle of **AI Sovereignty**. Security is not just about preventing unauthorized access, but about ensuring the user maintains full control over their data and AI models.
 
-1.  **Local-First Execution:** All primary AI inference (Ollama/AirLLM) runs on localhost. No data is sent to third-party cloud providers unless explicitly configured (e.g., Grok).
+1.  **Local-First Execution:** All primary AI inference (Ollama) runs on localhost. No data is sent to third-party cloud providers unless explicitly configured (e.g., Grok).
 2.  **Air-Gapped Ready:** The system is designed to run without an internet connection once dependencies and models are cached.
 3.  **Secret Management:** Secrets are never hard-coded. They are managed via Pydantic-settings from `.env` or environment variables.
 

docs/SOVEREIGN_AGI_RESEARCH.md

@@ -59,7 +59,7 @@ already works.
 | LLM routing | CascadeRouter with circuit breakers | Good |
 | Memory tiers | Hot (MEMORY.md) → Vault (markdown) → Semantic (SQLite+vectors) | Good foundation |
 | Module boundaries | 8 packages with clear responsibilities | Good |
-| Multi-backend LLM | Ollama/AirLLM/Grok/Claude with auto-detection | Good |
+| Multi-backend LLM | Ollama/Grok/Claude with auto-detection | Good |
 | Security posture | CSRF, security headers, secret validation, telemetry off | Good |
 
 ### Architecture Diagram (Current State)
@@ -473,7 +473,7 @@ The proposal enforces a strict 2,000-line limit for `src/timmy/`:
 | `workflow_engine.py` | ~200 | YAML loader, step executor, state machine |
 | `tool_registry.py` | ~200 | Dynamic tool discovery, spawn, health check |
 | `memory_system.py` | ~300 | Hot/Vault/Semantic memory interface (existing) |
-| `backends.py` | ~200 | Ollama/AirLLM/Claude/Grok adapters |
+| `backends.py` | ~200 | Ollama/Claude/Grok adapters |
 | `config.py` | ~150 | Pydantic-settings (existing) |
 | `lightning_wallet.py` | ~200 | L402 handling, invoice generation, balance |
 | `utils/` | ~300 | Shared helpers, logging, serialization |

docs/adr/020-cascade-router-integration.md

@@ -4,7 +4,6 @@
 Proposed
 
 ## Context
-Currently, the Timmy agent (`src/timmy/agent.py`) uses `src/timmy/backends.py` which provides a simple abstraction over Ollama and AirLLM. However, this lacks:
 - Automatic failover between multiple LLM providers
 - Circuit breaker pattern for failing providers
 - Cost and latency tracking per provider
@@ -19,14 +18,13 @@ Integrate the Cascade Router as the primary LLM routing layer for Timmy, replaci
 
 ### Current Flow
 ```
-User Request → Timmy Agent → backends.py → Ollama/AirLLM
+User Request → Timmy Agent → backends.py → Ollama
 ```
 
 ### Proposed Flow
 ```
 User Request → Timmy Agent → Cascade Router → Provider 1 (Ollama)
                                       ↓ (if fail)
-                                 Provider 2 (Local AirLLM)
                                       ↓ (if fail)
                                  Provider 3 (API - optional)
                                       ↓
@@ -41,7 +39,6 @@ User Request → Timmy Agent → Cascade Router → Provider 1 (Ollama)
    - Expose provider status in agent responses
 
 2. **Cascade Router** (`src/router/cascade.py`)
-   - Already supports: Ollama, OpenAI, Anthropic, AirLLM
    - Already has: Circuit breakers, metrics, failover logic
    - Add: Integration with existing `src/timmy/prompts.py`
 
@@ -57,7 +54,6 @@ User Request → Timmy Agent → Cascade Router → Provider 1 (Ollama)
 ### Provider Priority Order
 
 1. **Ollama (local)** - Priority 1, always try first
-2. **AirLLM (local)** - Priority 2, if Ollama unavailable
 3. **API providers** - Priority 3+, only if configured
 
 ### Data Flow

src/dashboard/app.py

@@ -329,33 +329,35 @@ async def _discord_token_watcher() -> None:
                 logger.warning("Discord auto-start failed: %s", exc)
 
 
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Application lifespan manager with non-blocking startup."""
-
-    # Validate security config (no-op in test mode)
+def _startup_init() -> None:
+    """Validate config and enable event persistence."""
     from config import validate_startup
 
     validate_startup()
 
-    # Enable event persistence (unified EventBus + swarm event_log)
     from infrastructure.events.bus import init_event_bus_persistence
 
     init_event_bus_persistence()
 
-    # Create all background tasks without waiting for them
-    briefing_task = asyncio.create_task(_briefing_scheduler())
-    thinking_task = asyncio.create_task(_thinking_scheduler())
-    loop_qa_task = asyncio.create_task(_loop_qa_scheduler())
-    presence_task = asyncio.create_task(_presence_watcher())
-
-    # Initialize Spark Intelligence engine
     from spark.engine import get_spark_engine
 
     if get_spark_engine().enabled:
         logger.info("Spark Intelligence active — event capture enabled")
 
-    # Auto-prune old vector store memories on startup
+
+def _startup_background_tasks() -> list[asyncio.Task]:
+    """Spawn all recurring background tasks (non-blocking)."""
+    return [
+        asyncio.create_task(_briefing_scheduler()),
+        asyncio.create_task(_thinking_scheduler()),
+        asyncio.create_task(_loop_qa_scheduler()),
+        asyncio.create_task(_presence_watcher()),
+        asyncio.create_task(_start_chat_integrations_background()),
+    ]
+
+
+def _startup_pruning() -> None:
+    """Auto-prune old memories, thoughts, and events on startup."""
     if settings.memory_prune_days > 0:
         try:
             from timmy.memory_system import prune_memories
@@ -373,7 +375,6 @@ async def lifespan(app: FastAPI):
         except Exception as exc:
             logger.debug("Memory auto-prune skipped: %s", exc)
 
-    # Auto-prune old thoughts on startup
     if settings.thoughts_prune_days > 0:
         try:
             from timmy.thinking import thinking_engine
@@ -391,7 +392,6 @@ async def lifespan(app: FastAPI):
         except Exception as exc:
             logger.debug("Thought auto-prune skipped: %s", exc)
 
-    # Auto-prune old system events on startup
     if settings.events_prune_days > 0:
         try:
             from swarm.event_log import prune_old_events
@@ -409,7 +409,6 @@ async def lifespan(app: FastAPI):
         except Exception as exc:
             logger.debug("Event auto-prune skipped: %s", exc)
 
-    # Warn if memory vault exceeds size limit
     if settings.memory_vault_max_mb > 0:
         try:
             vault_path = Path(settings.repo_root) / "memory" / "notes"
@@ -425,6 +424,42 @@ async def lifespan(app: FastAPI):
         except Exception as exc:
             logger.debug("Vault size check skipped: %s", exc)
 
+
+async def _shutdown_cleanup(
+    bg_tasks: list[asyncio.Task],
+    workshop_heartbeat,
+) -> None:
+    """Stop chat bots, MCP sessions, heartbeat, and cancel background tasks."""
+    from integrations.chat_bridge.vendors.discord import discord_bot
+    from integrations.telegram_bot.bot import telegram_bot
+
+    await discord_bot.stop()
+    await telegram_bot.stop()
+
+    try:
+        from timmy.mcp_tools import close_mcp_sessions
+
+        await close_mcp_sessions()
+    except Exception as exc:
+        logger.debug("MCP shutdown: %s", exc)
+
+    await workshop_heartbeat.stop()
+
+    for task in bg_tasks:
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager with non-blocking startup."""
+    _startup_init()
+    bg_tasks = _startup_background_tasks()
+    _startup_pruning()
+
     # Start Workshop presence heartbeat with WS relay
     from dashboard.routes.world import broadcast_world_state
     from timmy.workshop_state import WorkshopHeartbeat
@@ -432,10 +467,7 @@ async def lifespan(app: FastAPI):
     workshop_heartbeat = WorkshopHeartbeat(on_change=broadcast_world_state)
     await workshop_heartbeat.start()
 
-    # Start chat integrations in background
-    chat_task = asyncio.create_task(_start_chat_integrations_background())
-
-    # Register session logger with error capture (breaks infrastructure → timmy circular dep)
+    # Register session logger with error capture
     try:
         from infrastructure.error_capture import register_error_recorder
         from timmy.session_logger import get_session_logger
@@ -448,30 +480,7 @@ async def lifespan(app: FastAPI):
 
     yield
 
-    # Cleanup on shutdown
-    from integrations.chat_bridge.vendors.discord import discord_bot
-    from integrations.telegram_bot.bot import telegram_bot
-
-    await discord_bot.stop()
-    await telegram_bot.stop()
-
-    # Close MCP tool server sessions
-    try:
-        from timmy.mcp_tools import close_mcp_sessions
-
-        await close_mcp_sessions()
-    except Exception as exc:
-        logger.debug("MCP shutdown: %s", exc)
-
-    await workshop_heartbeat.stop()
-
-    for task in [briefing_task, thinking_task, chat_task, loop_qa_task, presence_task]:
-        if task:
-            task.cancel()
-            try:
-                await task
-            except asyncio.CancelledError:
-                pass
+    await _shutdown_cleanup(bg_tasks, workshop_heartbeat)
 
 
 app = FastAPI(

src/timmy/__init__.py

@@ -1 +1 @@
-"""Timmy — Core AI agent (Ollama/AirLLM backends, CLI, prompts)."""
+"""Timmy — Core AI agent (Ollama backend, CLI, prompts)."""

src/timmy/thinking.py

@@ -232,6 +232,90 @@ class ThinkingEngine:
             return False  # Disabled — never idle
         return datetime.now(UTC) - self._last_input_time > timedelta(minutes=timeout)
 
+    def _build_thinking_context(self) -> tuple[str, str, list["Thought"]]:
+        """Assemble the context needed for a thinking cycle.
+
+        Returns:
+            (memory_context, system_context, recent_thoughts)
+        """
+        memory_context = self._load_memory_context()
+        system_context = self._gather_system_snapshot()
+        recent_thoughts = self.get_recent_thoughts(limit=5)
+        return memory_context, system_context, recent_thoughts
+
+    async def _generate_novel_thought(
+        self,
+        prompt: str | None,
+        memory_context: str,
+        system_context: str,
+        recent_thoughts: list["Thought"],
+    ) -> tuple[str | None, str]:
+        """Run the dedup-retry loop to produce a novel thought.
+
+        Returns:
+            (content, seed_type) — content is None if no novel thought produced.
+        """
+        seed_type: str = "freeform"
+
+        for attempt in range(self._MAX_DEDUP_RETRIES + 1):
+            if prompt:
+                seed_type = "prompted"
+                seed_context = f"Journal prompt: {prompt}"
+            else:
+                seed_type, seed_context = self._gather_seed()
+
+            continuity = self._build_continuity_context()
+
+            full_prompt = _THINKING_PROMPT.format(
+                memory_context=memory_context,
+                system_context=system_context,
+                seed_context=seed_context,
+                continuity_context=continuity,
+            )
+
+            try:
+                raw = await self._call_agent(full_prompt)
+            except Exception as exc:
+                logger.warning("Thinking cycle failed (Ollama likely down): %s", exc)
+                return None, seed_type
+
+            if not raw or not raw.strip():
+                logger.debug("Thinking cycle produced empty response, skipping")
+                return None, seed_type
+
+            content = raw.strip()
+
+            # Dedup: reject thoughts too similar to recent ones
+            if not self._is_too_similar(content, recent_thoughts):
+                return content, seed_type  # Good — novel thought
+
+            if attempt < self._MAX_DEDUP_RETRIES:
+                logger.info(
+                    "Thought too similar to recent (attempt %d/%d), retrying with new seed",
+                    attempt + 1,
+                    self._MAX_DEDUP_RETRIES + 1,
+                )
+            else:
+                logger.warning(
+                    "Thought still repetitive after %d retries, discarding",
+                    self._MAX_DEDUP_RETRIES + 1,
+                )
+                return None, seed_type
+
+        return None, seed_type
+
+    async def _process_thinking_result(self, thought: "Thought") -> None:
+        """Run all post-hooks after a thought is stored."""
+        self._maybe_check_memory()
+        await self._maybe_distill()
+        await self._maybe_file_issues()
+        await self._check_workspace()
+        self._maybe_check_memory_status()
+        self._update_memory(thought)
+        self._log_event(thought)
+        self._write_journal(thought)
+        await self._broadcast(thought)
+
     async def think_once(self, prompt: str | None = None) -> Thought | None:
         """Execute one thinking cycle.
 
@@ -257,91 +341,21 @@ class ThinkingEngine:
             )
             return None
 
-        memory_context = self._load_memory_context()
-        system_context = self._gather_system_snapshot()
-        recent_thoughts = self.get_recent_thoughts(limit=5)
-
-        content: str | None = None
-        seed_type: str = "freeform"
-
-        for attempt in range(self._MAX_DEDUP_RETRIES + 1):
-            if prompt:
-                seed_type = "prompted"
-                seed_context = f"Journal prompt: {prompt}"
-            else:
-                seed_type, seed_context = self._gather_seed()
-
-            continuity = self._build_continuity_context()
-
-            full_prompt = _THINKING_PROMPT.format(
-                memory_context=memory_context,
-                system_context=system_context,
-                seed_context=seed_context,
-                continuity_context=continuity,
-            )
-
-            try:
-                raw = await self._call_agent(full_prompt)
-            except Exception as exc:
-                logger.warning("Thinking cycle failed (Ollama likely down): %s", exc)
-                return None
-
-            if not raw or not raw.strip():
-                logger.debug("Thinking cycle produced empty response, skipping")
-                return None
-
-            content = raw.strip()
-
-            # Dedup: reject thoughts too similar to recent ones
-            if not self._is_too_similar(content, recent_thoughts):
-                break  # Good — novel thought
-
-            if attempt < self._MAX_DEDUP_RETRIES:
-                logger.info(
-                    "Thought too similar to recent (attempt %d/%d), retrying with new seed",
-                    attempt + 1,
-                    self._MAX_DEDUP_RETRIES + 1,
-                )
-                content = None  # Will retry
-            else:
-                logger.warning(
-                    "Thought still repetitive after %d retries, discarding",
-                    self._MAX_DEDUP_RETRIES + 1,
-                )
-                return None
+        memory_context, system_context, recent_thoughts = self._build_thinking_context()
 
+        content, seed_type = await self._generate_novel_thought(
+            prompt,
+            memory_context,
+            system_context,
+            recent_thoughts,
+        )
         if not content:
             return None
 
         thought = self._store_thought(content, seed_type)
         self._last_thought_id = thought.id
 
-        # Post-hook: check memory status periodically
-        self._maybe_check_memory()
-
-        # Post-hook: distill facts from recent thoughts periodically
-        await self._maybe_distill()
-
-        # Post-hook: file Gitea issues for actionable observations
-        await self._maybe_file_issues()
-
-        # Post-hook: check workspace for new messages from Hermes
-        await self._check_workspace()
-
-        # Post-hook: proactive memory status audit
-        self._maybe_check_memory_status()
-
-        # Post-hook: update MEMORY.md with latest reflection
-        self._update_memory(thought)
-
-        # Log to swarm event system
-        self._log_event(thought)
-
-        # Append to daily journal file
-        self._write_journal(thought)
-
-        # Broadcast to WebSocket clients
-        await self._broadcast(thought)
+        await self._process_thinking_result(thought)
 
         logger.info(
             "Thought [%s] (%s): %s",

tests/dashboard/test_mobile_scenarios.py

@@ -10,7 +10,7 @@ Categories:
   M3xx  iOS keyboard & zoom prevention
   M4xx  HTMX robustness (double-submit, sync)
   M5xx  Safe-area / notch support
-  M6xx  AirLLM backend interface contract
+  M6xx  Backend interface contract
 """
 
 import re
@@ -208,7 +208,7 @@ def test_M505_dvh_units_used():
     assert "dvh" in css
 
 
-# ── M6xx — AirLLM backend interface contract ──────────────────────────────────
+# ── M6xx — Backend interface contract ──────────────────────────────────
 
 
 def test_M601_airllm_agent_has_run_method():

tests/timmy/test_backends.py

@@ -1,4 +1,4 @@
-"""Tests for src/timmy/backends.py — AirLLM wrapper and helpers."""
+"""Tests for src/timmy/backends.py — backend helpers."""
 
 import sys
 from unittest.mock import MagicMock, patch