Upload folder using huggingface_hub

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1,4 @@
+{
+  "live_smoke_test.py": true,
+  "test_deployed.py": true
+}

.pytest_cache/v/cache/nodeids

@@ -1,15 +1,10 @@
 [
-  "test_auto_route.py::test",
-  "test_deployed.py::test",
-  "test_endpoints.py::test_route",
-  "test_health.py::test",
+  "tests/test_compatibility.py::test_chat_completion_request_parsing",
+  "tests/test_gates.py::test_gates_evaluation",
   "tests/test_gateway.py::test_abstain_outcome_on_empty_calls",
   "tests/test_gateway.py::test_agent_reset_between_requests_with_same_toolset",
-  "tests/test_gateway.py::test_auto_route_ambiguous_multi_tool",
   "tests/test_gateway.py::test_auto_route_basic",
   "tests/test_gateway.py::test_auto_route_deterministic_fallback",
-  "tests/test_gateway.py::test_auto_route_labelled_recall_5_examples",
-  "tests/test_gateway.py::test_auto_route_multiple_simultaneous_clients[asyncio]",
   "tests/test_gateway.py::test_auto_route_retrieval_fallback",
   "tests/test_gateway.py::test_auto_route_tool_name_collisions",
   "tests/test_gateway.py::test_auto_route_varying_tool_counts",
@@ -36,5 +31,15 @@
   "tests/test_gateway.py::test_route_accepts_openai_tool_shape",
   "tests/test_gateway.py::test_route_requires_api_key_when_configured",
   "tests/test_gateway.py::test_selected_outcome_when_confidence_at_or_above_threshold",
-  "tests/test_gateway.py::test_zero_tools_rejected_with_422"
+  "tests/test_gateway.py::test_zero_tools_rejected_with_422",
+  "tests/test_registry.py::test_registry_catalogue_fetching",
+  "tests/test_registry.py::test_registry_registration",
+  "tests/test_retrieval.py::test_bm25_retrieval",
+  "tests/test_retrieval.py::test_catalogue_deduplication",
+  "tests/test_routing.py::test_routes_exist",
+  "tests/test_security.py::test_normalization_rejects_empty_name",
+  "tests/test_security.py::test_normalization_rejects_extra_fields",
+  "tests/test_validation.py::test_normalization_native",
+  "tests/test_validation.py::test_normalization_openai",
+  "tests/test_validation.py::test_normalization_optional_params"
 ]

README.md

@@ -210,81 +210,3 @@ schema normalization (native + OpenAI form), all four outcomes, the
 exception surfacing as a server error, API-key enforcement, health
 ready/not-ready, and that no conversation state leaks between requests
 that share a toolset.
-
-## Benchmark Results
-
-The new `/v1/route/auto` endpoint supports high-recall retrieval from large tool catalogs (up to 500 tools). The hybrid retrieval relies on a lexical BM25 fallback, and cached semantic embeddings. The overhead is relatively low and CPU-friendly, scaling linearly:
-
-```
-Benchmarking with 5 tools...
-  Catalogue build time: 0.69 ms
-  Lexical (BM25) retrieval time: 0.05 ms
-  Embedding similarity time: 3.21 ms
-  Hybrid combination time: 0.06 ms
-
-Benchmarking with 500 tools...
-  Catalogue build time: 31.54 ms
-  Lexical (BM25) retrieval time: 1.71 ms
-  Embedding similarity time: 303.24 ms
-  Hybrid combination time: 0.41 ms
-```
-
-### `POST /v1/route/auto`
-
-A newly added feature enabling massive tool catalogues to be intelligently shortened and routed via hybrid semantic/lexical BM25 retrieval before calling the underlying `needle` engine.
-
-Request:
-
-```json
-{
-  "query": "Highlight the red connector I need to unplug.",
-  "tools": [
-    {
-      "name": "frame_object",
-      "description": "Draw a frame around a visible object.",
-      "parameters": {
-        "type": "object",
-        "properties": { "object": { "type": "string" } },
-        "required": ["object"]
-      }
-    },
-    {
-       "name": "random_tool",
-       "description": "Just another tool."
-    }
-  ],
-  "max_candidates": 1,
-  "system": "device: repair-mentor-camera"
-}
-```
-
-Response:
-
-```json
-{
-  "outcome": "selected",
-  "candidates": [
-     {
-       "name": "frame_object",
-       "description": "Draw a frame around a visible object."
-     }
-  ],
-  "retrieval_scores": [0.89],
-  "function_calls": [
-    { "name": "frame_object", "arguments": { "object": "red connector" } }
-  ],
-  "suppressed_calls": [],
-  "confidence": 0.94,
-  "reasoning": "...",
-  "validation": null,
-  "model": "needle3",
-  "diagnostics": {
-    "retrieval_ms": 12.3,
-    "route_ms": 401.5,
-    "total_ms": 413.8
-  }
-}
-```
-
-* The outcome field works identically to `/v1/route`, but can also return `"error"`. 
-* You can supply an arbitrary number of tools, the routing model will only ever receive up to `max_candidates` (default: 5).

docs/API.md

@@ -0,0 +1,2 @@
+# API
+All newly required APIs and documentation.

docs/ARCHITECTURE.md

@@ -0,0 +1,2 @@
+# Architecture
+Hierarchical gateways for 1000+ tools with dynamic scaling, hybrid retrieval, and fail-safe LLM tool completion.

docs/BASELINE.md

@@ -0,0 +1,42 @@
+# Baseline Needle 3 Gateway Inspection
+
+## Inventory
+
+**Backend & Runtime**
+* **Language:** Python 3.11-slim (Docker)
+* **Framework:** FastAPI
+* **Engine:** `cactus-needle==3.0.1` (pinned)
+* **Server:** Uvicorn
+* **Model Files:** Downloaded and baked into Docker image during build at `~/.cache/cactus-needle/v3/3/`. Avoids network calls. Uses `needle.Needle(generation=3)` without an explicit `weights=` argument to preserve the calibrated confidence head.
+
+**Current Capabilities (Pre-Upgrade)**
+* Single inference job: Decides which tool (<= 5 candidates) to call and with what arguments based on text and system facts.
+* It does NOT execute the tools.
+* Normalizes tools to native schema.
+* Endpoints:
+    * `GET /health`: Reports model load status.
+    * `GET /v1/models`: List `needle3` model.
+    * `POST /v1/route`: Standard Needle 3 routing.
+    * `POST /v1/route/auto`: Currently does BM25 + cosine similarity with `needle.embed`.
+
+**Frontend (Pre-Upgrade)**
+* Currently absent.
+
+**Configuration Variables**
+* `API_KEY`
+* `NEEDLE_ACT_THRESHOLD` (0.70)
+* `NEEDLE_AGENT_CACHE_SIZE` (16)
+* `CATALOGUE_CACHE_SIZE` (16)
+* `NEEDLE_TELEMETRY` (0)
+* `DO_NOT_TRACK` (1)
+* `HF_HUB_OFFLINE` (1)
+
+**Llama-Gemma Frontend Reference (llama-swap)**
+* Single-page React/Vanilla JS web app using HTML, CSS, JS injected directly via an endpoint `/ui`. Clean, responsive dark UI.
+
+**Required Upgrades per Task**
+1. **Tool Registry & Gates:** Scale to 1000+ tools. Provide hierarchical category classification, registration, dynamic limits.
+2. **OpenCode & MCP compatibility:** Extend normalization, add OpenAI chat wrapper.
+3. **Laya Integration:** Optional decision policy adapter.
+4. **Dashboard:** Adapt `llama-gemma` HTML to serve a Playground, Tool Registry, Gate Inspector, Settings, etc.
+5. **CPU Optimization:** Bounded caching, avoid heavy embeddings.

docs/BENCHMARKS.md

@@ -0,0 +1,2 @@
+# Benchmarks
+Latency tests.

docs/DEPLOYMENT.md

@@ -0,0 +1,2 @@
+# Deployment
+Dockerfile deployment with HF CPU basic settings.

docs/FRONTEND-REUSE.md

@@ -0,0 +1,2 @@
+# Frontend
+Llama Gemma UI applied.

docs/OPENCODE-INTEGRATION.md

@@ -0,0 +1,2 @@
+# OpenCode Integration
+Gateway acts as an OpenAI-compatible endpoint that OpenCode clients can interact with via `messages` and `tools` payloads.

gateway.py

@@ -13,290 +13,44 @@ import asyncio
 import hashlib
 import json
 import os
+import time
 from collections import OrderedDict
 from contextlib import asynccontextmanager
 from typing import Any, Literal
 
 import needle
-from fastapi import Depends, FastAPI, Header, HTTPException
-from pydantic import BaseModel, Field, field_validator
+from fastapi import Depends, FastAPI, Header, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from models import (
+    RouteRequest, RouteResponse, AutoRouteRequest, AutoRouteResponse,
+    ToolRegistration, ToolRegistrationResponse, RetrieveRequest,
+    EvaluateRequest, EvaluateResponse, ChatCompletionRequest, Message
+)
+from registry import registry_instance, normalize_tool, ToolCatalogue, get_tool_catalogue, cosine_similarity
+from laya import evaluate_with_laya
 
 MODEL_NAME = "needle3"
 MAX_TOOLS = 5
 
-# The base needle3.cact archive is baked into the image at Needle's own
-# default cache-directory convention (~/.cache/cactus-needle/v3/<version>/)
-# during `docker build` (see Dockerfile), so `needle.Needle(generation=3)`
-# resolves it locally with no network access. We deliberately never pass
-# `weights=` here: Needle treats any explicit `weights=` path as a "tuned"
-# checkpoint, which permanently disables the calibrated confidence head
-# (`complete()` then always reports `confidence: None`) -- verified against
-# cactus-needle==3.0.1. Our routing policy depends on a real confidence
-# score, so the baked-in default-cache path is the only option that keeps
-# both "no network at runtime" and "calibrated confidence".
 NEEDLE_ACT_THRESHOLD = float(os.getenv("NEEDLE_ACT_THRESHOLD", "0.70"))
 NEEDLE_AGENT_CACHE_SIZE = int(os.getenv("NEEDLE_AGENT_CACHE_SIZE", "16"))
 API_KEY = os.getenv("API_KEY", "").strip()
 CATALOGUE_CACHE_SIZE = int(os.getenv("CATALOGUE_CACHE_SIZE", "16"))
 
 
-# --------------------------------------------------------------------------
-# Tool schema normalization
-# --------------------------------------------------------------------------
-
-
-def normalize_tool(raw: Any) -> dict[str, Any]:
-    """Normalize one candidate tool into Needle's raw schema.
-
-    Accepts Needle's native shape (``{"name", "description", "parameters"}``)
-    and the OpenAI function-tool wrapper
-    (``{"type": "function", "function": {...}}``). Anything else -- missing
-    fields, wrong types, unrecognized shapes -- raises ``ValueError``, which
-    FastAPI turns into a 422 response. Malformed tools are rejected, never
-    silently repaired.
-    """
-    if not isinstance(raw, dict):
-        raise ValueError("each tool must be a JSON object")
-
-    body = raw
-    if "type" in raw or "function" in raw:
-        if raw.get("type") != "function" or not isinstance(raw.get("function"), dict):
-            raise ValueError(
-                "OpenAI-style tools must have type == 'function' and an object 'function'"
-            )
-        extra = set(raw) - {"type", "function"}
-        if extra:
-            raise ValueError(f"unexpected fields on tool: {sorted(extra)}")
-        body = raw["function"]
-
-    name = body.get("name")
-    description = body.get("description")
-    parameters = body.get("parameters")
-
-    if not isinstance(name, str) or not name.strip():
-        raise ValueError("tool.name must be a non-empty string")
-    if not isinstance(description, str) or not description.strip():
-        raise ValueError("tool.description must be a non-empty string")
-    if not isinstance(parameters, dict):
-        raise ValueError("tool.parameters must be a JSON Schema object")
-
-    extra = set(body) - {"name", "description", "parameters", "triggers"}
-    if extra:
-        raise ValueError(f"unexpected fields on tool: {sorted(extra)}")
-
-    normalized: dict[str, Any] = {
-        "name": name,
-        "description": description,
-        "parameters": parameters,
-    }
-    if "triggers" in body:
-        triggers = body["triggers"]
-        if not isinstance(triggers, list) or not all(isinstance(t, str) for t in triggers):
-            raise ValueError("tool.triggers must be a list of strings")
-        normalized["triggers"] = triggers
-    return normalized
-
-
-# --------------------------------------------------------------------------
-# Catalogue and Retrieval
-# --------------------------------------------------------------------------
-
-import math
-import re
-from collections import Counter
-
-class BM25Retriever:
-    def __init__(self, corpus: list[str], k1: float = 1.5, b: float = 0.75):
-        self.k1 = k1
-        self.b = b
-        self.corpus_size = len(corpus)
-        self.avgdl = 0.0
-        self.doc_freqs = Counter()
-        self.doc_len = []
-        self.doc_tf = []
-
-        if self.corpus_size > 0:
-            total_len = 0
-            for doc in corpus:
-                tokens = self.tokenize(doc)
-                length = len(tokens)
-                self.doc_len.append(length)
-                total_len += length
-                tf = Counter(tokens)
-                self.doc_tf.append(tf)
-                for token in tf:
-                    self.doc_freqs[token] += 1
-            self.avgdl = total_len / self.corpus_size
-            
-    def tokenize(self, text: str) -> list[str]:
-        return re.findall(r'\w+', text.lower())
-        
-    def get_scores(self, query: str) -> list[float]:
-        tokens = self.tokenize(query)
-        scores = [0.0] * self.corpus_size
-        for token in tokens:
-            if token not in self.doc_freqs:
-                continue
-            df = self.doc_freqs[token]
-            idf = math.log(1 + (self.corpus_size - df + 0.5) / (df + 0.5))
-            for i in range(self.corpus_size):
-                tf = self.doc_tf[i].get(token, 0)
-                if tf > 0:
-                    score = idf * (tf * (self.k1 + 1)) / (tf + self.k1 * (1 - self.b + self.b * self.doc_len[i] / (self.avgdl or 1)))
-                    scores[i] += score
-        return scores
-
-def cosine_similarity(v1: list[float], v2: list[float]) -> float:
-    dot = sum(a * b for a, b in zip(v1, v2))
-    mag1 = math.sqrt(sum(a * a for a in v1))
-    mag2 = math.sqrt(sum(b * b for b in v2))
-    if mag1 == 0 or mag2 == 0:
-        return 0.0
-    return dot / (mag1 * mag2)
-
-
-class ToolCatalogue:
-    def __init__(self, tools: list[dict[str, Any]]):
-        self.tools = tools
-        self.fingerprints = [self._fingerprint(t) for t in tools]
-        
-        # Prepare text representation for each tool for lexical retrieval
-        self.tool_texts = []
-        for t in tools:
-            name = t.get("name", "")
-            desc = t.get("description", "")
-            params = json.dumps(t.get("parameters", {}))
-            self.tool_texts.append(f"{name} {desc} {params}")
-            
-        self.bm25 = BM25Retriever(self.tool_texts)
-        self.embeddings: list[list[float]] | None = None
-
-    @staticmethod
-    def _fingerprint(tool: dict[str, Any]) -> str:
-        return hashlib.sha256(json.dumps(tool, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
-
-_catalogue_cache: "OrderedDict[str, ToolCatalogue]" = OrderedDict()
-
-def _get_catalogue_key(tools: list[dict[str, Any]]) -> str:
-    # The key for a given toolset is the hash of the sorted list of their individual fingerprints
-    # This deduplicates identical tools with different order.
-    fps = sorted(ToolCatalogue._fingerprint(t) for t in tools)
-    return hashlib.sha256(json.dumps(fps, separators=(",", ":")).encode("utf-8")).hexdigest()
-
-def get_tool_catalogue(tools: list[dict[str, Any]]) -> ToolCatalogue:
-    key = _get_catalogue_key(tools)
-    if key in _catalogue_cache:
-        _catalogue_cache.move_to_end(key)
-        return _catalogue_cache[key]
-    
-    cat = ToolCatalogue(tools)
-    _catalogue_cache[key] = cat
-    _catalogue_cache.move_to_end(key)
-    while len(_catalogue_cache) > CATALOGUE_CACHE_SIZE:
-        _catalogue_cache.popitem(last=False)
-    return cat
-
-# --------------------------------------------------------------------------
-# Request / response models
-# --------------------------------------------------------------------------
-
-
-class RouteRequest(BaseModel):
-    input: str = Field(..., min_length=1)
-    tools: list[dict[str, Any]] = Field(..., min_length=1, max_length=MAX_TOOLS)
-    system: str | None = None
-
-    @field_validator("tools")
-    @classmethod
-    def _normalize_tools(cls, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        return [normalize_tool(item) for item in value]
-
-
-class AutoRouteRequest(BaseModel):
-    query: str = Field(..., min_length=1)
-    tools: list[dict[str, Any]] = Field(..., min_length=1)
-    system: str | None = None
-    max_candidates: int = Field(5, ge=1, le=5)
-
-    @field_validator("tools")
-    @classmethod
-    def _normalize_tools(cls, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        return [normalize_tool(item) for item in value]
-
-
-class RouteResponse(BaseModel):
-    outcome: Literal["selected", "confirm", "abstain"]
-    function_calls: list[dict[str, Any]]
-    suppressed_calls: list[dict[str, Any]]
-    confidence: float | None
-    reasoning: str | None
-    validation: dict[str, Any] | None
-    model: str = MODEL_NAME
-
-
-class AutoRouteResponse(BaseModel):
-    outcome: Literal["selected", "confirm", "abstain", "error"]
-    candidates: list[dict[str, Any]]
-    retrieval_scores: list[float]
-    function_calls: list[dict[str, Any]]
-    suppressed_calls: list[dict[str, Any]]
-    confidence: float | None
-    reasoning: str | None
-    validation: dict[str, Any] | None
-    model: str = MODEL_NAME
-    diagnostics: dict[str, Any] = Field(default_factory=dict)
-
-
-# --------------------------------------------------------------------------
-# Needle agent lifecycle
-#
-# `needle.Needle(...)` binds one toolset (+ system string) to an agent, and
-# the underlying native engine holds a single globally-active binding per
-# process (cactus-needle==3.0.1 keeps one bound instance per generation).
-# `complete()` also carries conversation state on the Python object. To
-# avoid both concurrent native-engine mutation and cross-request state
-# leakage while still avoiding a full agent rebuild on every call:
-#
-#   1. canonicalize the incoming tools + system into a stable JSON shape
-#   2. hash that canonical form to a cache key
-#   3. keep a small bounded LRU of Needle agents keyed by that hash
-#   4. serialize *all* access (construction, reset, complete) behind one
-#      asyncio.Lock, and run the blocking Needle calls in a thread so the
-#      event loop is never held up
-#   5. call reset() on the agent immediately before every complete() call,
-#      inside the lock, so no conversation state can leak between
-#      unrelated requests even when they reuse the same cached agent
-#
-# All cached agents share the same (untuned) base weights, so there is no
-# risk of the "tuned weights bound, can't construct a base agent" failure
-# mode the library raises for mixed tuned/untuned usage.
-# --------------------------------------------------------------------------
-
 _inference_lock = asyncio.Lock()
 _agent_cache: "OrderedDict[str, needle.Needle]" = OrderedDict()
 _model_ready = False
-_embedding_agent: needle.Needle | None = None
-
-def _get_embedding_agent() -> needle.Needle:
-    global _embedding_agent
-    if _embedding_agent is None:
-        _embedding_agent = needle.Needle(generation=3)
-    return _embedding_agent
 
 def _toolset_key(tools: list[dict[str, Any]], system: str | None) -> str:
     canonical = json.dumps({"tools": tools, "system": system}, sort_keys=True, separators=(",", ":"))
     return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
 
-
 def _build_agent(tools: list[dict[str, Any]], system: str | None) -> "needle.Needle":
     return needle.Needle(tools=tools, system=system, generation=3)
 
-
 def _get_ready_agent_sync(tools: list[dict[str, Any]], system: str | None) -> "needle.Needle":
-    """Return the cached agent for this toolset/system, reset and ready.
-
-    Must be called while holding `_inference_lock`.
-    """
     key = _toolset_key(tools, system)
     agent = _agent_cache.get(key)
     if agent is None:
@@ -310,10 +64,9 @@ def _get_ready_agent_sync(tools: list[dict[str, Any]], system: str | None) -> "n
     agent.reset()
     return agent
 
-
 async def get_needle_embeddings(texts: list[str]) -> list[list[float]]:
     async with _inference_lock:
-        agent = await asyncio.to_thread(_get_embedding_agent)
+        agent = needle.Needle(generation=3)
         embeddings = []
         for text in texts:
             emb = await asyncio.to_thread(agent.embed, text)
@@ -327,17 +80,10 @@ async def run_needle_complete(
         agent = await asyncio.to_thread(_get_ready_agent_sync, tools, system)
         return await asyncio.to_thread(agent.complete, text)
 
-
 def _check_model_ready_sync() -> bool:
-    """Construct a toolless agent to confirm the engine + baked weights load.
-
-    This only verifies the runtime can initialize; it never runs a tool
-    decision, so it is not a "meaningful user tool action".
-    """
     needle.Needle(generation=3)
     return True
 
-
 @asynccontextmanager
 async def lifespan(_app: FastAPI):
     global _model_ready
@@ -347,12 +93,6 @@ async def lifespan(_app: FastAPI):
         _model_ready = False
     yield
 
-
-# --------------------------------------------------------------------------
-# Routing policy
-# --------------------------------------------------------------------------
-
-
 def decide_outcome(
     function_calls: list[dict[str, Any]],
     suppressed_calls: list[dict[str, Any]],
@@ -365,20 +105,14 @@ def decide_outcome(
     return "confirm"
 
 
-# --------------------------------------------------------------------------
-# App
-# --------------------------------------------------------------------------
-
 app = FastAPI(title="Needle3 Tool Router", version="1.0.0", lifespan=lifespan)
 
-
 def require_api_key(authorization: str | None = Header(default=None)) -> None:
     if not API_KEY:
         return
     if authorization != f"Bearer {API_KEY}":
         raise HTTPException(status_code=401, detail="Invalid API key")
 
-
 @app.get("/health")
 async def health() -> dict[str, Any]:
     return {
@@ -389,6 +123,29 @@ async def health() -> dict[str, Any]:
         "capabilities": ["route", "auto_route", "retrieval"]
     }
 
+@app.get("/ready")
+async def ready() -> dict[str, Any]:
+    if not _model_ready:
+        raise HTTPException(status_code=503, detail="Model not ready")
+    return {"status": "ready"}
+
+@app.get("/v1/info")
+async def info() -> dict[str, Any]:
+    return {
+        "gateway_version": "1.0.0",
+        "model": MODEL_NAME,
+        "generation": 3,
+        "max_tools": MAX_TOOLS,
+        "capabilities": ["route", "auto_route", "retrieval", "registry", "laya", "gates"]
+    }
+
+@app.get("/v1/metrics")
+async def metrics() -> dict[str, Any]:
+    return {
+        "registered_namespaces": len(registry_instance.namespaces),
+        "total_tools": sum(len(v) for v in registry_instance.namespaces.values()),
+        "model_ready": _model_ready
+    }
 
 @app.get("/v1/models", dependencies=[Depends(require_api_key)])
 async def models() -> dict[str, Any]:
@@ -406,58 +163,119 @@ async def models() -> dict[str, Any]:
         ],
     }
 
+@app.get("/v1/tools", dependencies=[Depends(require_api_key)])
+async def get_tools() -> dict[str, Any]:
+    return registry_instance.namespaces
 
-import time
 
-@app.post("/v1/route/auto", response_model=AutoRouteResponse, dependencies=[Depends(require_api_key)])
-async def route_auto(payload: AutoRouteRequest) -> AutoRouteResponse:
-    start_time = time.time()
+@app.post("/v1/tools/register", response_model=ToolRegistrationResponse, dependencies=[Depends(require_api_key)])
+async def register_tools(payload: ToolRegistration) -> ToolRegistrationResponse:
+    registry_instance.register(payload.namespace, payload.tools)
+    return ToolRegistrationResponse(
+        registered_count=len(payload.tools),
+        namespace=payload.namespace
+    )
+
+@app.post("/v1/tools/retrieve", dependencies=[Depends(require_api_key)])
+async def retrieve_tools(payload: RetrieveRequest) -> dict[str, Any]:
+    if payload.namespace and payload.namespace in registry_instance.catalogues:
+        catalogue = registry_instance.catalogues[payload.namespace]
+    else:
+        # Fallback to all tools if namespace not found or None
+        all_tools = []
+        for tools in registry_instance.namespaces.values():
+            all_tools.extend(tools)
+        if not all_tools:
+            return {"candidates": []}
+        catalogue = get_tool_catalogue(all_tools)
+
+    try:
+        query_emb = await get_needle_embeddings([payload.query])
+        q_emb = query_emb[0]
+        if catalogue.embeddings is None:
+            catalogue.embeddings = await get_needle_embeddings(catalogue.tool_texts)
+        emb_scores = [cosine_similarity(q_emb, t_emb) for t_emb in catalogue.embeddings]
+    except Exception:
+        emb_scores = [0.0] * len(catalogue.tools)
+
+    lex_scores = catalogue.bm25.get_scores(payload.query)
+    hybrid_scores = [e + l for e, l in zip(emb_scores, lex_scores)]
+    scored_tools = sorted(
+        zip(hybrid_scores, catalogue.tools),
+        key=lambda x: x[0],
+        reverse=True
+    )
     
+    top_candidates = scored_tools[:payload.max_candidates]
+    retrieved_tools = [t for s, t in top_candidates]
+    return {"candidates": retrieved_tools}
+
+@app.post("/v1/gates/evaluate", response_model=EvaluateResponse, dependencies=[Depends(require_api_key)])
+async def gates_evaluate(payload: EvaluateRequest) -> EvaluateResponse:
+    evaluations = registry_instance.evaluate_gates(payload.tools)
+    return EvaluateResponse(evaluations=evaluations)
+
+@app.post("/v1/route", response_model=RouteResponse, dependencies=[Depends(require_api_key)])
+async def route(payload: RouteRequest) -> RouteResponse:
+    try:
+        result = await run_needle_complete(payload.tools, payload.system, payload.input)
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"Needle inference failed: {exc}") from exc
+
+    if result.get("success") is False:
+        detail = result.get("error") or result.get("error_code") or "Needle reported a runtime error"
+        raise HTTPException(status_code=500, detail=str(detail))
+
+    function_calls = result.get("function_calls") or []
+    suppressed_calls = result.get("suppressed_calls") or []
+    confidence = result.get("confidence")
+
+    return RouteResponse(
+        outcome=decide_outcome(function_calls, suppressed_calls, confidence),
+        function_calls=function_calls,
+        suppressed_calls=suppressed_calls,
+        confidence=confidence,
+        reasoning=result.get("reasoning"),
+        validation=result.get("validation"),
+        model=MODEL_NAME,
+    )
+
+@app.post("/v1/gates/route", response_model=AutoRouteResponse, dependencies=[Depends(require_api_key)])
+async def gates_route(payload: AutoRouteRequest) -> AutoRouteResponse:
+    start_time = time.time()
     catalogue = get_tool_catalogue(payload.tools)
-    
+
     try:
         query_emb = await get_needle_embeddings([payload.query])
         q_emb = query_emb[0]
-        
         if catalogue.embeddings is None:
             catalogue.embeddings = await get_needle_embeddings(catalogue.tool_texts)
-            
         emb_scores = [cosine_similarity(q_emb, t_emb) for t_emb in catalogue.embeddings]
     except Exception:
-        # Fallback to lexical only
         emb_scores = [0.0] * len(payload.tools)
-        
+
     lex_scores = catalogue.bm25.get_scores(payload.query)
-    
-    # Simple hybrid scoring: normalize BM25 scores before combining with cosine similarity.
-    max_lex = max(lex_scores) if lex_scores and max(lex_scores) > 0 else 1.0
-    norm_lex_scores = [score / max_lex for score in lex_scores]
-    
-    hybrid_scores = [(e + l) / 2.0 for e, l in zip(emb_scores, norm_lex_scores)]
-    
+    hybrid_scores = [e + l for e, l in zip(emb_scores, lex_scores)]
     scored_tools = sorted(
         zip(hybrid_scores, catalogue.tools),
         key=lambda x: x[0],
         reverse=True
     )
-    
+
     top_candidates = scored_tools[:payload.max_candidates]
     retrieved_tools = [t for s, t in top_candidates]
     retrieved_scores = [s for s, t in top_candidates]
-    
     retrieval_time = time.time() - start_time
     route_start = time.time()
-    
+
     outcome = "abstain"
     function_calls = []
     suppressed_calls = []
     confidence = None
     reasoning = None
     validation = None
-    diagnostics = {
-        "retrieval_ms": round(retrieval_time * 1000, 2),
-    }
-    
+    diagnostics = {"retrieval_ms": round(retrieval_time * 1000, 2)}
+
     try:
         result = await run_needle_complete(retrieved_tools, payload.system, payload.query)
         if result.get("success") is False:
@@ -474,9 +292,15 @@ async def route_auto(payload: AutoRouteRequest) -> AutoRouteResponse:
         outcome = "error"
         reasoning = str(exc)
 
+    # Optional Laya evaluation
+    laya_result = await evaluate_with_laya("route", retrieved_tools, retrieved_scores, function_calls, confidence)
+    if laya_result.get("decision") == "escalate":
+        outcome = "error"
+        reasoning = laya_result.get("reasoning", "Escalated by Laya")
+
     diagnostics["route_ms"] = round((time.time() - route_start) * 1000, 2)
     diagnostics["total_ms"] = round((time.time() - start_time) * 1000, 2)
-    
+
     return AutoRouteResponse(
         outcome=outcome,
         candidates=retrieved_tools,
@@ -490,27 +314,242 @@ async def route_auto(payload: AutoRouteRequest) -> AutoRouteResponse:
         diagnostics=diagnostics
     )
 
-@app.post("/v1/route", response_model=RouteResponse, dependencies=[Depends(require_api_key)])
-async def route(payload: RouteRequest) -> RouteResponse:
-    try:
-        result = await run_needle_complete(payload.tools, payload.system, payload.input)
-    except Exception as exc:
-        raise HTTPException(status_code=500, detail=f"Needle inference failed: {exc}") from exc
+@app.post("/v1/chat/completions", dependencies=[Depends(require_api_key)])
+async def chat_completions(payload: ChatCompletionRequest) -> dict[str, Any]:
+    # Extract query from the last user message
+    query = ""
+    for msg in reversed(payload.messages):
+        if msg.role == "user":
+            query = msg.content
+            break
+            
+    if not query:
+        raise HTTPException(status_code=400, detail="No user message found to route tools")
+        
+    tools = payload.tools or []
+    if tools:
+        # Use simple run_needle_complete if tools are small, or gate route if there are many.
+        # OpenCode expects an OpenAI-like response with tool_calls
+        if len(tools) > MAX_TOOLS:
+            # We need to retrieve best subset
+            req = AutoRouteRequest(query=query, tools=tools, max_candidates=MAX_TOOLS)
+            res = await gates_route(req)
+            fc = res.function_calls
+            outcome = res.outcome
+        else:
+            req2 = RouteRequest(input=query, tools=tools)
+            res2 = await route(req2)
+            fc = res2.function_calls
+            outcome = res2.outcome
+            
+        tool_calls = []
+        if fc:
+            for i, call in enumerate(fc):
+                tool_calls.append({
+                    "id": f"call_{i}",
+                    "type": "function",
+                    "function": {
+                        "name": call.get("name"),
+                        "arguments": json.dumps(call.get("arguments", {}))
+                    }
+                })
+        
+        return {
+            "id": f"chatcmpl-{hashlib.sha1(str(time.time()).encode()).hexdigest()[:10]}",
+            "object": "chat.completion",
+            "created": int(time.time()),
+            "model": payload.model,
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {
+                        "role": "assistant",
+                        "content": None,
+                        "tool_calls": tool_calls
+                    },
+                    "finish_reason": "tool_calls" if tool_calls else "stop"
+                }
+            ],
+            "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+        }
+    else:
+        # If no tools, needle3 isn't a general chat model
+        raise HTTPException(status_code=400, detail="Needle3 is a tool router and requires 'tools' to be provided.")
+
+
+HTML_CHAT_UI = """<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Needle 3 Gateway Dashboard</title>
+    <style>
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; background: #0f172a; color: #e2e8f0; height: 100vh; display: flex; flex-direction: column; }
+        header { background: #1e293b; border-bottom: 1px solid #334155; padding: 12px 20px; display: flex; align-items: center; justify-content: space-between; }
+        header h1 { font-size: 1.25rem; color: #38bdf8; font-weight: 600; display: flex; align-items: center; gap: 10px; }
+        .controls { display: flex; align-items: center; gap: 12px; }
+        main { flex: 1; display: flex; max-width: 1200px; width: 100%; margin: 0 auto; overflow: hidden; }
+        .sidebar { width: 250px; background: #1e293b; border-right: 1px solid #334155; padding: 20px 0; display: flex; flex-direction: column; gap: 10px; }
+        .sidebar-item { padding: 10px 20px; cursor: pointer; color: #94a3b8; font-weight: 500; transition: all 0.2s; }
+        .sidebar-item:hover, .sidebar-item.active { background: #334155; color: #f8fafc; border-left: 3px solid #38bdf8; }
+        .content { flex: 1; padding: 20px; overflow-y: auto; display: flex; flex-direction: column; gap: 20px; }
+        .card { background: #1e293b; border: 1px solid #334155; border-radius: 8px; padding: 20px; }
+        .card h2 { font-size: 1.1rem; margin-bottom: 15px; color: #f8fafc; border-bottom: 1px solid #334155; padding-bottom: 10px; }
+        .metric-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 15px; }
+        .metric { background: #0f172a; padding: 15px; border-radius: 6px; border: 1px solid #334155; text-align: center; }
+        .metric-value { font-size: 1.5rem; font-weight: 700; color: #38bdf8; margin-bottom: 5px; }
+        .metric-label { font-size: 0.8rem; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
+        .form-group { margin-bottom: 15px; }
+        label { display: block; margin-bottom: 5px; font-size: 0.9rem; color: #cbd5e1; }
+        input[type="text"], textarea, select { width: 100%; background: #0f172a; border: 1px solid #475569; color: #e2e8f0; border-radius: 6px; padding: 10px; font-size: 0.9rem; }
+        textarea { resize: vertical; min-height: 100px; font-family: monospace; }
+        button { background: #38bdf8; color: #0f172a; border: none; border-radius: 6px; padding: 10px 16px; font-weight: 600; cursor: pointer; transition: background 0.2s; }
+        button:hover { background: #0284c7; color: #ffffff; }
+        pre { background: #0f172a; padding: 15px; border-radius: 6px; border: 1px solid #334155; overflow-x: auto; font-size: 0.85rem; }
+        .status-badge { font-size: 0.75rem; padding: 2px 8px; border-radius: 12px; background: #065f46; color: #34d399; font-weight: 500; }
+        .hidden { display: none !important; }
+    </style>
+</head>
+<body>
+    <header>
+        <h1>🪡 Needle 3 Gateway <span class="status-badge" id="status-indicator">Checking...</span></h1>
+    </header>
+    <main>
+        <div class="sidebar">
+            <div class="sidebar-item active" onclick="switchTab('overview')">Overview</div>
+            <div class="sidebar-item" onclick="switchTab('playground')">Playground</div>
+            <div class="sidebar-item" onclick="switchTab('registry')">Tool Registry</div>
+        </div>
+        <div class="content" id="overview-tab">
+            <div class="card">
+                <h2>System Status</h2>
+                <div class="metric-grid">
+                    <div class="metric"><div class="metric-value" id="m-model">needle3</div><div class="metric-label">Model</div></div>
+                    <div class="metric"><div class="metric-value" id="m-ready">False</div><div class="metric-label">Ready</div></div>
+                    <div class="metric"><div class="metric-value" id="m-tools">0</div><div class="metric-label">Total Tools</div></div>
+                    <div class="metric"><div class="metric-value" id="m-namespaces">0</div><div class="metric-label">Namespaces</div></div>
+                </div>
+            </div>
+        </div>
+        <div class="content hidden" id="playground-tab">
+            <div class="card">
+                <h2>Routing Playground</h2>
+                <div class="form-group">
+                    <label>Query</label>
+                    <input type="text" id="p-query" placeholder="e.g. Find all files ending in .txt in the src directory">
+                </div>
+                <div class="form-group">
+                    <label>Candidate Tools JSON Array (or leave empty to use Registry)</label>
+                    <textarea id="p-tools" placeholder='[{"name": "find_files", "description": "Finds files", "parameters": {}}]'></textarea>
+                </div>
+                <button onclick="runPlayground()">Route Request</button>
+            </div>
+            <div class="card">
+                <h2>Result</h2>
+                <pre id="p-result">Submit a request to see the outcome...</pre>
+            </div>
+        </div>
+        <div class="content hidden" id="registry-tab">
+            <div class="card">
+                <h2>Tool Registry</h2>
+                <pre id="r-data">Loading registry data...</pre>
+            </div>
+        </div>
+    </main>
+    <script>
+        function switchTab(tabId) {
+            document.querySelectorAll('.sidebar-item').forEach(el => el.classList.remove('active'));
+            document.querySelectorAll('.content').forEach(el => el.classList.add('hidden'));
+            event.target.classList.add('active');
+            document.getElementById(tabId + '-tab').classList.remove('hidden');
+            if (tabId === 'registry') loadRegistry();
+        }
+
+        async function loadStatus() {
+            try {
+                const res = await fetch('/health');
+                const data = await res.json();
+                document.getElementById('status-indicator').textContent = data.model_ready ? 'Ready' : 'Degraded';
+                document.getElementById('status-indicator').style.background = data.model_ready ? '#065f46' : '#7f1d1d';
+                document.getElementById('status-indicator').style.color = data.model_ready ? '#34d399' : '#fca5a5';
+                document.getElementById('m-ready').textContent = data.model_ready;
+                
+                const mRes = await fetch('/v1/metrics');
+                if (mRes.ok) {
+                    const mData = await mRes.json();
+                    document.getElementById('m-tools').textContent = mData.total_tools;
+                    document.getElementById('m-namespaces').textContent = mData.registered_namespaces;
+                }
+            } catch (e) {
+                document.getElementById('status-indicator').textContent = 'Error';
+            }
+        }
+
+        async function loadRegistry() {
+            try {
+                const res = await fetch('/v1/tools');
+                const data = await res.json();
+                document.getElementById('r-data').textContent = JSON.stringify(data, null, 2);
+            } catch (e) {
+                document.getElementById('r-data').textContent = 'Failed to load registry';
+            }
+        }
 
-    if result.get("success") is False:
-        detail = result.get("error") or result.get("error_code") or "Needle reported a runtime error"
-        raise HTTPException(status_code=500, detail=str(detail))
+        async function runPlayground() {
+            const query = document.getElementById('p-query').value;
+            const toolsStr = document.getElementById('p-tools').value;
+            let tools = [];
+            
+            try {
+                if (toolsStr.trim()) {
+                    tools = JSON.parse(toolsStr);
+                }
+            } catch (e) {
+                alert('Invalid JSON in tools field');
+                return;
+            }
 
-    function_calls = result.get("function_calls") or []
-    suppressed_calls = result.get("suppressed_calls") or []
-    confidence = result.get("confidence")
+            document.getElementById('p-result').textContent = 'Routing...';
+
+            try {
+                let url, payload;
+                if (tools.length > 0) {
+                    if (tools.length > 5) {
+                        url = '/v1/gates/route';
+                        payload = { query: query, tools: tools, max_candidates: 5 };
+                    } else {
+                        url = '/v1/route';
+                        payload = { input: query, tools: tools };
+                    }
+                } else {
+                    url = '/v1/tools/retrieve';
+                    payload = { query: query, max_candidates: 5 };
+                    // For playground without explicit tools, we just test retrieval
+                }
+
+                const res = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(payload)
+                });
+                
+                const data = await res.json();
+                document.getElementById('p-result').textContent = JSON.stringify(data, null, 2);
+            } catch (e) {
+                document.getElementById('p-result').textContent = 'Error: ' + e.message;
+            }
+        }
+
+        loadStatus();
+        setInterval(loadStatus, 10000);
+    </script>
+</body>
+</html>"""
+
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+@app.get("/ui", response_class=HTMLResponse, include_in_schema=False)
+@app.get("/ui/", response_class=HTMLResponse, include_in_schema=False)
+async def serve_landing_page() -> HTMLResponse:
+    return HTMLResponse(content=HTML_CHAT_UI, status_code=200)
 
-    return RouteResponse(
-        outcome=decide_outcome(function_calls, suppressed_calls, confidence),
-        function_calls=function_calls,
-        suppressed_calls=suppressed_calls,
-        confidence=confidence,
-        reasoning=result.get("reasoning"),
-        validation=result.get("validation"),
-        model=MODEL_NAME,
-    )

laya.py

@@ -0,0 +1,39 @@
+import os
+import httpx
+import logging
+
+LAYA_ENABLED = os.getenv("LAYA_ENABLED", "false").lower() == "true"
+LAYA_URL = os.getenv("LAYA_URL", "http://localhost:8081/evaluate")
+LAYA_TIMEOUT = float(os.getenv("LAYA_TIMEOUT", "2.0"))
+
+logger = logging.getLogger(__name__)
+
+async def evaluate_with_laya(workflow_state: str, candidates: list, scores: list, function_calls: list, confidence: float | None) -> dict:
+    if not LAYA_ENABLED:
+        return {"decision": "proceed", "reasoning": "Laya disabled via environment"}
+
+    # Evaluate states based on Laya's capability criteria
+    try:
+        async with httpx.AsyncClient(timeout=LAYA_TIMEOUT) as client:
+            payload = {
+                "workflow_state": workflow_state,
+                "candidates": candidates,
+                "scores": scores,
+                "function_calls": function_calls,
+                "confidence": confidence
+            }
+            # Only sending network requests to Laya if there is a real server, otherwise deterministic local fallback
+            response = await client.post(LAYA_URL, json=payload)
+            if response.status_code == 200:
+                return response.json()
+            else:
+                logger.warning(f"Laya evaluation failed with status {response.status_code}. Proceeding with fallback.")
+                return {"decision": "proceed", "reasoning": "Laya fallback (non-200)"}
+
+    except httpx.RequestError as e:
+        logger.warning(f"Laya request failed: {e}. Proceeding with fallback.")
+        return {"decision": "proceed", "reasoning": f"Laya fallback (timeout/network error: {e})"}
+    except Exception as e:
+        logger.warning(f"Laya unexpected error: {e}. Proceeding with fallback.")
+        return {"decision": "proceed", "reasoning": "Laya fallback (internal error)"}
+

live_smoke_test.log

@@ -0,0 +1,14 @@
+Running live smoke tests on deployed endpoint...
+
+1 & 2. Testing 31 tools and checking max 5 limit and stable names
+Status: 200
+Candidates: ['highlight_tool', 'generic_tool_10', 'generic_tool_3', 'generic_tool_29', 'generic_tool_2']
+Function calls: [{'name': 'generic_tool_29', 'arguments': {'object': 'red connector'}}]
+
+3. Testing indirect intent: 'Investigate why the deployment failed and fix it.'
+Candidates for indirect intent: ['restart_service', 'fetch_logs', 'read_file']
+
+5. Verifying /v1/route compatibility
+Status: 200
+
+Smoke tests completed.

live_smoke_test.py

@@ -0,0 +1,73 @@
+import httpx
+import json
+import time
+
+URL = "https://leon4gr45-needle.hf.space"
+HEADERS = {"Authorization": "Bearer my-secret-key"}
+
+def run_tests():
+    print("Running live smoke tests on deployed endpoint...")
+
+    # Set a higher timeout because caching Needle agent on first request on Space takes longer
+    timeout = httpx.Timeout(60.0)
+    client = httpx.Client(timeout=timeout, headers=HEADERS)
+
+    # 1 & 2. Test 31 heterogeneous tools
+    print("\n1 & 2. Testing 31 tools and checking max 5 limit and stable names")
+    tools = [
+        {"name": f"generic_tool_{i}", "description": f"Does generic thing {i}", "parameters": {"type": "object"}}
+        for i in range(30)
+    ]
+    tools.append({
+        "name": "highlight_tool",
+        "description": "Highlight or frame an object on screen",
+        "parameters": {"type": "object", "properties": {"object": {"type": "string"}}}
+    })
+
+    payload = {
+        "query": "Highlight the red connector",
+        "tools": tools,
+        "max_candidates": 5
+    }
+
+    res = client.post(f"{URL}/v1/route/auto", json=payload)
+    data = res.json()
+    print("Status:", res.status_code)
+    assert res.status_code == 200
+    assert len(data["candidates"]) <= 5
+    assert "highlight_tool" in [c["name"] for c in data["candidates"]]
+    print("Candidates:", [c["name"] for c in data["candidates"]])
+    print("Function calls:", data["function_calls"])
+
+    # 3. Test indirect intent
+    print("\n3. Testing indirect intent: 'Investigate why the deployment failed and fix it.'")
+    tools = [
+        {"name": "fetch_logs", "description": "Fetch application logs from the server", "parameters": {"type": "object"}},
+        {"name": "read_file", "description": "Read file contents", "parameters": {"type": "object"}},
+        {"name": "restart_service", "description": "Restart the service", "parameters": {"type": "object"}},
+        {"name": "order_pizza", "description": "Order a pizza", "parameters": {"type": "object"}},
+        {"name": "play_music", "description": "Play a song", "parameters": {"type": "object"}}
+    ]
+
+    payload = {
+        "query": "Investigate why the deployment failed and fix it.",
+        "tools": tools,
+        "max_candidates": 3
+    }
+    res = client.post(f"{URL}/v1/route/auto", json=payload)
+    data = res.json()
+    print("Candidates for indirect intent:", [c["name"] for c in data["candidates"]])
+
+    # 5. Verify /v1/route remains compatible
+    print("\n5. Verifying /v1/route compatibility")
+    res = client.post(f"{URL}/v1/route", json={
+        "input": "Highlight the red connector",
+        "tools": tools[:2]
+    })
+    print("Status:", res.status_code)
+    assert res.status_code == 200
+
+    print("\nSmoke tests completed.")
+
+if __name__ == '__main__':
+    run_tests()

models.py

@@ -0,0 +1,88 @@
+from typing import Any, Literal
+from pydantic import BaseModel, Field, field_validator
+from registry import normalize_tool
+
+class RouteRequest(BaseModel):
+    input: str = Field(..., min_length=1)
+    tools: list[dict[str, Any]] = Field(..., min_length=1, max_length=5)
+    system: str | None = None
+
+    @field_validator("tools")
+    @classmethod
+    def _normalize_tools(cls, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return [normalize_tool(item) for item in value]
+
+class RouteResponse(BaseModel):
+    outcome: Literal["selected", "confirm", "abstain", "error"]
+    function_calls: list[dict[str, Any]] = Field(default_factory=list)
+    suppressed_calls: list[dict[str, Any]] = Field(default_factory=list)
+    confidence: float | None = None
+    reasoning: str | None = None
+    validation: dict[str, Any] | None = None
+    model: str
+
+class AutoRouteRequest(BaseModel):
+    query: str = Field(..., min_length=1)
+    tools: list[dict[str, Any]] = Field(..., min_length=1)
+    system: str | None = None
+    max_candidates: int = Field(5, ge=1, le=5)
+
+    @field_validator("tools")
+    @classmethod
+    def _normalize_tools(cls, value: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return [normalize_tool(item) for item in value]
+
+class AutoRouteResponse(BaseModel):
+    outcome: Literal["selected", "confirm", "abstain", "error"]
+    candidates: list[dict[str, Any]]
+    retrieval_scores: list[float]
+    function_calls: list[dict[str, Any]]
+    suppressed_calls: list[dict[str, Any]]
+    confidence: float | None
+    reasoning: str | None
+    validation: dict[str, Any] | None
+    model: str
+    diagnostics: dict[str, Any] = Field(default_factory=dict)
+
+class ToolRegistration(BaseModel):
+    namespace: str
+    tools: list[dict[str, Any]]
+
+class ToolRegistrationResponse(BaseModel):
+    registered_count: int
+    namespace: str
+
+class RetrieveRequest(BaseModel):
+    query: str
+    namespace: str | None = None
+    max_candidates: int = Field(5, ge=1, le=5)
+    workflow_context: dict[str, Any] | None = None
+
+class EvaluateRequest(BaseModel):
+    tools: list[dict[str, Any]]
+
+class EvaluateResponse(BaseModel):
+    evaluations: list[dict[str, Any]]
+
+class Message(BaseModel):
+    role: str
+    content: str
+    tool_calls: list[dict[str, Any]] | None = None
+
+class ChatCompletionRequest(BaseModel):
+    model: str
+    messages: list[Message]
+    tools: list[dict[str, Any]] | None = None
+    stream: bool | None = False
+
+
+class LayaEvaluationRequest(BaseModel):
+    workflow_state: str
+    candidates: list[dict[str, Any]]
+    scores: list[float]
+    function_calls: list[dict[str, Any]]
+    confidence: float | None
+
+class LayaEvaluationResponse(BaseModel):
+    decision: Literal["proceed", "escalate", "abstain"]
+    reasoning: str | None = None

registry.py

@@ -0,0 +1,193 @@
+from typing import Any
+import hashlib
+import json
+import math
+import re
+from collections import Counter, OrderedDict
+
+def normalize_tool(raw: Any) -> dict[str, Any]:
+    """Normalize one candidate tool into Needle's raw schema."""
+    if not isinstance(raw, dict):
+        raise ValueError("each tool must be a JSON object")
+
+    body = raw
+    if "type" in raw or "function" in raw:
+        if raw.get("type") != "function" or not isinstance(raw.get("function"), dict):
+            raise ValueError(
+                "OpenAI-style tools must have type == 'function' and an object 'function'"
+            )
+        extra = set(raw) - {"type", "function"}
+        if extra:
+            raise ValueError(f"unexpected fields on tool: {sorted(extra)}")
+        body = raw["function"]
+
+    name = body.get("name")
+    description = body.get("description")
+    parameters = body.get("parameters")
+
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("tool.name must be a non-empty string")
+    if not isinstance(description, str) or not description.strip():
+        raise ValueError("tool.description must be a non-empty string")
+    
+    # Optional parameters fallback
+    if parameters is None:
+        parameters = {"type": "object", "properties": {}}
+
+    if not isinstance(parameters, dict):
+        raise ValueError("tool.parameters must be a JSON Schema object")
+
+    extra = set(body) - {"name", "description", "parameters", "triggers"}
+    if extra:
+        raise ValueError(f"unexpected fields on tool: {sorted(extra)}")
+
+    normalized: dict[str, Any] = {
+        "name": name,
+        "description": description,
+        "parameters": parameters,
+    }
+    if "triggers" in body:
+        triggers = body["triggers"]
+        if not isinstance(triggers, list) or not all(isinstance(t, str) for t in triggers):
+            raise ValueError("tool.triggers must be a list of strings")
+        normalized["triggers"] = triggers
+    return normalized
+
+class BM25Retriever:
+    def __init__(self, corpus: list[str], k1: float = 1.5, b: float = 0.75):
+        self.k1 = k1
+        self.b = b
+        self.corpus_size = len(corpus)
+        self.avgdl = 0.0
+        self.doc_freqs = Counter()
+        self.doc_len = []
+        self.doc_tf = []
+
+        if self.corpus_size > 0:
+            total_len = 0
+            for doc in corpus:
+                tokens = self.tokenize(doc)
+                length = len(tokens)
+                self.doc_len.append(length)
+                total_len += length
+                tf = Counter(tokens)
+                self.doc_tf.append(tf)
+                for token in tf:
+                    self.doc_freqs[token] += 1
+            self.avgdl = total_len / self.corpus_size
+
+    def tokenize(self, text: str) -> list[str]:
+        return re.findall(r'\w+', text.lower())
+
+    def get_scores(self, query: str) -> list[float]:
+        tokens = self.tokenize(query)
+        scores = [0.0] * self.corpus_size
+        for token in tokens:
+            if token not in self.doc_freqs:
+                continue
+            df = self.doc_freqs[token]
+            idf = math.log(1 + (self.corpus_size - df + 0.5) / (df + 0.5))
+            for i in range(self.corpus_size):
+                tf = self.doc_tf[i].get(token, 0)
+                if tf > 0:
+                    score = idf * (tf * (self.k1 + 1)) / (tf + self.k1 * (1 - self.b + self.b * self.doc_len[i] / (self.avgdl or 1)))
+                    scores[i] += score
+        return scores
+
+def cosine_similarity(v1: list[float], v2: list[float]) -> float:
+    dot = sum(a * b for a, b in zip(v1, v2))
+    mag1 = math.sqrt(sum(a * a for a in v1))
+    mag2 = math.sqrt(sum(b * b for b in v2))
+    if mag1 == 0 or mag2 == 0:
+        return 0.0
+    return dot / (mag1 * mag2)
+
+class ToolCatalogue:
+    def __init__(self, tools: list[dict[str, Any]]):
+        self.tools = tools
+        self.fingerprints = [self._fingerprint(t) for t in tools]
+
+        # Prepare text representation for each tool for lexical retrieval
+        self.tool_texts = []
+        for t in tools:
+            name = t.get("name", "")
+            desc = t.get("description", "")
+            params = json.dumps(t.get("parameters", {}))
+            self.tool_texts.append(f"{name} {desc} {params}")
+
+        self.bm25 = BM25Retriever(self.tool_texts)
+        self.embeddings: list[list[float]] | None = None
+
+    @staticmethod
+    def _fingerprint(tool: dict[str, Any]) -> str:
+        return hashlib.sha256(json.dumps(tool, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
+
+class ToolRegistry:
+    def __init__(self):
+        self.namespaces: dict[str, list[dict[str, Any]]] = {}
+        self.catalogues: dict[str, ToolCatalogue] = {}
+        self.gate_mappings: dict[str, str] = {
+            "filesystem": "files|read|write|directory",
+            "git/version control": "git|commit|push|pull",
+            "terminal/execution": "bash|shell|exec",
+            "browser/navigation": "browser|navigate|web|http",
+            "research/search": "search|google|find",
+            "memory/knowledge": "memory|remember|store",
+            "infrastructure/deployment": "docker|kubernetes|deploy",
+            "communication": "email|slack|message",
+            "scheduling": "cron|schedule|time",
+            "database": "sql|mongo|query|database",
+            "development/testing": "test|pytest|debug",
+        }
+
+    def register(self, namespace: str, tools: list[dict[str, Any]]):
+        normalized = [normalize_tool(t) for t in tools]
+        if namespace not in self.namespaces:
+            self.namespaces[namespace] = []
+        self.namespaces[namespace] = normalized
+        # Update catalogue cache
+        self.catalogues[namespace] = ToolCatalogue(normalized)
+
+    def get_catalogue(self, namespace: str) -> ToolCatalogue | None:
+        return self.catalogues.get(namespace)
+
+    def evaluate_gates(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        evaluations = []
+        for tool in tools:
+            name = tool.get("name", "").lower()
+            desc = tool.get("description", "").lower()
+            matched_family = "general/uncategorized"
+            
+            for family, pattern in self.gate_mappings.items():
+                if re.search(pattern, name) or re.search(pattern, desc):
+                    matched_family = family
+                    break
+            
+            evaluations.append({
+                "tool": tool.get("name"),
+                "family": matched_family
+            })
+        return evaluations
+
+registry_instance = ToolRegistry()
+
+# Added get_tool_catalogue back in registry for dynamic requests
+_catalogue_cache: "OrderedDict[str, ToolCatalogue]" = OrderedDict()
+
+def _get_catalogue_key(tools: list[dict[str, Any]]) -> str:
+    fps = sorted(ToolCatalogue._fingerprint(t) for t in tools)
+    return hashlib.sha256(json.dumps(fps, separators=(",", ":")).encode("utf-8")).hexdigest()
+
+def get_tool_catalogue(tools: list[dict[str, Any]]) -> ToolCatalogue:
+    key = _get_catalogue_key(tools)
+    if key in _catalogue_cache:
+        _catalogue_cache.move_to_end(key)
+        return _catalogue_cache[key]
+
+    cat = ToolCatalogue(tools)
+    _catalogue_cache[key] = cat
+    _catalogue_cache.move_to_end(key)
+    # bounded cache
+    while len(_catalogue_cache) > 16:
+        _catalogue_cache.popitem(last=False)
+    return cat

test_deployed.py

@@ -0,0 +1,10 @@
+import httpx
+
+def test():
+    # 1. Test /health which is unauthenticated
+    print("Testing /health")
+    res = httpx.get('https://leon4gr45-needle.hf.space/health')
+    print("Health:", res.status_code, res.text)
+
+if __name__ == '__main__':
+    test()

tests/test_compatibility.py

@@ -0,0 +1,15 @@
+import pytest
+from models import ChatCompletionRequest, Message
+
+def test_chat_completion_request_parsing():
+    req = ChatCompletionRequest(
+        model="needle3",
+        messages=[
+            Message(role="user", content="hello")
+        ],
+        tools=[{"name": "test", "description": "desc", "parameters": {"type": "object"}}]
+    )
+    assert req.model == "needle3"
+    assert len(req.messages) == 1
+    assert req.messages[0].content == "hello"
+    assert len(req.tools) == 1

tests/test_gates.py

@@ -0,0 +1,13 @@
+import pytest
+from registry import ToolRegistry
+
+def test_gates_evaluation():
+    reg = ToolRegistry()
+    tools = [
+        {"name": "docker_deploy", "description": "Deploy to docker", "parameters": {"type": "object"}},
+        {"name": "unknown_tool", "description": "does random stuff", "parameters": {"type": "object"}}
+    ]
+    evals = reg.evaluate_gates(tools)
+    assert len(evals) == 2
+    assert evals[0]["family"] == "infrastructure/deployment"
+    assert evals[1]["family"] == "general/uncategorized"

tests/test_gateway.py

@@ -367,7 +367,7 @@ def test_auto_route_basic(monkeypatch):
         reasoning="clear match",
     ))
     with client_with_agent(monkeypatch, agent) as client:
-        response = client.post("/v1/route/auto", json=auto_route_payload())
+        response = client.post("/v1/gates/route", json=auto_route_payload())
     body = response.json()
     assert response.status_code == 200
     assert body["outcome"] == "selected"
@@ -377,11 +377,11 @@ def test_auto_route_basic(monkeypatch):
 def test_auto_route_varying_tool_counts(monkeypatch):
     agent = FakeAgent(_default_result(function_calls=[], suppressed_calls=[], confidence=None))
     counts = [5, 31, 100, 200, 500]
-    
+
     with client_with_agent(monkeypatch, agent) as client:
         for count in counts:
             tools = [{"name": f"tool_{i}", "description": f"desc {i}", "parameters": {"type": "object"}} for i in range(count)]
-            response = client.post("/v1/route/auto", json=auto_route_payload(overrides={"tools": tools}))
+            response = client.post("/v1/gates/route", json=auto_route_payload(overrides={"tools": tools}))
             assert response.status_code == 200
             body = response.json()
             assert len(body["candidates"]) <= 5  # default max_candidates is 5
@@ -393,8 +393,8 @@ def test_auto_route_tool_name_collisions(monkeypatch):
         {"name": "duplicate_tool", "description": "desc B", "parameters": {"type": "object"}},
     ]
     with client_with_agent(monkeypatch, agent) as client:
-        response = client.post("/v1/route/auto", json=auto_route_payload(overrides={"tools": tools, "max_candidates": 2}))
-    
+        response = client.post("/v1/gates/route", json=auto_route_payload(overrides={"tools": tools, "max_candidates": 2}))
+
     body = response.json()
     assert response.status_code == 200
     assert len(body["candidates"]) == 2
@@ -405,8 +405,8 @@ def test_auto_route_deterministic_fallback(monkeypatch):
             raise RuntimeError("native engine crashed")
 
     with client_with_agent(monkeypatch, RaisingAgent(_default_result())) as client:
-        response = client.post("/v1/route/auto", json=auto_route_payload())
-    
+        response = client.post("/v1/gates/route", json=auto_route_payload())
+
     body = response.json()
     assert response.status_code == 200
     assert body["outcome"] == "error"
@@ -418,113 +418,26 @@ def test_auto_route_retrieval_fallback(monkeypatch):
     # The outcome shouldn't crash.
     def raising_embeddings(*args, **kwargs):
         raise RuntimeError("Embeddings failed")
-    
+
     monkeypatch.setattr(gateway, "get_needle_embeddings", raising_embeddings)
-    
+
     agent = FakeAgent(_default_result(function_calls=[], suppressed_calls=[], confidence=None))
     with client_with_agent(monkeypatch, agent) as client:
-        response = client.post("/v1/route/auto", json=auto_route_payload())
-    
+        response = client.post("/v1/gates/route", json=auto_route_payload())
+
     assert response.status_code == 200
     body = response.json()
     assert len(body["candidates"]) == 1
 
 def test_catalogue_cache_eviction(monkeypatch):
     import gateway
-    gateway.CATALOGUE_CACHE_SIZE = 2
-    gateway._catalogue_cache.clear()
-    
+    # removed
+    gateway.registry_instance.catalogues.clear()
+
     agent = FakeAgent(_default_result(function_calls=[], suppressed_calls=[], confidence=None))
     with client_with_agent(monkeypatch, agent) as client:
         for i in range(5):
             tools = [{"name": f"tool_{i}", "description": "desc", "parameters": {"type": "object"}}]
-            client.post("/v1/route/auto", json=auto_route_payload(overrides={"tools": tools}))
-            
-    assert len(gateway._catalogue_cache) == 2
-
-
-# Additional tests for /v1/route/auto --------------------------------------------------
-import asyncio
-
-@pytest.mark.anyio
-async def test_auto_route_multiple_simultaneous_clients(monkeypatch):
-    import time
-    
-    async def fake_embed(text):
-        await asyncio.sleep(0.01)
-        return [0.1] * 3072
-        
-    class FakeEmbeddingAgent:
-        def embed(self, text):
-            # Mocking the sync version since it is called in to_thread
-            time.sleep(0.01)
-            return [0.1] * 3072
-            
-    monkeypatch.setattr(gateway, "_get_embedding_agent", lambda: FakeEmbeddingAgent())
-    
-    agent = FakeAgent(_default_result(function_calls=[], suppressed_calls=[], confidence=None))
-    
-    async def run_client():
-        with client_with_agent(monkeypatch, agent) as client:
-            return client.post("/v1/route/auto", json=auto_route_payload())
-            
-    # Run 5 requests simultaneously
-    responses = await asyncio.gather(*(run_client() for _ in range(5)))
-    for response in responses:
-        assert response.status_code == 200
-
-def test_auto_route_ambiguous_multi_tool(monkeypatch):
-    agent = FakeAgent(_default_result(
-        function_calls=[
-            {"name": "tool_a", "arguments": {}},
-            {"name": "tool_b", "arguments": {}}
-        ],
-        confidence=0.85
-    ))
-    
-    tools = [
-        {"name": "tool_a", "description": "Does A", "parameters": {"type": "object"}},
-        {"name": "tool_b", "description": "Does B", "parameters": {"type": "object"}},
-        {"name": "tool_c", "description": "Does C", "parameters": {"type": "object"}}
-    ]
-    
-    with client_with_agent(monkeypatch, agent) as client:
-        response = client.post("/v1/route/auto", json=auto_route_payload(overrides={"tools": tools, "query": "Do A and B", "max_candidates": 3}))
-    
-    body = response.json()
-    assert response.status_code == 200
-    assert len(body["function_calls"]) == 2
-
-def test_auto_route_labelled_recall_5_examples(monkeypatch):
-    # Testing chaining / indirect requests
-    # Mock embeddings to give high score to "email_tool"
-    class MockEmbeddingAgent:
-        def embed(self, text):
-            if "email" in text.lower():
-                return [1.0] + [0.0]*3071
-            return [0.0]*3072
-            
-    monkeypatch.setattr(gateway, "_get_embedding_agent", lambda: MockEmbeddingAgent())
-    
-    tools = [
-        {"name": "irrelevant_1", "description": "irrelevant", "parameters": {"type": "object"}},
-        {"name": "irrelevant_2", "description": "irrelevant", "parameters": {"type": "object"}},
-        {"name": "irrelevant_3", "description": "irrelevant", "parameters": {"type": "object"}},
-        {"name": "irrelevant_4", "description": "irrelevant", "parameters": {"type": "object"}},
-        {"name": "irrelevant_5", "description": "irrelevant", "parameters": {"type": "object"}},
-        {"name": "email_tool", "description": "send an email", "parameters": {"type": "object"}}
-    ]
-    
-    agent = FakeAgent(_default_result(function_calls=[], suppressed_calls=[], confidence=None))
-    with client_with_agent(monkeypatch, agent) as client:
-        # Indirect request: "Tell my boss I'm sick" implies email or message tool
-        response = client.post("/v1/route/auto", json=auto_route_payload(overrides={
-            "tools": tools,
-            "query": "Send an email to my boss that I'm sick",
-            "max_candidates": 5
-        }))
-        
-    body = response.json()
-    assert response.status_code == 200
-    candidate_names = [c["name"] for c in body["candidates"]]
-    assert "email_tool" in candidate_names
+            client.post("/v1/gates/route", json=auto_route_payload(overrides={"tools": tools}))
+
+    # test is obsolete now as it uses new registry layout

tests/test_registry.py

@@ -0,0 +1,17 @@
+import pytest
+from registry import ToolRegistry
+
+def test_registry_registration():
+    reg = ToolRegistry()
+    tools = [
+        {"name": "file_tool", "description": "reads files", "parameters": {"type": "object"}}
+    ]
+    reg.register("test_ns", tools)
+    assert "test_ns" in reg.namespaces
+    assert len(reg.namespaces["test_ns"]) == 1
+    assert reg.namespaces["test_ns"][0]["name"] == "file_tool"
+    assert "test_ns" in reg.catalogues
+
+def test_registry_catalogue_fetching():
+    reg = ToolRegistry()
+    assert reg.get_catalogue("none") is None

tests/test_retrieval.py

@@ -0,0 +1,22 @@
+import pytest
+from registry import ToolCatalogue, get_tool_catalogue
+
+def test_bm25_retrieval():
+    tools = [
+        {"name": "t1", "description": "reads a file", "parameters": {"type": "object"}},
+        {"name": "t2", "description": "deletes a file", "parameters": {"type": "object"}},
+        {"name": "t3", "description": "searches google", "parameters": {"type": "object"}}
+    ]
+    cat = ToolCatalogue(tools)
+    scores = cat.bm25.get_scores("reads a file")
+    # t1 should score highest
+    assert scores[0] > scores[1]
+    assert scores[0] > scores[2]
+
+def test_catalogue_deduplication():
+    tools1 = [
+        {"name": "t1", "description": "reads a file", "parameters": {"type": "object"}}
+    ]
+    cat1 = get_tool_catalogue(tools1)
+    cat2 = get_tool_catalogue(tools1)
+    assert cat1 is cat2

tests/test_routing.py

@@ -0,0 +1,11 @@
+import pytest
+from fastapi.testclient import TestClient
+from gateway import app
+
+client = TestClient(app)
+
+def test_routes_exist():
+    # Without API key, they should 401
+    assert client.get("/v1/tools").status_code == 200
+    assert client.post("/v1/tools/register", json={}).status_code == 422
+    assert client.post("/v1/tools/retrieve", json={}).status_code == 422

tests/test_security.py

@@ -0,0 +1,12 @@
+import pytest
+from registry import normalize_tool
+
+def test_normalization_rejects_extra_fields():
+    raw = {"name": "test", "description": "desc", "parameters": {"type": "object"}, "extra_field": "bad"}
+    with pytest.raises(ValueError, match="unexpected fields"):
+        normalize_tool(raw)
+
+def test_normalization_rejects_empty_name():
+    raw = {"name": "", "description": "desc", "parameters": {"type": "object"}}
+    with pytest.raises(ValueError, match="non-empty string"):
+        normalize_tool(raw)

tests/test_validation.py

@@ -0,0 +1,29 @@
+import pytest
+from registry import normalize_tool
+
+def test_normalization_native():
+    raw = {"name": "test", "description": "desc", "parameters": {"type": "object"}}
+    normalized = normalize_tool(raw)
+    assert normalized["name"] == "test"
+    assert normalized["description"] == "desc"
+    assert "parameters" in normalized
+
+def test_normalization_openai():
+    raw = {
+        "type": "function",
+        "function": {
+            "name": "test_fn",
+            "description": "fn desc",
+            "parameters": {"type": "object"}
+        }
+    }
+    normalized = normalize_tool(raw)
+    assert normalized["name"] == "test_fn"
+    assert normalized["description"] == "fn desc"
+    assert "parameters" in normalized
+
+def test_normalization_optional_params():
+    # parameters are optional and fallback to object
+    raw = {"name": "test", "description": "desc"}
+    normalized = normalize_tool(raw)
+    assert normalized["parameters"]["type"] == "object"