Deploy Nancy Relay Gateway

.gitignore

@@ -0,0 +1,7 @@
+.env
+__pycache__/
+*.pyc
+.git/
+.env.*
+.venv/
+venv/

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.11-slim
+
+# HF Spaces requires UID 1000
+RUN useradd -m -u 1000 appuser
+
+WORKDIR /app
+
+# Install dependencies first for layer caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Switch to non-root user
+USER appuser
+
+# HF Spaces expects port 7860
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7860/health')"
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -0,0 +1,41 @@
+---
+title: Nancy
+emoji: 🔀
+colorFrom: purple
+colorTo: blue
+sdk: docker
+pinned: false
+license: mit
+app_port: 7860
+---
+
+# Nancy — Free LLM Router
+
+Nancy converts free chatbot web UIs into OpenAI-compatible APIs.
+
+## Architecture
+
+- **API Layer**: OpenAI-compatible `/v1/chat/completions` and `/v1/models`
+- **Task Queue**: Async task queue bridges API requests to browser extension
+- **Extension Relay**: Chrome extension connects via SSE, executes tasks in real browser tabs
+- **Provider Router**: Circuit breaker + fallback chains across multiple free LLM providers
+
+## Usage
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://your-space.hf.space/v1",
+    api_key="your-nancy-api-key",
+)
+
+response = client.chat.completions.create(
+    model="chatgpt",
+    messages=[{"role": "user", "content": "Hello!"}],
+    stream=True,
+)
+
+for chunk in response:
+    print(chunk.choices[0].delta.content or "", end="")
+```

config.py

@@ -0,0 +1,148 @@
+"""
+Nancy HF Space — Configuration Module.
+
+All settings are loaded from environment variables with sensible defaults.
+Provider configuration can be supplied as a JSON string via PROVIDERS_CONFIG.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings
+
+logger = logging.getLogger("nancy.config")
+
+
+class Settings(BaseSettings):
+    """Application settings sourced from environment variables."""
+
+    # ── Auth ──────────────────────────────────────────────────────────
+    nancy_api_key: str = Field(
+        default="nancy-dev-key",
+        description="Bearer token required for /v1/* API endpoints.",
+    )
+    nancy_ext_secret: str = Field(
+        default="nancy-ext-dev-secret",
+        description="Bearer token required for /ext/* extension endpoints.",
+    )
+
+    # ── Upstash Redis (optional) ──────────────────────────────────────
+    upstash_redis_rest_url: str = Field(
+        default="",
+        description="Upstash Redis REST URL. Leave empty to use in-memory fallback.",
+    )
+    upstash_redis_rest_token: str = Field(
+        default="",
+        description="Upstash Redis REST bearer token.",
+    )
+
+    # ── Official Paid APIs / Hybrid Keys (optional) ───────────────────
+    mistral_api_key: str = Field(default="", description="Official Mistral API Key.")
+    nvidia_nim_api_key: str = Field(default="", description="Official NVIDIA NIM API Key.")
+    deepseek_api_key: str = Field(default="", description="Official DeepSeek API Key.")
+    anthropic_api_key: str = Field(default="", description="Official Anthropic/Claude API Key.")
+    z_ai_api_key: str = Field(default="", description="Official Z.ai API Key.")
+
+    # ── Provider Routing ──────────────────────────────────────────────
+    default_provider: str = Field(
+        default="chatgpt",
+        description="Default provider when the model name is not recognized.",
+    )
+    fallback_chain: list[str] = Field(
+        default=["chatgpt", "gemini", "deepseek", "kimi", "claude", "nim", "zai"],
+        description="Ordered list of providers to try on failure.",
+    )
+    providers_config: dict[str, Any] = Field(
+        default_factory=lambda: {
+            "chatgpt":  {"rpm": 10, "tpm": 40000, "url_pattern": "https://chatgpt.com"},
+            "gemini":   {"rpm": 15, "tpm": 60000, "url_pattern": "https://gemini.google.com"},
+            "deepseek": {"rpm": 10, "tpm": 40000, "url_pattern": "https://chat.deepseek.com"},
+            "kimi":     {"rpm": 10, "tpm": 40000, "url_pattern": "https://kimi.moonshot.cn"},
+            "claude":   {"rpm": 5,  "tpm": 30000, "url_pattern": "https://claude.ai"},
+            "nim":      {"rpm": 5,  "tpm": 20000, "url_pattern": "https://build.nvidia.com/nim"},
+            "zai":      {"rpm": 5,  "tpm": 20000, "url_pattern": "https://chat.z.ai"},
+        },
+        description="Per-provider configuration. Supply as JSON string via env var.",
+    )
+
+
+    # ── Circuit Breaker ───────────────────────────────────────────────
+    cb_failure_threshold: int = Field(
+        default=3,
+        description="Consecutive failures before tripping the circuit breaker.",
+    )
+    cb_cooldown_seconds: float = Field(
+        default=60.0,
+        description="Seconds to wait before retrying a tripped provider.",
+    )
+
+    # ── Task Queue ────────────────────────────────────────────────────
+    task_timeout_seconds: float = Field(
+        default=120.0,
+        description="Max seconds to wait for extension to complete a task.",
+    )
+    task_queue_max_size: int = Field(
+        default=100,
+        description="Maximum number of pending tasks in the queue.",
+    )
+
+    # ── Extension ─────────────────────────────────────────────────────
+    ext_heartbeat_timeout_seconds: float = Field(
+        default=30.0,
+        description="Seconds after last heartbeat before extension is considered offline.",
+    )
+    ext_sse_keepalive_seconds: float = Field(
+        default=15.0,
+        description="Interval for SSE keepalive pings to the extension.",
+    )
+
+    # ── Server ────────────────────────────────────────────────────────
+    log_level: str = Field(default="INFO", description="Logging level.")
+    cors_origins: list[str] = Field(
+        default=["*"],
+        description="Allowed CORS origins.",
+    )
+
+    # ── Validators ────────────────────────────────────────────────────
+    @field_validator("providers_config", mode="before")
+    @classmethod
+    def parse_providers_json(cls, v: Any) -> dict[str, Any]:
+        """Accept a JSON string or dict for providers_config."""
+        if isinstance(v, str):
+            try:
+                return json.loads(v)
+            except json.JSONDecodeError as exc:
+                logger.error("Invalid PROVIDERS_CONFIG JSON: %s", exc)
+                raise ValueError(f"PROVIDERS_CONFIG is not valid JSON: {exc}") from exc
+        return v
+
+    @field_validator("fallback_chain", mode="before")
+    @classmethod
+    def parse_fallback_chain(cls, v: Any) -> list[str]:
+        """Accept a comma-separated string or list."""
+        if isinstance(v, str):
+            return [s.strip() for s in v.split(",") if s.strip()]
+        return v
+
+    @field_validator("cors_origins", mode="before")
+    @classmethod
+    def parse_cors_origins(cls, v: Any) -> list[str]:
+        """Accept a comma-separated string or list."""
+        if isinstance(v, str):
+            return [s.strip() for s in v.split(",") if s.strip()]
+        return v
+
+    @property
+    def redis_enabled(self) -> bool:
+        """Return True if Upstash Redis is configured."""
+        return bool(self.upstash_redis_rest_url and self.upstash_redis_rest_token)
+
+    model_config = {"env_prefix": "", "case_sensitive": False}
+
+
+# Module-level singleton
+settings = Settings()

core/__init__.py

@@ -0,0 +1 @@
+"""Nancy core package."""

core/auth.py

@@ -0,0 +1,122 @@
+"""
+Nancy — Authentication & Authorization.
+
+Provides FastAPI dependency functions for bearer token validation.
+Two separate tokens are used:
+  - ``NANCY_API_KEY``  → for agent-facing ``/v1/*`` endpoints
+  - ``NANCY_EXT_SECRET`` → for extension-facing ``/ext/*`` endpoints
+"""
+
+from __future__ import annotations
+
+import logging
+import hashlib
+import time
+import asyncio
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from config import settings
+from core.redis_client import redis_client
+
+
+logger = logging.getLogger("nancy.auth")
+
+# Reusable security scheme — auto_error=False lets us return a nicer message
+_bearer_scheme = HTTPBearer(auto_error=False)
+
+
+def _extract_token(
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None,
+) -> str:
+    """
+    Extract the bearer token from the Authorization header.
+
+    Falls back to the ``authorization`` query parameter for SSE connections
+    where some clients cannot set custom headers.
+
+    Raises:
+        HTTPException(401): If no token is present.
+    """
+    if credentials and credentials.credentials:
+        return credentials.credentials
+
+    # Fallback: query param (useful for EventSource which can't set headers)
+    query_token = request.query_params.get("authorization") or request.query_params.get("token")
+    if query_token:
+        # Strip "Bearer " prefix if present
+        if query_token.lower().startswith("bearer "):
+            return query_token[7:]
+        return query_token
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Missing authorization header. Provide 'Authorization: Bearer <token>'.",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+async def require_api_key(
+    request: Request,
+    credentials: Annotated[
+        HTTPAuthorizationCredentials | None, Depends(_bearer_scheme)
+    ] = None,
+) -> str:
+    """
+    FastAPI dependency: validates the bearer token against either NANCY_API_KEY
+    or a SHA-256 hashed token cached dynamically in Upstash Redis.
+
+    Returns the validated token string on success.
+    """
+    token = _extract_token(request, credentials)
+    
+    # 1. Master Key Local Bypass
+    if token == settings.nancy_api_key:
+        return token
+
+    # 2. Dynamic Redis Hashed Key validation
+    hashed = hashlib.sha256(token.encode("utf-8")).hexdigest()
+    try:
+        key_meta = await redis_client.get_json(f"nancy:api_keys:{hashed}")
+        if key_meta:
+            # Asynchronously update key metadata (fire-and-forget to keep requests fast)
+            key_meta["last_used"] = int(time.time())
+            key_meta["request_count"] = key_meta.get("request_count", 0) + 1
+            asyncio.create_task(redis_client.set_json(f"nancy:api_keys:{hashed}", key_meta))
+            return token
+    except Exception as exc:
+        logger.error("Error validating dynamic hashed token in Redis: %s", exc)
+
+    logger.warning("Invalid API key attempt from %s", request.client.host if request.client else "unknown")
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid API key.",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+
+
+async def require_ext_secret(
+    request: Request,
+    credentials: Annotated[
+        HTTPAuthorizationCredentials | None, Depends(_bearer_scheme)
+    ] = None,
+) -> str:
+    """
+    FastAPI dependency: validates the bearer token against ``NANCY_EXT_SECRET``.
+
+    Used for all ``/ext/*`` endpoints.
+    """
+    token = _extract_token(request, credentials)
+    if token != settings.nancy_ext_secret:
+        logger.warning(
+            "Invalid extension secret attempt from %s",
+            request.client.host if request.client else "unknown",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid extension secret.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return token

core/queue.py

@@ -0,0 +1,243 @@
+"""
+Nancy — Task Queue.
+
+Manages the lifecycle of tasks using ``asyncio.Queue`` for the pending
+work queue and a dict of ``TaskHandle`` objects for in-flight coordination.
+
+The queue bridges two sides:
+  - **API side** (producer): creates a task, enqueues it, waits for chunks.
+  - **Extension side** (consumer): dequeues tasks via SSE, pushes response chunks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import AsyncIterator
+
+from config import settings
+from models.task import Task, TaskHandle, TaskStatus
+
+logger = logging.getLogger("nancy.queue")
+
+
+class TaskQueue:
+    """
+    Central task queue and handle registry.
+
+    This is a singleton that coordinates between the API router
+    (which creates tasks) and the extension router (which fulfills them).
+
+    Attributes:
+        _pending: asyncio.Queue of Task objects waiting for an extension.
+        _handles: dict mapping ``task_id`` → ``TaskHandle`` for in-flight tasks.
+        _history: bounded list of recently completed task summaries.
+    """
+
+    def __init__(self, max_size: int | None = None) -> None:
+        self._max_size = max_size or settings.task_queue_max_size
+        self._pending: asyncio.Queue[Task] = asyncio.Queue(maxsize=self._max_size)
+        self._handles: dict[str, TaskHandle] = {}
+        self._history: list[dict] = []
+        self._max_history = 100
+        # Event fired whenever a new task is enqueued — used to wake the
+        # extension SSE stream.
+        self._new_task_event = asyncio.Event()
+
+    # ── API-side operations ───────────────────────────────────────────
+
+    async def submit_task(self, task: Task) -> TaskHandle:
+        """
+        Submit a new task and return its handle.
+
+        The handle's ``chunk_queue`` and ``done_event`` are used by the
+        API router to stream chunks back to the caller.
+
+        Raises:
+            asyncio.QueueFull: If the pending queue is at capacity.
+        """
+        handle = TaskHandle(task)
+        self._handles[task.task_id] = handle
+
+        try:
+            self._pending.put_nowait(task)
+        except asyncio.QueueFull:
+            # Clean up the handle
+            self._handles.pop(task.task_id, None)
+            logger.error("Task queue full — rejecting task %s", task.task_id)
+            raise
+
+        self._new_task_event.set()
+        logger.info(
+            "Task %s submitted (provider=%s, model=%s, queue_size=%d)",
+            task.task_id,
+            task.provider,
+            task.model,
+            self._pending.qsize(),
+        )
+        return handle
+
+    def get_handle(self, task_id: str) -> TaskHandle | None:
+        """Retrieve a handle by task ID, or None if not found."""
+        return self._handles.get(task_id)
+
+    async def wait_for_completion(
+        self,
+        handle: TaskHandle,
+        timeout: float | None = None,
+    ) -> None:
+        """
+        Block until the task is done or timeout expires.
+
+        This is used for *non-streaming* requests that need the full response.
+
+        Raises:
+            asyncio.TimeoutError: If the task does not complete in time.
+        """
+        timeout = timeout or settings.task_timeout_seconds
+        try:
+            await asyncio.wait_for(handle.done_event.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            handle.task.status = TaskStatus.TIMED_OUT
+            handle.task.error = f"Task timed out after {timeout}s"
+            handle.finish(error=handle.task.error)
+            raise
+
+    async def stream_chunks(
+        self,
+        handle: TaskHandle,
+        timeout: float | None = None,
+    ) -> AsyncIterator[str]:
+        """
+        Async generator that yields text chunks from the extension.
+
+        Yields chunks until a ``None`` sentinel is received (end of stream)
+        or the timeout expires.
+        """
+        timeout = timeout or settings.task_timeout_seconds
+        deadline = time.time() + timeout
+
+        while True:
+            remaining = deadline - time.time()
+            if remaining <= 0:
+                handle.task.status = TaskStatus.TIMED_OUT
+                handle.task.error = "Streaming timed out"
+                logger.warning("Task %s stream timed out", handle.task_id)
+                break
+
+            try:
+                chunk = await asyncio.wait_for(
+                    handle.chunk_queue.get(),
+                    timeout=min(remaining, 30.0),
+                )
+            except asyncio.TimeoutError:
+                # Check if there's still time left
+                if time.time() >= deadline:
+                    handle.task.status = TaskStatus.TIMED_OUT
+                    handle.task.error = "Streaming timed out"
+                    logger.warning("Task %s stream timed out", handle.task_id)
+                    break
+                continue
+
+            if chunk is None:
+                # End-of-stream sentinel
+                break
+
+            yield chunk
+
+    # ── Extension-side operations ─────────────────────────────────────
+
+    async def dequeue_task(self, timeout: float = 30.0) -> Task | None:
+        """
+        Dequeue the next pending task.
+
+        Returns ``None`` if no task is available within ``timeout`` seconds.
+        Used by the extension SSE stream.
+        """
+        try:
+            task = await asyncio.wait_for(self._pending.get(), timeout=timeout)
+            task.status = TaskStatus.ASSIGNED
+            task.assigned_at = time.time()
+            logger.info("Task %s dequeued (provider=%s)", task.task_id, task.provider)
+            return task
+        except asyncio.TimeoutError:
+            return None
+
+    def push_chunk(self, task_id: str, chunk: str) -> bool:
+        """
+        Push a response chunk for a task. Returns False if task not found.
+        """
+        handle = self._handles.get(task_id)
+        if not handle:
+            logger.warning("Chunk received for unknown task %s", task_id)
+            return False
+        if handle.task.status == TaskStatus.ASSIGNED:
+            handle.task.status = TaskStatus.STREAMING
+        handle.push_chunk(chunk)
+        return True
+
+    def complete_task(self, task_id: str, error: str | None = None) -> bool:
+        """
+        Mark a task as complete. Returns False if task not found.
+        """
+        handle = self._handles.get(task_id)
+        if not handle:
+            logger.warning("Completion signal for unknown task %s", task_id)
+            return False
+        handle.finish(error=error)
+
+        # Archive to history
+        self._history.append(handle.task.to_status_dict())
+        if len(self._history) > self._max_history:
+            self._history = self._history[-self._max_history:]
+
+        logger.info(
+            "Task %s completed (status=%s, error=%s)",
+            task_id,
+            handle.task.status.value,
+            error,
+        )
+        return True
+
+    def cleanup_task(self, task_id: str) -> None:
+        """Remove a task handle from the registry."""
+        self._handles.pop(task_id, None)
+
+    # ── Observability ─────────────────────────────────────────────────
+
+    @property
+    def pending_count(self) -> int:
+        """Number of tasks waiting in the queue."""
+        return self._pending.qsize()
+
+    @property
+    def active_count(self) -> int:
+        """Number of in-flight task handles."""
+        return len(self._handles)
+
+    @property
+    def new_task_event(self) -> asyncio.Event:
+        """Event that fires when a new task is enqueued."""
+        return self._new_task_event
+
+    def get_status(self) -> dict:
+        """Return queue status for health endpoints."""
+        return {
+            "pending": self.pending_count,
+            "active": self.active_count,
+            "max_size": self._max_size,
+            "recent_history": len(self._history),
+        }
+
+    def get_active_tasks(self) -> list[dict]:
+        """Return status dicts for all active tasks."""
+        return [h.task.to_status_dict() for h in self._handles.values()]
+
+    def get_history(self, limit: int = 20) -> list[dict]:
+        """Return recent task history."""
+        return self._history[-limit:]
+
+
+# Module-level singleton
+task_queue = TaskQueue()

core/redis_client.py

@@ -0,0 +1,295 @@
+"""
+Nancy — Upstash Redis REST API client.
+
+Uses ``httpx`` to communicate with Upstash Redis via its REST interface.
+All operations are optional — if Redis is not configured, methods are
+no-ops that return sensible defaults.
+
+This allows the HF Space to work without any external dependencies while
+supporting persistence when Upstash credentials are provided.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+
+from config import settings
+
+logger = logging.getLogger("nancy.redis")
+
+
+class RedisClient:
+    """
+    Async client for the Upstash Redis REST API.
+
+    All public methods are safe to call even when Redis is not configured —
+    they will log a debug message and return ``None`` / empty defaults.
+
+    Usage::
+
+        redis = RedisClient()
+        await redis.set("key", "value", ex=300)
+        val = await redis.get("key")
+    """
+
+    def __init__(self) -> None:
+        self._enabled = settings.redis_enabled
+        self._base_url = settings.upstash_redis_rest_url.rstrip("/")
+        self._token = settings.upstash_redis_rest_token
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def is_enabled(self) -> bool:
+        """Return True if Redis is configured and the client is initialized."""
+        return self._enabled and self._client is not None
+
+
+    async def startup(self) -> None:
+        """Initialize the HTTP client. Call during app startup."""
+        if not self._enabled:
+            logger.info("Redis not configured — using in-memory fallbacks.")
+            return
+        import base64
+        import os
+
+        # Determine authentication headers (Upstash Bearer vs Self-hosted Webdis Basic Auth)
+        redis_secret = os.getenv("NANCY_REDIS_SECRET", "")
+        if self._token:
+            headers = {"Authorization": f"Bearer {self._token}"}
+            logger.info("Configuring REST client using Upstash Bearer token.")
+        elif redis_secret:
+            auth_str = f"nancy_admin:{redis_secret}"
+            b64_auth = base64.b64encode(auth_str.encode("utf-8")).decode("utf-8")
+            headers = {"Authorization": f"Basic {b64_auth}"}
+            logger.info("Configuring REST client using Self-Hosted Webdis Basic Auth.")
+        else:
+            headers = {}
+            logger.warning("No authentication credentials found for REST client.")
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=headers,
+            timeout=httpx.Timeout(10.0, connect=5.0),
+        )
+        # Verify connectivity
+        try:
+            resp = await self._client.post("/", json=["PING"])
+            resp.raise_for_status()
+            logger.info("Redis connected: %s", resp.json())
+        except Exception as exc:
+            logger.warning("Redis PING failed (non-fatal): %s", exc)
+
+    async def shutdown(self) -> None:
+        """Close the HTTP client. Call during app shutdown."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    # ── Low-level command execution ───────────────────────────────────
+
+    async def _execute(self, *args: str) -> Any:
+        """
+        Execute a raw Redis command via the REST API.
+
+        Returns the ``result`` field from the Upstash response, or ``None``
+        on error / when Redis is disabled.
+        """
+        if not self._enabled or not self._client:
+            return None
+
+        import os
+        is_webdis = os.getenv("NANCY_REDIS_SECRET", "") and not settings.upstash_redis_rest_token
+
+        if not is_webdis:
+            # Traditional Upstash REST API call
+            try:
+                resp = await self._client.post("/", json=list(args))
+                resp.raise_for_status()
+                data = resp.json()
+                return data.get("result")
+            except httpx.HTTPStatusError as exc:
+                logger.error("Redis HTTP error: %s %s", exc.response.status_code, exc.response.text)
+                return None
+            except Exception as exc:
+                logger.error("Redis error: %s", exc)
+                return None
+
+        # Webdis REST API Translation logic
+        try:
+            if not args:
+                return None
+
+            cmd = args[0].upper()
+
+            # Special case: SET with or without EX
+            if cmd == "SET":
+                key = args[1]
+                value = args[2]
+                ex = None
+                if len(args) > 4 and args[3].upper() == "EX":
+                    ex = args[4]
+
+                # Use PUT to pass large/complex value safely in the body
+                resp = await self._client.put(f"/SET/{key}", content=value)
+                resp.raise_for_status()
+
+                if ex is not None:
+                    # Set expire separately
+                    exp_resp = await self._client.post(f"/EXPIRE/{key}/{ex}")
+                    exp_resp.raise_for_status()
+
+                return "OK"
+
+            # Special case: HSET
+            elif cmd == "HSET":
+                key = args[1]
+                field = args[2]
+                value = args[3]
+                import urllib.parse
+                safe_field = urllib.parse.quote(field, safe="")
+                resp = await self._client.put(f"/HSET/{key}/{safe_field}", content=value)
+                resp.raise_for_status()
+                return 1
+
+            # Special case: LPUSH / RPUSH
+            elif cmd in ("LPUSH", "RPUSH"):
+                key = args[1]
+                value = args[2]
+                resp = await self._client.put(f"/{cmd}/{key}", content=value)
+                resp.raise_for_status()
+                data = resp.json()
+                return data.get(cmd)
+
+            # Special case: SADD / SREM / SISMEMBER
+            elif cmd in ("SADD", "SREM", "SISMEMBER"):
+                key = args[1]
+                value = args[2]
+                resp = await self._client.put(f"/{cmd}/{key}", content=value)
+                resp.raise_for_status()
+                data = resp.json()
+                res = data.get(cmd)
+                if res is None:
+                    res = data.get(cmd.lower())
+                return res
+
+            else:
+                # Fallback for standard commands: urlencode arguments in the path
+                import urllib.parse
+                encoded_args = [urllib.parse.quote(str(arg), safe="") for arg in args[1:]]
+                if encoded_args:
+                    path = f"/{cmd}/" + "/".join(encoded_args)
+                else:
+                    path = f"/{cmd}"
+
+                # Execute via GET
+                resp = await self._client.get(path)
+                resp.raise_for_status()
+                data = resp.json()
+
+                res = data.get(cmd)
+                if res is None:
+                    res = data.get(cmd.lower())
+                return res
+
+        except httpx.HTTPStatusError as exc:
+            logger.error("Webdis Redis HTTP error: %s %s", exc.response.status_code, exc.response.text)
+            return None
+        except Exception as exc:
+            logger.error("Webdis Redis error: %s", exc)
+            return None
+
+    # ── High-level operations ─────────────────────────────────────────
+
+    async def get(self, key: str) -> str | None:
+        """Get a string value by key."""
+        return await self._execute("GET", key)
+
+    async def set(
+        self,
+        key: str,
+        value: str,
+        ex: int | None = None,
+    ) -> bool:
+        """
+        Set a string value, optionally with expiration in seconds.
+
+        Returns True on success.
+        """
+        if ex is not None:
+            result = await self._execute("SET", key, value, "EX", str(ex))
+        else:
+            result = await self._execute("SET", key, value)
+        return result == "OK"
+
+    async def delete(self, key: str) -> bool:
+        """Delete a key. Returns True if the key existed."""
+        result = await self._execute("DEL", key)
+        return result is not None and int(result) > 0
+
+    async def incr(self, key: str) -> int | None:
+        """Increment an integer key. Returns the new value."""
+        result = await self._execute("INCR", key)
+        return int(result) if result is not None else None
+
+    async def expire(self, key: str, seconds: int) -> bool:
+        """Set expiration on an existing key."""
+        result = await self._execute("EXPIRE", key, str(seconds))
+        return result is not None and int(result) == 1
+
+    async def lpush(self, key: str, value: str) -> int | None:
+        """Push a value to the head of a list."""
+        result = await self._execute("LPUSH", key, value)
+        return int(result) if result is not None else None
+
+    async def lrange(self, key: str, start: int, stop: int) -> list[str]:
+        """Return a range of elements from a list."""
+        result = await self._execute("LRANGE", key, str(start), str(stop))
+        return result if isinstance(result, list) else []
+
+    async def hset(self, key: str, field: str, value: str) -> bool:
+        """Set a hash field."""
+        result = await self._execute("HSET", key, field, value)
+        return result is not None
+
+    async def hget(self, key: str, field: str) -> str | None:
+        """Get a hash field value."""
+        return await self._execute("HGET", key, field)
+
+    async def hgetall(self, key: str) -> dict[str, str]:
+        """Get all fields and values in a hash."""
+        result = await self._execute("HGETALL", key)
+        if not result or not isinstance(result, list):
+            return {}
+        # Upstash returns [field1, val1, field2, val2, ...]
+        it = iter(result)
+        return dict(zip(it, it))
+
+    # ── JSON helpers ──────────────────��───────────────────────────────
+
+    async def set_json(
+        self,
+        key: str,
+        value: Any,
+        ex: int | None = None,
+    ) -> bool:
+        """Serialize ``value`` as JSON and store it."""
+        return await self.set(key, json.dumps(value, default=str), ex=ex)
+
+    async def get_json(self, key: str) -> Any | None:
+        """Retrieve and deserialize a JSON value."""
+        raw = await self.get(key)
+        if raw is None:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("Failed to parse JSON for key '%s'", key)
+            return None
+
+
+# Module-level singleton
+redis_client = RedisClient()

core/router.py

@@ -0,0 +1,227 @@
+"""
+Nancy — Provider Router.
+
+Responsible for selecting which provider handles a given request.
+Implements:
+  - Circuit breaker (trip after N consecutive failures, cooldown period)
+  - RPM rate limiting (sliding window per provider)
+  - Fallback chains (try next provider when current is unavailable)
+  - Model → provider name resolution
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from config import settings
+from models.provider import CircuitState, ProviderConfig, ProviderState
+
+logger = logging.getLogger("nancy.router")
+
+
+# ── Model-to-Provider mapping ────────────────────────────────────────────────
+
+# Maps model name aliases to canonical provider names.
+# The extension uses the provider name to know which chatbot tab to target.
+MODEL_TO_PROVIDER: dict[str, str] = {
+    # ChatGPT
+    "chatgpt": "chatgpt",
+    "gpt-4": "chatgpt",
+    "gpt-4o": "chatgpt",
+    "gpt-4o-mini": "chatgpt",
+    "gpt-3.5-turbo": "chatgpt",
+    # Gemini
+    "gemini": "gemini",
+    "gemini-pro": "gemini",
+    "gemini-2.0-flash": "gemini",
+    "gemini-2.5-pro": "gemini",
+    # DeepSeek
+    "deepseek": "deepseek",
+    "deepseek-chat": "deepseek",
+    "deepseek-r1": "deepseek",
+    # Kimi
+    "kimi": "kimi",
+    "moonshot": "kimi",
+    # Official Paid API / Hybrid models
+    "mistral-large": "api-mistral",
+    "nvidia-llama3": "api-nvidia-nim",
+    "deepseek-api": "api-deepseek",
+    "claude-api": "api-anthropic",
+    "z-ai-api": "api-z-ai",
+    # Browser relay: NIM Portal (free playground)
+    "nim": "nim",
+    "nim-llama3": "nim",
+    "nim-mistral": "nim",
+    # Browser relay: z.ai portal
+    "zai": "zai",
+    "z-ai": "zai",
+    # Claude (browser portal)
+    "claude": "claude",
+    "claude-3": "claude",
+}
+
+
+class ProviderRouter:
+    """
+    Selects providers for incoming requests with circuit breaking,
+    rate limiting, and fallback chain support.
+
+    Usage::
+
+        router = ProviderRouter()
+        provider = router.resolve("gpt-4o")        # → "chatgpt"
+        available = router.select_provider("chatgpt")  # checks CB + RPM
+        router.record_success("chatgpt")
+        router.record_failure("chatgpt")
+    """
+
+    def __init__(self) -> None:
+        self._states: dict[str, ProviderState] = {}
+        self._initialize_providers()
+
+    def _initialize_providers(self) -> None:
+        """Build ProviderState objects from configuration."""
+        for name, raw_config in settings.providers_config.items():
+            config = ProviderConfig(**raw_config) if isinstance(raw_config, dict) else ProviderConfig()
+            self._states[name] = ProviderState(name, config)
+            logger.info(
+                "Provider '%s' initialized (rpm=%d, tpm=%d)",
+                name,
+                config.rpm,
+                config.tpm,
+            )
+
+        # Ensure all fallback chain providers exist
+        for name in settings.fallback_chain:
+            if name not in self._states:
+                self._states[name] = ProviderState(name, ProviderConfig())
+                logger.info("Provider '%s' added from fallback chain with defaults", name)
+
+    # ── Resolution ────────────────────────────────────────────────────
+
+    def resolve(self, model: str) -> str:
+        """
+        Resolve a model name to a canonical provider name.
+
+        Falls back to ``settings.default_provider`` if the model is unknown.
+        """
+        provider = MODEL_TO_PROVIDER.get(model.lower(), model.lower())
+        # If the resolved name is a known provider, use it
+        if provider in self._states:
+            return provider
+        # Otherwise fall back to default
+        logger.debug(
+            "Unknown model '%s' → defaulting to '%s'",
+            model,
+            settings.default_provider,
+        )
+        return settings.default_provider
+
+    # ── Provider Selection with Circuit Breaker + Rate Limit ──────────
+
+    def select_provider(
+        self,
+        preferred: str,
+        exclude: set[str] | None = None,
+    ) -> str | None:
+        """
+        Select the best available provider.
+
+        1. Try the preferred provider first.
+        2. If it's unavailable (circuit open, rate limited), walk the fallback chain.
+        3. Return ``None`` if no provider is available.
+
+        Args:
+            preferred: The preferred provider name.
+            exclude: Set of provider names to skip (already tried and failed).
+        """
+        exclude = exclude or set()
+        candidates = [preferred] + [
+            p for p in settings.fallback_chain if p != preferred
+        ]
+
+        for name in candidates:
+            if name in exclude:
+                continue
+
+            state = self._states.get(name)
+            if not state:
+                continue
+
+            # Check circuit breaker
+            if not state.should_allow_request(
+                settings.cb_failure_threshold,
+                settings.cb_cooldown_seconds,
+            ):
+                logger.debug("Provider '%s' circuit is OPEN — skipping", name)
+                continue
+
+            # Check rate limit
+            if not state.check_rate_limit():
+                logger.debug("Provider '%s' rate limited — skipping", name)
+                continue
+
+            # Record the request
+            state.record_request()
+            logger.info("Selected provider: '%s'", name)
+            return name
+
+        logger.error(
+            "No available provider (preferred=%s, exclude=%s)",
+            preferred,
+            exclude,
+        )
+        return None
+
+    # ── Feedback ──────────────────────────────────────────────────────
+
+    def record_success(self, provider: str) -> None:
+        """Record a successful completion for the given provider."""
+        state = self._states.get(provider)
+        if state:
+            state.record_success()
+            logger.debug("Provider '%s' success recorded", provider)
+
+    def record_failure(self, provider: str) -> None:
+        """Record a failure for the given provider (may trip circuit)."""
+        state = self._states.get(provider)
+        if state:
+            state.record_failure(settings.cb_failure_threshold)
+            logger.warning(
+                "Provider '%s' failure recorded (consecutive=%d, circuit=%s)",
+                provider,
+                state.consecutive_failures,
+                state.circuit_state.value,
+            )
+
+    # ── Observability ─────────────────────────────────────────────────
+
+    def get_provider_states(self) -> list[dict[str, Any]]:
+        """Return status dicts for all providers."""
+        return [state.to_dict() for state in self._states.values()]
+
+    def get_available_models(self) -> list[str]:
+        """Return list of all recognized model names."""
+        return sorted(MODEL_TO_PROVIDER.keys())
+
+    def get_available_providers(self) -> list[str]:
+        """Return list of all configured provider names."""
+        return sorted(self._states.keys())
+
+    def is_provider_available(self, provider: str) -> bool:
+        """Check if a specific provider is currently available."""
+        state = self._states.get(provider)
+        if not state:
+            return False
+        return (
+            state.should_allow_request(
+                settings.cb_failure_threshold,
+                settings.cb_cooldown_seconds,
+            )
+            and state.check_rate_limit()
+        )
+
+
+# Module-level singleton
+provider_router = ProviderRouter()

core/sessions.py

@@ -0,0 +1,246 @@
+"""
+Nancy HF Space — Session Manager.
+
+Manages multi-conversation sessions so agents can:
+  - Start fresh conversations (new chat)
+  - Resume specific past conversations by navigating to their saved URLs
+  - Track conversation URLs per provider and session
+  - Persist sessions in Upstash Redis (with in-memory fallback)
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from typing import Any
+
+from core.redis_client import redis_client
+
+logger = logging.getLogger("nancy.sessions")
+
+# ── Session Data Structure ─────────────────────────────────────────────────────
+
+class SessionRecord:
+    """Represents a tracked conversation session."""
+
+    def __init__(
+        self,
+        session_id: str,
+        provider: str,
+        title: str | None = None,
+        conversation_url: str | None = None,
+        system_prompt: str | None = None,
+    ) -> None:
+        self.session_id = session_id
+        self.provider = provider
+        self.title = title or f"Session {session_id[:8]}"
+        self.conversation_url = conversation_url
+        self.system_prompt = system_prompt
+        self.created_at: float = time.time()
+        self.last_used_at: float = time.time()
+        self.message_count: int = 0
+        self.status: str = "active"  # active | archived | error
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for Redis storage and API responses."""
+        return {
+            "session_id": self.session_id,
+            "provider": self.provider,
+            "title": self.title,
+            "conversation_url": self.conversation_url,
+            "system_prompt": self.system_prompt,
+            "created_at": self.created_at,
+            "last_used_at": self.last_used_at,
+            "message_count": self.message_count,
+            "status": self.status,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SessionRecord":
+        """Deserialize from dictionary (from Redis)."""
+        session = cls(
+            session_id=data["session_id"],
+            provider=data["provider"],
+            title=data.get("title"),
+            conversation_url=data.get("conversation_url"),
+            system_prompt=data.get("system_prompt"),
+        )
+        session.created_at = data.get("created_at", time.time())
+        session.last_used_at = data.get("last_used_at", time.time())
+        session.message_count = data.get("message_count", 0)
+        session.status = data.get("status", "active")
+        return session
+
+
+# ── Session Store ──────────────────────────────────────────────────────────────
+
+class SessionStore:
+    """
+    Manages conversation sessions.
+    Uses Upstash Redis for persistence if available, in-memory dict otherwise.
+    """
+
+    REDIS_PREFIX = "nancy:session:"
+    REDIS_INDEX_KEY = "nancy:sessions:index"
+    SESSION_TTL = 60 * 60 * 24 * 30  # 30 days in seconds
+
+    def __init__(self) -> None:
+        # In-memory fallback when Redis is not configured
+        self._sessions: dict[str, SessionRecord] = {}
+
+    # ── CRUD ───────────────────────────────────────────────────────────
+
+    async def create_session(
+        self,
+        provider: str,
+        title: str | None = None,
+        system_prompt: str | None = None,
+    ) -> SessionRecord:
+        """
+        Create a new session and persist it.
+
+        Args:
+            provider: Target provider key (e.g. "chatgpt", "gemini")
+            title: Optional human-readable title for the session
+            system_prompt: Optional system prompt to prepend in new chat
+
+        Returns:
+            The newly created SessionRecord
+        """
+        session_id = str(uuid.uuid4())
+        session = SessionRecord(
+            session_id=session_id,
+            provider=provider,
+            title=title,
+            system_prompt=system_prompt,
+        )
+
+        await self._save(session)
+        logger.info("Created session '%s' for provider '%s'", session_id[:8], provider)
+        return session
+
+    async def get_session(self, session_id: str) -> SessionRecord | None:
+        """Fetch a session by ID."""
+        # Try Redis first
+        data = await redis_client.get(f"{self.REDIS_PREFIX}{session_id}")
+        if data:
+            try:
+                import json
+                return SessionRecord.from_dict(json.loads(data))
+            except Exception as e:
+                logger.warning("Failed to deserialize session '%s': %s", session_id[:8], e)
+
+        # Fall back to in-memory
+        return self._sessions.get(session_id)
+
+    async def list_sessions(self, provider: str | None = None) -> list[SessionRecord]:
+        """
+        List all known sessions, optionally filtered by provider.
+
+        Returns sessions sorted by last_used_at descending.
+        """
+        sessions: list[SessionRecord] = []
+
+        # Try Redis
+        if redis_client.is_enabled:
+            try:
+                import json
+                index = await redis_client.get(self.REDIS_INDEX_KEY)
+                if index:
+                    session_ids: list[str] = json.loads(index)
+                    for sid in session_ids:
+                        session = await self.get_session(sid)
+                        if session and session.status != "archived":
+                            sessions.append(session)
+            except Exception as e:
+                logger.warning("Redis session list failed, using in-memory: %s", e)
+
+        if not sessions:
+            sessions = [s for s in self._sessions.values() if s.status != "archived"]
+
+        if provider:
+            sessions = [s for s in sessions if s.provider == provider]
+
+        sessions.sort(key=lambda s: s.last_used_at, reverse=True)
+        return sessions
+
+    async def update_session_url(
+        self,
+        session_id: str,
+        conversation_url: str,
+        message_count_delta: int = 1,
+    ) -> None:
+        """
+        Update a session's conversation URL after a task completes.
+        Called by the extension via the server when it reports back the active tab URL.
+
+        Args:
+            session_id: The session to update
+            conversation_url: The current browser tab URL (e.g. chatgpt.com/c/abc123)
+            message_count_delta: How many messages to add to the count
+        """
+        session = await self.get_session(session_id)
+        if not session:
+            logger.warning("Cannot update URL: session '%s' not found", session_id[:8])
+            return
+
+        session.conversation_url = conversation_url
+        session.last_used_at = time.time()
+        session.message_count += message_count_delta
+
+        await self._save(session)
+        logger.info(
+            "Session '%s' URL updated → %s (total messages: %d)",
+            session_id[:8], conversation_url, session.message_count
+        )
+
+    async def delete_session(self, session_id: str) -> bool:
+        """
+        Soft-delete (archive) a session.
+
+        Returns True if the session was found and archived.
+        """
+        session = await self.get_session(session_id)
+        if not session:
+            return False
+
+        session.status = "archived"
+        await self._save(session)
+        logger.info("Session '%s' archived", session_id[:8])
+        return True
+
+    # ── Internal helpers ───────────────────────────────────────────────
+
+    async def _save(self, session: SessionRecord) -> None:
+        """Persist session to Redis and in-memory."""
+        import json
+        data = json.dumps(session.to_dict())
+
+        # Always keep in-memory
+        self._sessions[session.session_id] = session
+
+        # Persist to Redis if available
+        if redis_client.is_enabled:
+            try:
+                await redis_client.set(
+                    f"{self.REDIS_PREFIX}{session.session_id}",
+                    data,
+                    ex=self.SESSION_TTL,
+                )
+                # Update the index
+                index_data = await redis_client.get(self.REDIS_INDEX_KEY)
+                session_ids: list[str] = json.loads(index_data) if index_data else []
+                if session.session_id not in session_ids:
+                    session_ids.append(session.session_id)
+                    await redis_client.set(
+                        self.REDIS_INDEX_KEY,
+                        json.dumps(session_ids),
+                        ex=self.SESSION_TTL,
+                    )
+            except Exception as e:
+                logger.warning("Failed to persist session to Redis: %s", e)
+
+
+# Module-level singleton
+session_store = SessionStore()

core/tools.py

@@ -0,0 +1,246 @@
+"""
+Nancy HF Space — Executable Tools Core.
+
+Provides standard server-side tools that can be exposed to AI agents (like Ultron)
+and executed locally on the FastAPI backend.
+"""
+
+from __future__ import annotations
+
+import logging
+import json
+from typing import Any, Callable
+
+from core.sessions import session_store
+
+logger = logging.getLogger("nancy.tools")
+
+# ─── Built-in Tools Implementation ──────────────────────────────────────────
+
+async def web_search(query: str) -> str:
+    """
+    Search the web for the given query using DuckDuckGo Search.
+    
+    Args:
+        query: The search query string.
+        
+    Returns:
+        A text summary of top search results.
+    """
+    logger.info("Executing web search: '%s'", query)
+    try:
+        from duckduckgo_search import DDGS
+        with DDGS() as ddgs:
+            results = list(ddgs.text(query, max_results=5))
+            if not results:
+                return "No search results found."
+            
+            output = []
+            for i, r in enumerate(results, 1):
+                title = r.get("title", "No Title")
+                href = r.get("href", "#")
+                body = r.get("body", "")
+                output.append(f"[{i}] {title}\nURL: {href}\nSnippet: {body}\n")
+            return "\n".join(output)
+    except Exception as e:
+        logger.error("Web search failed for query '%s': %s", query, e)
+        return f"Error executing web search: {str(e)}"
+
+
+async def nancy_new_chat(provider: str, system_prompt: str | None = None, title: str | None = None) -> str:
+    """
+    Start a brand new conversation session with the specified provider.
+    
+    Args:
+        provider: Target chatbot provider (e.g. 'chatgpt', 'gemini', 'deepseek').
+        system_prompt: Optional initial prompt or instructions to prep in the new chat.
+        title: Optional custom session title.
+        
+    Returns:
+        JSON string indicating new session details.
+    """
+    logger.info("Creating new session for provider '%s'", provider)
+    try:
+        session = await session_store.create_session(
+            provider=provider,
+            title=title,
+            system_prompt=system_prompt
+        )
+        return json.dumps({
+            "status": "success",
+            "message": "New chat session created successfully. To use it, pass the session_id in the 'user' field in future completions.",
+            "session_id": session.session_id,
+            "provider": session.provider,
+            "title": session.title
+        })
+    except Exception as e:
+        logger.error("Failed to create new session: %s", e)
+        return json.dumps({"status": "error", "message": str(e)})
+
+
+async def nancy_resume_chat(session_id: str) -> str:
+    """
+    Retrieve details of a saved chat session to resume it.
+    
+    Args:
+        session_id: The UUID of the session.
+        
+    Returns:
+        JSON string with session details.
+    """
+    logger.info("Resuming session: '%s'", session_id)
+    try:
+        session = await session_store.get_session(session_id)
+        if not session:
+            return json.dumps({"status": "error", "message": f"Session {session_id} not found."})
+        return json.dumps({
+            "status": "success",
+            "session_id": session.session_id,
+            "provider": session.provider,
+            "title": session.title,
+            "conversation_url": session.conversation_url,
+            "system_prompt": session.system_prompt,
+            "message_count": session.message_count,
+            "status_state": session.status
+        })
+    except Exception as e:
+        logger.error("Failed to resume session '%s': %s", session_id, e)
+        return json.dumps({"status": "error", "message": str(e)})
+
+
+async def nancy_list_sessions(provider: str | None = None) -> str:
+    """
+    List all tracked conversation sessions, optionally filtered by provider.
+    
+    Args:
+        provider: Optional filter (e.g. 'chatgpt', 'gemini').
+        
+    Returns:
+        JSON string with session list.
+    """
+    logger.info("Listing sessions. Filter: %s", provider)
+    try:
+        sessions = await session_store.list_sessions(provider=provider)
+        serialized = [s.to_dict() for s in sessions]
+        return json.dumps({
+            "status": "success",
+            "sessions": serialized
+        })
+    except Exception as e:
+        logger.error("Failed to list sessions: %s", e)
+        return json.dumps({"status": "error", "message": str(e)})
+
+
+# ─── Tool Registry & Dispatcher ──────────────────────────────────────────────
+
+class ToolRegistry:
+    """Registry mapping tool names to their async handlers and schemas."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, Callable[..., Any]] = {}
+        self._schemas: list[dict[str, Any]] = []
+
+        # Register our built-in tools
+        self.register("web_search", web_search, {
+            "type": "function",
+            "function": {
+                "name": "web_search",
+                "description": "Search the web for real-time information or questions requiring search.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query text."
+                        }
+                    },
+                    "required": ["query"]
+                }
+            }
+        })
+
+        self.register("nancy_new_chat", nancy_new_chat, {
+            "type": "function",
+            "function": {
+                "name": "nancy_new_chat",
+                "description": "Start a brand new conversation session with a chatbot provider.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "provider": {
+                            "type": "string",
+                            "description": "Target provider key, e.g. 'chatgpt', 'gemini', 'deepseek'."
+                        },
+                        "system_prompt": {
+                            "type": "string",
+                            "description": "Optional instructions/rules to prepend to this conversation."
+                        },
+                        "title": {
+                            "type": "string",
+                            "description": "Optional human-readable title."
+                        }
+                    },
+                    "required": ["provider"]
+                }
+            }
+        })
+
+        self.register("nancy_resume_chat", nancy_resume_chat, {
+            "type": "function",
+            "function": {
+                "name": "nancy_resume_chat",
+                "description": "Retrieve information on an existing saved chat session by ID.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "session_id": {
+                            "type": "string",
+                            "description": "The session ID UUID."
+                        }
+                    },
+                    "required": ["session_id"]
+                }
+            }
+        })
+
+        self.register("nancy_list_sessions", nancy_list_sessions, {
+            "type": "function",
+            "function": {
+                "name": "nancy_list_sessions",
+                "description": "List all active saved conversation sessions in Nancy.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "provider": {
+                            "type": "string",
+                            "description": "Optional chatbot provider to filter by."
+                        }
+                    }
+                }
+            }
+        })
+
+    def register(self, name: str, handler: Callable[..., Any], schema: dict[str, Any]) -> None:
+        """Register a new tool."""
+        self._handlers[name] = handler
+        self._schemas.append(schema)
+
+    def get_schemas(self) -> list[dict[str, Any]]:
+        """Get the schemas of all registered tools."""
+        return self._schemas
+
+    async def execute(self, name: str, arguments: dict[str, Any]) -> str:
+        """Execute a tool by name with arguments."""
+        handler = self._handlers.get(name)
+        if not handler:
+            raise ValueError(f"Tool '{name}' is not registered.")
+        
+        try:
+            return await handler(**arguments)
+        except Exception as e:
+            logger.error("Error executing tool '%s': %s", name, e)
+            return f"Execution error: {str(e)}"
+
+
+# Module-level singleton registry
+tool_registry = ToolRegistry()

main.py

@@ -0,0 +1,102 @@
+"""
+Nancy HF Space — FastAPI Main Entry Point.
+
+Initializes the FastAPI application, registers routers (API, Extension, Health),
+manages startup/shutdown hooks (Redis, logging), and configures CORS middleware.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from config import settings
+from core.redis_client import redis_client
+from models.openai import ErrorDetail, ErrorResponse
+from routers.api import router as api_router
+from routers.extension import router as extension_router
+from routers.health import router as health_router
+from routers.sessions import router as sessions_router
+from routers.admin import router as admin_router
+
+# ── Logging Configuration ─────────────────────────────────────────────────────
+logging.basicConfig(
+    level=getattr(logging, settings.log_level.upper(), logging.INFO),
+    format="%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d - %(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+logger = logging.getLogger("nancy.main")
+
+
+# ── Lifespan Context Manager ──────────────────────────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Handles startup and shutdown hooks for Nancy."""
+    logger.info("Initializing Nancy HF Space backend...")
+
+    # Startup Upstash Redis if configured
+    await redis_client.startup()
+
+    yield
+
+    logger.info("Shutting down Nancy HF Space backend...")
+    # Shutdown Upstash Redis
+    await redis_client.shutdown()
+
+
+# ── FastAPI App Initialization ────────────────────────────────────────────────
+app = FastAPI(
+    title="Nancy",
+    description="Free Chatbot to OpenAI-Compatible API Orchestrator",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# ── CORS Middleware ───────────────────────────────────────────────────────────
+# Allow access from Chrome extension environment (chrome-extension://*)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Router Registration ───────────────────────────────────────────────────────
+app.include_router(health_router)
+app.include_router(extension_router)
+app.include_router(api_router)
+app.include_router(sessions_router)
+app.include_router(admin_router)
+
+
+# ── Global Exception Handlers ─────────────────────────────────────────────────
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    """Catch-all standard OpenAI-compatible error response for internal errors."""
+    logger.error("Unhandled error at %s: %s", request.url.path, exc, exc_info=True)
+    error_detail = ErrorDetail(
+        message=f"Nancy server internal error: {str(exc)}",
+        type="internal_server_error",
+        code="500",
+    )
+    return JSONResponse(
+        status_code=500,
+        content=ErrorResponse(error=error_detail).model_dump(),
+    )
+
+
+@app.get("/")
+async def root_index():
+    """Welcome index page for browser landing."""
+    return {
+        "name": "Nancy",
+        "description": "API Orchestrator for converting free chatbot interfaces into structured APIs.",
+        "version": "0.1.0",
+        "docs_url": "/docs",
+        "health_check": "/health",
+    }

models/__init__.py

@@ -0,0 +1 @@
+"""Nancy models package."""

models/openai.py

@@ -0,0 +1,289 @@
+"""
+Nancy — OpenAI-compatible Pydantic v2 schemas.
+
+These models exactly match the OpenAI Chat Completions API response format
+so that the official ``openai`` Python SDK works seamlessly.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _chatcmpl_id() -> str:
+    """Generate an OpenAI-style completion ID."""
+    return f"chatcmpl-{uuid.uuid4().hex[:29]}"
+
+
+def _unix_ts() -> int:
+    """Current UTC Unix timestamp."""
+    return int(time.time())
+
+
+# ── Request Models ────────────────────────────────────────────────────────────
+
+
+class ChatMessage(BaseModel):
+    """A single chat message in the OpenAI format."""
+
+    role: Literal["system", "user", "assistant", "function", "tool"] = Field(
+        ..., description="The role of the message author."
+    )
+    content: str | None = Field(
+        default=None, description="The text content of the message."
+    )
+    name: str | None = Field(
+        default=None, description="Optional name for the message author."
+    )
+    tool_call_id: str | None = Field(
+        default=None, description="Tool call that this message is responding to."
+    )
+
+
+class ChatCompletionRequest(BaseModel):
+    """
+    Incoming request body for ``POST /v1/chat/completions``.
+
+    Mirrors the subset of OpenAI fields that Nancy supports.
+    """
+
+    model: str = Field(
+        ..., description="Model/provider name, e.g. 'chatgpt', 'gemini'."
+    )
+    messages: list[ChatMessage] = Field(
+        ..., min_length=1, description="Conversation messages."
+    )
+    stream: bool = Field(
+        default=False, description="Whether to stream the response via SSE."
+    )
+    temperature: float | None = Field(
+        default=None, ge=0.0, le=2.0, description="Sampling temperature."
+    )
+    max_tokens: int | None = Field(
+        default=None, ge=1, description="Maximum tokens to generate."
+    )
+    top_p: float | None = Field(
+        default=None, ge=0.0, le=1.0, description="Nucleus sampling parameter."
+    )
+    stop: str | list[str] | None = Field(
+        default=None, description="Stop sequences."
+    )
+    user: str | None = Field(
+        default=None, description="End-user identifier for abuse tracking."
+    )
+    tools: list[dict] | None = Field(
+        default=None, description="A list of tools the model may call."
+    )
+    tool_choice: str | dict | None = Field(
+        default=None, description="Controls which (if any) tool is called."
+    )
+
+
+# ── Response Models — Non-streaming ──────────────────────────────────────────
+
+
+class UsageInfo(BaseModel):
+    """Token usage statistics."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+class ChoiceMessage(BaseModel):
+    """The assistant's response message in a non-streaming completion."""
+
+    role: Literal["assistant"] = "assistant"
+    content: str | None = ""
+    tool_calls: list[dict] | None = Field(
+        default=None, description="The tool calls generated by the model."
+    )
+
+
+class Choice(BaseModel):
+    """A single choice in a non-streaming completion response."""
+
+    index: int = 0
+    message: ChoiceMessage = Field(default_factory=ChoiceMessage)
+    finish_reason: Literal["stop", "length", "content_filter", "tool_calls"] | None = None
+
+
+class ChatCompletionResponse(BaseModel):
+    """
+    Non-streaming response for ``POST /v1/chat/completions``.
+
+    Matches ``openai.types.chat.ChatCompletion``.
+    """
+
+    id: str = Field(default_factory=_chatcmpl_id)
+    object: Literal["chat.completion"] = "chat.completion"
+    created: int = Field(default_factory=_unix_ts)
+    model: str = ""
+    choices: list[Choice] = Field(default_factory=lambda: [Choice()])
+    usage: UsageInfo = Field(default_factory=UsageInfo)
+    system_fingerprint: str | None = None
+
+    @classmethod
+    def from_content(
+        cls,
+        content: str,
+        model: str,
+        finish_reason: str = "stop",
+    ) -> ChatCompletionResponse:
+        """Build a complete response from a single content string."""
+        return cls(
+            model=model,
+            choices=[
+                Choice(
+                    index=0,
+                    message=ChoiceMessage(content=content),
+                    finish_reason=finish_reason,  # type: ignore[arg-type]
+                )
+            ],
+            usage=UsageInfo(
+                prompt_tokens=0,
+                completion_tokens=len(content.split()),
+                total_tokens=len(content.split()),
+            ),
+        )
+
+
+# ── Response Models — Streaming (SSE chunks) ─────────────────────────────────
+
+
+class DeltaContent(BaseModel):
+    """
+    Delta object inside a streaming chunk.
+
+    On the first chunk, ``role`` is set to ``"assistant"`` with no content.
+    On subsequent chunks, ``content`` carries the text fragment.
+    On the final chunk, both may be absent (empty delta).
+    """
+
+    role: Literal["assistant"] | None = None
+    content: str | None = None
+    tool_calls: list[dict] | None = Field(
+        default=None, description="The tool calls generated by the model."
+    )
+
+
+class StreamChoice(BaseModel):
+    """A single choice in a streaming chunk."""
+
+    index: int = 0
+    delta: DeltaContent = Field(default_factory=DeltaContent)
+    finish_reason: Literal["stop", "length", "content_filter", "tool_calls"] | None = None
+
+
+class ChatCompletionChunk(BaseModel):
+    """
+    A single SSE chunk for streaming ``POST /v1/chat/completions``.
+
+    Matches ``openai.types.chat.ChatCompletionChunk``.
+    """
+
+    id: str = Field(default_factory=_chatcmpl_id)
+    object: Literal["chat.completion.chunk"] = "chat.completion.chunk"
+    created: int = Field(default_factory=_unix_ts)
+    model: str = ""
+    choices: list[StreamChoice] = Field(default_factory=lambda: [StreamChoice()])
+    system_fingerprint: str | None = None
+
+    def to_sse_data(self) -> str:
+        """Serialize to the JSON string used in ``data: ...`` SSE frames."""
+        return self.model_dump_json(exclude_none=False)
+
+    # ── Convenience factories ─────────────────────────────────────────
+
+    @classmethod
+    def first_chunk(cls, completion_id: str, model: str) -> ChatCompletionChunk:
+        """Role-only opening chunk (no content)."""
+        return cls(
+            id=completion_id,
+            model=model,
+            choices=[
+                StreamChoice(
+                    delta=DeltaContent(role="assistant"),
+                    finish_reason=None,
+                )
+            ],
+        )
+
+    @classmethod
+    def content_chunk(
+        cls, completion_id: str, model: str, content: str
+    ) -> ChatCompletionChunk:
+        """A chunk carrying a text fragment."""
+        return cls(
+            id=completion_id,
+            model=model,
+            choices=[
+                StreamChoice(
+                    delta=DeltaContent(content=content),
+                    finish_reason=None,
+                )
+            ],
+        )
+
+    @classmethod
+    def final_chunk(
+        cls,
+        completion_id: str,
+        model: str,
+        finish_reason: str = "stop",
+    ) -> ChatCompletionChunk:
+        """Terminal chunk with ``finish_reason`` and empty delta."""
+        return cls(
+            id=completion_id,
+            model=model,
+            choices=[
+                StreamChoice(
+                    delta=DeltaContent(),
+                    finish_reason=finish_reason,  # type: ignore[arg-type]
+                )
+            ],
+        )
+
+
+# ── /v1/models response ──────────────────────────────────────────────────────
+
+
+class ModelInfo(BaseModel):
+    """A single model entry returned by ``GET /v1/models``."""
+
+    id: str
+    object: Literal["model"] = "model"
+    created: int = Field(default_factory=_unix_ts)
+    owned_by: str = "nancy"
+
+
+class ModelListResponse(BaseModel):
+    """Response body for ``GET /v1/models``."""
+
+    object: Literal["list"] = "list"
+    data: list[ModelInfo] = Field(default_factory=list)
+
+
+# ── Error response ────────────────────────────────────────────────────────────
+
+
+class ErrorDetail(BaseModel):
+    """OpenAI-style error detail."""
+
+    message: str
+    type: str = "invalid_request_error"
+    param: str | None = None
+    code: str | None = None
+
+
+class ErrorResponse(BaseModel):
+    """OpenAI-style error envelope."""
+
+    error: ErrorDetail

models/provider.py

@@ -0,0 +1,156 @@
+"""
+Nancy — Provider models.
+
+Tracks per-provider runtime state: rate limits, circuit breaker status,
+and routing metadata.
+"""
+
+from __future__ import annotations
+
+import time
+try:
+    from enum import StrEnum
+except ImportError:
+    import enum
+    class StrEnum(str, enum.Enum):
+        pass
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CircuitState(StrEnum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"        # healthy — requests flow through
+    OPEN = "open"            # tripped — requests are blocked
+    HALF_OPEN = "half_open"  # cooldown expired — next request is a probe
+
+
+class ProviderConfig(BaseModel):
+    """
+    Static configuration for a single provider.
+
+    Loaded from the ``PROVIDERS_CONFIG`` environment variable or defaults.
+    """
+
+    rpm: int = Field(default=10, description="Requests per minute limit.")
+    tpm: int = Field(default=40000, description="Tokens per minute limit.")
+    url_pattern: str = Field(
+        default="", description="Base URL pattern for the chatbot UI."
+    )
+
+
+class ProviderState:
+    """
+    Mutable runtime state for a single provider.
+
+    This is NOT a Pydantic model because it holds mutable counters and
+    timestamps that change on every request.
+
+    Attributes:
+        name: Provider identifier (e.g. ``"chatgpt"``).
+        config: Static provider configuration.
+        circuit_state: Current circuit breaker state.
+        consecutive_failures: Count of back-to-back failures.
+        last_failure_time: Timestamp of the most recent failure.
+        last_success_time: Timestamp of the most recent success.
+        request_timestamps: Rolling window of request timestamps for RPM.
+    """
+
+    __slots__ = (
+        "name",
+        "config",
+        "circuit_state",
+        "consecutive_failures",
+        "last_failure_time",
+        "last_success_time",
+        "request_timestamps",
+    )
+
+    def __init__(self, name: str, config: ProviderConfig) -> None:
+        self.name = name
+        self.config = config
+        self.circuit_state = CircuitState.CLOSED
+        self.consecutive_failures: int = 0
+        self.last_failure_time: float = 0.0
+        self.last_success_time: float = 0.0
+        self.request_timestamps: list[float] = []
+
+    # ── Circuit Breaker ───────────────────────────────────────────────
+
+    def record_success(self) -> None:
+        """Reset failure counter and close the circuit."""
+        self.consecutive_failures = 0
+        self.last_success_time = time.time()
+        self.circuit_state = CircuitState.CLOSED
+
+    def record_failure(self, threshold: int) -> None:
+        """Increment failure counter; trip if threshold is reached."""
+        self.consecutive_failures += 1
+        self.last_failure_time = time.time()
+        if self.consecutive_failures >= threshold:
+            self.circuit_state = CircuitState.OPEN
+
+    def should_allow_request(self, threshold: int, cooldown: float) -> bool:
+        """
+        Check whether the circuit breaker allows a request.
+
+        - CLOSED → always allow.
+        - OPEN → allow only if cooldown has elapsed (transition to HALF_OPEN).
+        - HALF_OPEN → allow (it's a probe request).
+        """
+        if self.circuit_state == CircuitState.CLOSED:
+            return True
+        if self.circuit_state == CircuitState.OPEN:
+            elapsed = time.time() - self.last_failure_time
+            if elapsed >= cooldown:
+                self.circuit_state = CircuitState.HALF_OPEN
+                return True
+            return False
+        # HALF_OPEN — allow the probe
+        return True
+
+    # ── Rate Limiting (sliding window) ────────────────────────────────
+
+    def check_rate_limit(self) -> bool:
+        """
+        Return True if the provider is within its RPM budget.
+
+        Prunes timestamps older than 60 seconds.
+        """
+        now = time.time()
+        cutoff = now - 60.0
+        self.request_timestamps = [
+            ts for ts in self.request_timestamps if ts > cutoff
+        ]
+        return len(self.request_timestamps) < self.config.rpm
+
+    def record_request(self) -> None:
+        """Record a request timestamp for RPM tracking."""
+        self.request_timestamps.append(time.time())
+
+    # ── Serialization ─────────────────────────────────────────────────
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for health / debug endpoints."""
+        now = time.time()
+        cutoff = now - 60.0
+        active_rpm = len([ts for ts in self.request_timestamps if ts > cutoff])
+        return {
+            "name": self.name,
+            "circuit_state": self.circuit_state.value,
+            "consecutive_failures": self.consecutive_failures,
+            "rpm_current": active_rpm,
+            "rpm_limit": self.config.rpm,
+            "last_failure_ago": (
+                round(now - self.last_failure_time, 1)
+                if self.last_failure_time
+                else None
+            ),
+            "last_success_ago": (
+                round(now - self.last_success_time, 1)
+                if self.last_success_time
+                else None
+            ),
+        }

models/task.py

@@ -0,0 +1,201 @@
+"""
+Nancy — Task models.
+
+A *task* is the unit of work that flows through the system:
+  1. API receives a chat completion request → creates a Task
+  2. Task enters the queue → extension picks it up via SSE
+  3. Extension sends response chunks back → routed to the waiting API caller
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+try:
+    from enum import StrEnum
+except ImportError:
+    import enum
+    class StrEnum(str, enum.Enum):
+        pass
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TaskStatus(StrEnum):
+    """Lifecycle states of a task."""
+
+    PENDING = "pending"
+    ASSIGNED = "assigned"
+    STREAMING = "streaming"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    TIMED_OUT = "timed_out"
+    CANCELLED = "cancelled"
+
+
+class Task(BaseModel):
+    """
+    Represents a single chat completion request flowing through the relay.
+
+    The ``completion_id`` is the OpenAI-format ``chatcmpl-*`` ID that will be
+    used across all SSE chunks for this task.
+    """
+
+    task_id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+    completion_id: str = Field(
+        default_factory=lambda: f"chatcmpl-{uuid.uuid4().hex[:29]}"
+    )
+    provider: str = Field(..., description="Target provider, e.g. 'chatgpt'.")
+    model: str = Field(..., description="Original model name from the request.")
+    messages: list[dict[str, Any]] = Field(
+        ..., description="Chat messages to send to the provider."
+    )
+    temperature: float | None = None
+    max_tokens: int | None = None
+    stream: bool = True
+    status: TaskStatus = TaskStatus.PENDING
+    created_at: float = Field(default_factory=time.time)
+    assigned_at: float | None = None
+    completed_at: float | None = None
+    error: str | None = None
+
+    # ── Session-aware routing fields ──────────────────────────────────
+    session_id: str | None = Field(
+        default=None,
+        description="Optional session ID for conversation tracking."
+    )
+    conversation_url: str | None = Field(
+        default=None,
+        description="URL to navigate to when resuming a session (e.g. chatgpt.com/c/<id>)."
+    )
+    action: str = Field(
+        default="continue",
+        description="'new_chat' = open fresh conversation, 'resume_chat' = navigate to URL, 'continue' = send to current tab."
+    )
+
+    # These fields are NOT serialized — they are runtime-only handles.
+    model_config = {"arbitrary_types_allowed": True}
+
+    def to_extension_payload(self) -> dict[str, Any]:
+        """
+        Serialize the task for delivery to the Chrome extension via SSE.
+
+        Includes session navigation fields so the extension knows whether to
+        open a new chat, resume a specific conversation, or continue in the current tab.
+        """
+        return {
+            "task_id": self.task_id,
+            "provider": self.provider,
+            "model": self.model,
+            "messages": self.messages,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            # Session navigation
+            "session_id": self.session_id,
+            "conversation_url": self.conversation_url,
+            "action": self.action,
+        }
+
+    def to_status_dict(self) -> dict[str, Any]:
+        """Compact status representation for health / debug endpoints."""
+        return {
+            "task_id": self.task_id,
+            "provider": self.provider,
+            "model": self.model,
+            "status": self.status.value,
+            "created_at": self.created_at,
+            "assigned_at": self.assigned_at,
+            "completed_at": self.completed_at,
+            "error": self.error,
+        }
+
+
+class TaskHandle:
+    """
+    Runtime handle for an in-flight task.
+
+    Bundles the ``Task`` data model with the asyncio primitives needed
+    to coordinate between the API caller and the extension relay.
+
+    Attributes:
+        task: The Task data model.
+        chunk_queue: Queue where the extension pushes response chunks.
+        done_event: Event set when the extension signals completion.
+    """
+
+    __slots__ = ("task", "chunk_queue", "done_event", "created_at")
+
+    def __init__(self, task: Task) -> None:
+        self.task = task
+        self.chunk_queue: asyncio.Queue[str | None] = asyncio.Queue()
+        self.done_event = asyncio.Event()
+        self.created_at = time.time()
+
+    @property
+    def task_id(self) -> str:
+        return self.task.task_id
+
+    def push_chunk(self, chunk: str) -> None:
+        """
+        Enqueue a text chunk from the extension.
+
+        A ``None`` sentinel signals end-of-stream.
+        """
+        self.chunk_queue.put_nowait(chunk)
+
+    def finish(self, error: str | None = None) -> None:
+        """
+        Mark the task as done.
+
+        Pushes a ``None`` sentinel into the chunk queue and sets the
+        done event so the API handler can stop waiting.
+        """
+        if error:
+            self.task.status = TaskStatus.FAILED
+            self.task.error = error
+        else:
+            self.task.status = TaskStatus.COMPLETED
+        self.task.completed_at = time.time()
+        self.chunk_queue.put_nowait(None)  # sentinel
+        self.done_event.set()
+
+
+class ExtensionResponseChunk(BaseModel):
+    """
+    Payload sent by the Chrome extension via ``POST /ext/response``.
+    """
+
+    task_id: str = Field(..., description="ID of the task this chunk belongs to.")
+    chunk: str = Field(default="", description="Text fragment (may be empty on final).")
+    is_done: bool = Field(
+        default=False, description="True on the final chunk."
+    )
+    error: str | None = Field(
+        default=None, description="Error message if the extension failed."
+    )
+    # Session URL reporting: extension reports back the current tab URL after task completes
+    conversation_url: str | None = Field(
+        default=None,
+        description="Current browser tab URL after task completes. Used to update session records."
+    )
+
+
+class ExtensionHeartbeat(BaseModel):
+    """
+    Payload sent by the Chrome extension via ``POST /ext/heartbeat``.
+    """
+
+    extension_id: str = Field(
+        default="default",
+        description="Unique extension instance identifier.",
+    )
+    timestamp: float = Field(
+        default_factory=time.time,
+        description="Client-side UTC Unix timestamp.",
+    )
+    active_tasks: list[str] = Field(
+        default_factory=list,
+        description="Task IDs currently being processed by this extension.",
+    )

requirements.txt

@@ -0,0 +1,18 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+pydantic==2.10.4
+pydantic-settings==2.7.1
+sse-starlette==2.2.1
+httpx==0.28.1
+python-multipart==0.0.20
+duckduckgo-search>=5.0.0
+jinja2>=3.0.0
+pydantic-ai>=0.0.18
+langgraph>=0.1.0
+upstash-redis>=1.0.0
+pyturso>=0.1.0
+asyncpg>=0.29.0
+neo4j>=5.20.0
+boto3>=1.34.0
+structlog>=24.0.0
+google-generativeai>=0.8.0

routers/__init__.py

@@ -0,0 +1 @@
+# Nancy routers package

routers/admin.py

@@ -0,0 +1,831 @@
+"""
+Nancy HF Space — Admin Dashboard.
+
+Exposes a beautiful, premium dark-mode, glassmorphic monitoring dashboard at /admin
+for visualizing system health, queues, circuit breakers, and active sessions.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+import hashlib
+from fastapi import APIRouter, Request, Body
+from fastapi.responses import HTMLResponse
+
+
+from core.queue import task_queue
+from core.router import provider_router
+from core.sessions import session_store
+from core.redis_client import redis_client
+
+router = APIRouter(prefix="/admin", tags=["Nancy Administration"])
+
+# HTML template string containing premium CSS styled with glassmorphic cards and gradients
+DASHBOARD_HTML = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nancy v2 — Control Center</title>
+    <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --bg-dark: #090a0f;
+            --panel-bg: rgba(17, 19, 31, 0.7);
+            --border-glow: rgba(124, 58, 237, 0.25);
+            --primary: #8b5cf6;
+            --primary-glow: rgba(139, 92, 246, 0.4);
+            --accent: #06b6d4;
+            --accent-glow: rgba(6, 182, 212, 0.4);
+            --success: #10b981;
+            --danger: #ef4444;
+            --warning: #f59e0b;
+            --text-main: #f3f4f6;
+            --text-muted: #9ca3af;
+        }
+
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: 'Plus Jakarta Sans', sans-serif;
+            background-color: var(--bg-dark);
+            color: var(--text-main);
+            min-height: 100vh;
+            overflow-x: hidden;
+            background-image: 
+                radial-gradient(circle at 10% 20%, rgba(139, 92, 246, 0.1) 0%, transparent 40%),
+                radial-gradient(circle at 90% 80%, rgba(6, 182, 212, 0.08) 0%, transparent 40%);
+            background-attachment: fixed;
+        }
+
+        /* Container & Navigation */
+        .container {
+            max-width: 1300px;
+            margin: 0 auto;
+            padding: 2rem;
+        }
+
+        header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 2.5rem;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.05);
+            padding-bottom: 1.5rem;
+        }
+
+        .logo-section h1 {
+            font-size: 1.8rem;
+            font-weight: 700;
+            background: linear-gradient(135deg, #a78bfa 0%, #22d3ee 100%);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            letter-spacing: -0.5px;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+
+        .logo-section h1::before {
+            content: '';
+            display: inline-block;
+            width: 12px;
+            height: 12px;
+            background: #a78bfa;
+            border-radius: 3px;
+            box-shadow: 0 0 10px #a78bfa;
+            animation: pulse-glow 2s infinite;
+        }
+
+        .logo-section p {
+            font-size: 0.85rem;
+            color: var(--text-muted);
+            margin-top: 0.2rem;
+        }
+
+        .sys-time {
+            font-size: 0.9rem;
+            color: var(--text-muted);
+            background: rgba(255, 255, 255, 0.03);
+            padding: 0.5rem 1rem;
+            border-radius: 99px;
+            border: 1px solid rgba(255, 255, 255, 0.05);
+        }
+
+        /* Stats Grid */
+        .stats-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+            gap: 1.5rem;
+            margin-bottom: 2rem;
+        }
+
+        .stat-card {
+            background: var(--panel-bg);
+            border-radius: 16px;
+            border: 1px solid rgba(255, 255, 255, 0.05);
+            padding: 1.5rem;
+            position: relative;
+            overflow: hidden;
+            transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+            backdrop-filter: blur(10px);
+        }
+
+        .stat-card::before {
+            content: '';
+            position: absolute;
+            top: 0;
+            left: 0;
+            right: 0;
+            height: 2px;
+            background: linear-gradient(90deg, transparent, var(--primary-glow), transparent);
+            opacity: 0;
+            transition: opacity 0.3s ease;
+        }
+
+        .stat-card:hover {
+            transform: translateY(-4px);
+            border-color: var(--border-glow);
+            box-shadow: 0 8px 30px rgba(0, 0, 0, 0.3);
+        }
+
+        .stat-card:hover::before {
+            opacity: 1;
+        }
+
+        .stat-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            color: var(--text-muted);
+            font-size: 0.85rem;
+            font-weight: 500;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+            margin-bottom: 1rem;
+        }
+
+        .stat-val {
+            font-size: 2.2rem;
+            font-weight: 700;
+            color: var(--text-main);
+            letter-spacing: -1px;
+            line-height: 1;
+        }
+
+        .stat-sub {
+            font-size: 0.8rem;
+            margin-top: 0.6rem;
+            display: flex;
+            align-items: center;
+            gap: 0.4rem;
+        }
+
+        /* Circuit Breakers & Health Panel */
+        .main-layout {
+            display: grid;
+            grid-template-columns: 2fr 1fr;
+            gap: 1.5rem;
+            margin-bottom: 2rem;
+        }
+
+        @media (max-width: 968px) {
+            .main-layout {
+                grid-template-columns: 1fr;
+            }
+        }
+
+        .panel {
+            background: var(--panel-bg);
+            border-radius: 20px;
+            border: 1px solid rgba(255, 255, 255, 0.05);
+            padding: 1.8rem;
+            backdrop-filter: blur(10px);
+        }
+
+        .panel-title {
+            font-size: 1.2rem;
+            font-weight: 600;
+            margin-bottom: 1.5rem;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.05);
+            padding-bottom: 0.8rem;
+        }
+
+        /* Provider Tables & Lists */
+        .provider-list {
+            display: flex;
+            flex-direction: column;
+            gap: 1rem;
+        }
+
+        .provider-row {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: 1rem 1.2rem;
+            background: rgba(255, 255, 255, 0.02);
+            border: 1px solid rgba(255, 255, 255, 0.03);
+            border-radius: 12px;
+            transition: background 0.2s ease;
+        }
+
+        .provider-row:hover {
+            background: rgba(255, 255, 255, 0.04);
+        }
+
+        .provider-info {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+        }
+
+        .provider-avatar {
+            width: 36px;
+            height: 36px;
+            border-radius: 8px;
+            background: linear-gradient(135deg, rgba(139, 92, 246, 0.2), rgba(6, 182, 212, 0.2));
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-weight: 700;
+            color: var(--primary);
+            font-size: 0.9rem;
+            text-transform: uppercase;
+        }
+
+        .provider-details h3 {
+            font-size: 0.95rem;
+            font-weight: 600;
+            margin-bottom: 0.15rem;
+            text-transform: capitalize;
+        }
+
+        .provider-details span {
+            font-size: 0.75rem;
+            color: var(--text-muted);
+        }
+
+        .status-badge {
+            padding: 0.35rem 0.75rem;
+            border-radius: 99px;
+            font-size: 0.75rem;
+            font-weight: 600;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+            display: flex;
+            align-items: center;
+            gap: 0.3rem;
+        }
+
+        .status-healthy {
+            background: rgba(16, 185, 129, 0.1);
+            color: var(--success);
+            border: 1px solid rgba(16, 185, 129, 0.2);
+        }
+
+        .status-degraded {
+            background: rgba(245, 158, 11, 0.1);
+            color: var(--warning);
+            border: 1px solid rgba(245, 158, 11, 0.2);
+        }
+
+        .status-broken {
+            background: rgba(239, 68, 68, 0.1);
+            color: var(--danger);
+            border: 1px solid rgba(239, 68, 68, 0.2);
+        }
+
+        /* Sessions list */
+        .session-item {
+            padding: 1rem;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.04);
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+
+        .session-item:last-child {
+            border-bottom: none;
+        }
+
+        .session-meta h4 {
+            font-size: 0.9rem;
+            font-weight: 600;
+            margin-bottom: 0.2rem;
+            color: var(--text-main);
+        }
+
+        .session-meta p {
+            font-size: 0.75rem;
+            color: var(--text-muted);
+            white-space: nowrap;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            max-width: 250px;
+        }
+
+        .badge {
+            background: rgba(255, 255, 255, 0.05);
+            padding: 0.25rem 0.5rem;
+            border-radius: 6px;
+            font-size: 0.7rem;
+            color: var(--text-muted);
+            border: 1px solid rgba(255, 255, 255, 0.05);
+        }
+
+        /* Animations */
+        @keyframes pulse-glow {
+            0%, 100% {
+                transform: scale(1);
+                box-shadow: 0 0 10px #a78bfa;
+            }
+            50% {
+                transform: scale(1.15);
+                box-shadow: 0 0 18px #a78bfa, 0 0 5px #22d3ee;
+            }
+        }
+
+        .pulse-dot {
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            display: inline-block;
+        }
+        .pulse-dot.active {
+            background-color: var(--success);
+            box-shadow: 0 0 8px var(--success);
+            animation: pulse-active 1.5s infinite;
+        }
+        @keyframes pulse-active {
+            0% { transform: scale(0.9); opacity: 1; }
+            50% { transform: scale(1.2); opacity: 0.7; }
+            100% { transform: scale(0.9); opacity: 1; }
+        }
+
+        .refresh-btn {
+            background: linear-gradient(135deg, var(--primary) 0%, var(--accent) 100%);
+            border: none;
+            color: white;
+            padding: 0.5rem 1.2rem;
+            border-radius: 8px;
+            font-size: 0.85rem;
+            font-weight: 600;
+            cursor: pointer;
+            transition: opacity 0.2s ease;
+        }
+
+        .refresh-btn:hover {
+            opacity: 0.9;
+        }
+
+        /* Dynamic API Key Vault UI Styles */
+        .revoke-btn {
+            background: rgba(239, 68, 68, 0.15);
+            border: 1px solid rgba(239, 68, 68, 0.3);
+            color: var(--danger);
+            padding: 0.35rem 0.8rem;
+            border-radius: 6px;
+            font-size: 0.75rem;
+            font-weight: 600;
+            cursor: pointer;
+            transition: all 0.2s ease;
+        }
+        .revoke-btn:hover {
+            background: var(--danger);
+            color: white;
+            box-shadow: 0 0 10px rgba(239, 68, 68, 0.4);
+        }
+        .generate-panel {
+            display: flex;
+            gap: 1rem;
+            margin-top: 1rem;
+            align-items: center;
+        }
+        .api-input {
+            flex: 1;
+            background: rgba(0, 0, 0, 0.3);
+            border: 1px solid rgba(255, 255, 255, 0.08);
+            border-radius: 8px;
+            padding: 0.6rem 1rem;
+            color: white;
+            font-family: inherit;
+            font-size: 0.9rem;
+            outline: none;
+            transition: border-color 0.2s;
+        }
+        .api-input:focus {
+            border-color: var(--primary);
+        }
+        .api-table {
+            width: 100%;
+            border-collapse: collapse;
+            margin-top: 1rem;
+        }
+        .api-table th {
+            text-align: left;
+            padding: 0.8rem 1rem;
+            color: var(--text-muted);
+            font-size: 0.8rem;
+            font-weight: 600;
+            text-transform: uppercase;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+        }
+        .copy-btn {
+            background: rgba(255, 255, 255, 0.08);
+            border: 1px solid rgba(255, 255, 255, 0.12);
+            color: white;
+            padding: 0.6rem 1.2rem;
+            border-radius: 8px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: all 0.2s;
+        }
+        .copy-btn:hover {
+            background: rgba(255, 255, 255, 0.15);
+        }
+
+    </style>
+</head>
+<body>
+    <div class="container">
+        <header>
+            <div class="logo-section">
+                <h1>NANCY CONTROL</h1>
+                <p>Advanced Free Chatbot Orchestrator & API Router</p>
+            </div>
+            <div class="sys-time">
+                SYS STATE: <span style="color: var(--success); font-weight:600;">OPERATIONAL</span>
+            </div>
+        </header>
+
+        <!-- Stats row -->
+        <div class="stats-grid">
+            <div class="stat-card">
+                <div class="stat-header">
+                    <span>Task Queue Depth</span>
+                    <span class="badge">SSE Queue</span>
+                </div>
+                <div class="stat-val">{queue_depth}</div>
+                <div class="stat-sub" style="color: var(--text-muted);">
+                    <span class="pulse-dot active"></span> Active tasks waiting for pickup
+                </div>
+            </div>
+
+            <div class="stat-card">
+                <div class="stat-header">
+                    <span>Active Sessions</span>
+                    <span class="badge">Redis</span>
+                </div>
+                <div class="stat-val">{session_count}</div>
+                <div class="stat-sub" style="color: var(--text-muted);">
+                    Tracked multi-conversation sessions
+                </div>
+            </div>
+
+            <div class="stat-card">
+                <div class="stat-header">
+                    <span>Extension Hub</span>
+                    <span class="badge">Relay Status</span>
+                </div>
+                <div class="stat-val" style="color: var(--success);">{ext_status}</div>
+                <div class="stat-sub" style="color: var(--text-muted);">
+                    Clients connected in real-time
+                </div>
+            </div>
+
+            <div class="stat-card">
+                <div class="stat-header">
+                    <span>Upstash Persistence</span>
+                    <span class="badge">Cache</span>
+                </div>
+                <div class="stat-val" style="color: {redis_color}; font-size: 1.8rem; margin-top: 0.3rem;">{redis_status}</div>
+                <div class="stat-sub" style="color: var(--text-muted);">
+                    State persistence engine status
+                </div>
+            </div>
+        </div>
+
+        <div class="main-layout">
+            <!-- Left panel: Health & Providers -->
+            <div class="panel">
+                <div class="panel-title">
+                    <span>Provider Status & Failover Configuration</span>
+                    <button class="refresh-btn" onclick="location.reload()">REFRESH STATE</button>
+                </div>
+                <div class="provider-list">
+                    {provider_rows}
+                </div>
+            </div>
+
+            <!-- Right panel: Active sessions list -->
+            <div class="panel">
+                <div class="panel-title">
+                    <span>Active Sessions</span>
+                    <span class="badge">{session_count} Total</span>
+                </div>
+                <div style="max-height: 400px; overflow-y: auto;">
+                    {session_rows}
+                </div>
+            </div>
+        </div>
+
+        <!-- 🔑 Dynamic API Key Vault Panel -->
+        <div class="panel" style="margin-top: 1.5rem;">
+            <div class="panel-title">
+                <span>🔑 Dynamic API Key Handoff Vault</span>
+                <span class="badge">Redis Hashed Credentials</span>
+            </div>
+            
+            <div style="margin-bottom: 1.5rem; background: rgba(139, 92, 246, 0.05); border: 1px solid rgba(139, 92, 246, 0.1); border-radius: 12px; padding: 1.2rem; display: flex; flex-direction: column; gap: 0.5rem;">
+                <h4 style="color: #a78bfa; font-size: 0.95rem; font-weight: 600;">How to connect Ultron Swarm (or external agents)</h4>
+                <p style="color: var(--text-muted); font-size: 0.85rem; line-height: 1.4;">
+                    Generate a secure API key below. Paste it along with your Nancy server URL (e.g. <code>https://ghostdriveg1-free-llm-router.hf.space</code>) into the Ultron Swarm Control Dashboard. Nancy hashes and saves all keys securely using SHA-256 in Upstash Redis.
+                </p>
+            </div>
+
+            <!-- New Key Generator -->
+            <div class="generate-panel">
+                <input type="text" id="key-desc" class="api-input" placeholder="e.g. Ultron Swarm Production Client" />
+                <button class="refresh-btn" onclick="generateKey()">GENERATE ACCESS KEY</button>
+            </div>
+
+            <!-- Plaintext Key Display (Shown once on generation) -->
+            <div id="key-result-container" style="display: none; margin-top: 1.2rem; padding: 1.2rem; background: rgba(16, 185, 129, 0.06); border: 1px solid rgba(16, 185, 129, 0.15); border-radius: 12px;">
+                <h4 style="color: var(--success); font-size: 0.9rem; font-weight: 600; margin-bottom: 0.5rem;">Access Key Generated Successfully!</h4>
+                <p style="color: var(--text-muted); font-size: 0.8rem; margin-bottom: 0.8rem;">
+                    ⚠️ Copy this key now! For security reasons, you will <strong>NOT</strong> be able to view this plaintext key again.
+                </p>
+                <div style="display: flex; gap: 0.8rem; align-items: center;">
+                    <input type="text" id="generated-key-display" class="api-input" readonly style="font-family: monospace; font-size: 0.95rem; color: var(--success); border-color: rgba(16, 185, 129, 0.25);" />
+                    <button id="copy-btn" class="copy-btn" onclick="copyToClipboard()">COPY KEY</button>
+                </div>
+            </div>
+
+            <!-- API Keys List Table -->
+            <div style="overflow-x: auto; margin-top: 1.5rem;">
+                <table class="api-table">
+                    <thead>
+                        <tr>
+                            <th>Client Description</th>
+                            <th>Key Hash (SHA-256)</th>
+                            <th>Created At</th>
+                            <th>Last Active</th>
+                            <th style="text-align: right;">Action</th>
+                        </tr>
+                    </thead>
+                    <tbody id="keys-tbody">
+                        <tr>
+                            <td colspan="5" style="text-align: center; padding: 1.5rem; color: var(--text-muted);">
+                                Loading API keys vault...
+                            </td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- Frontend AJAX Scripting -->
+    <script>
+        async function loadKeys() {
+            try {
+                const resp = await fetch("/admin/keys/list");
+                const keys = await resp.json();
+                const tbody = document.getElementById("keys-tbody");
+                if (!keys || keys.length === 0) {
+                    tbody.innerHTML = '<tr><td colspan="5" style="text-align: center; padding: 1.5rem; color: var(--text-muted);">No dynamic API keys found. Generate one above!</td></tr>';
+                    return;
+                }
+                tbody.innerHTML = keys.map(k => {
+                    const date = new Date(k.created_at * 1000).toLocaleString();
+                    const lastUsed = k.last_used ? new Date(k.last_used * 1000).toLocaleString() : "Never";
+                    return `
+                        <tr>
+                            <td style="padding: 1rem; border-bottom: 1px solid rgba(255,255,255,0.04); font-weight: 500;">${escapeHtml(k.description)}</td>
+                            <td style="padding: 1rem; border-bottom: 1px solid rgba(255,255,255,0.04); font-family: monospace; color: var(--accent);">${k.hash.substring(0, 12)}...</td>
+                            <td style="padding: 1rem; border-bottom: 1px solid rgba(255,255,255,0.04); color: var(--text-muted); font-size: 0.85rem;">${date}</td>
+                            <td style="padding: 1rem; border-bottom: 1px solid rgba(255,255,255,0.04); color: var(--text-muted); font-size: 0.85rem;">${lastUsed}</td>
+                            <td style="padding: 1rem; border-bottom: 1px solid rgba(255,255,255,0.04); text-align: right;">
+                                <button class="revoke-btn" onclick="revokeKey('${k.hash}')">REVOKE</button>
+                            </td>
+                        </tr>
+                    `;
+                }).join('');
+            } catch (e) {
+                console.error("Error loading keys:", e);
+            }
+        }
+
+        function escapeHtml(str) {
+            return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+        }
+
+        async function generateKey() {
+            const desc = document.getElementById("key-desc").value.trim() || "Swarm Client";
+            try {
+                const resp = await fetch("/admin/keys/create", {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ description: desc })
+                });
+                const data = await resp.json();
+                
+                // Show generated key container
+                const resultDiv = document.getElementById("key-result-container");
+                resultDiv.style.display = "block";
+                document.getElementById("generated-key-display").value = data.plaintext_key;
+                
+                document.getElementById("key-desc").value = "";
+                await loadKeys();
+            } catch (e) {
+                alert("Error generating key: " + e);
+            }
+        }
+
+        async function revokeKey(hash) {
+            if (!confirm("Are you sure you want to revoke this API key? Connected systems using this key will immediately lose access!")) return;
+            try {
+                await fetch(`/admin/keys/revoke/${hash}`, { method: "DELETE" });
+                await loadKeys();
+            } catch (e) {
+                alert("Error revoking key: " + e);
+            }
+        }
+
+        function copyToClipboard() {
+            const copyText = document.getElementById("generated-key-display");
+            copyText.select();
+            copyText.setSelectionRange(0, 99999);
+            navigator.clipboard.writeText(copyText.value);
+            
+            const copyBtn = document.getElementById("copy-btn");
+            copyBtn.innerText = "COPIED!";
+            copyBtn.style.background = "var(--success)";
+            setTimeout(() => {
+                copyBtn.innerText = "COPY KEY";
+                copyBtn.style.background = "rgba(255,255,255,0.08)";
+            }, 2000);
+        }
+
+        // Auto-run on startup
+        document.addEventListener("DOMContentLoaded", loadKeys);
+    </script>
+</body>
+</html>
+
+"""
+
+@router.get("/", response_class=HTMLResponse)
+async def admin_dashboard(request: Request):
+    """Renders the control center admin status page."""
+    
+    # 1. Fetch current queue size
+    try:
+        queue_depth = len(task_queue.queue)
+    except Exception:
+        queue_depth = 0
+
+    # 2. Check Extension SSE connections status
+    ext_connected = task_queue.is_extension_active()
+    ext_status = "Connected" if ext_connected else "Offline"
+
+    # 3. Check Redis Connection Status
+    redis_active = redis_client.is_enabled
+    redis_status = "ONLINE" if redis_active else "FALLBACK (IN-MEMORY)"
+    redis_color = "var(--success)" if redis_active else "var(--warning)"
+
+    # 4. Fetch Sessions list
+    try:
+        sessions = await session_store.list_sessions()
+        session_count = len(sessions)
+    except Exception:
+        sessions = []
+        session_count = 0
+
+    # 5. Build dynamic session items
+    session_rows = ""
+    if not sessions:
+        session_rows = '<div style="padding: 1.5rem; text-align: center; color: var(--text-muted); font-size: 0.85rem;">No active tracked sessions found.</div>'
+    else:
+        for sess in sessions[:8]: # Show top 8 active
+            session_rows += f"""
+            <div class="session-item">
+                <div class="session-meta">
+                    <h4>{sess.title}</h4>
+                    <p>{sess.conversation_url or 'Fresh Chat (No URL yet)'}</p>
+                </div>
+                <span class="badge" style="text-transform: capitalize;">{sess.provider}</span>
+            </div>
+            """
+
+    # 6. Fetch Providers circuit breaker states
+    # Default list of providers
+    all_providers = ["chatgpt", "gemini", "deepseek", "kimi", "claude", "nim", "zai"]
+    provider_rows = ""
+
+    for provider in all_providers:
+        # Determine status
+        is_healthy = provider_router.is_provider_healthy(provider)
+        
+        badge_class = "status-healthy" if is_healthy else "status-broken"
+        status_text = "HEALTHY" if is_healthy else "DEGRADED / DRAINED"
+        
+        # Determine adapter fallback priority indicator
+        fallback_pos = "Primary" if provider in provider_router.fallback_chain else "Bypass / API"
+        if provider in provider_router.fallback_chain:
+            idx = provider_router.fallback_chain.index(provider) + 1
+            fallback_pos = f"Fallback Chain #{idx}"
+
+        provider_rows += f"""
+        <div class="provider-row">
+            <div class="provider-info">
+                <div class="provider-avatar">{provider[:2]}</div>
+                <div class="provider-details">
+                    <h3>{provider}</h3>
+                    <span>Priority: {fallback_pos}</span>
+                </div>
+            </div>
+            <div class="status-badge {badge_class}">
+                <span class="pulse-dot active" style="background-color: currentColor;"></span>
+                {status_text}
+            </div>
+        </div>
+        """
+
+    # Render dashboard
+    rendered = DASHBOARD_HTML.format(
+        queue_depth=queue_depth,
+        session_count=session_count,
+        ext_status=ext_status,
+        redis_status=redis_status,
+        redis_color=redis_color,
+        session_rows=session_rows,
+        provider_rows=provider_rows
+    )
+    
+    return HTMLResponse(content=rendered)
+
+
+# ── Dynamic API Key AJAX Endpoints ───────────────────────────────────────────
+
+@router.post("/keys/create")
+async def create_api_key(payload: dict = Body(default={})):
+    """Generates a secure UUID API key prefixed with ny_, hashes it, and caches in Redis."""
+    description = payload.get("description", "Swarm Integration Client")
+    plaintext_uuid = uuid.uuid4().hex
+    plaintext_key = f"ny_{plaintext_uuid}"
+    hashed = hashlib.sha256(plaintext_key.encode("utf-8")).hexdigest()
+    
+    key_id = str(uuid.uuid4())
+    metadata = {
+        "id": key_id,
+        "description": description,
+        "hash": hashed,
+        "created_at": int(time.time()),
+        "last_used": None,
+        "request_count": 0
+    }
+    
+    # Save key metadata and register in active hashes set
+    await redis_client.set_json(f"nancy:api_keys:{hashed}", metadata)
+    await redis_client._execute("SADD", "nancy:active_key_hashes", hashed)
+    
+    return {
+        "key_id": key_id,
+        "plaintext_key": plaintext_key,
+        "description": description,
+        "created_at": metadata["created_at"]
+    }
+
+
+@router.get("/keys/list")
+async def list_api_keys():
+    """Lists metadata for all active dynamic API keys."""
+    try:
+        hashes = await redis_client._execute("SMEMBERS", "nancy:active_key_hashes") or []
+        keys_list = []
+        for h in hashes:
+            meta = await redis_client.get_json(f"nancy:api_keys:{h}")
+            if meta:
+                keys_list.append(meta)
+        return sorted(keys_list, key=lambda x: x.get("created_at", 0), reverse=True)
+    except Exception:
+        return []
+
+
+@router.delete("/keys/revoke/{hashed_key}")
+async def revoke_api_key(hashed_key: str):
+    """Revokes and deletes an API key using its SHA-256 hash."""
+    await redis_client.delete(f"nancy:api_keys:{hashed_key}")
+    await redis_client._execute("SREM", "nancy:active_key_hashes", hashed_key)
+    return {"success": True, "message": "API key revoked successfully."}
+

routers/api.py

@@ -0,0 +1,512 @@
+"""
+Nancy HF Space — OpenAI-Compatible API Router.
+
+Provides standard chat completion and models endpoints matching the OpenAI spec.
+This allows any OpenAI-compatible client (e.g. LiteLLM, langchain, openai SDK)
+to use Nancy as a drop-in replacement backbone.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import AsyncGenerator
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi.responses import JSONResponse
+from sse_starlette.sse import EventSourceResponse
+
+from config import settings
+from core.auth import require_api_key
+from core.queue import task_queue
+from core.router import provider_router
+from models.openai import (
+    ChatCompletionChunk,
+    ChatCompletionRequest,
+    ChatCompletionResponse,
+    ErrorDetail,
+    ErrorResponse,
+    ModelInfo,
+    ModelListResponse,
+)
+from models.task import Task, TaskStatus
+
+logger = logging.getLogger("nancy.api")
+
+def parse_tool_call_json(text: str) -> list[dict] | None:
+    import json
+    import re
+    import uuid
+    text = text.strip()
+
+    # Resilient check for CALL: tool_name(...) format
+    if "CALL:" in text:
+        match = re.search(r"CALL:\s*(\w+)\((.*?)\)", text, re.DOTALL)
+        if match:
+            func_name = match.group(1)
+            args_content = match.group(2)
+            
+            # Parse arguments in key="value" or key=value format
+            args = {}
+            arg_matches = re.findall(r"(\w+)\s*=\s*(?:\"([^\"]*)\"|'([^']*)'|([^\s,]+))", args_content)
+            for key, val1, val2, val3 in arg_matches:
+                val = val1 or val2 or val3
+                val_strip = val.strip()
+                if val_strip.lower() == "true":
+                    val = True
+                elif val_strip.lower() == "false":
+                    val = False
+                else:
+                    try:
+                        if "." in val_strip:
+                            val = float(val_strip)
+                        else:
+                            val = int(val_strip)
+                    except:
+                        pass
+                args[key] = val
+                
+            call_id = f"call_{uuid.uuid4().hex[:12]}"
+            return [{
+                "id": call_id,
+                "type": "function",
+                "function": {
+                    "name": func_name,
+                    "arguments": json.dumps(args)
+                }
+            }]
+
+    # Fallback to standard Markdown/JSON block parser
+    if text.startswith("```"):
+        match = re.search(r"```(?:json)?\s*(.*?)\s*```", text, re.DOTALL)
+        if match:
+            text = match.group(1).strip()
+            
+    if not (text.startswith("{") and "tool_calls" in text):
+        return None
+        
+    try:
+        data = json.loads(text)
+        if "tool_calls" in data and isinstance(data["tool_calls"], list):
+            validated = []
+            for tc in data["tool_calls"]:
+                if "name" in tc or ("function" in tc and "name" in tc["function"]):
+                    func_name = tc.get("name") or tc["function"].get("name")
+                    args = tc.get("arguments") or tc["function"].get("arguments", {})
+                    if isinstance(args, str):
+                        try:
+                            args = json.loads(args)
+                        except:
+                            pass
+                    
+                    call_id = tc.get("id") or f"call_{uuid.uuid4().hex[:12]}"
+                    validated.append({
+                        "id": call_id,
+                        "type": tc.get("type", "function"),
+                        "function": {
+                            "name": func_name,
+                            "arguments": json.dumps(args) if isinstance(args, dict) else str(args)
+                        }
+                    })
+            if validated:
+                return validated
+    except Exception as e:
+        logger.warning("Failed to parse potential tool call JSON: %s", e)
+    return None
+
+
+router = APIRouter(prefix="/v1", tags=["OpenAI Compatible API"])
+
+
+@router.post("/chat/completions", response_model=ChatCompletionResponse)
+async def chat_completions(
+    request: ChatCompletionRequest,
+    api_key: str = Depends(require_api_key),
+):
+    """
+    OpenAI-Compatible Chat Completions Endpoint.
+    Receives prompt, selects available provider, enqueues task for extension,
+    and returns either a JSON response or an SSE stream.
+    """
+    # 1. Resolve request model to canonical provider
+    requested_model = request.model
+    provider = provider_router.resolve(requested_model)
+
+    # Inject tool instructions into system prompt if requested
+    if request.tools:
+        # Build a clean, simplified human-readable tool definition list
+        tool_specs = []
+        for t in request.tools:
+            func = t.get("function", {})
+            name = func.get("name")
+            desc = func.get("description", "")
+            params = func.get("parameters", {}).get("properties", {})
+            param_list = ", ".join(f"{k}: {v.get('type')}" for k, v in params.items())
+            tool_specs.append(f"- {name}({param_list}): {desc}")
+        
+        specs_str = "\n".join(tool_specs)
+        system_instruction = (
+            "You are a helpful assistant with access to the following server-side tools. "
+            "If you need to call a tool, you MUST respond ONLY with a clean tool execution instruction in this exact format:\n"
+            "CALL: tool_name(arg1=\"value1\", arg2=\"value2\")\n"
+            "and absolutely nothing else. Do not add any greeting, markdown formatting (like ```json), or explanatory text before or after the CALL. "
+            "If no tool is needed or you are answering with the tool result, respond with standard conversational text.\n\n"
+            "Here are the available tools:\n"
+            f"{specs_str}"
+        )
+        messages_dump = [msg.model_dump() for msg in request.messages]
+        if messages_dump and messages_dump[0]["role"] == "system":
+            messages_dump[0]["content"] = system_instruction + "\n\n" + (messages_dump[0]["content"] or "")
+        else:
+            messages_dump.insert(0, {"role": "system", "content": system_instruction})
+    else:
+        messages_dump = [msg.model_dump() for msg in request.messages]
+
+    # 2. Select available provider with routing / failover checks
+    selected_provider = provider_router.select_provider(provider)
+    if not selected_provider:
+        error_detail = ErrorDetail(
+            message="No healthy chatbot providers available at the moment.",
+            type="service_unavailable",
+            code="503",
+        )
+        return JSONResponse(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            content=ErrorResponse(error=error_detail).model_dump(),
+        )
+
+    # 2b. Handle Hybrid Official API Routing
+    if selected_provider.startswith("api-"):
+        import httpx
+        
+        # Resolve target API URL and Authorization headers
+        api_url = ""
+        headers = {"Content-Type": "application/json"}
+        
+        if selected_provider == "api-mistral":
+            api_url = "https://api.mistral.ai/v1/chat/completions"
+            headers["Authorization"] = f"Bearer {settings.mistral_api_key}"
+        elif selected_provider == "api-nvidia-nim":
+            api_url = "https://integrate.api.nvidia.com/v1/chat/completions"
+            headers["Authorization"] = f"Bearer {settings.nvidia_nim_api_key}"
+        elif selected_provider == "api-deepseek":
+            api_url = "https://api.deepseek.com/v1/chat/completions"
+            headers["Authorization"] = f"Bearer {settings.deepseek_api_key}"
+        elif selected_provider == "api-anthropic":
+            api_url = "https://api.anthropic.com/v1/messages"
+            headers["x-api-key"] = settings.anthropic_api_key
+            headers["anthropic-version"] = "2023-06-01"
+        elif selected_provider == "api-z-ai":
+            api_url = "https://api.z.ai/v1/chat/completions"
+            headers["Authorization"] = f"Bearer {settings.z_ai_api_key}"
+            
+        if not api_url:
+            raise HTTPException(status_code=500, detail="API URL not configured for selected hybrid provider.")
+
+        # Prepare request payload matching standard OpenAI schemas
+        # Note: Anthropic uses a different schema, but we keep it simple for OpenAI compatible endpoints here
+        payload = request.model_dump(exclude_none=True)
+        # Override the model name in request to use the canonical official API model
+        if selected_provider == "api-mistral":
+            payload["model"] = "mistral-large-latest"
+        elif selected_provider == "api-nvidia-nim":
+            payload["model"] = "meta/llama3-70b-instruct"
+        elif selected_provider == "api-deepseek":
+            payload["model"] = "deepseek-chat"
+        elif selected_provider == "api-anthropic":
+            # Direct mapping from openai to anthropic messages format if needed, 
+            # but for hybrid fallbacks we assume standard OpenAI endpoints or proxy models.
+            payload["model"] = "claude-3-5-sonnet-latest"
+        elif selected_provider == "api-z-ai":
+            payload["model"] = "z-ai-latest"
+
+        if request.stream:
+            async def official_stream_generator() -> AsyncGenerator[dict, None]:
+                async with httpx.AsyncClient() as client:
+                    try:
+                        async with client.stream("POST", api_url, headers=headers, json=payload, timeout=60.0) as resp:
+                            if resp.status_code != 200:
+                                yield {"data": f"[ERROR] Official API returned status code {resp.status_code}"}
+                                yield {"data": "[DONE]"}
+                                return
+                            async for line in resp.aiter_lines():
+                                if line.strip():
+                                    yield {"data": line}
+                    except Exception as e:
+                        logger.error("Error in hybrid official API streaming: %s", e)
+                        yield {"data": f"[ERROR] {str(e)}"}
+                        yield {"data": "[DONE]"}
+            return EventSourceResponse(official_stream_generator())
+        else:
+            async with httpx.AsyncClient() as client:
+                try:
+                    resp = await client.post(api_url, headers=headers, json=payload, timeout=60.0)
+                    if resp.status_code != 200:
+                        raise HTTPException(status_code=resp.status_code, detail=f"Official API Error: {resp.text}")
+                    return JSONResponse(status_code=200, content=resp.json())
+                except Exception as e:
+                    logger.error("Error in hybrid official API: %s", e)
+                    raise HTTPException(status_code=500, detail=f"Hybrid API call failed: {str(e)}")
+
+    # 3. Create the internal Task
+    session_id = None
+    conversation_url = None
+    action = "continue"
+
+    if request.user:
+        user_str = request.user.strip()
+        if user_str.startswith("session:") or user_str.startswith("resume:"):
+            parts = user_str.split(":", 1)
+            target_sid = parts[1]
+            from core.sessions import session_store
+            session = await session_store.get_session(target_sid)
+            if session:
+                session_id = session.session_id
+                conversation_url = session.conversation_url
+                action = "resume_chat" if conversation_url else "new_chat"
+                logger.info("Resuming session: %s (url: %s)", session_id, conversation_url)
+        elif user_str.startswith("new_chat"):
+            from core.sessions import session_store
+            parts = user_str.split(":", 1)
+            prov = parts[1] if len(parts) > 1 else selected_provider
+            session = await session_store.create_session(provider=prov)
+            session_id = session.session_id
+            action = "new_chat"
+            logger.info("Created new session: %s for provider: %s", session_id, prov)
+        else:
+            # Maybe it is a raw session_id
+            from core.sessions import session_store
+            session = await session_store.get_session(user_str)
+            if session:
+                session_id = session.session_id
+                conversation_url = session.conversation_url
+                action = "resume_chat" if conversation_url else "new_chat"
+                logger.info("Resuming session via raw ID: %s", session_id)
+
+    task = Task(
+        provider=selected_provider,
+        model=requested_model,
+        messages=messages_dump,
+        temperature=request.temperature,
+        max_tokens=request.max_tokens,
+        stream=request.stream,
+        session_id=session_id,
+        conversation_url=conversation_url,
+        action=action,
+    )
+
+    # 4. Submit to queue
+    try:
+        handle = await task_queue.submit_task(task)
+    except asyncio.QueueFull:
+        error_detail = ErrorDetail(
+            message="Nancy task queue is currently full. Try again later.",
+            type="rate_limit_error",
+            code="429",
+        )
+        return JSONResponse(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            content=ErrorResponse(error=error_detail).model_dump(),
+        )
+
+    # 5. Handle Streaming Response (stream=True)
+    if request.stream:
+        async def stream_generator() -> AsyncGenerator[dict, None]:
+            completion_id = handle.task.completion_id
+            try:
+                if request.tools:
+                    buffer = []
+                    is_potential_json = False
+                    streamed_buffer = False
+
+                    # Stream response chunks from the queue
+                    async for chunk in task_queue.stream_chunks(handle):
+                        if not buffer:
+                            stripped = chunk.strip()
+                            if stripped.startswith("{") or stripped.startswith("`"):
+                                is_potential_json = True
+                        
+                        if is_potential_json and not streamed_buffer:
+                            buffer.append(chunk)
+                            if sum(len(c) for c in buffer) > 1536:
+                                yield {
+                                    "data": ChatCompletionChunk.first_chunk(
+                                        completion_id, requested_model
+                                    ).to_sse_data()
+                                }
+                                for b_chunk in buffer:
+                                    yield {
+                                        "data": ChatCompletionChunk.content_chunk(
+                                            completion_id, requested_model, b_chunk
+                                        ).to_sse_data()
+                                    }
+                                streamed_buffer = True
+                        else:
+                            if not streamed_buffer and not is_potential_json:
+                                yield {
+                                    "data": ChatCompletionChunk.first_chunk(
+                                        completion_id, requested_model
+                                    ).to_sse_data()
+                                }
+                                is_potential_json = True
+                            yield {
+                                "data": ChatCompletionChunk.content_chunk(
+                                    completion_id, requested_model, chunk
+                                ).to_sse_data()
+                            }
+
+                    # Flush or parse buffer
+                    if is_potential_json and not streamed_buffer:
+                        full_text = "".join(buffer)
+                        tool_calls = parse_tool_call_json(full_text)
+                        if tool_calls:
+                            from models.openai import StreamChoice, DeltaContent
+                            yield {
+                                "data": ChatCompletionChunk(
+                                    id=completion_id,
+                                    model=requested_model,
+                                    choices=[
+                                        StreamChoice(
+                                            index=0,
+                                            delta=DeltaContent(
+                                                role="assistant",
+                                                tool_calls=tool_calls
+                                            ),
+                                            finish_reason="tool_calls"
+                                        )
+                                    ]
+                                ).to_sse_data()
+                            }
+                        else:
+                            yield {
+                                "data": ChatCompletionChunk.first_chunk(
+                                    completion_id, requested_model
+                                ).to_sse_data()
+                            }
+                            for b_chunk in buffer:
+                                yield {
+                                    "data": ChatCompletionChunk.content_chunk(
+                                        completion_id, requested_model, b_chunk
+                                    ).to_sse_data()
+                                }
+                else:
+                    yield {
+                        "data": ChatCompletionChunk.first_chunk(
+                            completion_id, requested_model
+                        ).to_sse_data()
+                    }
+                    async for chunk in task_queue.stream_chunks(handle):
+                        yield {
+                            "data": ChatCompletionChunk.content_chunk(
+                                completion_id, requested_model, chunk
+                            ).to_sse_data()
+                        }
+
+                # Final chunk: finish reason
+                yield {
+                    "data": ChatCompletionChunk.final_chunk(
+                        completion_id, requested_model, "stop"
+                    ).to_sse_data()
+                }
+
+                # Raw [DONE] terminator
+                yield {"data": "[DONE]"}
+
+            except Exception as exc:
+                logger.error("Error streaming chunks for task %s: %s", handle.task_id, exc)
+                error_chunk = ChatCompletionChunk.final_chunk(
+                    completion_id, requested_model, "length"
+                )
+                yield {"data": error_chunk.to_sse_data()}
+                yield {"data": "[DONE]"}
+            finally:
+                # Release resources
+                task_queue.cleanup_task(handle.task_id)
+
+        return EventSourceResponse(stream_generator())
+
+    # 6. Handle Non-streaming Blocking Response (stream=False)
+    else:
+        try:
+            # Drain the queue to aggregate response chunks
+            chunks = []
+            async for chunk in task_queue.stream_chunks(handle):
+                chunks.append(chunk)
+
+            # Check if task failed or timed out
+            if handle.task.status == TaskStatus.FAILED:
+                raise HTTPException(
+                    status_code=status.HTTP_502_BAD_GATEWAY,
+                    detail=f"Chatbot provider failed: {handle.task.error}",
+                )
+            elif handle.task.status == TaskStatus.TIMED_OUT:
+                raise HTTPException(
+                    status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+                    detail="Chatbot provider timed out responding.",
+                )
+
+            full_content = "".join(chunks)
+            if request.tools:
+                tool_calls = parse_tool_call_json(full_content)
+                if tool_calls:
+                    from models.openai import Choice, ChoiceMessage
+                    response = ChatCompletionResponse(
+                        id=handle.task.completion_id,
+                        model=requested_model,
+                        choices=[
+                            Choice(
+                                index=0,
+                                message=ChoiceMessage(
+                                    role="assistant",
+                                    content=None,
+                                    tool_calls=tool_calls
+                                ),
+                                finish_reason="tool_calls"
+                            )
+                        ]
+                    )
+                    return response
+
+            response = ChatCompletionResponse.from_content(
+                content=full_content,
+                model=requested_model,
+            )
+            response.id = handle.task.completion_id
+            return response
+
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.error("Error completing non-streaming task %s: %s", handle.task_id, exc)
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Nancy internal server error: {exc}",
+            )
+        finally:
+            # Release resources
+            task_queue.cleanup_task(handle.task_id)
+
+
+@router.get("/models", response_model=ModelListResponse)
+async def list_models(api_key: str = Depends(require_api_key)):
+    """
+    List Available OpenAI Models.
+    Maps to available providers configured in Nancy.
+    """
+    models = provider_router.get_available_models()
+    model_infos = [ModelInfo(id=model) for model in models]
+    return ModelListResponse(data=model_infos)
+
+
+@router.get("/models/{model}", response_model=ModelInfo)
+async def get_model(model: str, api_key: str = Depends(require_api_key)):
+    """
+    Retrieve specific model details.
+    """
+    models = provider_router.get_available_models()
+    if model.lower() not in models:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Model '{model}' not found in Nancy configuration.",
+        )
+    return ModelInfo(id=model.lower())

routers/extension.py

@@ -0,0 +1,150 @@
+"""
+Nancy HF Space — Extension Relay Router.
+
+Exposes endpoints for the Chrome extension:
+  - GET /ext/tasks/stream (SSE) — Extension receives new task assignments
+  - POST /ext/heartbeat — Extension reports health and active tasks
+  - POST /ext/response — Extension streams chunks and signals completion / error
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from typing import AsyncGenerator
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from sse_starlette.sse import EventSourceResponse
+
+from config import settings
+from core.auth import require_ext_secret
+from core.queue import task_queue
+from core.router import provider_router
+from core.sessions import session_store
+from models.task import ExtensionHeartbeat, ExtensionResponseChunk
+
+logger = logging.getLogger("nancy.extension")
+
+router = APIRouter(prefix="/ext", tags=["Extension Relay"])
+
+# Global dictionary to track connected extension instances: extension_id -> last_seen_timestamp
+active_extensions: dict[str, float] = {}
+
+
+@router.get("/tasks/stream")
+async def tasks_stream(
+    request: Request,
+    secret: str = Depends(require_ext_secret),
+):
+    """
+    Server-Sent Events (SSE) stream for Chrome Extensions.
+    Delivers task assignments to connected extensions.
+    """
+    extension_id = request.query_params.get("extension_id", "default")
+    active_extensions[extension_id] = time.time()
+    logger.info("Extension client '%s' connected to task stream", extension_id)
+
+    async def event_generator() -> AsyncGenerator[dict, None]:
+        try:
+            while True:
+                # Disconnect check
+                if await request.is_disconnected():
+                    logger.info("Extension client '%s' disconnected from stream", extension_id)
+                    break
+
+                # Update heartbeat timestamp
+                active_extensions[extension_id] = time.time()
+
+                # Dequeue a task. We use a 15-second timeout so we can yield a ping if idle.
+                task = await task_queue.dequeue_task(timeout=15.0)
+                if task:
+                    logger.info("Relaying task %s to extension '%s'", task.task_id, extension_id)
+                    yield {
+                        "event": "task",
+                        "data": json.dumps(task.to_extension_payload()),
+                        "id": task.task_id,
+                    }
+                else:
+                    # Keep-alive SSE ping
+                    yield {
+                        "event": "ping",
+                        "data": "keep-alive",
+                    }
+        except asyncio.CancelledError:
+            logger.info("Extension client '%s' stream cancelled", extension_id)
+        finally:
+            active_extensions.pop(extension_id, None)
+
+    return EventSourceResponse(event_generator())
+
+
+@router.post("/heartbeat")
+async def heartbeat(
+    payload: ExtensionHeartbeat,
+    secret: str = Depends(require_ext_secret),
+):
+    """
+    Extension health check. Pinned every 25s by active extension instances.
+    """
+    active_extensions[payload.extension_id] = time.time()
+    logger.debug(
+        "Extension '%s' heartbeat received (active_tasks=%d)",
+        payload.extension_id,
+        len(payload.active_tasks),
+    )
+    return {"status": "ok", "timestamp": time.time()}
+
+
+@router.post("/response")
+async def receive_response(
+    payload: ExtensionResponseChunk,
+    secret: str = Depends(require_ext_secret),
+):
+    """
+    Receive streaming response chunks and completion/error notifications from Chrome Extension.
+    """
+    task_id = payload.task_id
+    handle = task_queue.get_handle(task_id)
+
+    if not handle:
+        logger.warning("Received chunk/completion for unknown task %s", task_id)
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Task {task_id} not found or expired.",
+        )
+
+    # 1. Handle error reported by the extension
+    if payload.error:
+        logger.error("Extension reported failure for task %s: %s", task_id, payload.error)
+        task_queue.complete_task(task_id, error=payload.error)
+        provider_router.record_failure(handle.task.provider)
+        return {"status": "error_registered"}
+
+    # 2. Push text chunk if present
+    if payload.chunk:
+        task_queue.push_chunk(task_id, payload.chunk)
+
+    # 3. Handle final chunk/completion signal
+    if payload.is_done:
+        logger.info("Extension completed task %s successfully", task_id)
+        task_queue.complete_task(task_id, error=None)
+        provider_router.record_success(handle.task.provider)
+
+        # 4. Auto-update session URL if extension reported back the conversation URL
+        if payload.conversation_url and handle.task.session_id:
+            try:
+                await session_store.update_session_url(
+                    session_id=handle.task.session_id,
+                    conversation_url=payload.conversation_url,
+                    message_count_delta=1,
+                )
+                logger.info(
+                    "Session '%s' URL updated to '%s'",
+                    handle.task.session_id[:8],
+                    payload.conversation_url,
+                )
+            except Exception as e:
+                logger.warning("Failed to update session URL: %s", e)
+
+    return {"status": "accepted"}

routers/health.py

@@ -0,0 +1,62 @@
+"""
+Nancy HF Space — Health & Status Router.
+
+Provides health checks and detailed status monitoring endpoints for system observability.
+"""
+
+from __future__ import annotations
+
+import time
+from fastapi import APIRouter, Depends
+
+from core.auth import require_api_key
+from core.queue import task_queue
+from core.router import provider_router
+
+router = APIRouter(tags=["Health & Monitoring"])
+
+
+@router.get("/health")
+async def health_check():
+    """
+    Simple Liveness/Readiness Probe.
+    Used by keep-alive cron pings to prevent HF Space sleeping.
+    """
+    return {
+        "status": "healthy",
+        "timestamp": time.time(),
+    }
+
+
+@router.get("/status")
+async def detailed_status(api_key: str = Depends(require_api_key)):
+    """
+    Detailed System Status.
+    Requires Nancy API key authentication. Returns task queue size,
+    provider circuit breaker states, and connected extension sessions.
+    """
+    # Import active_extensions dynamically to avoid circular import
+    active_exts = {}
+    try:
+        from routers.extension import active_extensions
+        now = time.time()
+        for ext_id, last_seen in list(active_extensions.items()):
+            active_exts[ext_id] = {
+                "last_seen_ago": round(now - last_seen, 1),
+                "online": (now - last_seen) < 30.0,  # 30 seconds threshold
+            }
+    except Exception:
+        pass
+
+    return {
+        "status": "running",
+        "timestamp": time.time(),
+        "queue": task_queue.get_status(),
+        "router": {
+            "providers": provider_router.get_provider_states(),
+            "available_models": provider_router.get_available_models(),
+        },
+        "active_tasks": task_queue.get_active_tasks(),
+        "recent_history": task_queue.get_history(20),
+        "connected_extensions": active_exts,
+    }

routers/sessions.py

@@ -0,0 +1,164 @@
+"""
+Nancy HF Space — Session REST API Router.
+
+Provides session management endpoints so agents can:
+  - Create new tracked conversation sessions
+  - List all sessions (optionally filtered by provider)
+  - Get a specific session's state
+  - Delete / archive sessions
+  - Update a session's conversation URL (called internally after task completion)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from core.auth import require_api_key
+from core.sessions import session_store
+
+logger = logging.getLogger("nancy.sessions_router")
+
+router = APIRouter(prefix="/v1/sessions", tags=["Session Management"])
+
+
+# ── Request / Response Schemas ────────────────────────────────────────────────
+
+class CreateSessionRequest(BaseModel):
+    """Request body for creating a new conversation session."""
+    provider: str = Field(
+        ...,
+        description="Target provider key (e.g. 'chatgpt', 'gemini', 'nim'). "
+                    "Determines which browser tab / official API to use."
+    )
+    title: str | None = Field(
+        default=None,
+        description="Optional human-readable title for this session."
+    )
+    system_prompt: str | None = Field(
+        default=None,
+        description="Optional system prompt to prepend when starting a new chat."
+    )
+
+
+class UpdateSessionURLRequest(BaseModel):
+    """Internal: update a session's conversation URL after a chat."""
+    conversation_url: str = Field(
+        ...,
+        description="The browser tab URL for the active conversation (e.g. chatgpt.com/c/abc123)."
+    )
+    message_count_delta: int = Field(
+        default=1,
+        description="How many messages to add to the running total."
+    )
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.post("", status_code=status.HTTP_201_CREATED)
+async def create_session(
+    body: CreateSessionRequest,
+    api_key: str = Depends(require_api_key),
+) -> dict[str, Any]:
+    """
+    Create a new conversation session.
+
+    Returns the session_id and metadata. Use this session_id in subsequent
+    chat completion requests (as the `user` field or via custom header) to
+    automatically resume the same conversation tab.
+    """
+    session = await session_store.create_session(
+        provider=body.provider,
+        title=body.title,
+        system_prompt=body.system_prompt,
+    )
+    logger.info("Created session '%s' for provider '%s'", session.session_id[:8], body.provider)
+    return {
+        "session_id": session.session_id,
+        "message": f"Session created for provider '{body.provider}'.",
+        "session": session.to_dict(),
+    }
+
+
+@router.get("")
+async def list_sessions(
+    provider: str | None = Query(default=None, description="Filter by provider key."),
+    api_key: str = Depends(require_api_key),
+) -> dict[str, Any]:
+    """
+    List all tracked sessions, optionally filtered by provider.
+    Sessions are sorted by last_used_at (most recent first).
+    """
+    sessions = await session_store.list_sessions(provider=provider)
+    return {
+        "total": len(sessions),
+        "sessions": [s.to_dict() for s in sessions],
+    }
+
+
+@router.get("/{session_id}")
+async def get_session(
+    session_id: str,
+    api_key: str = Depends(require_api_key),
+) -> dict[str, Any]:
+    """
+    Retrieve a specific session by its ID.
+    """
+    session = await session_store.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+    return session.to_dict()
+
+
+@router.patch("/{session_id}/url")
+async def update_session_url(
+    session_id: str,
+    body: UpdateSessionURLRequest,
+    api_key: str = Depends(require_api_key),
+) -> dict[str, Any]:
+    """
+    Update a session's conversation URL.
+
+    Called after a task completes to record the browser URL for the conversation,
+    enabling future resume operations.
+    """
+    session = await session_store.get_session(session_id)
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+    await session_store.update_session_url(
+        session_id=session_id,
+        conversation_url=body.conversation_url,
+        message_count_delta=body.message_count_delta,
+    )
+    updated = await session_store.get_session(session_id)
+    return {
+        "message": "Session URL updated.",
+        "session": updated.to_dict() if updated else {},
+    }
+
+
+@router.delete("/{session_id}", status_code=status.HTTP_200_OK)
+async def delete_session(
+    session_id: str,
+    api_key: str = Depends(require_api_key),
+) -> dict[str, Any]:
+    """
+    Archive / soft-delete a session.
+    The session record is kept but marked as archived and excluded from list results.
+    """
+    deleted = await session_store.delete_session(session_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Session '{session_id}' not found.",
+        )
+    return {"message": f"Session '{session_id[:8]}...' archived successfully."}