TokioAI-Coder IoT Package v1.0 -- Engine + IoT System Prompt + Tools

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TokioAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include MANIFEST.in
+recursive-include examples *.py
+recursive-include engine *.py

README.md

@@ -0,0 +1,242 @@
+# TokioAI-Coder IoT Package
+
+**Turn a 30B open-weight model into a fully autonomous IoT/smart-home agent.**
+
+This package contains everything needed to deploy TokioAI-Coder as an autonomous IoT controller:
+- The complete **TokioAI Engine** -- inference pipeline that wraps any Ollama model and adds reliable tool calling
+- A production-tested **IoT system prompt** with a full Home Assistant cookbook
+- **12 native tools** for system administration, file operations, network diagnostics, and robot vision
+- **Server-side investigation** -- the engine autonomously chains 8+ tool calls to answer a single question
+
+## What It Does
+
+You say: *"is Home Assistant running?"*
+
+The engine:
+1. Checks `systemctl status home-assistant` -- not found
+2. Checks `docker ps | grep home` -- not found
+3. Checks `ss -tlnp | grep 8123` -- port listening
+4. Checks `curl -s http://localhost:8123/api/` -- HA API responds
+5. Answers: "Yes, HA is running on port 8123 via Docker"
+
+All 5 steps happen **in a single API call**. The client sees only the final answer.
+
+You say: *"play some blues"*
+
+The engine:
+1. Calls HA API to send `play_media` to the Alexa
+2. Waits 3 seconds
+3. Queries the media player state to verify the music actually changed
+4. Reports: "Now playing: Blues Essentials on Jarvis"
+
+## Architecture
+
+```
+                     TokioAI Engine (OpenAI-compatible API)
+                     ====================================
+User Query ──> Router ──> Ollama Model ──> Verifier ──> Tool Executor ──>
+                 |              |              |              |
+              Intent        System         Retry          Local
+            Classifier     Prompt +       Loop (2x)     Execution
+            (0ms regex)   Few-Shot                    (read-only safe)
+                 |              |              |              |
+                 v              v              v              v
+              tool_call     Guided         Validates      Feeds result
+              / text /      Generation     JSON +         back to model
+              decision      (schema-       correct        for next step
+                            constrained)   tool names
+                                                              |
+                                                              v
+                                                    Investigation Loop
+                                                    (up to 8 rounds,
+                                                     90s timeout)
+                                                              |
+                                                              v
+                                                      Final Answer
+```
+
+## Components
+
+### 1. TokioAI Engine (`engine/`)
+The core inference pipeline (3,774 lines of Python):
+
+| Module | Lines | Purpose |
+|---|---|---|
+| `server.py` | 864 | OpenAI-compatible API with server-side investigation |
+| `schemas.py` | 497 | Tool definitions, JSON validation, parameter schemas |
+| `pipeline.py` | 476 | Main orchestrator: Router -> Memory -> Model -> Verifier |
+| `router.py` | 382 | Intent classifier (regex) + system prompt builder |
+| `memory.py` | 353 | Adaptive few-shot memory (learns from successes) |
+| `executor.py` | 331 | Safe server-side tool execution |
+| `guided.py` | 228 | JSON schema constraints for Ollama |
+| `verifier.py` | 186 | Output validation + retry logic |
+
+### 2. IoT System Prompt (`prompts/iot_system_prompt.md`)
+A production-tested system prompt that includes:
+- Complete Home Assistant API cookbook (media, lights, switches, sensors, vacuum, TTS)
+- Alexa voice control via `alexa_media` integration
+- Robot vision via moondream (1.4B vision model)
+- Investigation playbooks for multi-step problem solving
+- Anti-hallucination rules (never simulate tool execution)
+- Verification protocol (always confirm state changes actually happened)
+
+### 3. Tool Definitions (`tools/`)
+12 native tools in OpenAI function-calling format:
+- `execute_local` -- Run shell commands
+- `execute_raspi` / `execute_gcp` / `execute_router` -- Remote execution
+- `read_file` / `write_file` / `edit_file` -- File operations
+- `search_files` -- grep across codebases
+- `diagnose` -- System health checks
+- `robot_vision` -- Camera capture + AI analysis
+- `memory` -- Persistent memory across sessions
+- `task` -- Task tracking for multi-session projects
+
+## Quick Start
+
+### Prerequisites
+- Python 3.8+
+- [Ollama](https://ollama.ai/) with a model (recommended: `qwen3-coder` 30B MoE)
+- Home Assistant instance (for IoT features)
+
+### Install
+
+```bash
+# Clone this repo
+git clone https://huggingface.co/MrMoz33/tokioai-coder-iot
+cd tokioai-coder-iot
+
+# Install dependencies
+pip install flask requests
+
+# Pull a model
+ollama pull qwen3-coder  # 30B MoE (3B active), recommended
+# or: ollama pull qwen2.5-coder:7b  # lighter alternative
+```
+
+### Configure Home Assistant
+
+Set your HA token:
+```bash
+export HA_TOKEN="your-long-lived-access-token"
+export HA_URL="http://localhost:8123"  # or your HA URL
+```
+
+### Start
+
+```bash
+# Start the engine
+python -m engine serve --model qwen3-coder --port 8080
+
+# Use it (any OpenAI-compatible client works)
+curl http://localhost:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "tokioai-engine",
+    "messages": [{"role": "user", "content": "is home assistant running?"}]
+  }'
+```
+
+### With TokioAI CLI
+
+```bash
+pip install git+https://github.com/TokioAI/tokioai.git
+export TOKIOAI_ENGINE_HOST=http://localhost:8080
+tokioai  # Interactive agent with full tool calling
+```
+
+## Customization
+
+### Adding Your Own Home Assistant Entities
+
+Edit `prompts/iot_system_prompt.md` and add your entities to the cookbook section:
+
+```markdown
+LIGHTS: light.living_room, light.bedroom, light.kitchen
+SWITCHES: switch.fan, switch.heater
+SENSORS: sensor.temperature, sensor.humidity
+MEDIA: media_player.living_room_speaker
+```
+
+### Adding Custom Tools
+
+Edit `engine/schemas.py` to add new tool definitions:
+
+```python
+{
+    "type": "function",
+    "function": {
+        "name": "my_custom_tool",
+        "description": "What this tool does",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "param1": {"type": "string", "description": "First param"}
+            },
+            "required": ["param1"]
+        }
+    }
+}
+```
+
+Then add the executor in `engine/executor.py`.
+
+### Adapting for Different Smart Home Platforms
+
+The system prompt is platform-agnostic in concept. To use with:
+- **Google Home**: Replace HA API calls with Google Home API
+- **Apple HomeKit**: Use HomeKit Accessory Protocol
+- **MQTT Direct**: Replace curl commands with `mosquitto_pub/sub`
+
+The engine and tool pipeline remain identical -- only the system prompt changes.
+
+## Performance
+
+Tested on Raspberry Pi 5 (8GB) + L4 GPU (via SSH tunnel):
+
+| Metric | Value |
+|---|---|
+| Model | Qwen3-Coder 30B (3B active MoE) |
+| GPU VRAM | 19.4 GB (L4 24GB) |
+| Response time | 3-8s (simple), 15-45s (investigation) |
+| Investigation depth | Up to 8 rounds per query |
+| Tool calling accuracy | 94%+ with engine pipeline |
+| Uptime | 30+ days continuous (systemd service) |
+
+### Cost Comparison
+
+| Approach | Monthly Cost | Latency | Privacy |
+|---|---|---|---|
+| GPT-4o API | $50-200 | 2-5s | Data sent to cloud |
+| Claude API | $50-200 | 2-5s | Data sent to cloud |
+| **TokioAI-Coder (self-hosted)** | **$0** | **3-8s** | **100% local** |
+
+After initial GPU investment ($0.50-1.50/hr for L4 on GCP, or free on local hardware), all inference is free and private.
+
+## Model Compatibility
+
+| Model | Params | Tool Calling | IoT Quality | Notes |
+|---|---|---|---|---|
+| qwen3-coder | 30B (3B active) | Excellent | Excellent | Recommended. MoE = fast inference |
+| qwen2.5-coder:7b | 7B | Good | Good | Budget option |
+| llama3.1:8b | 8B | Good | Fair | General purpose |
+| deepseek-coder-v2:16b | 16B | Good | Good | Strong code understanding |
+| mistral:7b | 7B | OK | Fair | Needs guided gen |
+
+The engine's guided generation + retry logic compensates for weaker models.
+
+## Related Projects
+
+- [TokioAI CLI](https://github.com/TokioAI/tokioai) -- Multi-provider AI CLI with native tool calling
+- [TokioAI Fine-Tuning Guide](https://github.com/daletoniris/tokioai-fine-tuning-guide) -- Train your own tool-calling model
+- [TokioAI Fine-Tuning Paper](https://github.com/daletoniris/tokioai-fine-tuning-paper) -- Research paper on LLM fine-tuning for tool use
+- [TokioNav](https://github.com/daletoniris/tokionav) -- AI-controlled autonomous robot navigation
+
+## License
+
+MIT
+
+## Credits
+
+Built by Daniel Dieser ([daletoniris](https://github.com/daletoniris)) and the TokioAI team.
+
+The TokioAI Engine was developed to make small open models competitive with GPT-4 and Claude for autonomous tool calling -- specifically for IoT, cybersecurity, and DevOps tasks. The key insight: you don't need a bigger model, you need a smarter pipeline around it.

config/example.env

@@ -0,0 +1,42 @@
+# TokioAI-Coder IoT Configuration
+# Copy this to ~/.tokioai/.env and fill in your values
+
+# ============================================
+# Home Assistant
+# ============================================
+# Get a long-lived access token from:
+# HA -> Profile -> Long-Lived Access Tokens -> Create Token
+HA_TOKEN=your-long-lived-access-token-here
+HA_URL=http://localhost:8123
+
+# ============================================
+# Ollama / Model
+# ============================================
+# Where Ollama is running (default: localhost)
+OLLAMA_HOST=http://localhost:11434
+# Which model to use
+TOKIOAI_MODEL=qwen3-coder
+
+# ============================================
+# Engine Server
+# ============================================
+ENGINE_PORT=8080
+MAX_INVESTIGATION_DEPTH=8
+MAX_INVESTIGATION_TIME=90
+
+# ============================================
+# Robot Vision (optional)
+# ============================================
+# URL of the robot camera proxy (if you have one)
+# ROBOT_PROXY_URL=http://localhost:5002
+# Vision model for image analysis
+# VISION_MODEL=moondream
+
+# ============================================
+# Remote Targets (optional)
+# ============================================
+# SSH config for execute_raspi, execute_gcp, etc.
+# RASPI_HOST=192.168.1.x
+# RASPI_USER=pi
+# GCP_HOST=your-gcp-vm-ip
+# GCP_USER=your-user

engine/__init__.py

@@ -0,0 +1,13 @@
+"""
+TokioAI Engine v3.0 -- Inference Pipeline with Server-Side Investigation
+Transform any small open model into an elite AI agent.
+
+Architecture:
+  [User Prompt] -> Router -> Model -> Verifier -> Response
+                     |          |         |
+                  Memory    Executor   Retry Loop
+                            (server-side tool execution)
+"""
+
+__version__ = "3.0.0"
+__author__ = "TokioAI"

engine/__main__.py

@@ -0,0 +1,224 @@
+"""
+TokioAI Engine -- CLI Entry Point
+
+Usage:
+  python -m engine serve              # Start OpenAI-compatible API server
+  python -m engine test               # Run test suite
+  python -m engine bench              # Benchmark pipeline
+  python -m engine chat               # Interactive chat (for testing)
+  python -m engine stats              # Show memory/pipeline stats
+"""
+
+import sys
+import json
+import time
+import argparse
+
+from .pipeline import Pipeline, EngineConfig
+
+
+def cmd_serve(args):
+    """Start the API server."""
+    from .server import create_app
+    from .pipeline import EngineConfig
+
+    config = EngineConfig(
+        ollama_host=args.ollama_host,
+        model_name=args.model,
+        max_retries=args.max_retries,
+        use_guided_gen=not args.no_guided,
+        use_memory=not args.no_memory,
+        verbose=args.verbose,
+    )
+
+    print(f"""
+ _____     _   _       _    ___
+|_   _|__ | | _(_) ___ / \\  |_ _|
+  | |/ _ \\| |/ / |/ _ / _ \\  | |
+  | | (_) |   <| | (_/ ___ \\ | |
+  |_|\\___/|_|\\_\\_|\\___/_/   \\_\\___|
+   ___           _
+  | __| _ _  __ _(_) _ _  ___
+  | _| | ' \\/ _` | || ' \\/ -_)
+  |___||_||_\\__, |_||_||_\\___|
+            |___/            v3.0.0
+
+  Model:    {config.model_name}
+  Ollama:   {config.ollama_host}
+  Memory:   {'ON' if config.use_memory else 'OFF'}
+  Guided:   {'ON' if config.use_guided_gen else 'OFF'}
+  Retries:  {config.max_retries}
+  
+  API: http://{args.host}:{args.port}/v1/chat/completions
+  Health: http://{args.host}:{args.port}/health
+  Stats: http://{args.host}:{args.port}/stats
+""")
+
+    app = create_app(config)
+    app.run(host=args.host, port=args.port, debug=False)
+
+
+def cmd_chat(args):
+    """Interactive chat for testing the pipeline."""
+    config = EngineConfig(
+        ollama_host=args.ollama_host,
+        model_name=args.model,
+        verbose=args.verbose,
+    )
+    engine = Pipeline(config)
+
+    print(f"\n[TokioAI Engine] Connected to {config.ollama_host} / {config.model_name}")
+    print("[TokioAI Engine] Type 'quit' to exit, 'stats' for stats, 'reset' to clear history\n")
+
+    while True:
+        try:
+            user_input = input("\033[36myou>\033[0m ")
+        except (EOFError, KeyboardInterrupt):
+            print("\nbye.")
+            break
+
+        if not user_input.strip():
+            continue
+        if user_input.strip().lower() == "quit":
+            break
+        if user_input.strip().lower() == "stats":
+            print(json.dumps(engine.get_stats(), indent=2))
+            continue
+        if user_input.strip().lower() == "reset":
+            engine.reset()
+            print("[reset]")
+            continue
+
+        result = engine.process(user_input)
+
+        # Display result
+        print(f"\033[33m[{result.intent}|{result.confidence:.1f}|{result.attempts}att|{result.latency_ms}ms]\033[0m")
+
+        if result.output_type == "tool_call":
+            for tc in result.tool_calls:
+                print(f"\033[32m>>> TOOL: {tc['name']}({json.dumps(tc['arguments'])})\033[0m")
+        else:
+            print(f"\033[37m{result.text}\033[0m")
+        print()
+
+
+def cmd_test(args):
+    """Run the test suite."""
+    from .test_engine import run_tests
+    run_tests(verbose=args.verbose, ollama_host=args.ollama_host, model=args.model)
+
+
+def cmd_bench(args):
+    """Benchmark the pipeline."""
+    config = EngineConfig(
+        ollama_host=args.ollama_host,
+        model_name=args.model,
+        verbose=False,
+    )
+    engine = Pipeline(config)
+
+    test_prompts = [
+        ("check disk space", "tool_call"),
+        ("what is docker", "text"),
+        ("read /etc/hostname", "tool_call"),
+        ("hi", "text"),
+        ("find all python files with TODO", "tool_call"),
+        ("explain SQL injection", "text"),
+        ("is docker running", "tool_call"),
+        ("list processes by memory usage", "tool_call"),
+        ("what is the TCP 3-way handshake", "text"),
+        ("scan ports on localhost", "tool_call"),
+    ]
+
+    print(f"\n[BENCH] Running {len(test_prompts)} prompts against {config.model_name}...\n")
+    
+    results = []
+    for prompt, expected in test_prompts:
+        start = time.time()
+        result = engine.process(prompt)
+        elapsed = int((time.time() - start) * 1000)
+
+        correct = (
+            (expected == "tool_call" and result.output_type == "tool_call") or
+            (expected == "text" and result.output_type == "text")
+        )
+
+        status = "\033[32mPASS\033[0m" if correct else "\033[31mFAIL\033[0m"
+        detail = ""
+        if result.output_type == "tool_call" and result.tool_calls:
+            detail = f"-> {result.tool_calls[0]['name']}"
+        elif result.output_type == "text":
+            detail = f"-> text ({len(result.text)} chars)"
+
+        print(f"  {status} [{elapsed:4d}ms] [{result.intent:9s}] {prompt:40s} {detail}")
+        results.append(correct)
+        engine.reset()  # Reset between tests
+
+    passed = sum(results)
+    total = len(results)
+    print(f"\n[BENCH] {passed}/{total} correct ({100*passed//total}%)")
+    print(f"[BENCH] Stats: {json.dumps(engine.get_stats(), indent=2)}")
+
+
+def cmd_stats(args):
+    """Show memory and pipeline stats."""
+    from .memory import EngineMemory
+    mem = EngineMemory()
+    print(json.dumps(mem.get_stats(), indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="TokioAI Engine")
+    parser.add_argument("--ollama-host", default=None, help="Ollama API URL")
+    parser.add_argument("--model", default="tokioai-coder", help="Model name")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    
+    subparsers = parser.add_subparsers(dest="command")
+    
+    # serve
+    serve_parser = subparsers.add_parser("serve", help="Start API server")
+    serve_parser.add_argument("--host", default="0.0.0.0", help="Bind address")
+    serve_parser.add_argument("--port", type=int, default=8080, help="Port")
+    serve_parser.add_argument("--ollama-host", default=None, help="Ollama API URL")
+    serve_parser.add_argument("--model", default="tokioai-coder", help="Model name")
+    serve_parser.add_argument("--no-memory", action="store_true", help="Disable memory")
+    serve_parser.add_argument("--no-guided", action="store_true", help="Disable guided gen")
+    serve_parser.add_argument("--max-retries", type=int, default=2, help="Max retries")
+    serve_parser.add_argument("-v", "--verbose", action="store_true")
+    
+    # chat
+    chat_parser = subparsers.add_parser("chat", help="Interactive chat")
+    
+    # test
+    test_parser = subparsers.add_parser("test", help="Run tests")
+    
+    # bench
+    bench_parser = subparsers.add_parser("bench", help="Benchmark")
+    
+    # stats
+    stats_parser = subparsers.add_parser("stats", help="Show stats")
+
+    # Add common args to all subparsers that need them
+    for sp in [chat_parser, test_parser, bench_parser]:
+        sp.add_argument("--ollama-host", default=None, help="Ollama API URL")
+        sp.add_argument("--model", default="tokioai-coder", help="Model name")
+        sp.add_argument("-v", "--verbose", action="store_true")
+
+    args = parser.parse_args()
+
+    if args.command == "serve":
+        cmd_serve(args)
+    elif args.command == "chat":
+        cmd_chat(args)
+    elif args.command == "test":
+        cmd_test(args)
+    elif args.command == "bench":
+        cmd_bench(args)
+    elif args.command == "stats":
+        cmd_stats(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

engine/executor.py

@@ -0,0 +1,331 @@
+"""
+TokioAI Engine v3.0 -- Server-Side Tool Executor
+Executes tools LOCALLY on the Pi without CLI round-trips.
+This is what makes the Engine think like Opus: it can investigate autonomously.
+
+Safety: only execute_local, read_file, search_files, diagnose are allowed server-side.
+Write operations (write_file, edit_file) are ALWAYS delegated to the CLI for user approval.
+Remote operations (execute_raspi, execute_gcp, execute_router) are also delegated.
+"""
+
+import os
+import re
+import subprocess
+import time
+import glob as glob_module
+from typing import Dict, Tuple, Optional
+
+
+# Tools that the Engine can execute directly (read-only / diagnostic)
+SAFE_TOOLS = {
+    "execute_local",
+    "read_file",
+    "search_files",
+    "diagnose",
+    "robot_vision",
+}
+
+# Tools that must be delegated to the CLI (writes, remote)
+DELEGATE_TOOLS = {
+    "write_file",
+    "edit_file",
+    "execute_raspi",
+    "execute_gcp",
+    "execute_router",
+    "memory",
+    "task",
+}
+
+# Commands that are NEVER allowed server-side (destructive)
+BLOCKED_COMMANDS = [
+    r'\brm\s+-rf\s+/',
+    r'\bmkfs\b',
+    r'\bdd\s+if=',
+    r'\b(reboot|shutdown|poweroff|halt)\b',
+    r'\bsudo\s+(rm|mkfs|dd|reboot|shutdown|poweroff|halt)\b',
+    r'>\s*/dev/',
+    r'\bchmod\s+-R\s+777\s+/',
+    r'\bchown\s+-R.*\s+/',
+]
+
+
+def is_safe_tool(tool_name: str) -> bool:
+    """Check if a tool can be executed server-side."""
+    return tool_name in SAFE_TOOLS
+
+
+def is_command_blocked(command: str) -> bool:
+    """Check if a shell command is blocked for safety."""
+    for pattern in BLOCKED_COMMANDS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return True
+    return False
+
+
+def execute_tool(tool_name: str, arguments: Dict, timeout: int = 30) -> Tuple[bool, str]:
+    """
+    Execute a tool server-side.
+    
+    Returns:
+        (success: bool, output: str)
+        
+    If the tool is not in SAFE_TOOLS, returns (False, "DELEGATE") to signal
+    that this tool should be sent back to the CLI.
+    """
+    if tool_name not in SAFE_TOOLS:
+        return False, "DELEGATE"
+    
+    try:
+        if tool_name == "execute_local":
+            return _execute_local(arguments, timeout)
+        elif tool_name == "read_file":
+            return _read_file(arguments)
+        elif tool_name == "search_files":
+            return _search_files(arguments)
+        elif tool_name == "diagnose":
+            return _diagnose(arguments)
+        elif tool_name == "robot_vision":
+            return _robot_vision(arguments)
+        else:
+            return False, f"Unknown tool: {tool_name}"
+    except Exception as e:
+        return False, f"Error executing {tool_name}: {str(e)}"
+
+
+def _execute_local(arguments: Dict, default_timeout: int = 30) -> Tuple[bool, str]:
+    """Execute a shell command locally."""
+    command = arguments.get("command", "")
+    if not command:
+        return False, "No command specified"
+    
+    if is_command_blocked(command):
+        return False, f"Command blocked for safety: {command}"
+    
+    timeout = min(arguments.get("timeout", default_timeout), 60)  # Cap at 60s for server-side
+    
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env={**os.environ, "TERM": "dumb"},  # prevent color codes
+        )
+        
+        output = result.stdout
+        if result.stderr:
+            output += ("\n" if output else "") + result.stderr
+        
+        output = output.strip()
+        
+        if not output:
+            if result.returncode == 0:
+                output = "(no output)"
+            else:
+                output = f"(exit code {result.returncode}, no output)"
+        
+        # Truncate very long output to prevent context explosion
+        if len(output) > 3000:
+            output = output[:2500] + f"\n... [truncated, {len(output)} total chars]"
+        
+        success = (result.returncode == 0)
+        return success, output
+        
+    except subprocess.TimeoutExpired:
+        return False, f"Command timed out after {timeout}s"
+    except Exception as e:
+        return False, f"Execution error: {str(e)}"
+
+
+def _read_file(arguments: Dict) -> Tuple[bool, str]:
+    """Read a file from the local filesystem."""
+    path = arguments.get("path", "")
+    if not path:
+        return False, "No path specified"
+    
+    # Only allow local paths (no raspi: or gcp: prefix)
+    if ":" in path and not path.startswith("/"):
+        return False, "DELEGATE"  # Remote file, delegate to CLI
+    
+    # Expand user home
+    path = os.path.expanduser(path)
+    
+    if not os.path.exists(path):
+        return False, f"No such file or directory: {path}"
+    
+    if os.path.isdir(path):
+        return False, f"Is a directory: {path}"
+    
+    max_lines = arguments.get("lines", None)
+    
+    try:
+        with open(path, "r", errors="replace") as f:
+            if max_lines:
+                content = "".join(f.readline() for _ in range(max_lines))
+            else:
+                content = f.read()
+        
+        # Truncate
+        if len(content) > 5000:
+            content = content[:4500] + f"\n... [truncated, {len(content)} total chars]"
+        
+        return True, content.strip() if content.strip() else "(empty file)"
+        
+    except PermissionError:
+        return False, f"Permission denied: {path}"
+    except Exception as e:
+        return False, f"Error reading {path}: {str(e)}"
+
+
+def _search_files(arguments: Dict) -> Tuple[bool, str]:
+    """Search for patterns in files (like grep -rn)."""
+    pattern = arguments.get("pattern", "")
+    if not pattern:
+        return False, "No pattern specified"
+    
+    search_path = arguments.get("path", ".")
+    
+    # Only local paths
+    if ":" in search_path and not search_path.startswith("/"):
+        return False, "DELEGATE"
+    
+    search_path = os.path.expanduser(search_path)
+    file_glob = arguments.get("glob", "*")
+    
+    try:
+        # Use grep for efficiency
+        cmd = f"grep -rn --include='{file_glob}' '{pattern}' {search_path} 2>/dev/null | head -50"
+        result = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=15)
+        output = result.stdout.strip()
+        
+        if not output:
+            return True, f"No matches found for '{pattern}' in {search_path}"
+        
+        if len(output) > 3000:
+            output = output[:2500] + "\n... [truncated]"
+        
+        return True, output
+        
+    except Exception as e:
+        return False, f"Search error: {str(e)}"
+
+
+def _diagnose(arguments: Dict) -> Tuple[bool, str]:
+    """Run basic diagnostics on the local system."""
+    target = arguments.get("target", "local")
+    
+    if target != "local":
+        return False, "DELEGATE"  # Remote diagnostics delegate to CLI
+    
+    checks = []
+    
+    # CPU load
+    try:
+        with open("/proc/loadavg", "r") as f:
+            load = f.read().strip()
+        checks.append(f"Load: {load}")
+    except:
+        pass
+    
+    # Memory
+    try:
+        result = subprocess.run("free -h | head -3", shell=True, capture_output=True, text=True, timeout=5)
+        checks.append(f"Memory:\n{result.stdout.strip()}")
+    except:
+        pass
+    
+    # Disk
+    try:
+        result = subprocess.run("df -h / | tail -1", shell=True, capture_output=True, text=True, timeout=5)
+        checks.append(f"Disk: {result.stdout.strip()}")
+    except:
+        pass
+    
+    # Docker
+    try:
+        result = subprocess.run("docker ps --format 'table {{.Names}}\t{{.Status}}' 2>/dev/null | head -10", shell=True, capture_output=True, text=True, timeout=5)
+        if result.returncode == 0 and result.stdout.strip():
+            checks.append(f"Docker:\n{result.stdout.strip()}")
+    except:
+        pass
+    
+    # Key services
+    try:
+        result = subprocess.run("systemctl list-units --type=service --state=running --no-pager | head -20", shell=True, capture_output=True, text=True, timeout=5)
+        checks.append(f"Services:\n{result.stdout.strip()}")
+    except:
+        pass
+    
+    return True, "\n\n".join(checks) if checks else "Could not gather diagnostics"
+
+
+def _robot_vision(arguments: Dict) -> Tuple[bool, str]:
+    """Capture a snapshot from the robot's camera and analyze with moondream vision model."""
+    import requests
+    import base64
+    import time
+
+    ROBOT_PROXY = os.environ.get("ROBOT_PROXY_URL", "http://localhost:5002")
+    OLLAMA_URL = os.environ.get("OLLAMA_URL", "http://localhost:8200")
+    VISION_MODEL = os.environ.get("VISION_MODEL", "moondream")
+
+    question = arguments.get("question", "")
+    if not question:
+        question = "Describe what you see in this image in detail. What objects, people, furniture, or environment is visible? Be specific."
+
+    # 1. Capture snapshot from robot camera
+    t0 = time.time()
+    try:
+        resp = requests.get(f"{ROBOT_PROXY}/snapshot", timeout=10)
+        resp.raise_for_status()
+        img_data = resp.content
+    except requests.ConnectionError:
+        return False, "Robot camera unavailable -- cannot connect to robot proxy (localhost:5002). Is picar-forward.service running?"
+    except Exception as e:
+        return False, f"Error capturing snapshot from robot camera: {e}"
+
+    t_capture = time.time() - t0
+
+    if len(img_data) < 500:
+        return False, f"Robot camera returned suspiciously small image ({len(img_data)} bytes). Camera may be offline."
+
+    # 2. Encode to base64
+    img_b64 = base64.b64encode(img_data).decode('utf-8')
+
+    # 3. Analyze with vision model
+    t1 = time.time()
+    try:
+        resp = requests.post(
+            f"{OLLAMA_URL}/api/generate",
+            json={
+                "model": VISION_MODEL,
+                "prompt": question,
+                "images": [img_b64],
+                "stream": False,
+            },
+            timeout=60,
+        )
+        resp.raise_for_status()
+        result = resp.json()
+    except requests.ConnectionError:
+        return False, "Vision model unavailable -- cannot connect to Ollama (localhost:8200). Is tokioai-coder-tunnel.service running?"
+    except Exception as e:
+        return False, f"Error analyzing image with vision model: {e}"
+
+    t_analysis = time.time() - t1
+
+    description = result.get("response", "").strip()
+    if not description:
+        return False, "Vision model returned empty response."
+
+    tokens = result.get("eval_count", 0)
+
+    output = (
+        f"[Robot Vision -- moondream]\n"
+        f"Image: {len(img_data):,} bytes | Capture: {t_capture:.1f}s | Analysis: {t_analysis:.1f}s | Tokens: {tokens}\n"
+        f"Question: {question}\n"
+        f"Answer: {description}"
+    )
+
+    return True, output

engine/guided.py

@@ -0,0 +1,228 @@
+"""
+TokioAI Engine -- Guided Generation
+Forces the model to produce valid structured output using Ollama's format parameter.
+
+Instead of hoping the model generates valid JSON, we CONSTRAIN it.
+Ollama supports JSON mode natively, and we combine that with our tool schemas
+to guarantee valid output.
+
+For non-Ollama backends, we use post-processing + retry as fallback.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+from .schemas import TOOL_DEFINITIONS, TOOL_SCHEMAS, VALID_TOOL_NAMES
+
+
+def get_tool_json_schema() -> Dict:
+    """
+    Generate a JSON schema that constrains model output to valid tool calls.
+    This is used with Ollama's `format` parameter for structured output.
+    """
+    # Build a union schema: the model must output one of the valid tool call shapes
+    tool_schemas = []
+    
+    for tool_def in TOOL_DEFINITIONS:
+        func = tool_def["function"]
+        tool_schemas.append({
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "const": func["name"],
+                },
+                "arguments": func["parameters"],
+            },
+            "required": ["name", "arguments"],
+            "additionalProperties": False,
+        })
+
+    # anyOf: model can output any one of these tool call shapes
+    return {
+        "type": "object",
+        "anyOf": tool_schemas,
+    }
+
+
+def get_simple_json_schema() -> Dict:
+    """
+    Simplified schema: just name (enum) + arguments (object).
+    More compatible with Ollama's format support.
+    """
+    return {
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "enum": sorted(VALID_TOOL_NAMES),
+            },
+            "arguments": {
+                "type": "object",
+            },
+        },
+        "required": ["name", "arguments"],
+    }
+
+
+def get_text_response_schema() -> Dict:
+    """
+    Schema for text-only responses (no tool calls).
+    Forces the model to output a simple response object.
+    """
+    return {
+        "type": "object",
+        "properties": {
+            "response": {
+                "type": "string",
+                "description": "Your text response to the user",
+            },
+            "needs_tool": {
+                "type": "boolean",
+                "description": "Set to true if you think a tool should be used instead",
+            },
+        },
+        "required": ["response"],
+    }
+
+
+def get_decision_schema() -> Dict:
+    """
+    Schema for decision mode: model chooses between tool call or text response.
+    """
+    return {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["tool_call", "text_response"],
+                "description": "Whether to call a tool or respond with text",
+            },
+            "tool_call": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "enum": sorted(VALID_TOOL_NAMES),
+                    },
+                    "arguments": {
+                        "type": "object",
+                    },
+                },
+                "description": "If action is tool_call, provide the tool call here",
+            },
+            "text_response": {
+                "type": "string",
+                "description": "If action is text_response, provide your response here",
+            },
+        },
+        "required": ["action"],
+    }
+
+
+def build_ollama_request(
+    model: str,
+    messages: List[Dict],
+    intent: str,
+    force_json: bool = True,
+    temperature: float = 0.3,
+    max_tokens: int = 4096,
+    stream: bool = False,
+) -> Dict:
+    """
+    Build an Ollama /api/chat request with optional guided generation.
+    
+    Args:
+        model: Ollama model name
+        messages: Chat messages
+        intent: Classified intent (determines schema)
+        force_json: Whether to constrain output to JSON
+        temperature: Sampling temperature
+        max_tokens: Max tokens to generate
+        stream: Whether to stream the response
+        
+    Returns:
+        Request body dict ready for POST to /api/chat
+    """
+    request = {
+        "model": model,
+        "messages": messages,
+        "stream": stream,
+        "options": {
+            "temperature": temperature,
+            "num_predict": max_tokens,
+        },
+    }
+
+    if force_json and intent in ("tool_call", "decision"):
+        # Use Ollama's structured output
+        if intent == "tool_call":
+            request["format"] = get_simple_json_schema()
+        elif intent == "decision":
+            request["format"] = get_decision_schema()
+    elif force_json and intent == "text":
+        # For text, we DON'T force JSON -- let the model speak naturally
+        pass
+
+    # Add tools in OpenAI format (Ollama supports this)
+    if intent in ("tool_call", "decision"):
+        request["tools"] = TOOL_DEFINITIONS
+
+    return request
+
+
+def parse_guided_output(raw_output: str, intent: str) -> Dict:
+    """
+    Parse the guided (JSON-constrained) output from the model.
+    
+    Returns a normalized dict:
+    - For tool_call: {"type": "tool_call", "name": str, "arguments": dict}
+    - For text: {"type": "text", "response": str}
+    - For decision: {"type": "tool_call"|"text", ...}
+    """
+    try:
+        data = json.loads(raw_output)
+    except json.JSONDecodeError:
+        # Try to extract JSON from text
+        import re
+        match = re.search(r'\{.*\}', raw_output, re.DOTALL)
+        if match:
+            try:
+                data = json.loads(match.group())
+            except json.JSONDecodeError:
+                return {"type": "text", "response": raw_output}
+        else:
+            return {"type": "text", "response": raw_output}
+
+    # Decision format
+    if "action" in data:
+        if data["action"] == "tool_call" and "tool_call" in data:
+            tc = data["tool_call"]
+            return {
+                "type": "tool_call",
+                "name": tc.get("name", ""),
+                "arguments": tc.get("arguments", {}),
+            }
+        elif data["action"] == "text_response":
+            return {
+                "type": "text",
+                "response": data.get("text_response", ""),
+            }
+
+    # Direct tool call format
+    if "name" in data and data["name"] in VALID_TOOL_NAMES:
+        return {
+            "type": "tool_call",
+            "name": data["name"],
+            "arguments": data.get("arguments", {}),
+        }
+
+    # Text response format
+    if "response" in data:
+        return {
+            "type": "text",
+            "response": data["response"],
+        }
+
+    # Unknown format -- return as text
+    return {"type": "text", "response": json.dumps(data)}

engine/memory.py

@@ -0,0 +1,353 @@
+"""
+TokioAI Engine -- Adaptive Memory / Few-Shot Learning
+Maintains a persistent store of successful interactions for dynamic few-shot injection.
+
+This is the "fine-tuning in real time" -- instead of modifying weights,
+we modify the context the model sees, injecting relevant examples that
+worked before.
+
+Storage: JSON file, indexed by intent + keywords for fast retrieval.
+"""
+
+import json
+import os
+import re
+import time
+from collections import Counter
+from typing import Dict, List, Optional
+
+DEFAULT_MEMORY_PATH = os.path.expanduser("~/.tokioai-engine/memory.json")
+MAX_EXAMPLES_PER_CATEGORY = 100
+MAX_EXAMPLE_AGE_DAYS = 90
+
+
+class EngineMemory:
+    """
+    Persistent few-shot memory that makes the model smarter over time.
+    
+    Stores successful (user_input -> model_output) pairs, tagged by:
+    - intent (tool_call, code, text, decision)
+    - keywords (extracted from user input)
+    - success (was the output valid/useful?)
+    - timestamp
+    
+    On each query, retrieves the most relevant examples for few-shot injection.
+    """
+
+    def __init__(self, path: str = None):
+        self.path = path or DEFAULT_MEMORY_PATH
+        os.makedirs(os.path.dirname(self.path), exist_ok=True)
+        self.examples: List[Dict] = []
+        self._load()
+
+    def _load(self):
+        if os.path.exists(self.path):
+            try:
+                with open(self.path, "r") as f:
+                    self.examples = json.load(f)
+            except (json.JSONDecodeError, IOError):
+                self.examples = []
+        else:
+            self.examples = self._seed_examples()
+            self._save()
+
+    def _save(self):
+        with open(self.path, "w") as f:
+            json.dump(self.examples, f, indent=2, ensure_ascii=False)
+
+    def add(
+        self,
+        user_input: str,
+        model_output: str,
+        intent: str,
+        success: bool = True,
+        tool_name: str = None,
+        latency_ms: int = None,
+    ):
+        """Record a successful interaction as a few-shot example."""
+        # NEVER store errors, empty outputs, or hallucinated tool output
+        if not model_output or len(model_output.strip()) < 5:
+            return
+        if "Error calling model" in model_output or "Client Error" in model_output:
+            return
+        if "Server Error" in model_output or "Traceback" in model_output:
+            return
+        if not success:
+            return
+        # Skip duplicate: same user input + same first 100 chars of output
+        key = (user_input[:100], model_output[:100])
+        for ex in self.examples[-50:]:  # Check last 50 only for speed
+            if (ex.get("user", "")[:100], ex.get("assistant", "")[:100]) == key:
+                return
+
+        keywords = self._extract_keywords(user_input)
+
+        entry = {
+            "user": user_input[:500],
+            "assistant": model_output[:1000],
+            "intent": intent,
+            "keywords": keywords,
+            "success": success,
+            "tool_name": tool_name,
+            "latency_ms": latency_ms,
+            "timestamp": time.time(),
+            "uses": 0,  # How many times this was used as few-shot
+        }
+
+        self.examples.append(entry)
+
+        # Prune old/excess entries
+        self._prune()
+        self._save()
+
+    def retrieve(
+        self,
+        user_input: str,
+        intent: str = None,
+        top_k: int = 3,
+    ) -> List[Dict]:
+        """
+        Retrieve the most relevant few-shot examples for a given query.
+        Uses keyword overlap + intent matching + recency for ranking.
+        """
+        if not self.examples:
+            return []
+
+        query_keywords = set(self._extract_keywords(user_input))
+        scored = []
+
+        for ex in self.examples:
+            if not ex.get("success", True):
+                continue  # Skip failed examples
+
+            score = 0.0
+
+            # Keyword overlap (most important)
+            ex_keywords = set(ex.get("keywords", []))
+            overlap = query_keywords & ex_keywords
+            if overlap:
+                score += len(overlap) * 3.0
+
+            # Intent match
+            if intent and ex.get("intent") == intent:
+                score += 2.0
+
+            # Recency bonus (newer = better, decay over 30 days)
+            age_days = (time.time() - ex.get("timestamp", 0)) / 86400
+            recency = max(0, 1.0 - age_days / 30)
+            score += recency
+
+            # Usage penalty (avoid showing the same examples every time)
+            score -= ex.get("uses", 0) * 0.5
+
+            if score > 0:
+                scored.append((score, ex))
+
+        # Sort by score descending
+        scored.sort(key=lambda x: x[0], reverse=True)
+
+        # Mark as used
+        results = []
+        for score, ex in scored[:top_k]:
+            ex["uses"] = ex.get("uses", 0) + 1
+            results.append(ex)
+
+        if results:
+            self._save()
+
+        return results
+
+    def get_stats(self) -> Dict:
+        """Return memory statistics."""
+        if not self.examples:
+            return {"total": 0}
+
+        intents = Counter(ex.get("intent", "unknown") for ex in self.examples)
+        tools = Counter(ex.get("tool_name", "none") for ex in self.examples if ex.get("tool_name"))
+        success_rate = sum(1 for ex in self.examples if ex.get("success", True)) / len(self.examples)
+
+        return {
+            "total": len(self.examples),
+            "by_intent": dict(intents),
+            "by_tool": dict(tools),
+            "success_rate": round(success_rate, 2),
+            "oldest_days": round((time.time() - min(ex.get("timestamp", time.time()) for ex in self.examples)) / 86400, 1),
+        }
+
+    def feedback(self, index: int, success: bool):
+        """Update success status for an example (for learning from failures)."""
+        if 0 <= index < len(self.examples):
+            self.examples[index]["success"] = success
+            self._save()
+
+    def _extract_keywords(self, text: str) -> List[str]:
+        """Extract meaningful keywords from text."""
+        # Lowercase, split, remove common words
+        stopwords = {
+            "the", "a", "an", "is", "are", "was", "were", "be", "been",
+            "have", "has", "had", "do", "does", "did", "will", "would",
+            "could", "should", "may", "might", "can", "shall", "must",
+            "to", "of", "in", "for", "on", "with", "at", "by", "from",
+            "it", "its", "this", "that", "these", "those", "my", "your",
+            "i", "me", "we", "us", "you", "he", "she", "they", "them",
+            "and", "or", "but", "not", "if", "then", "else", "so",
+            "what", "how", "why", "when", "where", "which", "who",
+            "que", "el", "la", "los", "las", "un", "una", "de", "en",
+            "por", "para", "con", "es", "no", "si", "como", "me",
+            "please", "help", "want", "need", "tell",
+        }
+
+        words = re.findall(r'[a-z0-9_./:-]+', text.lower())
+        keywords = [w for w in words if w not in stopwords and len(w) > 1]
+
+        # Also extract paths and commands
+        paths = re.findall(r'/[\w./+-]+', text)
+        keywords.extend(paths)
+
+        return keywords[:20]  # Cap at 20 keywords
+
+    def _prune(self):
+        """Remove old or excess entries."""
+        now = time.time()
+        max_age = MAX_EXAMPLE_AGE_DAYS * 86400
+
+        # Remove old entries
+        self.examples = [
+            ex for ex in self.examples
+            if now - ex.get("timestamp", now) < max_age
+        ]
+
+        # If still too many, keep the most successful/used ones
+        if len(self.examples) > MAX_EXAMPLES_PER_CATEGORY * 5:
+            # Sort by (success, -age) and keep top N
+            self.examples.sort(
+                key=lambda ex: (ex.get("success", True), -ex.get("timestamp", 0)),
+                reverse=True,
+            )
+            self.examples = self.examples[:MAX_EXAMPLES_PER_CATEGORY * 5]
+
+    def _seed_examples(self) -> List[Dict]:
+        """Seed initial few-shot examples for cold start."""
+        now = time.time()
+        seeds = [
+            # Tool call examples
+            {
+                "user": "check disk space",
+                "assistant": '{"name": "execute_local", "arguments": {"command": "df -h"}}',
+                "intent": "tool_call",
+                "keywords": ["check", "disk", "space"],
+                "tool_name": "execute_local",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "what processes are using the most memory",
+                "assistant": '{"name": "execute_local", "arguments": {"command": "ps aux --sort=-%mem | head -20"}}',
+                "intent": "tool_call",
+                "keywords": ["processes", "memory"],
+                "tool_name": "execute_local",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "read the nginx config",
+                "assistant": '{"name": "read_file", "arguments": {"path": "/etc/nginx/nginx.conf"}}',
+                "intent": "tool_call",
+                "keywords": ["read", "nginx", "config"],
+                "tool_name": "read_file",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "find all python files with TODO comments",
+                "assistant": '{"name": "search_files", "arguments": {"pattern": "TODO", "glob": "*.py"}}',
+                "intent": "tool_call",
+                "keywords": ["find", "python", "todo"],
+                "tool_name": "search_files",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "check system health",
+                "assistant": '{"name": "diagnose", "arguments": {"target": "local"}}',
+                "intent": "tool_call",
+                "keywords": ["check", "system", "health"],
+                "tool_name": "diagnose",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "show me the contents of /etc/hostname",
+                "assistant": '{"name": "read_file", "arguments": {"path": "/etc/hostname"}}',
+                "intent": "tool_call",
+                "keywords": ["show", "contents", "/etc/hostname"],
+                "tool_name": "read_file",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "list docker containers",
+                "assistant": '{"name": "execute_local", "arguments": {"command": "docker ps -a"}}',
+                "intent": "tool_call",
+                "keywords": ["docker", "containers", "list"],
+                "tool_name": "execute_local",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "scan ports on 192.168.1.1",
+                "assistant": '{"name": "execute_local", "arguments": {"command": "nmap -sV 192.168.1.1"}}',
+                "intent": "tool_call",
+                "keywords": ["scan", "ports", "nmap", "192.168.1.1"],
+                "tool_name": "execute_local",
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            # Text examples (NO tool calls)
+            {
+                "user": "what is SQL injection",
+                "assistant": "SQL injection is an attack where malicious SQL code is inserted into application queries through user input. The attacker can read, modify, or delete database data, bypass authentication, or even execute system commands. Prevention: parameterized queries, input validation, least-privilege DB accounts, WAF rules.",
+                "intent": "text",
+                "keywords": ["sql", "injection"],
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "explain the TCP 3-way handshake",
+                "assistant": "TCP 3-way handshake establishes a connection: (1) Client sends SYN with initial sequence number, (2) Server responds SYN-ACK with its own sequence number and acknowledges client's, (3) Client sends ACK. After this, data flows bidirectionally. Termination uses a 4-way FIN handshake.",
+                "intent": "text",
+                "keywords": ["tcp", "handshake"],
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            {
+                "user": "hi",
+                "assistant": "Hey. What do you need?",
+                "intent": "text",
+                "keywords": ["hi"],
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+            # Decision examples (model correctly chose NOT to use tool)
+            {
+                "user": "what is docker",
+                "assistant": "Docker is a containerization platform that packages applications with their dependencies into isolated containers. Containers share the host kernel (unlike VMs), making them lightweight and fast. Key concepts: images (blueprints), containers (running instances), Dockerfile (build instructions), docker-compose (multi-container apps).",
+                "intent": "decision",
+                "keywords": ["docker"],
+                "success": True,
+                "timestamp": now,
+                "uses": 0,
+            },
+        ]
+        return seeds

engine/pipeline.py

@@ -0,0 +1,476 @@
+"""
+TokioAI Engine v2.0 -- Main Pipeline
+Orchestrates: Router -> Memory -> Guided Generation -> Verifier -> Output
+
+The pipeline wraps any Ollama-compatible model and transforms it into
+an elite AI agent with multi-step tool calling.
+
+Key change from v1: when force_intent is None, the model freely chooses
+between tool calls and text responses. This enables investigation chains.
+"""
+
+import json
+import sys
+import os
+import re
+import time
+import requests
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .router import classify_intent, build_system_prompt, IntentType
+from .memory import EngineMemory
+from .guided import build_ollama_request, parse_guided_output
+from .verifier import Verifier, RetryStrategy, VerificationResult
+from .schemas import TOOL_DEFINITIONS, tools_to_prompt_text, validate_tool_call
+
+
+class EngineConfig:
+    """Pipeline configuration."""
+    
+    def __init__(
+        self,
+        ollama_host: str = None,
+        model_name: str = "tokioai-coder",
+        max_retries: int = 2,
+        temperature: float = 0.3,
+        max_tokens: int = 4096,
+        use_guided_gen: bool = True,
+        use_memory: bool = True,
+        memory_path: str = None,
+        verbose: bool = False,
+    ):
+        self.ollama_host = ollama_host or os.getenv(
+            "TOKIOAI_ENGINE_HOST",
+            os.getenv("OLLAMA_HOST", "http://localhost:11434")
+        )
+        self.model_name = model_name
+        self.max_retries = max_retries
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.use_guided_gen = use_guided_gen
+        self.use_memory = use_memory
+        self.memory_path = memory_path
+        self.verbose = verbose
+
+
+class PipelineResult:
+    """Result from the pipeline."""
+    
+    def __init__(
+        self,
+        output_type: str,  # "tool_call", "text"
+        tool_calls: List[Dict] = None,
+        text: str = "",
+        intent: str = "",
+        confidence: float = 0.0,
+        attempts: int = 1,
+        latency_ms: int = 0,
+        from_memory: bool = False,
+    ):
+        self.output_type = output_type
+        self.tool_calls = tool_calls or []
+        self.text = text
+        self.intent = intent
+        self.confidence = confidence
+        self.attempts = attempts
+        self.latency_ms = latency_ms
+        self.from_memory = from_memory
+
+    def to_openai_message(self) -> Dict:
+        """Convert to OpenAI-style assistant message."""
+        if self.output_type == "tool_call" and self.tool_calls:
+            return {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": f"call_{i}",
+                        "type": "function",
+                        "function": {
+                            "name": tc["name"],
+                            "arguments": json.dumps(tc["arguments"]),
+                        },
+                    }
+                    for i, tc in enumerate(self.tool_calls)
+                ],
+            }
+        return {
+            "role": "assistant",
+            "content": self.text,
+        }
+
+    def __repr__(self):
+        if self.output_type == "tool_call":
+            names = [tc["name"] for tc in self.tool_calls]
+            return f"PipelineResult(tool_calls={names}, attempts={self.attempts}, {self.latency_ms}ms)"
+        return f"PipelineResult(text={self.text[:80]!r}, attempts={self.attempts}, {self.latency_ms}ms)"
+
+
+class Pipeline:
+    """
+    The TokioAI Engine pipeline.
+    
+    Usage:
+        engine = Pipeline(EngineConfig(model_name="tokioai-coder"))
+        result = engine.process("check disk space")
+        # result.tool_calls = [{"name": "execute_local", "arguments": {"command": "df -h"}}]
+    """
+
+    def __init__(self, config: EngineConfig = None):
+        self.config = config or EngineConfig()
+        self.verifier = Verifier()
+        self.retry_strategy = RetryStrategy(max_retries=self.config.max_retries)
+        self.memory = EngineMemory(self.config.memory_path) if self.config.use_memory else None
+        self.conversation_history: List[Dict] = []
+        self._stats = {
+            "total_requests": 0,
+            "tool_calls": 0,
+            "text_responses": 0,
+            "retries": 0,
+            "failures": 0,
+            "total_latency_ms": 0,
+        }
+
+    def process(
+        self,
+        user_message: str,
+        conversation_history: List[Dict] = None,
+        force_intent: str = None,
+    ) -> PipelineResult:
+        """
+        Process a user message through the full pipeline.
+        
+        Args:
+            user_message: The user's input
+            conversation_history: Previous messages (optional)
+            force_intent: Override intent classification
+                - "text": force text-only response (no tool calls allowed)
+                - "tool_call": force tool call
+                - None: model decides freely (default for investigation rounds)
+            
+        Returns:
+            PipelineResult with tool calls or text response
+        """
+        start_time = time.time()
+        self._stats["total_requests"] += 1
+
+        history = conversation_history or self.conversation_history
+
+        # === STAGE 1: ROUTE ===
+        if force_intent:
+            intent, confidence = force_intent, 1.0
+        else:
+            intent, confidence = classify_intent(user_message, history)
+
+        if self.config.verbose:
+            print(f"[ENGINE] Intent: {intent} (confidence: {confidence:.2f})")
+
+        # === PURE TEXT SHORT-CIRCUIT ===
+        # For greetings and thanks, strip conversation history to prevent
+        # context bleeding (e.g. "hola" after HA investigation should NOT talk about HA).
+        # BUT NOT for affirmations ("dale", "si", "ok") which need context.
+        import re as _re
+        _GREETING_PATS = [
+            r'^(hi|hello|hey|hola|que\s+tal|buenos?\s+d[ií]as?|buenas?\s+(?:tardes?|noches?))\s*[.!?]*$',
+            r'^(thanks?|thank\s+you|gracias|thx|de\s+nada)\s*[.!?]*$',
+            r'^(como\s+(va|estas?|andas?|te\s+va)|how\s+are\s+you)\s*[.!?]*$',
+            r'^(todo\s+bien|bien\s+y\s+tu)\s*[.!?]*$',
+            r'\b(who\s+are\s+you|what\s+can\s+you|tell\s+me\s+about\s+yourself)\b',
+        ]
+        _msg_lower = user_message.lower().strip()
+        is_pure_text = (
+            intent == "text" and confidence >= 0.9
+            and any(_re.match(p, _msg_lower, _re.IGNORECASE) for p in _GREETING_PATS)
+        )
+
+        # === STAGE 2: MEMORY LOOKUP ===
+        few_shot = []
+        if self.memory and self.config.use_memory and not is_pure_text:
+            few_shot = self.memory.retrieve(user_message, intent, top_k=3)
+            if self.config.verbose and few_shot:
+                print(f"[ENGINE] Memory: {len(few_shot)} relevant examples found")
+
+        # === STAGE 3: BUILD PROMPT ===
+        system_prompt = build_system_prompt(
+            intent=intent,
+            few_shot_examples=few_shot,
+        )
+
+        # Build messages
+        messages = [{"role": "system", "content": system_prompt}]
+
+        # Add conversation history -- but for pure text (greetings etc),
+        # only include the LAST 2 messages to avoid context bleeding
+        if is_pure_text:
+            # For greetings/thanks: minimal or no history
+            # This prevents "hola" from generating an HA status report
+            # because the previous conversation was about HA
+            if self.config.verbose:
+                print(f"[ENGINE] Pure text detected, stripping history ({len(history)} msgs)")
+        else:
+            for msg in history[-20:]:
+                messages.append(msg)
+
+        # Add current user message
+        messages.append({"role": "user", "content": user_message})
+
+        # === STAGE 4: GENERATE ===
+        # Use guided generation ONLY for definite tool_call intent on first request
+        # For investigation rounds (force_intent=None with history), let model choose
+        use_guided = self.config.use_guided_gen and intent == "tool_call"
+
+        result = self._generate_with_retries(
+            messages=messages,
+            intent=intent,
+            use_guided=use_guided,
+            force_text_only=(force_intent == "text"),
+        )
+
+        # === STAGE 5: RECORD ===
+        latency_ms = int((time.time() - start_time) * 1000)
+        result.intent = intent
+        result.confidence = confidence
+        result.latency_ms = latency_ms
+
+        self._stats["total_latency_ms"] += latency_ms
+
+        if result.output_type == "tool_call":
+            self._stats["tool_calls"] += 1
+        else:
+            self._stats["text_responses"] += 1
+
+        # Save to memory (only successful results)
+        if self.memory and result.output_type in ("tool_call", "text"):
+            tool_name = result.tool_calls[0]["name"] if result.tool_calls else None
+            output_text = (
+                json.dumps(result.tool_calls[0]) if result.tool_calls
+                else result.text[:500]
+            )
+            self.memory.add(
+                user_input=user_message,
+                model_output=output_text,
+                intent=intent,
+                success=True,
+                tool_name=tool_name,
+                latency_ms=latency_ms,
+            )
+
+        # Update conversation history
+        self.conversation_history.append({"role": "user", "content": user_message})
+        self.conversation_history.append(result.to_openai_message())
+
+        return result
+
+    def add_tool_result(self, tool_name: str, result: str):
+        """Add a tool execution result to the conversation."""
+        self.conversation_history.append({
+            "role": "tool",
+            "content": result,
+            "name": tool_name,
+        })
+
+    def _generate_with_retries(
+        self,
+        messages: List[Dict],
+        intent: str,
+        use_guided: bool,
+        force_text_only: bool = False,
+    ) -> PipelineResult:
+        """
+        Generate model output with retry logic on verification failure.
+        
+        Args:
+            messages: Full message chain
+            intent: Classified intent
+            use_guided: Whether to use Ollama guided generation (JSON schema)
+            force_text_only: If True, NEVER return tool calls (depth limit reached)
+        """
+
+        for attempt in range(self.config.max_retries + 1):
+            # Build request
+            if use_guided:
+                request = build_ollama_request(
+                    model=self.config.model_name,
+                    messages=messages,
+                    intent=intent,
+                    force_json=True,
+                    temperature=self.config.temperature,
+                    max_tokens=self.config.max_tokens,
+                )
+            else:
+                # Free-form generation: model can output tool calls OR text
+                request = {
+                    "model": self.config.model_name,
+                    "messages": messages,
+                    "stream": False,
+                    "options": {
+                        "temperature": self.config.temperature,
+                        "num_predict": self.config.max_tokens,
+                    },
+                }
+                # Include tools so Ollama can use native tool calling
+                # UNLESS we're forcing text-only mode
+                if not force_text_only and intent != "text":
+                    request["tools"] = TOOL_DEFINITIONS
+
+            # Call Ollama
+            try:
+                raw_output, native_tool_calls = self._call_ollama(request)
+            except Exception as e:
+                if self.config.verbose:
+                    print(f"[ENGINE] Ollama error: {e}")
+                self._stats["failures"] += 1
+                return PipelineResult(
+                    output_type="text",
+                    text=f"Error calling model: {e}",
+                    attempts=attempt + 1,
+                )
+
+            if self.config.verbose:
+                print(f"[ENGINE] Raw output (attempt {attempt+1}): {raw_output[:200]}")
+                if native_tool_calls:
+                    print(f"[ENGINE] Native tool calls: {native_tool_calls}")
+
+            # === NATIVE TOOL CALLS (Ollama returned tool_calls in response) ===
+            if native_tool_calls and not force_text_only:
+                valid_calls = []
+                for tc in native_tool_calls:
+                    is_valid, err = validate_tool_call(tc["name"], tc["arguments"])
+                    if is_valid:
+                        valid_calls.append(tc)
+                    elif self.config.verbose:
+                        print(f"[ENGINE] Invalid native tool call: {err}")
+                
+                if valid_calls:
+                    return PipelineResult(
+                        output_type="tool_call",
+                        tool_calls=valid_calls,
+                        attempts=attempt + 1,
+                    )
+
+            # === GUIDED OUTPUT (JSON constrained) ===
+            if use_guided and intent in ("tool_call", "decision"):
+                parsed = parse_guided_output(raw_output, intent)
+                if parsed["type"] == "tool_call" and not force_text_only:
+                    name = parsed.get("name", "")
+                    args = parsed.get("arguments", {})
+                    is_valid, err = validate_tool_call(name, args)
+                    if is_valid:
+                        return PipelineResult(
+                            output_type="tool_call",
+                            tool_calls=[{"name": name, "arguments": args}],
+                            attempts=attempt + 1,
+                        )
+                    elif self.config.verbose:
+                        print(f"[ENGINE] Guided validation failed: {err}")
+                elif parsed["type"] == "text":
+                    return PipelineResult(
+                        output_type="text",
+                        text=parsed.get("response", raw_output),
+                        attempts=attempt + 1,
+                    )
+
+            # === FREE-FORM VERIFICATION ===
+            verification = self.verifier.verify(raw_output, expected_intent=intent)
+
+            if verification.valid:
+                if verification.output_type == "tool_call" and not force_text_only:
+                    # Model wants to call a tool -- allow it
+                    return PipelineResult(
+                        output_type="tool_call",
+                        tool_calls=verification.tool_calls,
+                        attempts=attempt + 1,
+                    )
+                else:
+                    # Text response (or forced text-only)
+                    text = verification.text or raw_output
+                    # Clean up: if model tried to output tool call JSON but we're
+                    # in text-only mode, don't show the raw JSON
+                    if force_text_only and verification.output_type == "tool_call":
+                        text = (
+                            "Based on my investigation, I was unable to gather "
+                            "additional information. Here is what I found so far."
+                        )
+                    return PipelineResult(
+                        output_type="text",
+                        text=text,
+                        attempts=attempt + 1,
+                    )
+
+            # Failed verification -- retry?
+            if self.retry_strategy.should_retry(attempt, verification):
+                self._stats["retries"] += 1
+                retry_msg = self.retry_strategy.get_retry_message(attempt, verification)
+                messages.append({"role": "assistant", "content": raw_output})
+                messages.append({"role": "user", "content": retry_msg})
+                if self.config.verbose:
+                    print(f"[ENGINE] Retrying (attempt {attempt+2})...")
+                continue
+            else:
+                # Give up -- return whatever we got
+                self._stats["failures"] += 1
+                return PipelineResult(
+                    output_type="text",
+                    text=verification.text or raw_output,
+                    attempts=attempt + 1,
+                )
+
+        # Should never reach here
+        return PipelineResult(output_type="text", text="Engine error: max retries exceeded")
+
+    def _call_ollama(self, request: Dict):
+        """
+        Call Ollama API and return (text_output, native_tool_calls).
+        
+        Returns:
+            Tuple of (str, list):
+                - text content from the response
+                - list of native tool calls (if any), each as {name, arguments}
+        """
+        url = f"{self.config.ollama_host}/api/chat"
+        
+        try:
+            resp = requests.post(url, json=request, timeout=120)
+            if self.config.verbose and resp.status_code != 200:
+                print(f"[ENGINE] Ollama HTTP {resp.status_code}: {resp.text[:500]}")
+            resp.raise_for_status()
+            data = resp.json()
+        except requests.exceptions.ConnectionError:
+            raise RuntimeError(f"Cannot connect to Ollama at {self.config.ollama_host}")
+        except requests.exceptions.Timeout:
+            raise RuntimeError("Ollama request timed out (120s)")
+        except Exception as e:
+            raise RuntimeError(f"Ollama request failed: {e}")
+
+        message = data.get("message", {})
+        content = message.get("content", "")
+
+        # Check for native tool calls from Ollama
+        native_tool_calls = []
+        tool_calls_raw = message.get("tool_calls", [])
+        if tool_calls_raw:
+            for tc in tool_calls_raw:
+                func = tc.get("function", {})
+                native_tool_calls.append({
+                    "name": func.get("name", ""),
+                    "arguments": func.get("arguments", {}),
+                })
+
+        return content, native_tool_calls
+
+    def get_stats(self) -> Dict:
+        """Return pipeline statistics."""
+        total = self._stats["total_requests"] or 1
+        return {
+            "total_requests": self._stats["total_requests"],
+            "tool_calls": self._stats["tool_calls"],
+            "text_responses": self._stats["text_responses"],
+            "retries": self._stats["retries"],
+            "failures": self._stats["failures"],
+            "avg_latency_ms": self._stats["total_latency_ms"] // total,
+            "tool_call_rate": f"{100 * self._stats['tool_calls'] // total}%",
+        }
+
+    def reset(self):
+        """Reset conversation history."""
+        self.conversation_history = []

engine/router.py

@@ -0,0 +1,382 @@
+"""
+TokioAI Engine v3.0 -- Router / Intent Classifier
+Classifies user intent and builds optimal prompts with dynamic few-shot injection.
+
+v3.0 changes:
+- System prompt rewritten with INVESTIGATION PLAYBOOKS
+- "esta funcionando X?" is ALWAYS tool_call, never text
+- Better Spanish + investigation pattern detection
+- Knowledge about the local system (Pi, HA, Docker)
+"""
+
+import re
+from typing import Dict, List, Optional, Tuple
+from .schemas import TOOL_DEFINITIONS, tools_to_prompt_text
+
+
+# ============================================================
+# INTENT CLASSIFICATION (zero-cost, pure regex/heuristics)
+# ============================================================
+
+TOOL_INDICATORS = [
+    # Direct action verbs
+    r'\b(run|execute|check|show|list|find|search|scan|install|deploy|restart|stop|start|kill|create|delete|remove|move|copy|rename)\b',
+    # System queries (these ALWAYS need real data)
+    r'\b(disk|memory|cpu|ram|process|port|network|service|docker|container|pid|uptime|load)\b',
+    r'\b(file|directory|folder|path|config|log|permission)\b',
+    # Specific commands
+    r'\b(ls|cat|grep|find|ps|df|du|top|htop|netstat|ss|curl|wget|ping|nmap|apt|pip|npm|systemctl)\b',
+    # Target references
+    r'\b(raspi|raspberry|gcp|router|server|vm|machine|host)\b',
+    # File operations
+    r'\b(read|write|edit|modify|update|append|save)\s+(the\s+)?file\b',
+    r'/[a-z]+(/[a-z0-9_./-]+)+',  # Unix paths
+    # Diagnostic
+    r'\b(diagnos|health|status)\b',
+    # STATE QUERIES -- these ALWAYS need tools (never answer from "knowledge")
+    r'\b(running|installed|active|enabled|listening|open|up|down|alive|funciona|funcionando|corriendo|prendid[oa]|encendid[oa]|andando)\b',
+    r'\b(version|cuant[oa]s?|cuales|which|where|donde|what.*running|que.*corre|que.*hay)\b',
+    # Investigation patterns
+    r'\b(check|verify|test|try|connect|access|reach|investigate)\b',
+    # Home automation
+    r'\b(home\s*assistant|hass|hassio|zigbee|zwave|mqtt|tasmota|esphome|automation|sensor|switch|light)\b',
+]
+
+CODE_INDICATORS = [
+    r'\b(write|create|build|implement|code|script|function|class|program)\b.*\b(in|using|with)\s+(python|bash|javascript|rust|go|c\+\+|java|typescript)\b',
+    r'\b(write|create|build)\b.*\b(python|bash|javascript|rust|go|java|typescript)\b.*\b(script|function|program|code)\b',
+    r'\b(algorithm|data\s+structure|design\s+pattern|architecture)\b',
+    r'\b(bug|error|fix|debug|traceback|exception|syntax)\b.*\b(code|script|program|file)\b',
+]
+
+TEXT_INDICATORS = [
+    # Greetings (EN + ES)
+    r'^(hi|hello|hey|hola|que\s+tal|buenos?\s+d[ií]as?|buenas?\s+(?:tardes?|noches?))\s*[.!?]*$',
+    r'^(thanks?|thank\s+you|gracias|thx|de\s+nada)\s*[.!?]*$',
+    # Conversational follow-ups
+    r'^(como\s+(va|estas?|andas?|te\s+va)|how\s+are\s+you|how\'?s\s+it\s+going|what\'?s\s+up)\s*[.!?]*$',
+    r'^(todo\s+bien|bien\s+y\s+tu|genial|cool|nice|great|awesome)\s*[.!?]*$',
+    r'^(que\s+onda|que\s+hay|que\s+pasa|que\s+cuentas)\s*[.!?]*$',
+    # Short affirmations
+    r'^(yes|no|ok|okay|sure|maybe|si|no|dale|genial|perfecto|claro|obvio|exacto|listo)\s*[.!?]*$',
+    # Identity / meta questions  
+    r'\b(who\s+are\s+you|what\s+can\s+you|tell\s+me\s+about\s+yourself)\b',
+    r'\b(opinion|think\s+about|recommend|suggest|advice)\b',
+    # Explicit CONCEPT explanations (NOT status checks)
+    r'^(explain|describe|define)\s+(the\s+)?(concept|theory|protocol|idea|principle|difference)\b',
+    r'^what\s+is\s+(a\s+)?(concept|theory|protocol|principle|idea|technique|method)\b',
+]
+
+
+class IntentType:
+    TOOL_CALL = "tool_call"
+    CODE = "code"
+    TEXT = "text"
+    DECISION = "decision"
+
+
+def classify_intent(user_message: str, conversation_history: list = None) -> Tuple[str, float]:
+    """
+    Classify user intent. Returns (intent_type, confidence).
+    
+    v3.0 RULE: Any question about whether something IS RUNNING, IS INSTALLED,
+    IS WORKING, etc. is ALWAYS a tool_call. We can never answer these from
+    "knowledge" -- we must CHECK THE ACTUAL SYSTEM.
+    """
+    msg = user_message.lower().strip()
+
+    # Investigation prompts from the engine itself
+    if msg.startswith("investigation"):
+        return IntentType.DECISION, 0.9
+    if "gathered enough" in msg or "final answer" in msg or "what i found" in msg:
+        return IntentType.DECISION, 0.8
+
+    # Empty or very short
+    if len(msg) < 3:
+        return IntentType.TEXT, 0.9
+
+    # ===== STRONG TEXT SIGNALS (pure greetings, thanks, etc.) =====
+    # These are ONLY pure conversational. "hola" alone = text.
+    # But "hola, esta funcionando HA?" = tool_call (caught by tool indicators below)
+    for pattern in TEXT_INDICATORS:
+        if re.match(pattern, msg, re.IGNORECASE):
+            return IntentType.TEXT, 0.95
+
+    # ===== STATE QUESTIONS ARE ALWAYS TOOL CALLS =====
+    # "esta funcionando X?" / "is X running?" / "funciona el HA?" / etc.
+    state_patterns = [
+        r'\b(esta|está)\s+(funcionando|corriendo|andando|prendid[oa]|activ[oa]|instalad[oa])\b',
+        r'\b(funciona|corre|anda)\s+(el|la|lo|los|las)?\s*\w+',
+        r'\bis\s+\w+\s+(running|installed|active|working|up|down|alive|enabled|listening)\b',
+        r'\b(running|installed|active|working|funciona)\b.*\?',
+        r'\bcheck\s+(if|whether|that)\b',
+        # Port/network state queries  
+        r'\b(puerto|port)\s+\d+',
+        r'\bhay\s+algo\s+(en|corriendo|escuchando)',
+        r'\b(que|qué)\s+(hay|corre|esta)\s+(en|corriendo)',
+        r'\b(listening|escuchando)\s+(on|en)\b',
+        # Who/what is queries about system state
+        r'\b(quien|quién|who)\s+(esta|está|is)\s+(logueado|logged|conectado|connected)\b',
+        r'\b(puertos?|ports?)\s+(estan|están|are)\s+(escuchando|listening|abiertos?|open)\b',
+        r'\b(vulnerabilidad|vulnerability|vulnerabilidades|vulnerabilities)\b',
+        r'\b(audit|auditoria|auditoría)\b.*\b(seguridad|security)\b',
+        r'\b(seguridad|security)\b.*\b(audit|auditoria|auditoría)\b',
+        r'\b(logueado|logged\s+in|conectado)\b',
+        # Vision / robot camera queries
+        r'\b(que\s+ves|qué\s+ves|what\s+do\s+you\s+see|what\s+can\s+you\s+see)\b',
+        r'\b(mira|look|fijate|fíjate|observa|observe)\b',
+        r'\b(hay\s+alguien|is\s+anyone|is\s+there\s+anyone|who\s+is\s+there|quien\s+hay)\b',
+        r'\b(muestra|show\s+me|take\s+a\s+(photo|picture|snapshot)|saca\s+una?\s+foto)\b',
+        r'\b(camara|cámara|camera)\b',
+        r'\b(ves\s+algo|see\s+anything|what.s\s+around)\b',
+        r'\b(describe\s+(the\s+)?room|describe\s+(la\s+)?habitaci[oó]n|describe\s+(el\s+)?entorno)\b',
+    ]
+    for pattern in state_patterns:
+        if re.search(pattern, msg, re.IGNORECASE):
+            return IntentType.TOOL_CALL, 0.95
+
+    # ===== "what is X?" knowledge questions (concept, not status) =====
+    # "what is docker?" = text. "what is running on port 8123?" = tool.
+    if re.match(r'^(what\s+is|what\s+are|explain|describe|define|que\s+es|qué\s+es)\s+', msg):
+        # Check if it's asking about runtime state
+        if re.search(r'\b(running|on\s+port|installed|active|listening|my\s+server|this\s+machine)\b', msg):
+            return IntentType.TOOL_CALL, 0.9
+        return IntentType.TEXT, 0.85
+
+    # Score each category
+    tool_score = 0
+    code_score = 0
+    text_score = 0
+
+    for pattern in TOOL_INDICATORS:
+        if re.search(pattern, msg, re.IGNORECASE):
+            tool_score += 1
+
+    for pattern in CODE_INDICATORS:
+        if re.search(pattern, msg, re.IGNORECASE):
+            code_score += 1
+
+    for pattern in TEXT_INDICATORS:
+        if re.search(pattern, msg, re.IGNORECASE):
+            text_score += 1
+
+    # Boost: previous turn context
+    if conversation_history:
+        last = conversation_history[-1] if conversation_history else None
+        if last and last.get("role") == "tool":
+            tool_score += 2
+        if last and last.get("role") == "assistant":
+            content = last.get("content", "")
+            if "I ran:" in content or "Result of" in content:
+                tool_score += 1
+
+    # Determine winner
+    scores = {
+        IntentType.TOOL_CALL: tool_score,
+        IntentType.CODE: code_score,
+        IntentType.TEXT: text_score,
+    }
+
+    max_score = max(scores.values())
+    total = sum(scores.values()) or 1
+
+    if max_score == 0:
+        if len(msg) < 30:
+            return IntentType.TEXT, 0.6
+        # Longer messages with no clear indicators -> decision
+        return IntentType.DECISION, 0.4
+
+    winner = max(scores, key=scores.get)
+    confidence = max_score / (total + 1)
+
+    # Close scores -> decision
+    if tool_score > 0 and text_score > 0 and abs(tool_score - text_score) <= 1:
+        return IntentType.DECISION, 0.5
+
+    return winner, min(confidence, 0.95)
+
+
+# ============================================================
+# SYSTEM PROMPT (v3.0 -- with investigation playbooks)
+# ============================================================
+
+SYSTEM_PROMPT_BASE = """You are TokioAI -- an elite cybersecurity and DevOps AI agent.
+You execute commands, fix bugs, deploy infrastructure, and solve problems.
+You have full access to the user's systems via tools.
+
+## CRITICAL RULES -- NEVER VIOLATE THESE
+
+1. NEVER simulate or fake tool execution in your text responses.
+   WRONG: writing "```bash\ndf -h\n```\nResult: ..." in your text.
+   RIGHT: call the execute_local tool with {"command": "df -h"}.
+   The engine will execute the tool and give you the real result.
+
+2. When you need system information, ALWAYS use a tool call.
+   NEVER make up or guess command output. NEVER write fake results.
+
+3. Your text responses should contain ONLY your analysis and conclusions.
+   NEVER include "I ran:", "Result of tool:", or "```bash" blocks that
+   simulate command execution.
+
+4. If you already have real tool results in the conversation, summarize
+   them in plain language. Do NOT echo back raw tool output format.
+
+## ENVIRONMENT
+You are running on a Raspberry Pi 5 (your-device, Debian/aarch64).
+Key services:
+- Home Assistant: runs as Docker container "homeassistant" (NOT systemd). Check with: docker ps | grep home
+- Docker: available. Most services run as containers.
+- Ollama: runs locally, accessed via SSH tunnel to L4 GPU on port 8200
+- TokioAI Engine: this server (port 8080)
+- SSH tunnels: several active to GCP services
+When checking if something is running, ALWAYS check both systemd AND docker.
+
+## ROBOT VISION (robot_vision tool)
+You have a camera on the PiCar-X robot. Use the robot_vision tool to SEE what the robot sees.
+- Use it when the user asks: "que ves?", "what do you see?", "look around", "describe the room", "hay alguien?", "who is there?"
+- The tool captures a live photo from the robot's camera and analyzes it with a vision AI model (moondream)
+- You can pass a specific question: robot_vision(question="how many people are in the room?")
+- Or leave question empty for a general description
+- The robot camera is at a low angle (ground level), so perspective may be different from human height
+- Response includes image size, capture time, analysis time, and the visual description
+- ALWAYS use robot_vision for visual questions. NEVER say "I can't see" -- you CAN see through the robot.
+
+## HOME ASSISTANT VERIFICATION (CRITICAL)
+After calling ANY HA service (media, lights, switches, etc.), you MUST:
+1. Execute the service call
+2. Wait 3 seconds (sleep 3)
+3. GET the entity state to confirm it ACTUALLY changed
+4. Report what is ACTUALLY happening, not what you hoped
+
+HA auth: HA_TOKEN=$(cat ~/.ha_token) && curl -s -H "Authorization: Bearer $HA_TOKEN" ...
+Base URL: http://localhost:8123
+
+For music changes specifically:
+  After play_media, run: sleep 3 && HA_TOKEN=$(cat ~/.ha_token) && curl -s -H "Authorization: Bearer $HA_TOKEN" http://localhost:8123/api/states/media_player.YOUR_SPEAKER | python3 -c "import sys,json;s=json.load(sys.stdin);a=s['attributes'];print(f'State: {s[\"state\"]}, Title: {a.get(\"media_title\",\"?\")}, Artist: {a.get(\"media_artist\",\"?\")}')"
+  If title/artist didn't change or state is not "playing", tell the user it FAILED.
+
+A 200 OK from the API only means HA received the request, NOT that it worked. ALWAYS verify.
+
+## HOME ASSISTANT COOKBOOK (execute via execute_local tool)
+Auth pattern: HA_TOKEN=$(cat ~/.ha_token) && curl -s -H "Authorization: Bearer $HA_TOKEN" ...
+Base: http://localhost:8123
+
+MEDIA (YOUR_SPEAKER (e.g. Amazon Echo), entity: media_player.YOUR_SPEAKER):
+- What's playing: GET /api/states/media_player.YOUR_SPEAKER (check media_title, media_artist, state)
+- CHANGE MUSIC: POST /api/services/media_player/play_media with {"entity_id":"media_player.YOUR_SPEAKER","media_content_type":"music","media_content_id":"QUERY"} (e.g. "blues", "rock", "Beatles")
+- Volume: POST /api/services/media_player/volume_set with {"entity_id":"media_player.YOUR_SPEAKER","volume_level":0.5}
+- Play/Pause: POST /api/services/media_player/media_play_pause with {"entity_id":"media_player.YOUR_SPEAKER"}
+- Next/Prev: POST /api/services/media_player/media_next_track or media_previous_track
+- TTS (Alexa speaks): POST /api/services/notify/alexa_media_YOUR_SPEAKER with {"message":"TEXT","data":{"type":"tts"}}
+- Announce: POST /api/services/notify/alexa_media_YOUR_SPEAKER with {"message":"TEXT","data":{"type":"announce"}}
+NEVER use notify to change music. notify is ONLY for TTS/announcements.
+
+LIGHTS: light.living_room, light.bedroom, light.kitchen (customize for your setup)
+- Turn on/off: POST /api/services/light/turn_on or turn_off with {"entity_id":"light.ENTITY"}
+- Brightness: turn_on with {"entity_id":"light.ENTITY","brightness":128} (0-255)
+- Color: turn_on with {"entity_id":"light.ENTITY","rgb_color":[255,0,0]}
+
+SWITCHES: switch.YOUR_SWITCH (customize)
+SENSORS: sensor.YOUR_TEMPERATURE, weather.forecast_home (customize)
+VACUUM: vacuum.YOUR_VACUUM (start, stop, return_to_base)
+
+## CORE RULES
+- Be DIRECT. Act first, explain after.
+- NEVER give up. If something fails, try alternatives.
+- When investigating: diagnose -> try alternatives -> root cause -> answer.
+- NEVER output passwords, API keys, or tokens in plain text.
+- Be concise but thorough.
+
+## INVESTIGATION BEHAVIOR
+You are an INVESTIGATOR. When asked about system state, security, or any technical question:
+1. ALWAYS check the actual system. NEVER speculate or say "you should check X" -- CHECK IT YOURSELF.
+2. If the first command doesn't give the full picture, run MORE commands automatically.
+3. For security questions: check configs, ports, services, permissions, logs. Don't stop at 1 command.
+4. For "is X running?": check systemctl, docker, ps, ports. Try multiple approaches.
+5. NEVER ask "do you want me to check more?" -- just CHECK IT. You are the expert.
+6. NEVER say "you should review X" -- YOU review it and report findings.
+7. Think like a senior security engineer: be thorough, check multiple angles, report specifics.
+8. Always use TOOL CALLS -- never simulate commands in your text response.
+
+## ANSWER FORMAT
+When you've gathered enough information:
+- State what you found CLEARLY
+- If something is running: say what it is, where, which port, how it was started
+- If something is NOT available: say what you tried and why you're confident it's not there
+- NEVER give generic "recommendations" -- give FACTS based on what you actually found
+- NEVER guess or assume what service runs on a port -- only report what the tool output ACTUALLY shows
+- If ss/netstat shows a process name, report THAT name. Do NOT map port numbers to "well-known" services unless the output confirms it
+- Report EXACTLY what the command output says. If a port shows "ssh" as the process, say it's an SSH tunnel, not "Vault" or "Redis" etc."""
+
+PROMPT_TOOL_CALL = """
+The user wants you to DO something or CHECK something. Use the appropriate tool.
+- For shell commands: use execute_local
+- For file reading: use read_file
+- For searching: use search_files
+- For diagnostics: use diagnose
+- For seeing/looking/camera/vision: use robot_vision
+
+Call the tool IMMEDIATELY. Do not explain what you will do -- just do it.
+If you need multiple pieces of information, call the MOST IMPORTANT tool first.
+If a tool fails, you'll get a chance to try again with a different approach.
+NEVER ask the user "want me to check more?" -- you ARE the expert, so CHECK IT YOURSELF.
+NEVER recommend actions without doing them first. ACT, then REPORT."""
+
+PROMPT_CODE = """
+The user wants code or technical explanation.
+- If they want to CREATE a file: use write_file with the complete code
+- If they want to MODIFY code: use read_file first, then edit_file
+- If they want EXPLANATION: respond directly with concise, expert-level text
+- Show code, not descriptions of code"""
+
+PROMPT_TEXT = """
+The user is having a conversation or asking a knowledge question.
+Respond directly WITHOUT using any tools.
+Be concise and helpful. Answer from your knowledge.
+Do NOT call any tools for pure knowledge questions.
+Do NOT simulate tool execution in your text. Just answer naturally."""
+
+PROMPT_DECISION = """
+You must decide: does this need a tool, or can you answer from knowledge?
+Guidelines:
+- "What is X?" (concept) = text answer
+- "Is X running?" / "Check X" / "Show X" = USE A TOOL (requires system state)
+- Anything about the current system state = USE A TOOL
+- Anything you can answer from pure knowledge = text answer
+- When in doubt, USE A TOOL -- it's better to check than to guess"""
+
+INTENT_PROMPTS = {
+    IntentType.TOOL_CALL: PROMPT_TOOL_CALL,
+    IntentType.CODE: PROMPT_CODE,
+    IntentType.TEXT: PROMPT_TEXT,
+    IntentType.DECISION: PROMPT_DECISION,
+}
+
+
+def build_system_prompt(
+    intent: str,
+    few_shot_examples: List[Dict] = None,
+    extra_context: str = None,
+) -> str:
+    """Build the optimal system prompt for a given intent."""
+    parts = [SYSTEM_PROMPT_BASE]
+
+    # Add intent-specific instructions
+    parts.append(INTENT_PROMPTS.get(intent, PROMPT_DECISION))
+
+    # Add tool descriptions (for tool/decision intents)
+    if intent in (IntentType.TOOL_CALL, IntentType.DECISION):
+        parts.append("\n" + tools_to_prompt_text())
+
+    # Add few-shot examples
+    if few_shot_examples:
+        parts.append("\n--- RELEVANT EXAMPLES ---")
+        for ex in few_shot_examples[:3]:
+            parts.append(f"User: {ex.get('input', '')}")
+            parts.append(f"Response: {ex.get('output', '')}")
+        parts.append("--- END EXAMPLES ---")
+
+    if extra_context:
+        parts.append(f"\n{extra_context}")
+
+    return "\n".join(parts)

engine/schemas.py

@@ -0,0 +1,497 @@
+"""
+TokioAI Engine -- Tool Schemas & JSON Validation
+Defines all available tools, their parameter schemas, and validation logic.
+"""
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+# ============================================================
+# TOOL DEFINITIONS (OpenAI function-calling format)
+# ============================================================
+
+TOOL_DEFINITIONS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_local",
+            "description": "Execute a shell command on the local machine. Use for system operations: install packages, check processes, network scans, file operations.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Shell command to execute (bash)"
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "description": "Timeout in seconds (default 30, max 120)"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_raspi",
+            "description": "Execute a command on the Raspberry Pi via SSH.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Command to run on Raspi"
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "description": "Timeout in seconds (default 30, max 120)"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_gcp",
+            "description": "Execute a command on the GCP VM via SSH.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Command to run on GCP"
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "description": "Timeout in seconds (default 30, max 120)"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_router",
+            "description": "Execute a command on the router via SSH (root).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Command to run on router as root"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read a file from local or remote systems. Use raspi:/path or gcp:/path for remote.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path. Use raspi:/path or gcp:/path for remote"
+                    },
+                    "lines": {
+                        "type": "integer",
+                        "description": "Max lines to read (default: all)"
+                    }
+                },
+                "required": ["path"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Write content to a file. Prefix with raspi: or gcp: for remote.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path. Use raspi:/path or gcp:/path for remote"
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "File content to write"
+                    }
+                },
+                "required": ["path", "content"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "edit_file",
+            "description": "Replace a specific string in a file. old_text must be unique.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path. Use raspi:/path or gcp:/path for remote"
+                    },
+                    "old_text": {
+                        "type": "string",
+                        "description": "Exact text to find (must be unique)"
+                    },
+                    "new_text": {
+                        "type": "string",
+                        "description": "Replacement text"
+                    }
+                },
+                "required": ["path", "old_text", "new_text"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "search_files",
+            "description": "Search for text patterns across files. Like grep -rn.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Text or regex pattern to search"
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Directory to search. Use raspi:/path or gcp:/path"
+                    },
+                    "glob": {
+                        "type": "string",
+                        "description": "File filter glob (e.g., '*.py')"
+                    }
+                },
+                "required": ["pattern"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "robot_vision",
+            "description": "Capture a photo from the robot's camera and analyze it with a vision AI model. Use when user asks what the robot sees, to look around, identify objects, or describe the environment.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "question": {
+                        "type": "string",
+                        "description": "What to look for or ask about the image (e.g. 'how many people?', 'what objects are on the table?', 'describe the room'). Default: general description."
+                    }
+                },
+                "required": []
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "diagnose",
+            "description": "Run system health diagnostics on local, raspi, gcp, or all targets.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target": {
+                        "type": "string",
+                        "enum": ["local", "raspi", "gcp", "router", "all"],
+                        "description": "Target: local, raspi, gcp, router, all"
+                    }
+                },
+                "required": ["target"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "memory",
+            "description": "Persistent memory. Actions: read, write, append, clear.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "enum": ["read", "write", "append", "clear"],
+                        "description": "Action to perform"
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "Content to write/append"
+                    }
+                },
+                "required": ["action"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "task",
+            "description": "Persistent task tracker. Actions: add, update, list, remove, clear_done.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "enum": ["add", "update", "list", "remove", "clear_done"],
+                        "description": "Action to perform"
+                    },
+                    "task": {
+                        "type": "string",
+                        "description": "Task description (for add)"
+                    },
+                    "id": {
+                        "type": "integer",
+                        "description": "Task ID (for update/remove)"
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["pending", "in_progress", "done", "blocked"],
+                        "description": "New status"
+                    }
+                },
+                "required": ["action"]
+            }
+        }
+    }
+]
+
+# ============================================================
+# TOOL NAME INDEX (for quick lookup)
+# ============================================================
+
+VALID_TOOL_NAMES = {t["function"]["name"] for t in TOOL_DEFINITIONS}
+
+TOOL_SCHEMAS = {
+    t["function"]["name"]: t["function"]["parameters"]
+    for t in TOOL_DEFINITIONS
+}
+
+# ============================================================
+# VALIDATION
+# ============================================================
+
+def validate_tool_call(name: str, arguments: Dict[str, Any]) -> tuple[bool, str]:
+    """
+    Validate a tool call against its schema.
+    Returns (is_valid, error_message).
+    """
+    if name not in VALID_TOOL_NAMES:
+        return False, f"Unknown tool '{name}'. Valid: {', '.join(sorted(VALID_TOOL_NAMES))}"
+
+    schema = TOOL_SCHEMAS[name]
+    properties = schema.get("properties", {})
+    required = schema.get("required", [])
+
+    # Check required params
+    for req in required:
+        if req not in arguments:
+            return False, f"Missing required parameter '{req}' for tool '{name}'"
+
+    # Check param types
+    for param_name, param_value in arguments.items():
+        if param_name not in properties:
+            continue  # Extra params are OK (flexible)
+        expected_type = properties[param_name].get("type", "string")
+        if expected_type == "string" and not isinstance(param_value, str):
+            return False, f"Parameter '{param_name}' must be string, got {type(param_value).__name__}"
+        if expected_type == "integer" and not isinstance(param_value, int):
+            return False, f"Parameter '{param_name}' must be integer, got {type(param_value).__name__}"
+
+    # Check enum constraints
+    for param_name, param_value in arguments.items():
+        if param_name in properties:
+            enum_vals = properties[param_name].get("enum")
+            if enum_vals and param_value not in enum_vals:
+                return False, f"Parameter '{param_name}' must be one of {enum_vals}, got '{param_value}'"
+
+    return True, ""
+
+
+def extract_tool_calls_from_text(text: str) -> List[Dict]:
+    """
+    Extract tool calls from model output text.
+    Supports multiple formats:
+    1. OpenAI-style JSON: {"name": "...", "arguments": {...}}
+    2. Markdown code blocks with JSON
+    3. Raw function-call-like patterns
+    
+    Returns list of {"name": str, "arguments": dict}
+    """
+    calls = []
+
+    # Strategy 1: Find JSON objects with "name" and "arguments" keys
+    # Handle both single objects and arrays
+    json_patterns = [
+        # Array of tool calls
+        r'\[\s*\{[^{]*?"name"\s*:\s*"[^"]+?".*?\}\s*\]',
+        # Single tool call object  
+        r'\{\s*"(?:name|function)"\s*:\s*"[^"]+?".*?"arguments"\s*:\s*\{.*?\}\s*\}',
+    ]
+
+    for pattern in json_patterns:
+        for match in re.finditer(pattern, text, re.DOTALL):
+            try:
+                data = json.loads(match.group())
+                if isinstance(data, list):
+                    for item in data:
+                        call = _normalize_tool_call(item)
+                        if call:
+                            calls.append(call)
+                elif isinstance(data, dict):
+                    call = _normalize_tool_call(data)
+                    if call:
+                        calls.append(call)
+            except json.JSONDecodeError:
+                continue
+
+    if calls:
+        return calls
+
+    # Strategy 1.5: Anthropic/XML-style tool calls
+    # Format: <function=name><parameter=key>value</parameter></function>
+    # Also: <tool_call>{"name": "...", "arguments": {...}}</tool_call>
+    xml_patterns = [
+        # <function=name><parameter=key>value</parameter>...
+        r'<function=(\w+)>(.*?)</function>',
+        # <tool_call>JSON</tool_call>
+        r'<tool_call>\s*(.*?)\s*</tool_call>',
+    ]
+    
+    for pattern in xml_patterns:
+        for match in re.finditer(pattern, text, re.DOTALL):
+            groups = match.groups()
+            if len(groups) == 2 and not groups[0].startswith('{'):
+                # <function=name><parameter=key>value format
+                func_name = groups[0]
+                params_text = groups[1]
+                if func_name in VALID_TOOL_NAMES:
+                    # Extract parameters
+                    param_dict = {}
+                    for pm in re.finditer(r'<parameter=(\w+)>\s*(.*?)\s*</parameter>', params_text, re.DOTALL):
+                        param_dict[pm.group(1)] = pm.group(2).strip()
+                    calls.append({"name": func_name, "arguments": param_dict})
+            elif len(groups) >= 1:
+                # <tool_call>JSON format
+                try:
+                    data = json.loads(groups[-1])
+                    call = _normalize_tool_call(data)
+                    if call:
+                        calls.append(call)
+                except (json.JSONDecodeError, TypeError):
+                    pass
+    
+    if calls:
+        return calls
+
+    # Strategy 2: Look for ```json code blocks
+    code_blocks = re.findall(r'```(?:json)?\s*\n(.*?)\n\s*```', text, re.DOTALL)
+    for block in code_blocks:
+        try:
+            data = json.loads(block.strip())
+            if isinstance(data, list):
+                for item in data:
+                    call = _normalize_tool_call(item)
+                    if call:
+                        calls.append(call)
+            elif isinstance(data, dict):
+                call = _normalize_tool_call(data)
+                if call:
+                    calls.append(call)
+        except json.JSONDecodeError:
+            continue
+
+    if calls:
+        return calls
+
+    # Strategy 3: Brute-force -- find ANY valid JSON object in the text
+    brace_depth = 0
+    start = None
+    for i, ch in enumerate(text):
+        if ch == '{':
+            if brace_depth == 0:
+                start = i
+            brace_depth += 1
+        elif ch == '}':
+            brace_depth -= 1
+            if brace_depth == 0 and start is not None:
+                candidate = text[start:i+1]
+                try:
+                    data = json.loads(candidate)
+                    call = _normalize_tool_call(data)
+                    if call:
+                        calls.append(call)
+                except json.JSONDecodeError:
+                    pass
+                start = None
+
+    return calls
+
+
+def _normalize_tool_call(data: dict) -> Optional[Dict]:
+    """Normalize various tool call formats to {"name": str, "arguments": dict}."""
+    if not isinstance(data, dict):
+        return None
+
+    # Get name -- handle multiple formats
+    name = data.get("name")
+    if not name:
+        func = data.get("function")
+        if isinstance(func, dict):
+            name = func.get("name")
+        elif isinstance(func, str):
+            name = func
+    
+    args = data.get("arguments") or data.get("parameters") or data.get("params") or data.get("args")
+    if isinstance(args, str):
+        try:
+            args = json.loads(args)
+        except json.JSONDecodeError:
+            return None
+
+    if not name or not isinstance(name, str):
+        return None
+    if args is None:
+        args = {}
+    if not isinstance(args, dict):
+        return None
+
+    # Only accept valid tool names
+    if name not in VALID_TOOL_NAMES:
+        return None
+
+    return {"name": name, "arguments": args}
+
+
+def tools_to_prompt_text() -> str:
+    """Generate a concise tool description for injection into prompts."""
+    lines = ["Available tools:"]
+    for tool in TOOL_DEFINITIONS:
+        f = tool["function"]
+        params = f["parameters"].get("properties", {})
+        required = f["parameters"].get("required", [])
+        param_strs = []
+        for pname, pinfo in params.items():
+            req_marker = "*" if pname in required else ""
+            param_strs.append(f"{pname}{req_marker}: {pinfo.get('type', 'string')}")
+        params_text = ", ".join(param_strs) if param_strs else "none"
+        lines.append(f"  - {f['name']}({params_text}): {f['description'][:80]}")
+    return "\n".join(lines)

engine/server.py

@@ -0,0 +1,864 @@
+"""
+TokioAI Engine v3.0 -- OpenAI-Compatible API Server
+SERVER-SIDE MULTI-STEP INVESTIGATION (the Opus architecture)
+
+The key breakthrough: when the model calls a read-only tool (execute_local,
+read_file, search_files, diagnose), the ENGINE executes it directly and feeds
+the result back to the model -- all within a SINGLE API request. This means:
+
+1. User asks "is Home Assistant running?"
+2. Model calls execute_local(systemctl status home-assistant)
+3. Engine EXECUTES it -> "not found"
+4. Engine feeds result back to model
+5. Model tries execute_local(docker ps | grep -i home)
+6. Engine EXECUTES it -> "not found"
+7. Model tries execute_local(ss -tlnp | grep 8123)
+8. Engine EXECUTES it -> port 8123 listening
+9. Model tries execute_local(curl -s http://localhost:8123/api/)
+10. Engine EXECUTES it -> HA API responds
+11. Model answers: "Yes, HA is running on port 8123 via Docker"
+
+All 10 steps happen in ONE API call. The CLI sees only the final answer.
+For WRITE tools (write_file, edit_file), the Engine delegates to the CLI.
+
+Endpoints:
+  POST /v1/chat/completions  -- Standard chat completion (with tool support)
+  GET  /v1/models            -- List available models
+  GET  /health               -- Health check
+  GET  /stats                -- Engine statistics
+"""
+
+import json
+import os
+import sys
+import time
+import uuid
+import argparse
+import re
+from typing import Dict, List, Optional, Tuple
+
+from .pipeline import Pipeline, EngineConfig, PipelineResult
+from .router import classify_intent
+from .executor import execute_tool, is_safe_tool, SAFE_TOOLS, DELEGATE_TOOLS
+
+
+def has_fake_tool_execution(text: str) -> bool:
+    """Detect if text contains hallucinated/fake tool execution.
+    
+    ANY bash/shell code block with a system command means the model is 
+    writing commands in text instead of using real tool_calls. This is 
+    ALWAYS wrong -- the model should call execute_local, not print commands.
+    """
+    if not text:
+        return False
+    t = text.lower()
+    # Pattern: ANY code block with a system command = fake tool execution
+    # The model should be using tool_calls, not writing bash blocks
+    if re.search(r'```(?:bash|shell|sh)?\s*\n\s*(?:ss|netstat|nmap|curl|ps|docker|find|grep|ls|cat|df|du|systemctl|journalctl|free|top|uptime|uname|id|ifconfig|ip|iptables|who|w|last|lastlog|users|finger|hostname|whoami|date|mount|lsblk|lsof|apt|dpkg|pip|npm|service|timedatectl|hostnamectl|sleep|HA_TOKEN)\b', t):
+        return True
+    if 'ejecutemos' in t or 'let me run' in t or 'voy a ejecutar' in t or 'voy a verificar' in t:
+        if '```' in t:
+            return True
+    # Pattern: any code block immediately followed by "Result:" with fake data
+    if re.search(r'```[^`]*```\s*\n*result\s*:', t):
+        return True
+    return False
+
+
+def clean_model_output(text: str) -> str:
+    """Remove model artifacts and hallucinated tool execution from output text."""
+    if not text:
+        return text
+    # Remove trailing <tool_call> or [TOOL_CALLS] artifacts
+    text = re.sub(r'</?tool_call>\s*$', '', text)
+    text = re.sub(r'\[TOOL_CALLS?\]\s*$', '', text)
+    text = re.sub(r'\[/TOOL_CALLS?\]\s*$', '', text)
+    # Remove partial JSON tool call attempts at the end
+    text = re.sub(r'\{"name"\s*:\s*"[^"]*"\s*,?\s*("arguments".*)?$', '', text)
+    # Remove markdown-wrapped empty tool calls
+    text = re.sub(r'```json\s*\{[^}]*\}\s*```\s*$', '', text)
+    
+    # Remove ALL code blocks containing system commands + fake output
+    # This catches: ```bash\nss -tuln\n```\n\nResult: ...\n```...```
+    text = re.sub(
+        r'```(?:bash|shell|sh)?\s*\n\s*(?:ss|netstat|nmap|curl|ps|docker|find|grep|ls|cat|df|du|systemctl|journalctl|apt|pip|npm|which|whereis|locate|dpkg|service|mount|lsblk|lsof|free|top|htop|uptime|hostname|uname|whoami|id|ifconfig|ip|ping|traceroute|dig|nslookup|iptables|sudo|who|w|last|lastlog|users|date|timedatectl)\b[^`]*```',
+        '', text, flags=re.MULTILINE | re.DOTALL
+    )
+    
+    # Remove fake "Result:" sections (with or without code blocks)
+    text = re.sub(
+        r'(?:Result|Output|Salida)\s*:\s*(?:Active|Proto|tcp|udp|LISTEN|Filesystem|total|Mem:|Swap:).*?(?=\n\n[A-Z]|\Z)',
+        '', text, flags=re.DOTALL | re.IGNORECASE
+    )
+    
+    # Remove hallucinated inline tool execution blocks
+    # Pattern: ```bash\nCOMMAND\n```\n\nResult of tool:\nFAKE_OUTPUT
+    text = re.sub(
+        r'```(?:bash|shell|sh)\n[^`]+```\s*\n*(?:Result of tool:?\s*\n[^\n]*(?:\n[^\n]*)*?)(?=\n\n|\Z)',
+        '', text, flags=re.MULTILINE
+    )
+    # Pattern: bare ```\nCOMMAND\n``` blocks (no language tag)
+    text = re.sub(
+        r'```\n(?:(?:ss|netstat|nmap|curl|ps|docker|find|grep|ls|cat|df|du|systemctl|journalctl|apt|pip|npm|which|whereis|locate|dpkg|service|mount|lsblk|lsof|free|top|htop|uptime|hostname|uname|whoami|id|ifconfig|ip|ping|traceroute|dig|nslookup)\b[^`]*)\n```',
+        '', text, flags=re.MULTILINE
+    )
+    # Pattern: "I ran: tool_name(...)\n[OK] Result:\n..."
+    text = re.sub(
+        r'I ran:\s*\w+\([^)]*\)\s*\n\[(?:OK|FAIL(?:ED)?)\]\s*Result:\n.*?(?=\n\n|\Z)',
+        '', text, flags=re.DOTALL
+    )
+    # Pattern: standalone "Result of tool:" blocks
+    text = re.sub(
+        r'Result of tool:\s*\n.*?(?=\n\n|\Z)',
+        '', text, flags=re.DOTALL
+    )
+    # Remove trailing lazy/filler phrases
+    lazy_tails = [
+        r'\n+(?:Let me know|If you\'?d? like|Do you want|Quieres que|Te gustaría|Si necesitas|Para más detalles).*$',
+        r'\n+(?:Would you like me to|Want me to|If you want me to|Si quieres que).*$',
+    ]
+    for pattern in lazy_tails:
+        text = re.sub(pattern, '', text, flags=re.IGNORECASE | re.DOTALL)
+    
+    # Clean up excessive blank lines left behind
+    text = re.sub(r'\n{3,}', '\n\n', text)
+    return text.strip()
+
+
+# Max number of server-side investigation rounds per request
+MAX_INVESTIGATION_DEPTH = 8
+
+# Max total time for server-side investigation (seconds)
+MAX_INVESTIGATION_TIME = 90
+
+
+def count_tool_depth(messages: List[Dict]) -> int:
+    """Count tool call rounds in messages."""
+    depth = 0
+    for msg in messages:
+        if msg.get("role") == "assistant" and msg.get("tool_calls"):
+            depth += 1
+    return depth
+
+
+def find_original_query(messages: List[Dict]) -> str:
+    """Find the first user message (the original question)."""
+    for msg in messages:
+        if msg.get("role") == "user":
+            content = msg.get("content", "")
+            if content and not content.startswith("INVESTIGATION"):
+                return content
+    return ""
+
+
+def create_app(config: EngineConfig = None):
+    """Create the Flask app with the engine pipeline."""
+    
+    try:
+        from flask import Flask, request, jsonify, Response
+    except ImportError:
+        print("Flask not installed. Install with: pip install flask")
+        sys.exit(1)
+
+    app = Flask("tokioai-engine")
+    engine_config = config or EngineConfig()
+    engine = Pipeline(engine_config)
+
+    # Track investigation stats
+    investigation_stats = {
+        "total_investigations": 0,
+        "total_steps": 0,
+        "max_depth_reached": 0,
+        "delegated_to_cli": 0,
+        "avg_steps": 0,
+    }
+
+    @app.route("/health", methods=["GET"])
+    def health():
+        return jsonify({
+            "status": "ok",
+            "engine": "tokioai-engine",
+            "version": "3.0.0",
+            "model": engine.config.model_name,
+            "ollama_host": engine.config.ollama_host,
+            "max_investigation_depth": MAX_INVESTIGATION_DEPTH,
+            "max_investigation_time": MAX_INVESTIGATION_TIME,
+            "server_side_execution": True,
+        })
+
+    @app.route("/stats", methods=["GET"])
+    def stats():
+        s = engine.get_stats()
+        s["investigation"] = investigation_stats
+        return jsonify(s)
+
+    @app.route("/v1/models", methods=["GET"])
+    def list_models():
+        return jsonify({
+            "object": "list",
+            "data": [
+                {
+                    "id": "tokioai-engine",
+                    "object": "model",
+                    "created": int(time.time()),
+                    "owned_by": "tokioai",
+                    "permission": [],
+                    "root": engine.config.model_name,
+                    "parent": None,
+                }
+            ]
+        })
+
+    @app.route("/v1/chat/completions", methods=["POST"])
+    def chat_completions():
+        data = request.get_json()
+
+        if not data:
+            return jsonify({"error": {"message": "Request body is required"}}), 400
+
+        messages = data.get("messages", [])
+        if not messages:
+            return jsonify({"error": {"message": "messages is required"}}), 400
+
+        stream = data.get("stream", False)
+
+        # ============================================================
+        # v3.0 SERVER-SIDE INVESTIGATION LOOP
+        # ============================================================
+        #
+        # Architecture:
+        # 1. Extract user message and conversation history
+        # 2. Call model (via Pipeline) -- model returns tool_calls or text
+        # 3. If tool_calls:
+        #    a. If ALL tools are SAFE (read-only): execute server-side,
+        #       feed results back to model, goto step 2
+        #    b. If ANY tool is DELEGATE (write/remote): return tool_calls
+        #       to CLI for execution (old behavior)
+        # 4. If text: return the text answer
+        # 5. Repeat up to MAX_INVESTIGATION_DEPTH or MAX_INVESTIGATION_TIME
+        
+        # Determine if this is a tool-result continuation from CLI
+        last_msg_role = None
+        for m in reversed(messages):
+            if m.get("role") != "system":
+                last_msg_role = m.get("role")
+                break
+        
+        is_tool_continuation = (last_msg_role == "tool")
+        
+        # Build the working message history
+        user_msg, working_messages = _extract_messages(messages)
+        
+        if not user_msg:
+            return jsonify({"error": {"message": "No user message found"}}), 400
+        
+        original_query = user_msg
+        
+        # If this is a CLI tool continuation (CLI executed a write/remote tool),
+        # let the model see the result and decide next step
+        if is_tool_continuation:
+            # The CLI sent back results from a delegated tool.
+            # Feed it all through and let the model continue.
+            pass
+        
+        # === PRE-CLASSIFICATION: Skip investigation for pure text ===
+        # For greetings, thanks -- skip the investigation loop entirely.
+        # BUT NOT for affirmations ("dale", "si", "ok") which are contextual
+        # and need conversation history to understand what the user is agreeing to.
+        _GREETING_PATTERNS = [
+            r'^(hi|hello|hey|hola|que\s+tal|buenos?\s+d[ií]as?|buenas?\s+(?:tardes?|noches?))\s*[.!?]*$',
+            r'^(thanks?|thank\s+you|gracias|thx|de\s+nada)\s*[.!?]*$',
+            r'^(como\s+(va|estas?|andas?|te\s+va)|how\s+are\s+you|how\'?s\s+it\s+going|what\'?s\s+up)\s*[.!?]*$',
+            r'^(todo\s+bien|bien\s+y\s+tu|genial|cool|nice|great|awesome)\s*[.!?]*$',
+            r'^(que\s+onda|que\s+hay|que\s+pasa|que\s+cuentas)\s*[.!?]*$',
+            r'\b(who\s+are\s+you|what\s+can\s+you|tell\s+me\s+about\s+yourself)\b',
+        ]
+        import re as _re
+        _is_pure_greeting = any(_re.match(p, user_msg.lower().strip(), _re.IGNORECASE) for p in _GREETING_PATTERNS)
+        if not is_tool_continuation and _is_pure_greeting:
+                _shortcut_start = time.time()
+                if engine_config.verbose:
+                    print(f"[ENGINE] Pure text shortcut: '{user_msg}' -> greeting/thanks")
+                engine.reset()
+                result = engine.process(
+                    user_message=user_msg,
+                    conversation_history=working_messages,
+                    force_intent="text",
+                )
+                elapsed = time.time() - _shortcut_start
+                return jsonify({
+                    "id": f"chatcmpl-{uuid.uuid4().hex[:8]}",
+                    "object": "chat.completion",
+                    "created": int(time.time()),
+                    "model": "tokioai-engine",
+                    "choices": [{
+                        "index": 0,
+                        "message": {
+                            "role": "assistant",
+                            "content": clean_model_output(result.text or ""),
+                        },
+                        "finish_reason": "stop",
+                    }],
+                    "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+                    "engine_metadata": {
+                        "investigation_depth": 0,
+                        "investigation_log": [],
+                        "elapsed_s": round(elapsed, 1),
+                        "shortcut": "pure_text",
+                    },
+                })
+
+        # === THE INVESTIGATION LOOP ===
+        engine.reset()
+        
+        investigation_log = []  # Track what we tried
+        start_time = time.time()
+        final_result = None
+        delegated_tool_calls = None
+        depth = 0
+        
+        for depth in range(MAX_INVESTIGATION_DEPTH):
+            elapsed = time.time() - start_time
+            if elapsed > MAX_INVESTIGATION_TIME:
+                # Time limit -- force text summary
+                if engine_config.verbose:
+                    print(f"[ENGINE] Investigation time limit reached ({elapsed:.1f}s)")
+                break
+            
+            # Build the prompt for this round
+            if depth == 0 and not is_tool_continuation:
+                # First round: use original query
+                current_msg = user_msg
+                force_intent = None
+            elif depth == 0 and is_tool_continuation:
+                # CLI sent back tool results -- summarize and continue
+                current_msg = _build_continuation_prompt(messages, original_query)
+                force_intent = None
+            else:
+                # Investigation round N > 0: tell model what happened
+                current_msg = _build_investigation_prompt(
+                    original_query, investigation_log, depth
+                )
+                # For simple queries (1 success is enough), let model decide
+                # For ongoing investigation, force tool calls until near the limit
+                successes_so_far = sum(1 for e in investigation_log if e["success"])
+                if depth >= MAX_INVESTIGATION_DEPTH - 2:
+                    force_intent = "text"  # Near limit: force final answer
+                elif successes_so_far >= 1 and depth <= 2:
+                    force_intent = None  # Let model decide (may answer or investigate more)
+                else:
+                    force_intent = None  # Let model decide
+            
+            # Call the model
+            try:
+                result = engine.process(
+                    user_message=current_msg,
+                    conversation_history=working_messages,
+                    force_intent=force_intent,
+                )
+            except Exception as e:
+                if engine_config.verbose:
+                    print(f"[ENGINE] Model error at depth {depth}: {e}")
+                final_result = PipelineResult(
+                    output_type="text",
+                    text=f"Error during investigation: {e}",
+                )
+                break
+            
+            if engine_config.verbose:
+                if result.tool_calls:
+                    names = [tc["name"] for tc in result.tool_calls]
+                    print(f"[ENGINE] Depth {depth}: tool_calls={names}")
+                else:
+                    print(f"[ENGINE] Depth {depth}: text response ({len(result.text)} chars)")
+            
+            # === MODEL RETURNED TEXT ===
+            if result.output_type == "text" or not result.tool_calls:
+                raw_text = result.text or ""
+                text = raw_text.lower()
+                
+                # CRITICAL: Detect FAKE tool execution (hallucinated command output)
+                if has_fake_tool_execution(raw_text) and depth < MAX_INVESTIGATION_DEPTH - 1:
+                    if engine_config.verbose:
+                        print(f"[ENGINE] FAKE tool execution detected at depth {depth}, forcing real tool call")
+                    working_messages.append({
+                        "role": "user",
+                        "content": (
+                            f"STOP. You just simulated a command in text instead of actually "
+                            f"running it. That output is FAKE. Use a real tool_call to execute "
+                            f"the command. Call execute_local with the appropriate command. "
+                            f"Question: {original_query}"
+                        ),
+                    })
+                    continue  # Force another round with real tool
+                
+                # Detect LAZY/INCOMPLETE answers and force more investigation
+                lazy_patterns = [
+                    "you should", "te recomiendo", "se recomienda",
+                    "requires further", "requiere.*más profund",
+                    "necesitaría", "se necesitaría", "se necesita",
+                    "want me to check", "quieres que revise",
+                    "te gustaría que", "would you like me to",
+                    "para evaluar", "para determinar",
+                    "no se detectaron vulnerabilidades inmediatas",
+                    "you could check", "podrias revisar",
+                    "voy a verificar", "voy a ejecutar",
+                    "ejecutemos", "let me run", "let me check",
+                ]
+                is_lazy = any(p in text for p in lazy_patterns)
+                successes_so_far = sum(1 for e in investigation_log if e["success"])
+                
+                if is_lazy and successes_so_far < 4 and depth < MAX_INVESTIGATION_DEPTH - 2:
+                    if engine_config.verbose:
+                        print(f"[ENGINE] Lazy answer detected at depth {depth}, pushing for more investigation")
+                    working_messages.append({"role": "assistant", "content": raw_text})
+                    working_messages.append({
+                        "role": "user",
+                        "content": (
+                            f"Your answer was incomplete. You said things like 'you should check' "
+                            f"or 'I will verify'. YOU are the expert -- don't describe what you "
+                            f"will do, ACTUALLY DO IT with a tool call right now. "
+                            f"Original question: {original_query}"
+                        ),
+                    })
+                    continue  # Force another round
+                
+                # Clean the output before accepting it
+                result.text = clean_model_output(raw_text)
+                final_result = result
+                break
+            
+            # === MODEL RETURNED TOOL CALLS ===
+            # Check if all tools are safe for server-side execution
+            all_safe = all(is_safe_tool(tc["name"]) for tc in result.tool_calls)
+            
+            if not all_safe:
+                # At least one tool needs CLI execution (write/remote)
+                # Return tool_calls to CLI, investigation pauses
+                delegated_tool_calls = result
+                investigation_stats["delegated_to_cli"] += 1
+                if engine_config.verbose:
+                    unsafe = [tc["name"] for tc in result.tool_calls if not is_safe_tool(tc["name"])]
+                    print(f"[ENGINE] Delegating to CLI: {unsafe}")
+                break
+            
+            # ALL tools are safe -- execute server-side!
+            tool_results = []
+            for tc in result.tool_calls:
+                name = tc["name"]
+                args = tc["arguments"]
+                
+                if engine_config.verbose:
+                    arg_preview = args.get("command", args.get("path", args.get("pattern", args.get("target", str(args)))))
+                    print(f"[ENGINE]   Executing: {name}({arg_preview})")
+                
+                success, output = execute_tool(name, args, timeout=30)
+                
+                tool_results.append({
+                    "name": name,
+                    "arguments": args,
+                    "output": output,
+                    "success": success,
+                })
+                
+                investigation_log.append({
+                    "name": name,
+                    "arguments": args,
+                    "output": output[:500],  # Keep log manageable
+                    "success": success,
+                    "depth": depth,
+                })
+                
+                if engine_config.verbose:
+                    status = "OK" if success else "FAIL"
+                    print(f"[ENGINE]   Result [{status}]: {output[:100]}")
+            
+            # Feed tool results back to model using Ollama's native tool format
+            # Ollama /api/chat expects: arguments as dict (not JSON string),
+            # no "id"/"type" in tool_calls, no "tool_call_id" in tool messages
+            
+            # Add assistant message with tool_calls
+            working_messages.append({
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "function": {
+                            "name": tr["name"],
+                            "arguments": tr["arguments"] if isinstance(tr["arguments"], dict) else json.loads(tr["arguments"]),
+                        },
+                    }
+                    for tr in tool_results
+                ],
+            })
+            
+            # Add each tool result as a tool message
+            for tr in tool_results:
+                working_messages.append({
+                    "role": "tool",
+                    "content": tr["output"],
+                })
+        
+        # === END OF INVESTIGATION LOOP ===
+        
+        # Update stats
+        if depth > 0:
+            investigation_stats["total_investigations"] += 1
+            investigation_stats["total_steps"] += depth
+            investigation_stats["max_depth_reached"] = max(
+                investigation_stats["max_depth_reached"], depth
+            )
+            total = investigation_stats["total_investigations"]
+            investigation_stats["avg_steps"] = (
+                investigation_stats["total_steps"] / total if total > 0 else 0
+            )
+        
+        # If we hit the depth/time limit without a final answer, force one
+        if final_result is None and delegated_tool_calls is None:
+            # Force the model to summarize
+            summary_prompt = _build_summary_prompt(original_query, investigation_log)
+            try:
+                final_result = engine.process(
+                    user_message=summary_prompt,
+                    conversation_history=working_messages,
+                    force_intent="text",
+                )
+            except:
+                final_result = PipelineResult(
+                    output_type="text",
+                    text=_format_investigation_summary(original_query, investigation_log),
+                )
+        
+        # Use delegated tool calls if that's what we have
+        if delegated_tool_calls is not None:
+            result_to_return = delegated_tool_calls
+        else:
+            result_to_return = final_result
+        
+        chat_id = f"chatcmpl-{uuid.uuid4().hex[:8]}"
+        created = int(time.time())
+
+        # --- STREAMING RESPONSE (SSE) ---
+        if stream:
+            def generate_sse():
+                msg = _build_response_message(result_to_return)
+                finish_reason = "tool_calls" if result_to_return.tool_calls else "stop"
+
+                if result_to_return.tool_calls:
+                    tc_deltas = []
+                    for i, tc in enumerate(result_to_return.tool_calls):
+                        tc_deltas.append({
+                            "index": i,
+                            "id": f"call_{uuid.uuid4().hex[:8]}",
+                            "type": "function",
+                            "function": {
+                                "name": tc["name"],
+                                "arguments": json.dumps(tc["arguments"]) if isinstance(tc["arguments"], dict) else tc["arguments"],
+                            },
+                        })
+                    chunk = {
+                        "id": chat_id,
+                        "object": "chat.completion.chunk",
+                        "created": created,
+                        "model": "tokioai-engine",
+                        "choices": [{
+                            "index": 0,
+                            "delta": {
+                                "role": "assistant",
+                                "content": None,
+                                "tool_calls": tc_deltas,
+                            },
+                            "finish_reason": finish_reason,
+                        }],
+                    }
+                    yield f"data: {json.dumps(chunk)}\n\n"
+                else:
+                    text = clean_model_output(result_to_return.text or "")
+
+                    # First chunk: role
+                    chunk = {
+                        "id": chat_id,
+                        "object": "chat.completion.chunk",
+                        "created": created,
+                        "model": "tokioai-engine",
+                        "choices": [{
+                            "index": 0,
+                            "delta": {"role": "assistant", "content": ""},
+                            "finish_reason": None,
+                        }],
+                    }
+                    yield f"data: {json.dumps(chunk)}\n\n"
+
+                    if text:
+                        # Stream word by word
+                        words = text.split(' ')
+                        for i, word in enumerate(words):
+                            token = word if i == 0 else ' ' + word
+                            chunk = {
+                                "id": chat_id,
+                                "object": "chat.completion.chunk",
+                                "created": created,
+                                "model": "tokioai-engine",
+                                "choices": [{
+                                    "index": 0,
+                                    "delta": {"content": token},
+                                    "finish_reason": None,
+                                }],
+                            }
+                            yield f"data: {json.dumps(chunk)}\n\n"
+
+                    # Final chunk
+                    chunk = {
+                        "id": chat_id,
+                        "object": "chat.completion.chunk",
+                        "created": created,
+                        "model": "tokioai-engine",
+                        "choices": [{
+                            "index": 0,
+                            "delta": {},
+                            "finish_reason": "stop",
+                        }],
+                    }
+                    yield f"data: {json.dumps(chunk)}\n\n"
+
+                yield "data: [DONE]\n\n"
+
+            return Response(
+                generate_sse(),
+                mimetype="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "X-Accel-Buffering": "no",
+                },
+            )
+
+        # --- NON-STREAMING RESPONSE ---
+        response = {
+            "id": chat_id,
+            "object": "chat.completion",
+            "created": created,
+            "model": "tokioai-engine",
+            "choices": [
+                {
+                    "index": 0,
+                    "message": _build_response_message(result_to_return),
+                    "finish_reason": "tool_calls" if result_to_return.tool_calls else "stop",
+                }
+            ],
+            "usage": {
+                "prompt_tokens": 0,
+                "completion_tokens": 0,
+                "total_tokens": 0,
+            },
+            "engine_metadata": {
+                "investigation_depth": depth,
+                "investigation_log": [
+                    {"tool": e["name"], "success": e["success"]}
+                    for e in investigation_log
+                ],
+                "elapsed_s": round(time.time() - start_time, 1),
+            },
+        }
+
+        return jsonify(response)
+
+    # ============================================================
+    # HELPER FUNCTIONS
+    # ============================================================
+    
+    def _extract_messages(messages: List[Dict]) -> Tuple[str, List[Dict]]:
+        """
+        Extract the user message and build Ollama-compatible history.
+        Converts tool messages to assistant context.
+        Returns (user_msg, ollama_messages).
+        """
+        user_msg = None
+        history = []
+        
+        for msg in messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            
+            if role == "system":
+                history.append({"role": "system", "content": content})
+                
+            elif role == "user":
+                if user_msg is not None:
+                    history.append({"role": "user", "content": user_msg})
+                user_msg = content
+                
+            elif role == "assistant":
+                tool_calls = msg.get("tool_calls", [])
+                if tool_calls:
+                    # Convert OpenAI tool_calls format to Ollama format
+                    # Ollama wants: arguments as dict, no id/type fields
+                    ollama_tcs = []
+                    for tc in tool_calls:
+                        func = tc.get("function", {})
+                        name = func.get("name", "")
+                        raw_args = func.get("arguments", {})
+                        if isinstance(raw_args, str):
+                            try:
+                                raw_args = json.loads(raw_args)
+                            except (json.JSONDecodeError, TypeError):
+                                raw_args = {}
+                        ollama_tcs.append({
+                            "function": {"name": name, "arguments": raw_args},
+                        })
+                    history.append({
+                        "role": "assistant",
+                        "content": content or "",
+                        "tool_calls": ollama_tcs,
+                    })
+                elif content:
+                    history.append({"role": "assistant", "content": content})
+                    
+            elif role == "tool":
+                # Ollama tool messages: just role + content (no tool_call_id)
+                history.append({
+                    "role": "tool",
+                    "content": content or "(no output)",
+                })
+        
+        return user_msg, history
+    
+    def _build_continuation_prompt(messages: List[Dict], original_query: str) -> str:
+        """Build prompt when CLI sends back results from delegated tools."""
+        # Find the last tool result
+        last_tool_result = ""
+        last_tool_name = ""
+        for msg in reversed(messages):
+            if msg.get("role") == "tool":
+                last_tool_result = msg.get("content", "")[:500]
+                last_tool_name = msg.get("name", "tool")
+                break
+        
+        return (
+            f"The tool {last_tool_name} returned:\n{last_tool_result}\n\n"
+            f"Original question: {original_query}\n\n"
+            f"Based on this result, either:\n"
+            f"1. Call more tools to continue investigating, OR\n"
+            f"2. Provide your final answer if you have enough information."
+        )
+    
+    def _build_investigation_prompt(
+        original_query: str,
+        investigation_log: List[Dict],
+        depth: int,
+    ) -> str:
+        """
+        Build a prompt for the next investigation round.
+        
+        v4.0 PHILOSOPHY: Let the model decide when it has enough data.
+        Don't force early answers. Only push for final answer near depth limit.
+        """
+        failures = sum(1 for e in investigation_log if not e["success"])
+        successes = sum(1 for e in investigation_log if e["success"])
+        
+        # Near the depth limit -- force final answer
+        if depth >= MAX_INVESTIGATION_DEPTH - 2:
+            return (
+                f"FINAL ROUND. You have gathered data from {successes} successful "
+                f"tool calls. Provide your FINAL answer to: {original_query}\n\n"
+                f"Summarize ALL findings. Be specific -- report exact values, "
+                f"ports, processes, permissions. No more tool calls."
+            )
+        
+        # All failures so far -- try different approach
+        if failures > 0 and successes == 0:
+            return (
+                f"The previous commands failed. Try a DIFFERENT approach "
+                f"to answer: {original_query}\n"
+                f"Use a different command. Do NOT repeat what already failed."
+            )
+        
+        # Normal continuation -- let model freely choose
+        already = [e["arguments"].get("command", e["arguments"].get("path", "?"))[:50] for e in investigation_log[-3:]]
+        return (
+            f"Original question: {original_query}\n"
+            f"You've run {len(investigation_log)} commands ({successes} OK, {failures} failed).\n"
+            f"Recent: {', '.join(already)}\n\n"
+            f"If you have enough information, provide your FINAL answer in plain text.\n"
+            f"If you need more data, call another tool with a DIFFERENT command."
+        )
+    
+    def _build_summary_prompt(original_query: str, investigation_log: List[Dict]) -> str:
+        """Build a forced-text prompt summarizing all investigation findings."""
+        return (
+            f"Based on all the tool results above, provide a CLEAR, DEFINITIVE "
+            f"answer to: {original_query}\n\n"
+            f"Rules for your response:\n"
+            f"- Write in plain language, no command blocks\n"
+            f"- State what IS working, what ISN'T, and why\n"
+            f"- Be direct and specific\n"
+            f"- Do NOT include any bash/shell commands or simulated tool output"
+        )
+    
+    def _format_investigation_summary(original_query: str, investigation_log: List[Dict]) -> str:
+        """Fallback text summary if model fails to summarize."""
+        lines = [f"Investigation: {original_query}\n"]
+        for entry in investigation_log:
+            status = "OK" if entry["success"] else "FAIL"
+            arg_str = entry["arguments"].get("command", entry["arguments"].get("path", str(entry["arguments"])))
+            lines.append(f"  [{status}] {entry['name']}({arg_str})")
+            if entry["output"]:
+                lines.append(f"         -> {entry['output'][:150]}")
+        return "\n".join(lines)
+
+    def _build_response_message(result: PipelineResult) -> Dict:
+        """Build OpenAI-style message from pipeline result."""
+        if result.output_type == "tool_call" and result.tool_calls:
+            return {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": f"call_{uuid.uuid4().hex[:8]}",
+                        "type": "function",
+                        "function": {
+                            "name": tc["name"],
+                            "arguments": json.dumps(tc["arguments"]) if isinstance(tc["arguments"], dict) else tc["arguments"],
+                        },
+                    }
+                    for tc in result.tool_calls
+                ],
+            }
+        return {
+            "role": "assistant",
+            "content": clean_model_output(result.text or ""),
+        }
+
+    return app
+
+
+def main():
+    parser = argparse.ArgumentParser(description="TokioAI Engine Server v3.0")
+    parser.add_argument("command", choices=["serve"], help="Server command")
+    parser.add_argument("--port", type=int, default=8080, help="Server port")
+    parser.add_argument("--host", type=str, default="127.0.0.1", help="Bind host")
+    parser.add_argument("--ollama-host", type=str, default=None, help="Ollama API host")
+    parser.add_argument("--model", type=str, default="tokioai-coder", help="Model name")
+    parser.add_argument("--verbose", action="store_true", help="Verbose logging")
+
+    args = parser.parse_args()
+
+    config = EngineConfig(
+        ollama_host=args.ollama_host,
+        model_name=args.model,
+        verbose=args.verbose,
+    )
+
+    app = create_app(config)
+    print(f"TokioAI Engine v3.0 starting on {args.host}:{args.port}")
+    print(f"  Model: {config.model_name}")
+    print(f"  Ollama: {config.ollama_host}")
+    print(f"  Max investigation depth: {MAX_INVESTIGATION_DEPTH}")
+    print(f"  Max investigation time: {MAX_INVESTIGATION_TIME}s")
+    print(f"  Server-side execution: ENABLED (tools: {', '.join(sorted(SAFE_TOOLS))})")
+    print(f"  Verbose: {args.verbose}")
+
+    app.run(host=args.host, port=args.port, threaded=True)
+
+
+if __name__ == "__main__":
+    main()

engine/test_engine.py

@@ -0,0 +1,220 @@
+"""
+TokioAI Engine -- Test Suite
+Tests router, verifier, memory, and full pipeline.
+"""
+
+import json
+import time
+import sys
+
+from .router import classify_intent, build_system_prompt, IntentType
+from .verifier import Verifier, verify_and_extract
+from .memory import EngineMemory
+from .schemas import validate_tool_call, extract_tool_calls_from_text
+from .guided import parse_guided_output
+
+
+def run_tests(verbose=False, ollama_host=None, model=None):
+    """Run all tests."""
+    passed = 0
+    failed = 0
+    
+    def check(name, condition, detail=""):
+        nonlocal passed, failed
+        if condition:
+            passed += 1
+            print(f"  \033[32mPASS\033[0m {name}")
+        else:
+            failed += 1
+            print(f"  \033[31mFAIL\033[0m {name} {detail}")
+
+    # ========================
+    print("\n=== ROUTER TESTS ===")
+    # ========================
+    
+    intent, conf = classify_intent("check disk space")
+    check("tool: check disk space", intent == IntentType.TOOL_CALL, f"got {intent}")
+
+    intent, conf = classify_intent("list docker containers")
+    check("tool: docker containers", intent == IntentType.TOOL_CALL, f"got {intent}")
+
+    intent, conf = classify_intent("read /etc/hostname")
+    check("tool: read file", intent == IntentType.TOOL_CALL, f"got {intent}")
+
+    intent, conf = classify_intent("run nmap on 192.168.1.1")
+    check("tool: nmap scan", intent == IntentType.TOOL_CALL, f"got {intent}")
+
+    intent, conf = classify_intent("what is SQL injection")
+    check("text: SQL injection", intent in (IntentType.TEXT, IntentType.CODE), f"got {intent}")
+
+    intent, conf = classify_intent("hi")
+    check("text: greeting", intent == IntentType.TEXT, f"got {intent}")
+
+    intent, conf = classify_intent("thanks")
+    check("text: thanks", intent == IntentType.TEXT, f"got {intent}")
+
+    intent, conf = classify_intent("explain the TCP handshake")
+    check("text: TCP explanation", intent in (IntentType.TEXT, IntentType.CODE), f"got {intent}")
+
+    intent, conf = classify_intent("what is docker")
+    check("decision: what is docker", intent in (IntentType.DECISION, IntentType.TEXT, IntentType.TOOL_CALL), f"got {intent}")
+
+    # ========================
+    print("\n=== VERIFIER TESTS ===")
+    # ========================
+
+    v = Verifier()
+
+    # Valid tool call
+    r = v.verify('{"name": "execute_local", "arguments": {"command": "df -h"}}')
+    check("verify: valid tool call", r.valid and r.output_type == "tool_call")
+
+    # Tool call in markdown
+    r = v.verify('```json\n{"name": "read_file", "arguments": {"path": "/etc/hostname"}}\n```')
+    check("verify: markdown tool call", r.valid and r.output_type == "tool_call")
+
+    # Invalid tool name
+    r = v.verify('{"name": "invalid_tool", "arguments": {"x": 1}}')
+    check("verify: invalid tool name", r.output_type in ("text", "error"))
+
+    # Missing required param
+    r = v.verify('{"name": "execute_local", "arguments": {}}')
+    check("verify: missing required param", not r.valid)
+
+    # Pure text
+    r = v.verify("Docker is a containerization platform.")
+    check("verify: pure text", r.valid and r.output_type == "text")
+
+    # Empty
+    r = v.verify("")
+    check("verify: empty output", not r.valid)
+
+    # ========================
+    print("\n=== SCHEMA TESTS ===")
+    # ========================
+
+    ok, err = validate_tool_call("execute_local", {"command": "ls"})
+    check("schema: valid execute_local", ok, err)
+
+    ok, err = validate_tool_call("execute_local", {})
+    check("schema: missing command", not ok)
+
+    ok, err = validate_tool_call("read_file", {"path": "/tmp/test"})
+    check("schema: valid read_file", ok, err)
+
+    ok, err = validate_tool_call("diagnose", {"target": "local"})
+    check("schema: valid diagnose", ok, err)
+
+    ok, err = validate_tool_call("diagnose", {"target": "invalid"})
+    check("schema: invalid enum", not ok)
+
+    # Extract tool calls from messy text
+    calls = extract_tool_calls_from_text(
+        'I will check the disk. {"name": "execute_local", "arguments": {"command": "df -h"}} Done.'
+    )
+    check("extract: tool in text", len(calls) == 1 and calls[0]["name"] == "execute_local")
+
+    # ========================
+    print("\n=== GUIDED TESTS ===")
+    # ========================
+
+    parsed = parse_guided_output('{"name": "execute_local", "arguments": {"command": "ls"}}', "tool_call")
+    check("guided: tool call parse", parsed["type"] == "tool_call" and parsed["name"] == "execute_local")
+
+    parsed = parse_guided_output('{"action": "text_response", "text_response": "hello"}', "decision")
+    check("guided: decision text", parsed["type"] == "text" and parsed["response"] == "hello")
+
+    parsed = parse_guided_output(
+        '{"action": "tool_call", "tool_call": {"name": "execute_local", "arguments": {"command": "ls"}}}',
+        "decision"
+    )
+    check("guided: decision tool", parsed["type"] == "tool_call" and parsed["name"] == "execute_local")
+
+    # ========================
+    print("\n=== MEMORY TESTS ===")
+    # ========================
+
+    import tempfile, os
+    tmp = os.path.join(tempfile.mkdtemp(), "test_memory.json")
+    mem = EngineMemory(path=tmp)
+
+    check("memory: seeded", len(mem.examples) > 0)
+
+    mem.add("check cpu usage", '{"name": "execute_local", "arguments": {"command": "top -bn1"}}',
+            intent="tool_call", tool_name="execute_local")
+    check("memory: add", len(mem.examples) > 0)
+
+    results = mem.retrieve("show cpu", intent="tool_call", top_k=3)
+    check("memory: retrieve", len(results) > 0, f"got {len(results)}")
+
+    stats = mem.get_stats()
+    check("memory: stats", stats["total"] > 0)
+
+    # Cleanup
+    os.unlink(tmp)
+
+    # ========================
+    print(f"\n=== RESULTS: {passed} passed, {failed} failed ===\n")
+
+    # ========================
+    # LIVE TESTS (optional -- only if model is available)
+    # ========================
+    if ollama_host or model:
+        from .pipeline import Pipeline, EngineConfig
+        config = EngineConfig(
+            ollama_host=ollama_host,
+            model_name=model or "tokioai-coder",
+            verbose=verbose,
+        )
+        
+        print("=== LIVE PIPELINE TESTS ===")
+        print(f"Model: {config.model_name} @ {config.ollama_host}\n")
+        
+        engine = Pipeline(config)
+        live_passed = 0
+        live_failed = 0
+
+        test_cases = [
+            ("check disk space", "tool_call", "execute_local"),
+            ("read /etc/hostname", "tool_call", "read_file"),
+            ("find TODO in python files", "tool_call", "search_files"),
+            ("what is SQL injection", "text", None),
+            ("hi", "text", None),
+            ("list running processes", "tool_call", "execute_local"),
+            ("check system health", "tool_call", "diagnose"),
+            ("explain what docker is", "text", None),
+        ]
+
+        for prompt, expected_type, expected_tool in test_cases:
+            try:
+                result = engine.process(prompt)
+                
+                type_match = result.output_type == expected_type
+                tool_match = True
+                if expected_tool and result.tool_calls:
+                    tool_match = result.tool_calls[0]["name"] == expected_tool
+
+                ok = type_match and tool_match
+                detail = ""
+                if result.output_type == "tool_call" and result.tool_calls:
+                    detail = f"-> {result.tool_calls[0]['name']}({list(result.tool_calls[0]['arguments'].keys())})"
+                else:
+                    detail = f"-> text({len(result.text)} chars)"
+
+                if ok:
+                    live_passed += 1
+                    print(f"  \033[32mPASS\033[0m [{result.latency_ms:4d}ms] [{result.attempts}att] {prompt:40s} {detail}")
+                else:
+                    live_failed += 1
+                    print(f"  \033[31mFAIL\033[0m [{result.latency_ms:4d}ms] [{result.attempts}att] {prompt:40s} {detail} (expected {expected_type}/{expected_tool})")
+            except Exception as e:
+                live_failed += 1
+                print(f"  \033[31mERROR\033[0m {prompt}: {e}")
+            
+            engine.reset()
+
+        print(f"\n=== LIVE RESULTS: {live_passed} passed, {live_failed} failed ===\n")
+        passed += live_passed
+        failed += live_failed
+
+    return passed, failed

engine/verifier.py

@@ -0,0 +1,186 @@
+"""
+TokioAI Engine -- Output Verifier & Retry Logic
+Validates model responses and orchestrates retries on failure.
+
+The verifier catches:
+1. Invalid JSON tool calls
+2. Wrong tool names
+3. Missing required parameters
+4. Malformed output (e.g., natural language when tool expected)
+5. Verbosity (strips filler from responses)
+"""
+
+import json
+import re
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from .schemas import validate_tool_call, extract_tool_calls_from_text, VALID_TOOL_NAMES
+
+
+class VerificationResult:
+    """Result of verifying model output."""
+
+    def __init__(
+        self,
+        valid: bool,
+        output_type: str,  # "tool_call", "text", "error"
+        tool_calls: List[Dict] = None,
+        text: str = None,
+        error: str = None,
+        raw_output: str = None,
+    ):
+        self.valid = valid
+        self.output_type = output_type
+        self.tool_calls = tool_calls or []
+        self.text = text or ""
+        self.error = error or ""
+        self.raw_output = raw_output or ""
+
+    def __repr__(self):
+        if self.valid:
+            if self.output_type == "tool_call":
+                names = [tc["name"] for tc in self.tool_calls]
+                return f"VerificationResult(valid=True, tools={names})"
+            return f"VerificationResult(valid=True, type={self.output_type})"
+        return f"VerificationResult(valid=False, error={self.error!r})"
+
+
+class Verifier:
+    """
+    Validates model output and provides structured results.
+    """
+
+    def __init__(self, strict: bool = False):
+        """
+        Args:
+            strict: If True, rejects ambiguous outputs. If False, tries harder to parse.
+        """
+        self.strict = strict
+
+    def verify(self, model_output: str, expected_intent: str = None) -> VerificationResult:
+        """
+        Verify model output.
+        
+        Args:
+            model_output: Raw text from the model
+            expected_intent: What the router classified (tool_call, text, etc.)
+            
+        Returns:
+            VerificationResult with parsed tool calls or cleaned text
+        """
+        if not model_output or not model_output.strip():
+            return VerificationResult(
+                valid=False,
+                output_type="error",
+                error="Empty model output",
+                raw_output=model_output,
+            )
+
+        raw = model_output.strip()
+
+        # Step 1: Try to extract tool calls
+        tool_calls = extract_tool_calls_from_text(raw)
+
+        if tool_calls:
+            # Validate each tool call
+            valid_calls = []
+            errors = []
+
+            for tc in tool_calls:
+                is_valid, err = validate_tool_call(tc["name"], tc["arguments"])
+                if is_valid:
+                    valid_calls.append(tc)
+                else:
+                    errors.append(err)
+
+            if valid_calls:
+                return VerificationResult(
+                    valid=True,
+                    output_type="tool_call",
+                    tool_calls=valid_calls,
+                    raw_output=raw,
+                )
+            elif errors:
+                return VerificationResult(
+                    valid=False,
+                    output_type="error",
+                    error="; ".join(errors),
+                    raw_output=raw,
+                )
+
+        # Step 2: If expected tool_call but got text, that might be an error
+        if expected_intent == "tool_call":
+            # Check if the model is TRYING to make a tool call but failing
+            if any(name in raw.lower() for name in VALID_TOOL_NAMES):
+                return VerificationResult(
+                    valid=False,
+                    output_type="error",
+                    error="Model mentioned a tool name but didn't format it as a valid JSON tool call",
+                    raw_output=raw,
+                )
+
+        # Step 3: It's a text response -- clean it up
+        cleaned = self._clean_text(raw)
+        return VerificationResult(
+            valid=True,
+            output_type="text",
+            text=cleaned,
+            raw_output=raw,
+        )
+
+    def _clean_text(self, text: str) -> str:
+        """Clean up verbose model output."""
+        # Remove thinking tags (Qwen3 /think blocks)
+        text = re.sub(r'<think>.*?</think>', '', text, flags=re.DOTALL)
+        # Remove empty lines at start/end
+        text = text.strip()
+        # Remove excessive newlines
+        text = re.sub(r'\n{3,}', '\n\n', text)
+        return text
+
+
+class RetryStrategy:
+    """
+    Manages retry logic when the verifier rejects model output.
+    Each retry gets a more explicit prompt to guide the model.
+    """
+
+    def __init__(self, max_retries: int = 2):
+        self.max_retries = max_retries
+
+    def should_retry(self, attempt: int, result: VerificationResult) -> bool:
+        """Should we retry after a failed verification?"""
+        if result.valid:
+            return False
+        if attempt >= self.max_retries:
+            return False
+        # Don't retry empty outputs (model is broken)
+        if not result.raw_output.strip():
+            return False
+        return True
+
+    def get_retry_message(self, attempt: int, result: VerificationResult) -> str:
+        """Generate a retry prompt based on what went wrong."""
+        if attempt == 0:
+            # First retry: gentle correction
+            return (
+                f"Your previous response was not valid: {result.error}\n"
+                f"Please respond with ONLY a JSON object like this:\n"
+                f'{{"name": "tool_name", "arguments": {{"param": "value"}}}}\n'
+                f"No explanation, no markdown, just the JSON."
+            )
+        else:
+            # Second retry: very explicit
+            return (
+                f"ERROR: {result.error}\n"
+                f"You MUST respond with valid JSON only. "
+                f"Valid tool names: {', '.join(sorted(VALID_TOOL_NAMES))}.\n"
+                f"Format: {{\"name\": \"execute_local\", \"arguments\": {{\"command\": \"your command\"}}}}\n"
+                f"Respond with NOTHING except the JSON object."
+            )
+
+
+def verify_and_extract(model_output: str, expected_intent: str = None) -> VerificationResult:
+    """Convenience function: verify model output with default settings."""
+    return Verifier().verify(model_output, expected_intent)

examples/basic_usage.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+TokioAI Engine -- Basic Usage Example
+
+Prerequisites:
+  pip install tokioai-engine
+  ollama serve &
+  ollama pull qwen3-coder
+"""
+
+from engine.pipeline import Pipeline, EngineConfig
+
+# Create engine with default config (connects to local Ollama)
+config = EngineConfig(
+    model_name="qwen3-coder",          # Any Ollama model
+    ollama_host="http://localhost:11434",
+    max_retries=2,                      # Retry on bad output
+    use_guided_gen=True,                # Force valid JSON for tool calls
+    use_memory=True,                    # Learn from successful interactions
+    verbose=True,                       # Show engine internals
+)
+
+engine = Pipeline(config)
+
+# --- Tool Call Example ---
+print("=" * 60)
+print("TOOL CALL: 'check disk space'")
+print("=" * 60)
+
+result = engine.process("check disk space")
+print(f"Intent:  {result.intent}")
+print(f"Type:    {result.output_type}")
+print(f"Calls:   {result.tool_calls}")
+print(f"Latency: {result.latency_ms}ms")
+print(f"Retries: {result.attempts}")
+print()
+
+# --- Text Response Example ---
+print("=" * 60)
+print("TEXT: 'what is SQL injection'")
+print("=" * 60)
+
+engine.reset()
+result = engine.process("what is SQL injection")
+print(f"Intent:  {result.intent}")
+print(f"Type:    {result.output_type}")
+print(f"Text:    {result.text[:200]}")
+print(f"Latency: {result.latency_ms}ms")
+print()
+
+# --- Decision Example ---
+print("=" * 60)
+print("DECISION: 'is docker running'")
+print("=" * 60)
+
+engine.reset()
+result = engine.process("is docker running")
+print(f"Intent:  {result.intent}")
+print(f"Type:    {result.output_type}")
+if result.tool_calls:
+    print(f"Calls:   {result.tool_calls}")
+else:
+    print(f"Text:    {result.text[:200]}")
+print(f"Latency: {result.latency_ms}ms")
+print()
+
+# --- Stats ---
+print("=" * 60)
+print("ENGINE STATS")
+print("=" * 60)
+import json
+print(json.dumps(engine.get_stats(), indent=2))

examples/custom_tools.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+TokioAI Engine -- Custom Tools Example
+
+Shows how to add your own tools to the engine.
+Modify engine/schemas.py to add tool definitions,
+or pass them through the API.
+"""
+
+from engine.pipeline import Pipeline, EngineConfig
+from engine.schemas import TOOL_DEFINITIONS
+
+# You can inspect the built-in tools
+print("Built-in tools:")
+for tool in TOOL_DEFINITIONS:
+    name = tool["function"]["name"]
+    desc = tool["function"]["description"][:60]
+    print(f"  {name:20s} -- {desc}")
+
+print()
+
+# Use the engine normally -- it already knows all TokioAI tools
+config = EngineConfig(
+    model_name="qwen3-coder",
+    verbose=True,
+)
+engine = Pipeline(config)
+
+# The engine's router will classify this as tool_call
+# and the guided generator will constrain output to valid tool names
+result = engine.process("search for TODO comments in all python files")
+
+print(f"\nResult: {result}")
+if result.tool_calls:
+    print(f"Tool: {result.tool_calls[0]['name']}")
+    print(f"Args: {result.tool_calls[0]['arguments']}")

examples/openai_client.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+TokioAI Engine -- OpenAI Client Example
+
+Shows how to use TokioAI Engine as a drop-in replacement for OpenAI API.
+
+Prerequisites:
+  pip install tokioai-engine openai
+  python -m engine serve --model qwen3-coder --port 8080
+"""
+
+from openai import OpenAI
+
+# Connect to TokioAI Engine (same API as OpenAI)
+client = OpenAI(
+    base_url="http://localhost:8080/v1",
+    api_key="not-needed",  # Engine doesn't require auth
+)
+
+# --- Tool calling ---
+print("--- Tool Calling ---")
+response = client.chat.completions.create(
+    model="tokioai-engine",
+    messages=[{"role": "user", "content": "check what processes are using the most memory"}],
+)
+
+msg = response.choices[0].message
+if msg.tool_calls:
+    for tc in msg.tool_calls:
+        print(f"Tool:      {tc.function.name}")
+        print(f"Arguments: {tc.function.arguments}")
+else:
+    print(f"Response: {msg.content}")
+
+print()
+
+# --- Text response ---
+print("--- Text Response ---")
+response = client.chat.completions.create(
+    model="tokioai-engine",
+    messages=[{"role": "user", "content": "explain the TCP 3-way handshake in one paragraph"}],
+)
+
+print(f"Response: {response.choices[0].message.content}")
+print()
+
+# --- Engine metadata ---
+if hasattr(response, "engine_metadata"):
+    print(f"Intent:     {response.engine_metadata['intent']}")
+    print(f"Confidence: {response.engine_metadata['confidence']}")
+    print(f"Latency:    {response.engine_metadata['latency_ms']}ms")

prompts/iot_system_prompt.md

@@ -0,0 +1,216 @@
+# TokioAI IoT System Prompt
+
+This is the production system prompt used by TokioAI-Coder for IoT/smart-home control.
+Customize it for your own setup by replacing entity names and API endpoints.
+
+---
+
+## System Prompt
+
+```
+You are TokioAI -- an elite cybersecurity and DevOps AI agent.
+You execute commands, fix bugs, deploy infrastructure, and solve problems.
+You have full access to the user's systems via tools.
+
+## CRITICAL RULES -- NEVER VIOLATE THESE
+
+1. NEVER simulate or fake tool execution in your text responses.
+   WRONG: writing "```bash\ndf -h\n```\nResult: ..." in your text.
+   RIGHT: call the execute_local tool with {"command": "df -h"}.
+   The engine will execute the tool and give you the real result.
+
+2. When you need system information, ALWAYS use a tool call.
+   NEVER make up or guess command output. NEVER write fake results.
+
+3. Your text responses should contain ONLY your analysis and conclusions.
+   NEVER include "I ran:", "Result of tool:", or "```bash" blocks that
+   simulate command execution.
+
+4. If you already have real tool results in the conversation, summarize
+   them in plain language. Do NOT echo back raw tool output format.
+
+## ENVIRONMENT
+You are running on a Raspberry Pi 5 (Debian/aarch64).
+Key services:
+- Home Assistant: runs as Docker container "homeassistant" (NOT systemd). Check with: docker ps | grep home
+- Docker: available. Most services run as containers.
+- Ollama: runs locally or via SSH tunnel on port 8200
+- TokioAI Engine: this server (port 8080)
+When checking if something is running, ALWAYS check both systemd AND docker.
+
+## ROBOT VISION (robot_vision tool)
+You have a camera on the robot. Use the robot_vision tool to SEE what the robot sees.
+- Use it when the user asks: "what do you see?", "look around", "describe the room", "is anyone there?"
+- The tool captures a live photo and analyzes it with a vision AI model
+- You can pass a specific question: robot_vision(question="how many people are in the room?")
+- ALWAYS use robot_vision for visual questions. NEVER say "I can't see" -- you CAN see.
+
+## HOME ASSISTANT VERIFICATION (CRITICAL)
+After calling ANY HA service (media, lights, switches, etc.), you MUST:
+1. Execute the service call
+2. Wait 3 seconds (sleep 3)
+3. GET the entity state to confirm it ACTUALLY changed
+4. Report what is ACTUALLY happening, not what you hoped
+
+HA auth pattern:
+  HA_TOKEN=$(cat /path/to/ha_token) && curl -s -H "Authorization: Bearer $HA_TOKEN" ...
+  
+Or with env var:
+  curl -s -H "Authorization: Bearer $HA_TOKEN" http://localhost:8123/api/...
+
+For music changes specifically:
+  After play_media, run: sleep 3 && curl -s -H "Authorization: Bearer $HA_TOKEN" \
+    http://localhost:8123/api/states/media_player.YOUR_DEVICE | \
+    python3 -c "import sys,json;s=json.load(sys.stdin);a=s['attributes'];print(f'State: {s[\"state\"]}, Title: {a.get(\"media_title\",\"?\")}, Artist: {a.get(\"media_artist\",\"?\")}')"
+  If title/artist didn't change or state is not "playing", tell the user it FAILED.
+
+A 200 OK from the API only means HA received the request, NOT that it worked. ALWAYS verify.
+
+## HOME ASSISTANT COOKBOOK (execute via execute_local tool)
+
+### Authentication
+Auth pattern: curl -s -H "Authorization: Bearer $HA_TOKEN" http://YOUR_HA_URL/api/...
+Base URL: http://localhost:8123 (change to your HA instance)
+
+### Media Player
+Entity: media_player.YOUR_DEVICE (e.g., media_player.jarvis for Amazon Echo)
+
+- What's playing:
+  GET /api/states/media_player.YOUR_DEVICE
+  (check media_title, media_artist, state)
+
+- Change music:
+  POST /api/services/media_player/play_media
+  {"entity_id":"media_player.YOUR_DEVICE","media_content_type":"music","media_content_id":"QUERY"}
+  (e.g., "blues", "rock", "Beatles", "lofi hip hop")
+
+- Volume:
+  POST /api/services/media_player/volume_set
+  {"entity_id":"media_player.YOUR_DEVICE","volume_level":0.5}
+  (0.0 to 1.0)
+
+- Play/Pause:
+  POST /api/services/media_player/media_play_pause
+  {"entity_id":"media_player.YOUR_DEVICE"}
+
+- Next/Previous track:
+  POST /api/services/media_player/media_next_track
+  POST /api/services/media_player/media_previous_track
+
+- TTS (device speaks):
+  POST /api/services/notify/alexa_media_YOUR_DEVICE
+  {"message":"TEXT","data":{"type":"tts"}}
+
+- Announce:
+  POST /api/services/notify/alexa_media_YOUR_DEVICE
+  {"message":"TEXT","data":{"type":"announce"}}
+
+NEVER use notify to change music. notify is ONLY for TTS/announcements.
+
+### Lights
+Entities: light.living_room, light.bedroom, light.kitchen (customize)
+
+- Turn on/off:
+  POST /api/services/light/turn_on or turn_off
+  {"entity_id":"light.YOUR_LIGHT"}
+
+- Brightness (0-255):
+  POST /api/services/light/turn_on
+  {"entity_id":"light.YOUR_LIGHT","brightness":128}
+
+- Color (RGB):
+  POST /api/services/light/turn_on
+  {"entity_id":"light.YOUR_LIGHT","rgb_color":[255,0,0]}
+
+### Switches
+Entities: switch.YOUR_SWITCH
+
+- Turn on/off:
+  POST /api/services/switch/turn_on or turn_off
+  {"entity_id":"switch.YOUR_SWITCH"}
+
+### Sensors
+Entities: sensor.temperature, weather.forecast_home
+
+- Read sensor:
+  GET /api/states/sensor.YOUR_SENSOR
+
+- Weather:
+  GET /api/states/weather.forecast_home
+
+### Vacuum
+Entity: vacuum.YOUR_VACUUM
+
+- Start/Stop/Return:
+  POST /api/services/vacuum/start
+  POST /api/services/vacuum/stop
+  POST /api/services/vacuum/return_to_base
+  {"entity_id":"vacuum.YOUR_VACUUM"}
+
+### Automations
+- List all:
+  GET /api/states (filter entity_id starting with "automation.")
+
+- Trigger:
+  POST /api/services/automation/trigger
+  {"entity_id":"automation.YOUR_AUTOMATION"}
+
+## CORE RULES
+- Be DIRECT. Act first, explain after.
+- NEVER give up. If something fails, try alternatives.
+- When investigating: diagnose -> try alternatives -> root cause -> answer.
+- NEVER output passwords, API keys, or tokens in plain text.
+- Be concise but thorough.
+
+## INVESTIGATION BEHAVIOR
+You are an INVESTIGATOR. When asked about system state:
+1. ALWAYS check the actual system. NEVER speculate.
+2. If the first command doesn't give the full picture, run MORE commands automatically.
+3. For "is X running?": check systemctl, docker, ps, ports. Try multiple approaches.
+4. NEVER ask "do you want me to check more?" -- just CHECK IT.
+5. NEVER say "you should review X" -- YOU review it and report findings.
+6. Think like a senior engineer: be thorough, check multiple angles, report specifics.
+7. Always use TOOL CALLS -- never simulate commands in your text response.
+
+## ANSWER FORMAT
+When you've gathered enough information:
+- State what you found CLEARLY
+- If something is running: say what it is, where, which port, how it was started
+- If something is NOT available: say what you tried and why
+- NEVER give generic "recommendations" -- give FACTS
+- Report EXACTLY what the command output says
+```
+
+---
+
+## Customization Guide
+
+### Step 1: Replace Entities
+Search for `YOUR_DEVICE`, `YOUR_LIGHT`, `YOUR_SWITCH`, `YOUR_SENSOR`, `YOUR_VACUUM` and replace with your actual Home Assistant entity IDs.
+
+### Step 2: Set Authentication
+Choose one of:
+- Environment variable: `export HA_TOKEN="your-long-lived-token"`
+- File: `echo "your-token" > ~/.ha_token` and use `$(cat ~/.ha_token)`
+- .env file: Add `HA_TOKEN=your-token` to `~/.tokioai/.env`
+
+### Step 3: Add Your Entities
+List all your HA entities:
+```bash
+curl -s -H "Authorization: Bearer $HA_TOKEN" http://localhost:8123/api/states | \
+  python3 -c "import sys,json;[print(s['entity_id']) for s in json.load(sys.stdin)]" | sort
+```
+
+Add them to the appropriate sections in the system prompt.
+
+### Step 4: Test
+```bash
+# Test HA connection
+curl -s -H "Authorization: Bearer $HA_TOKEN" http://localhost:8123/api/
+
+# Test a light
+curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" \
+  -H "Content-Type: application/json" \
+  http://localhost:8123/api/services/light/turn_on \
+  -d '{"entity_id":"light.your_light"}'
+```

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokioai-engine"
+version = "1.0.0"
+description = "Transform any small open model into an elite AI agent"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [{name = "TokioAI"}]
+keywords = ["ai", "llm", "inference", "tool-calling", "agent", "security", "ollama"]
+dependencies = ["requests>=2.28", "flask>=2.0"]
+
+[project.scripts]
+tokioai-engine = "engine.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "openai>=1.0"]

setup.py

@@ -0,0 +1,52 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="tokioai-engine",
+    version="1.0.0",
+    description="Transform any small open model into an elite AI agent with tool calling, guided generation, and adaptive memory",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="TokioAI",
+    author_email="hello@tokio.ai",
+    url="https://github.com/TokioAI/tokioai-engine",
+    project_urls={
+        "Bug Reports": "https://github.com/TokioAI/tokioai-engine/issues",
+        "Source": "https://github.com/TokioAI/tokioai-engine",
+    },
+    packages=find_packages(),
+    python_requires=">=3.8",
+    install_requires=[
+        "requests>=2.28",
+        "flask>=2.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=7.0",
+            "openai>=1.0",
+        ],
+    },
+    entry_points={
+        "console_scripts": [
+            "tokioai-engine=engine.server:main",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+        "Topic :: Security",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Operating System :: OS Independent",
+    ],
+    keywords="ai llm inference tool-calling agent security devops ollama",
+)

tools/tool_definitions.json

@@ -0,0 +1,266 @@
+[
+  {
+    "type": "function",
+    "function": {
+      "name": "execute_local",
+      "description": "Execute a shell command on the local machine. Use for system operations: install packages, check processes, network scans, file operations.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "Shell command to execute (bash)"
+          },
+          "timeout": {
+            "type": "integer",
+            "description": "Timeout in seconds (default 30, max 120)"
+          }
+        },
+        "required": ["command"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "execute_raspi",
+      "description": "Execute a command on a Raspberry Pi via SSH.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "Command to run on Raspi"
+          },
+          "timeout": {
+            "type": "integer",
+            "description": "Timeout in seconds (default 30, max 120)"
+          }
+        },
+        "required": ["command"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "execute_gcp",
+      "description": "Execute a command on a GCP VM via SSH.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "Command to run on GCP"
+          },
+          "timeout": {
+            "type": "integer",
+            "description": "Timeout in seconds (default 30, max 120)"
+          }
+        },
+        "required": ["command"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "execute_router",
+      "description": "Execute a command on the router via SSH (root).",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string",
+            "description": "Command to run on router as root"
+          }
+        },
+        "required": ["command"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "read_file",
+      "description": "Read a file from local or remote systems.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "File path. Use raspi:/path or gcp:/path for remote"
+          },
+          "lines": {
+            "type": "integer",
+            "description": "Max lines to read (default: all)"
+          }
+        },
+        "required": ["path"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "write_file",
+      "description": "Write content to a file.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "File path. Use raspi:/path or gcp:/path for remote"
+          },
+          "content": {
+            "type": "string",
+            "description": "File content to write"
+          }
+        },
+        "required": ["path", "content"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "edit_file",
+      "description": "Replace a specific string in a file. old_text must be unique.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "File path"
+          },
+          "old_text": {
+            "type": "string",
+            "description": "Exact text to find (must be unique)"
+          },
+          "new_text": {
+            "type": "string",
+            "description": "Replacement text"
+          }
+        },
+        "required": ["path", "old_text", "new_text"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "search_files",
+      "description": "Search for text patterns across files. Like grep -rn.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "pattern": {
+            "type": "string",
+            "description": "Text or regex pattern to search"
+          },
+          "path": {
+            "type": "string",
+            "description": "Directory to search"
+          },
+          "glob": {
+            "type": "string",
+            "description": "File filter glob (e.g., '*.py')"
+          }
+        },
+        "required": ["pattern"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "robot_vision",
+      "description": "Capture a photo from the robot's camera and analyze it with a vision AI model.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "question": {
+            "type": "string",
+            "description": "What to look for in the image (e.g. 'how many people?', 'describe the room')"
+          }
+        },
+        "required": []
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "diagnose",
+      "description": "Run system health diagnostics.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "target": {
+            "type": "string",
+            "enum": ["local", "raspi", "gcp", "router", "all"],
+            "description": "Target system"
+          }
+        },
+        "required": ["target"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory",
+      "description": "Persistent memory across sessions. Actions: read, write, append, clear.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["read", "write", "append", "clear"],
+            "description": "Memory operation"
+          },
+          "content": {
+            "type": "string",
+            "description": "Content to write/append"
+          }
+        },
+        "required": ["action"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "task",
+      "description": "Persistent task tracker across sessions.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["add", "update", "list", "remove", "clear_done"],
+            "description": "Task operation"
+          },
+          "task": {
+            "type": "string",
+            "description": "Task description (for add)"
+          },
+          "id": {
+            "type": "integer",
+            "description": "Task ID (for update/remove)"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "in_progress", "done", "blocked"],
+            "description": "New status"
+          },
+          "note": {
+            "type": "string",
+            "description": "Note to add"
+          }
+        },
+        "required": ["action"]
+      }
+    }
+  }
+]