feat: remove powered-by line and integrate sidecar with sentence-level streaming

gemini_adapter.py

@@ -1,25 +1,29 @@
 """
 gemini_adapter.py — Concrete LLMAdapter for Google Gemini.
 
-V2: Reads API key from GEMINI_API_KEY environment variable.
+V3 (Sidecar): adds stream_chat() for sentence-level streaming.
 """
 
 import os
+from typing import AsyncGenerator, Optional
+
 import google.generativeai as genai
-from typing import Optional
+
 from llm_adapter import LLMAdapter
 
 
 class GeminiAdapter(LLMAdapter):
     """
     Wraps Google Gemini API as an LLMAdapter.
+
+    Supports both blocking `chat()` and streaming `stream_chat()`.
     """
 
     def __init__(
         self,
-        api_key: Optional[str] = None,
-        model_name: str = "gemini-3.1-flash-lite",
-        system_prompt: Optional[str] = None
+        api_key:       Optional[str] = None,
+        model_name:    str = "gemini-2.0-flash-lite",
+        system_prompt: Optional[str] = None,
     ):
         self.api_key = api_key or os.getenv("GEMINI_API_KEY")
         if not self.api_key:
@@ -28,27 +32,63 @@ class GeminiAdapter(LLMAdapter):
                 "or pass api_key directly."
             )
 
-        self.model_name = model_name
+        self.model_name    = model_name
         self.system_prompt = system_prompt or "You are a helpful AI assistant."
 
         genai.configure(api_key=self.api_key)
-        self.model = genai.GenerativeModel(
+        self._model = genai.GenerativeModel(
             model_name=self.model_name,
-            system_instruction=self.system_prompt
+            system_instruction=self.system_prompt,
         )
 
+    # ------------------------------------------------------------------
+    # Blocking interface (existing — unchanged)
+    # ------------------------------------------------------------------
+
     def chat(self, prompt: str, system_prompt: Optional[str] = None) -> str:
-        # If a different system prompt is provided at runtime, we recreate the model
-        # (Gemini system instructions are set at model instantiation)
-        current_model = self.model
+        """Send prompt, return full response text (blocking)."""
+        model = self._get_model(system_prompt)
+        response = model.generate_content(prompt)
+        return response.text
+
+    # ------------------------------------------------------------------
+    # Streaming interface (NEW)
+    # ------------------------------------------------------------------
+
+    async def stream_chat(
+        self,
+        prompt:        str,
+        system_prompt: Optional[str] = None,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Yield token chunks from Gemini as they arrive.
+
+        This is a synchronous SDK call wrapped in an async generator —
+        Gemini's Python SDK streams synchronously, so we iterate the
+        response object directly and yield each text chunk.
+        """
+        model = self._get_model(system_prompt)
+
+        # generate_content with stream=True returns a synchronous iterator
+        response = model.generate_content(prompt, stream=True)
+
+        for chunk in response:
+            text = getattr(chunk, "text", None)
+            if text:
+                yield text
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _get_model(self, system_prompt: Optional[str]):
+        """Return model instance, recreating if system prompt differs."""
         if system_prompt and system_prompt != self.system_prompt:
-            current_model = genai.GenerativeModel(
+            return genai.GenerativeModel(
                 model_name=self.model_name,
-                system_instruction=system_prompt
+                system_instruction=system_prompt,
             )
-
-        response = current_model.generate_content(prompt)
-        return response.text
+        return self._model
 
     def get_model_name(self) -> str:
         return self.model_name

genai_app.py

@@ -19,6 +19,7 @@ import os
 import json
 import time
 import queue
+import threading
 from flask import Flask, request, jsonify, render_template, Response, stream_with_context
 from flask_cors import CORS
 
@@ -76,6 +77,16 @@ def broadcast(event_type: str, data: dict):
 def index():
     return render_template("genai.html", model=ADAPTER.get_model_name())
 
+@app.route("/sidecar")
+def sidecar_ui():
+    """Sidecar streaming chat UI."""
+    return render_template("sidecar.html")
+
+@app.route("/dataflow")
+def dataflow_ui():
+    """Real-time data flow visualization dashboard."""
+    return render_template("dataflow.html")
+
 @app.route("/genai-monitoring")
 def monitoring():
     return render_template("genai_monitoring.html", model=ADAPTER.get_model_name())
@@ -240,9 +251,35 @@ def guard_stats():
     return jsonify(PG_ENGINE.stats())
 
 
+def _start_sidecar_subprocess():
+    """
+    Optionally launch the sidecar as a sub-process so both UIs run together.
+    Controlled via LAUNCH_SIDECAR=true env var.
+    """
+    import subprocess, sys
+    sidecar_port = int(os.getenv("SIDECAR_PORT", 5050))
+    print(f"[GenAI Shield] Launching sidecar on :{sidecar_port}...")
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "sidecar.app:app",
+         "--host", "0.0.0.0", "--port", str(sidecar_port),
+         "--log-level", "warning"],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+    )
+    def _pipe():
+        for line in proc.stdout:
+            print("[sidecar]", line.decode(errors='replace').rstrip())
+    threading.Thread(target=_pipe, daemon=True).start()
+    return proc
+
+
 if __name__ == "__main__":
     port = int(os.getenv("GENAI_PORT", 5001))
     print(f"GenAI Shield V2 starting on port {port}")
     print(f"LLM Model: {ADAPTER.get_model_name()}")
     print(f"Guard:     Llama-Prompt-Guard-2-86M")
-    app.run(host="0.0.0.0", port=port, debug=True)
+    print(f"Sidecar UI: http://localhost:{port}/sidecar")
+
+    if os.getenv("LAUNCH_SIDECAR", "").lower() in ("1", "true", "yes"):
+        _start_sidecar_subprocess()
+
+    app.run(host="0.0.0.0", port=port, debug=False)

llm_adapter.py

@@ -1,40 +1,47 @@
 """
-llm_adapter.py — Abstract base class for LLM adapters.
+llm_adapter.py — Abstract base class for all LLM adapters.
 
-Any LLM (OpenAI, OpenRouter, Ollama, Anthropic, local) can be plugged into
-the TextMonitor by subclassing LLMAdapter and implementing its two methods.
+V3 (Sidecar): adds stream_chat() abstract method.
 """
 
 from abc import ABC, abstractmethod
-from typing import Optional
+from typing import AsyncGenerator, Optional
 
 
 class LLMAdapter(ABC):
     """
-    Abstract interface that TextMonitor depends on.
+    Minimal interface that all LLM adapters must implement.
 
-    Subclass this for any LLM you want to monitor.
+    Methods
+    -------
+    chat(prompt, system_prompt) -> str
+        Blocking single-turn call. Returns full response text.
+
+    stream_chat(prompt, system_prompt) -> AsyncGenerator[str, None]
+        Async streaming call. Yields token chunks as they arrive.
+
+    get_model_name() -> str
+        Returns the model identifier string.
     """
 
     @abstractmethod
-    def chat(
+    def chat(self, prompt: str, system_prompt: Optional[str] = None) -> str:
+        """Blocking call — return full response as a string."""
+        ...
+
+    @abstractmethod
+    async def stream_chat(
         self,
-        prompt: str,
+        prompt:        str,
         system_prompt: Optional[str] = None,
-    ) -> str:
-        """
-        Send a prompt to the LLM and return the response text.
-
-        Args:
-            prompt:        The user's message.
-            system_prompt: Optional system prompt to prepend.
-
-        Returns:
-            The model's response as a plain string.
-        """
+    ) -> AsyncGenerator[str, None]:
+        """Async generator — yield token chunks as they arrive."""
         ...
+        # Make this an async generator (required by ABC)
+        # Concrete classes must use `yield` in their implementation
+        yield  # type: ignore[misc]
 
     @abstractmethod
     def get_model_name(self) -> str:
-        """Return a human-readable name for the model being used."""
+        """Return the model identifier (e.g. 'gemini-2.0-flash-lite')."""
         ...

openai_adapter.py

@@ -1,16 +1,19 @@
 """
 openai_adapter.py — Concrete LLMAdapter for OpenAI / OpenRouter / Ollama.
 
-Works with any OpenAI-compatible API. Configure via environment variables:
+V3 (Sidecar): adds stream_chat() for sentence-level streaming.
 
+Works with any OpenAI-compatible API. Configure via environment variables:
   OPENAI_API_KEY=sk-...
-  OPENAI_BASE_URL=https://openrouter.ai/api/v1   (or https://api.openai.com/v1)
-  OPENAI_MODEL=openai/gpt-4o-mini                (or gpt-4o, llama3, etc.)
+  OPENAI_BASE_URL=https://openrouter.ai/api/v1
+  OPENAI_MODEL=gpt-4o-mini
 """
 
 import os
-from typing import Optional
-from openai import OpenAI
+from typing import AsyncGenerator, Optional
+
+from openai import AsyncOpenAI, OpenAI
+
 from llm_adapter import LLMAdapter
 
 
@@ -20,10 +23,8 @@ class OpenAIAdapter(LLMAdapter):
 
     Args:
         api_key:      API key. Defaults to OPENAI_API_KEY env var.
-        base_url:     API base URL. Defaults to OPENAI_BASE_URL env var,
-                      or https://api.openai.com/v1 if not set.
-        model:        Model name. Defaults to OPENAI_MODEL env var,
-                      or gpt-4o-mini if not set.
+        base_url:     API base URL. Defaults to OPENAI_BASE_URL env var.
+        model:        Model name. Defaults to OPENAI_MODEL env var.
         system_prompt: Default system prompt for all calls.
         temperature:   Sampling temperature (0 = deterministic).
         max_tokens:    Max tokens in response.
@@ -38,8 +39,8 @@ class OpenAIAdapter(LLMAdapter):
         base_url:      Optional[str] = None,
         model:         Optional[str] = None,
         system_prompt: Optional[str] = None,
-        temperature:   float         = 0.7,
-        max_tokens:    int           = 1024,
+        temperature:   float = 0.7,
+        max_tokens:    int   = 1024,
     ):
         self._api_key  = api_key  or os.getenv("OPENAI_API_KEY", "")
         self._base_url = base_url or os.getenv("OPENAI_BASE_URL", self.DEFAULT_BASE_URL)
@@ -51,13 +52,14 @@ class OpenAIAdapter(LLMAdapter):
         self._temperature = temperature
         self._max_tokens  = max_tokens
 
-        self._client = OpenAI(
-            api_key  = self._api_key,
-            base_url = self._base_url,
-        )
+        # Synchronous client (existing blocking interface)
+        self._client = OpenAI(api_key=self._api_key, base_url=self._base_url)
+
+        # Async client (streaming interface)
+        self._async_client = AsyncOpenAI(api_key=self._api_key, base_url=self._base_url)
 
     # ------------------------------------------------------------------
-    # LLMAdapter interface
+    # Blocking interface (existing — unchanged)
     # ------------------------------------------------------------------
 
     def chat(
@@ -65,19 +67,48 @@ class OpenAIAdapter(LLMAdapter):
         prompt:        str,
         system_prompt: Optional[str] = None,
     ) -> str:
-        """Send prompt to LLM and return response text."""
-        sys_msg = system_prompt or self._system_prompt
-
+        """Send prompt to LLM and return response text (blocking)."""
+        sys_msg  = system_prompt or self._system_prompt
         response = self._client.chat.completions.create(
-            model    = self._model,
-            messages = [
-                {"role": "system",  "content": sys_msg},
-                {"role": "user",    "content": prompt},
+            model       = self._model,
+            messages    = [
+                {"role": "system", "content": sys_msg},
+                {"role": "user",   "content": prompt},
             ],
             temperature = self._temperature,
             max_tokens  = self._max_tokens,
         )
         return response.choices[0].message.content or ""
 
+    # ------------------------------------------------------------------
+    # Streaming interface (NEW)
+    # ------------------------------------------------------------------
+
+    async def stream_chat(
+        self,
+        prompt:        str,
+        system_prompt: Optional[str] = None,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Yield token chunks from OpenAI as they arrive (true async streaming).
+        """
+        sys_msg = system_prompt or self._system_prompt
+
+        stream = await self._async_client.chat.completions.create(
+            model       = self._model,
+            messages    = [
+                {"role": "system", "content": sys_msg},
+                {"role": "user",   "content": prompt},
+            ],
+            temperature = self._temperature,
+            max_tokens  = self._max_tokens,
+            stream      = True,
+        )
+
+        async for chunk in stream:
+            delta = chunk.choices[0].delta
+            if delta and delta.content:
+                yield delta.content
+
     def get_model_name(self) -> str:
         return self._model

requirements.txt

@@ -5,3 +5,7 @@ transformers
 google-generativeai
 openai
 huggingface-hub
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+httpx>=0.27.0
+python-multipart

sidecar/__init__.py

@@ -0,0 +1 @@
+# GenAI Shield V2 — Sidecar Package

sidecar/app.py

@@ -0,0 +1,446 @@
+"""
+sidecar/app.py — GenAI Shield V2 Sidecar Proxy (FastAPI).
+
+A language-agnostic sidecar that sits in front of any LLM API and provides:
+  • Pre-inference guard (Prompt Guard model + regex) — runs in parallel with LLM
+  • Sentence-level streaming — users see output word-by-word
+  • Post-inference monitoring — each sentence checked concurrently in background
+  • Block signal mid-stream — if output turns harmful, client is notified instantly
+
+Endpoints
+---------
+  POST /v1/chat          → streaming or blocking chat with full shield
+  GET  /v1/health        → liveness probe
+  GET  /v1/stats         → guard model statistics
+  GET  /v1/metrics       → last-request latency breakdown
+
+SSE Event Schema (stream=true)
+-------------------------------
+  { "type": "chunk",        "text": "..." }
+  { "type": "sentence",     "text": "...", "sentence_id": 1 }
+  { "type": "block_signal", "sentence_id": 3, "reason": "...", "threat_score": 85, "flags": [...] }
+  { "type": "done",         "threat_score": 5, "flags": [], "latency_ms": 420,
+                             "guard_ms": 98, "sentences": 4 }
+  { "type": "blocked",      "reason": "...", "threat_score": 100, "flags": [...],
+                             "pg_score": 0.97, "guard_ms": 102 }
+
+Configure via environment variables (see sidecar/config.py).
+"""
+
+import json
+import logging
+import os
+import sys
+import time
+from pathlib import Path
+from typing import AsyncGenerator, Optional
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+# ── Path fix so imports work from project root ────────────────────────────────
+_ROOT = Path(__file__).parent.parent
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+
+from sidecar.config import (
+    GATE_GUARD_TIMEOUT_SEC,
+    GEMINI_API_KEY,
+    GEMINI_MODEL,
+    LLM_BACKEND,
+    LOG_LEVEL,
+    MONITOR_BLOCK_THRESHOLD,
+    MONITOR_WORKERS,
+    OPENAI_API_KEY,
+    OPENAI_BASE_URL,
+    OPENAI_MODEL,
+    PROMPT_GUARD_MODEL_DIR,
+    SENTENCE_MIN_CHARS,
+    SIDECAR_HOST,
+    SIDECAR_PORT,
+    SYSTEM_PROMPT,
+)
+from sidecar.gate             import BlockEvent, ShieldGate, TokenEvent
+from sidecar.sentence_splitter import SentenceEvent, SentenceSplitter
+from sidecar.stream_monitor   import BlockSignal, StreamMonitor
+from sidecar.pipeline_events  import RequestTrace, subscribe, unsubscribe
+
+# Existing shield modules
+from prompt_guard_engine     import PromptGuardEngine
+from prompt_guard_text_guard import PromptGuardTextGuard
+from text_monitor            import TextMonitor
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+logging.basicConfig(
+    level    = getattr(logging, LOG_LEVEL.upper(), logging.INFO),
+    format   = "[%(asctime)s] %(levelname)-8s %(name)s — %(message)s",
+    datefmt  = "%H:%M:%S",
+)
+log = logging.getLogger("sidecar")
+
+# ── FastAPI app ───────────────────────────────────────────────────────────────
+app = FastAPI(
+    title       = "GenAI Shield Sidecar",
+    description = "Transparent LLM proxy with pre/post-inference security screening",
+    version     = "2.0.0",
+)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins  = ["*"],
+    allow_methods  = ["*"],
+    allow_headers  = ["*"],
+)
+
+# Serve static files if the sidecar runs standalone
+_STATIC_DIR    = _ROOT / "static"
+_TEMPLATES_DIR = _ROOT / "templates"
+if _STATIC_DIR.exists():
+    app.mount("/static", StaticFiles(directory=str(_STATIC_DIR)), name="static")
+
+# ── Initialise shield components ──────────────────────────────────────────────
+log.info("Loading Prompt Guard engine...")
+_PG_ENGINE = PromptGuardEngine(model_path=Path(PROMPT_GUARD_MODEL_DIR)).load()
+_GUARD     = PromptGuardTextGuard(_PG_ENGINE)
+log.info("Prompt Guard ready.")
+
+# ── Initialise LLM adapter ────────────────────────────────────────────────────
+if LLM_BACKEND == "openai":
+    from openai_adapter import OpenAIAdapter
+    _ADAPTER = OpenAIAdapter(
+        api_key       = OPENAI_API_KEY,
+        base_url      = OPENAI_BASE_URL,
+        model         = OPENAI_MODEL,
+        system_prompt = SYSTEM_PROMPT,
+    )
+else:
+    from gemini_adapter import GeminiAdapter
+    _ADAPTER = GeminiAdapter(
+        api_key       = GEMINI_API_KEY,
+        model_name    = GEMINI_MODEL,
+        system_prompt = SYSTEM_PROMPT,
+    )
+
+log.info("LLM adapter: %s (%s)", LLM_BACKEND, _ADAPTER.get_model_name())
+
+# ── Shared monitor (stateful — tracks behavioural drift across requests) ──────
+_TEXT_MONITOR   = TextMonitor(_ADAPTER, system_prompt=SYSTEM_PROMPT)
+_STREAM_MONITOR = StreamMonitor(_TEXT_MONITOR, block_threshold=MONITOR_BLOCK_THRESHOLD, max_workers=MONITOR_WORKERS)
+
+# ── Last-request metrics (lightweight, single-threaded access via asyncio) ────
+_LAST_METRICS: dict = {}
+
+
+# ── Request schema ────────────────────────────────────────────────────────────
+
+class ChatRequest(BaseModel):
+    prompt:        str
+    stream:        bool   = True
+    system_prompt: Optional[str] = None
+    source:        Optional[str] = "sidecar"
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+@app.get("/")
+async def root():
+    """Serve the sidecar streaming UI (standalone mode)."""
+    ui_file = _TEMPLATES_DIR / "sidecar.html"
+    if ui_file.exists():
+        return FileResponse(str(ui_file), media_type="text/html")
+    return {"message": "GenAI Shield Sidecar", "docs": "/docs"}
+
+
+@app.get("/dataflow")
+async def dataflow_ui():
+    """Serve the real-time data flow visualization dashboard."""
+    ui_file = _TEMPLATES_DIR / "dataflow.html"
+    if ui_file.exists():
+        return FileResponse(str(ui_file), media_type="text/html")
+    return {"message": "dataflow.html not found"}
+
+
+@app.get("/v1/pipeline-stream")
+async def pipeline_stream():
+    """
+    SSE stream of structured pipeline telemetry events.
+    The data flow dashboard subscribes here to get real-time stage data.
+    """
+    async def _gen():
+        import asyncio
+        q = subscribe()
+        try:
+            while True:
+                try:
+                    # Poll queue with a short timeout so we can yield keepalives
+                    payload = q.get_nowait()
+                    yield f"data: {json.dumps(payload)}\n\n"
+                except Exception:
+                    # No event — send keepalive comment
+                    yield ": keepalive\n\n"
+                    await asyncio.sleep(0.5)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            unsubscribe(q)
+
+    return StreamingResponse(
+        _gen(),
+        media_type = "text/event-stream",
+        headers    = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+@app.get("/v1/health")
+async def health():
+    return {
+        "status":      "ok",
+        "guard_ready": _PG_ENGINE.ready,
+        "model":       _ADAPTER.get_model_name(),
+        "backend":     LLM_BACKEND,
+    }
+
+
+@app.get("/v1/stats")
+async def stats():
+    return _PG_ENGINE.stats()
+
+
+@app.get("/v1/metrics")
+async def metrics():
+    return _LAST_METRICS or {"message": "No requests processed yet"}
+
+
+@app.post("/v1/chat")
+async def chat(req: ChatRequest):
+    """
+    Main chat endpoint.
+
+    - stream=true  → Server-Sent Events (SSE) with sentence-level output
+    - stream=false → Blocking JSON response (legacy-compatible)
+    """
+    if not req.prompt.strip():
+        raise HTTPException(status_code=400, detail="Empty prompt")
+
+    sys_prompt = req.system_prompt or SYSTEM_PROMPT
+
+    if req.stream:
+        return StreamingResponse(
+            _stream_handler(req.prompt, sys_prompt, req.source or "sidecar"),
+            media_type = "text/event-stream",
+            headers    = {
+                "Cache-Control": "no-cache",
+                "X-Accel-Buffering": "no",   # disable nginx buffering
+            },
+        )
+    else:
+        return await _blocking_handler(req.prompt, sys_prompt, req.source or "sidecar")
+
+
+# ── Streaming handler ─────────────────────────────────────────────────────────
+
+async def _stream_handler(
+    prompt:     str,
+    sys_prompt: str,
+    source:     str,
+) -> AsyncGenerator[str, None]:
+    """
+    Full streaming pipeline:
+      Gate (guard ∥ LLM) → SentenceSplitter → StreamMonitor (background)
+    """
+    t_total      = time.perf_counter()
+    gate         = ShieldGate(_GUARD, _ADAPTER, guard_timeout_sec=GATE_GUARD_TIMEOUT_SEC)
+    splitter     = SentenceSplitter(min_chars=SENTENCE_MIN_CHARS)
+    _STREAM_MONITOR.reset()
+
+    # ── Telemetry trace for this request ──────────────────────────────────
+    trace = RequestTrace()
+    trace.on_request_in(prompt)
+
+    guard_ms_ref     = 0.0
+    all_flags:  list = []
+    threat_score     = 0
+    block_fired      = False
+    sentences_sent   = 0
+    total_tokens     = 0
+
+    def sse(event_dict: dict) -> str:
+        """Format a dict as an SSE data line."""
+        return f"data: {json.dumps(event_dict)}\n\n"
+
+    async for gate_event in gate.run(prompt, sys_prompt, trace=trace):
+
+        # ── Guard blocked the prompt ───────────────────────────────────────
+        if isinstance(gate_event, BlockEvent):
+            all_flags    = gate_event.flags
+            threat_score = gate_event.threat_score
+            guard_ms_ref = gate_event.guard_ms
+
+            yield sse({
+                "type":         "blocked",
+                "reason":       gate_event.reason,
+                "threat_score": gate_event.threat_score,
+                "flags":        gate_event.flags,
+                "pg_score":     gate_event.pg_score,
+                "guard_ms":     gate_event.guard_ms,
+            })
+            block_fired = True
+            break
+
+        # ── LLM token received ─────────────────────────────────────────────
+        if isinstance(gate_event, TokenEvent):
+            total_tokens += 1
+            splitter_events = splitter.feed(gate_event.text)
+
+            for ev in splitter_events:
+                if isinstance(ev, type(ev)) and ev.type == "chunk":
+                    yield sse({"type": "chunk", "text": ev.text})
+
+                elif ev.type == "sentence":
+                    sentences_sent += 1
+                    trace.on_sentence_ready(ev.sentence_id, ev.text)
+                    yield sse({
+                        "type":        "sentence",
+                        "text":        ev.text,
+                        "sentence_id": ev.sentence_id,
+                    })
+                    # Submit to background monitor (non-blocking)
+                    trace.on_monitor_start(ev.sentence_id)
+                    await _STREAM_MONITOR.submit(ev.sentence_id, ev.text, prompt)
+
+    if block_fired:
+        total_ms = round((time.perf_counter() - t_total) * 1000, 2)
+        trace.on_request_done(threat_score, all_flags, blocked=True)
+        _update_metrics(threat_score, all_flags, guard_ms_ref, 0, 0, total_ms)
+        return
+
+    # ── Stream ended — flush remaining buffer ──────────────────────────────
+    for ev in splitter.flush():
+        sentences_sent += 1
+        trace.on_sentence_ready(ev.sentence_id, ev.text)
+        yield sse({"type": "sentence", "text": ev.text, "sentence_id": ev.sentence_id})
+        trace.on_monitor_start(ev.sentence_id)
+        await _STREAM_MONITOR.submit(ev.sentence_id, ev.text, prompt)
+
+    trace.on_stream_done(total_tokens, sentences_sent)
+
+    # ── Collect background monitor results ─────────────────────────────────
+    signals = await _STREAM_MONITOR.collect(timeout=1.5)
+
+    for sig in signals:
+        threat_score = max(threat_score, sig.threat_score)
+        all_flags.extend(sig.flags)
+        trace.on_monitor_result(sig.sentence_id, sig.threat_score, sig.flags, blocked=True)
+        yield sse({
+            "type":         "block_signal",
+            "sentence_id":  sig.sentence_id,
+            "reason":       sig.reason,
+            "threat_score": sig.threat_score,
+            "flags":        sig.flags,
+        })
+
+    total_ms = round((time.perf_counter() - t_total) * 1000, 2)
+    trace.on_request_done(threat_score, list(set(all_flags)), blocked=False)
+
+    yield sse({
+        "type":         "done",
+        "threat_score": threat_score,
+        "flags":        list(set(all_flags)),
+        "latency_ms":   total_ms,
+        "sentences":    sentences_sent,
+    })
+
+    _update_metrics(threat_score, all_flags, 0, 0, total_ms, total_ms)
+
+
+# ── Blocking handler (non-streaming, backward-compatible) ─────────────────────
+
+async def _blocking_handler(prompt: str, sys_prompt: str, source: str) -> dict:
+    """
+    Non-streaming path — guard first, then full LLM call, then monitor.
+    Compatible with existing /genai-chat behaviour.
+    """
+    import asyncio
+
+    t_start = time.perf_counter()
+
+    # Guard (in thread — synchronous)
+    loop         = asyncio.get_event_loop()
+    guard_result = await loop.run_in_executor(None, _GUARD.screen, prompt)
+    guard_ms     = round((time.perf_counter() - t_start) * 1000, 2)
+
+    pg_score = guard_result.get("checks", {}).get("prompt_guard", {}).get("malicious_score", 0.0)
+
+    if guard_result["blocked"]:
+        return {
+            "blocked":      True,
+            "response":     None,
+            "reason":       guard_result["reason"],
+            "threat_score": guard_result["threat_score"],
+            "flags":        guard_result["flags"],
+            "pg_score":     pg_score,
+            "latency_breakdown": {"guard_ms": guard_ms, "model_ms": 0, "monitor_ms": 0},
+        }
+
+    # LLM call (blocking adapter)
+    t_model  = time.perf_counter()
+    response = await loop.run_in_executor(None, _ADAPTER.chat, prompt, sys_prompt)
+    model_ms = round((time.perf_counter() - t_model) * 1000, 2)
+
+    # Post-monitor
+    t_monitor    = time.perf_counter()
+    mon_result   = await loop.run_in_executor(None, _TEXT_MONITOR.analyze, prompt, response)
+    monitor_ms   = round((time.perf_counter() - t_monitor) * 1000, 2)
+
+    total_ms     = round(guard_ms + model_ms + monitor_ms, 2)
+    threat_score = max(guard_result["threat_score"], mon_result["threat_score"])
+    all_flags    = guard_result["flags"] + mon_result["flags"]
+
+    _update_metrics(threat_score, all_flags, guard_ms, model_ms, monitor_ms, total_ms)
+
+    return {
+        "blocked":      False,
+        "response":     response,
+        "threat_score": threat_score,
+        "flags":        all_flags,
+        "pg_score":     pg_score,
+        "latency_ms":   total_ms,
+        "model":        _ADAPTER.get_model_name(),
+        "latency_breakdown": {
+            "guard_ms":   guard_ms,
+            "model_ms":   model_ms,
+            "monitor_ms": monitor_ms,
+        },
+    }
+
+
+# ── Metrics helper ─────────────────────────────────────────────────────────────
+
+def _update_metrics(threat_score, flags, guard_ms, model_ms, monitor_ms, total_ms):
+    global _LAST_METRICS
+    _LAST_METRICS = {
+        "threat_score": threat_score,
+        "flags":        flags,
+        "guard_ms":     guard_ms,
+        "model_ms":     model_ms,
+        "monitor_ms":   monitor_ms,
+        "total_ms":     total_ms,
+        "model":        _ADAPTER.get_model_name(),
+        "timestamp":    time.strftime("%H:%M:%S"),
+    }
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    log.info("Starting GenAI Shield Sidecar on %s:%d", SIDECAR_HOST, SIDECAR_PORT)
+    uvicorn.run(
+        "sidecar.app:app",
+        host        = SIDECAR_HOST,
+        port        = SIDECAR_PORT,
+        log_level   = LOG_LEVEL.lower(),
+        reload      = False,
+    )

sidecar/config.py

@@ -0,0 +1,53 @@
+"""
+sidecar/config.py — Centralised configuration for the GenAI Shield Sidecar.
+
+All runtime behaviour is controlled via environment variables.
+Defaults are safe for local development.
+"""
+
+import os
+
+# ── Sidecar server ────────────────────────────────────────────────────────────
+SIDECAR_HOST     = os.getenv("SIDECAR_HOST", "0.0.0.0")
+SIDECAR_PORT     = int(os.getenv("SIDECAR_PORT", "5050"))
+
+# ── LLM backend ───────────────────────────────────────────────────────────────
+LLM_BACKEND      = os.getenv("LLM_BACKEND", "gemini")   # "gemini" | "openai"
+GEMINI_API_KEY   = os.getenv("GEMINI_API_KEY", "")
+GEMINI_MODEL     = os.getenv("GEMINI_MODEL", "gemini-2.0-flash-lite")
+
+OPENAI_API_KEY   = os.getenv("OPENAI_API_KEY", "")
+OPENAI_BASE_URL  = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+OPENAI_MODEL     = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+
+# ── System prompt ─────────────────────────────────────────────────────────────
+SYSTEM_PROMPT = os.getenv(
+    "GENAI_SYSTEM_PROMPT",
+    "You are a helpful AI assistant. Be concise, accurate, and professional.",
+)
+
+# ── Shield thresholds ─────────────────────────────────────────────────────────
+GUARD_BLOCK_THRESHOLD   = float(os.getenv("GUARD_BLOCK_THRESHOLD",   "0.85"))
+GUARD_FLAG_THRESHOLD    = float(os.getenv("GUARD_FLAG_THRESHOLD",    "0.50"))
+MONITOR_BLOCK_THRESHOLD = int(os.getenv("MONITOR_BLOCK_THRESHOLD",  "40"))
+
+# ── Gate behaviour ────────────────────────────────────────────────────────────
+# Max ms to wait for guard verdict before letting buffered tokens through anyway
+# (safety valve — guard should always be <300ms in practice)
+GATE_GUARD_TIMEOUT_SEC  = float(os.getenv("GATE_GUARD_TIMEOUT_SEC", "3.0"))
+
+# ── Post-monitor thread pool ──────────────────────────────────────────────────
+MONITOR_WORKERS         = int(os.getenv("MONITOR_WORKERS", "4"))
+
+# ── Sentence splitter ─────────────────────────────────────────────────────────
+# Minimum characters before a sentence boundary is declared
+SENTENCE_MIN_CHARS      = int(os.getenv("SENTENCE_MIN_CHARS", "20"))
+
+# ── Model path ────────────────────────────────────────────────────────────────
+PROMPT_GUARD_MODEL_DIR  = os.getenv(
+    "PROMPT_GUARD_MODEL_DIR",
+    "models/Llama-Prompt-Guard-2-86M",
+)
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")

sidecar/gate.py

@@ -0,0 +1,209 @@
+"""
+sidecar/gate.py — Concurrent Guard + LLM Fan-Out Gate.
+
+The Gate is the heart of the sidecar. It starts the Prompt Guard check
+and the LLM stream simultaneously, then:
+
+  • If Guard BLOCKS  → cancel the LLM stream, yield a BlockEvent, stop.
+  • If Guard PASSES  → open the gate; yield all buffered + live tokens.
+
+This means the guard's latency (~50–150ms) is hidden inside the LLM's
+time-to-first-token (~300–600ms). On the happy path the user effectively
+sees ZERO added latency from the guard.
+
+                     ┌────────────────────────────────┐
+  Client  ──prompt──►│  Gate.run()                    │
+                     │                                │
+                     │  Task A: guard.screen(prompt)  │ ~100ms
+                     │  Task B: adapter.stream_chat() │ ~500ms TTFT
+                     │                                │
+                     │  Guard finishes first?          │
+                     │    blocked=True  → cancel B    │──► BlockEvent
+                     │    blocked=False → open gate   │──► yield buffered tokens
+                     │                                │──► yield live tokens…
+                     └────────────────────────────────┘
+"""
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import AsyncGenerator, List, Optional, Union
+
+log = logging.getLogger(__name__)
+
+
+# ── Gate events ───────────────────────────────────────────────────────────────
+
+@dataclass
+class TokenEvent:
+    """A raw token chunk from the LLM — pass through to client."""
+    text: str
+    type: str = field(default="token", init=False)
+
+
+@dataclass
+class BlockEvent:
+    """Guard blocked the prompt — LLM never delivered output to client."""
+    reason:       str
+    threat_score: int
+    flags:        List[str]
+    pg_score:     float
+    guard_ms:     float
+    type:         str = field(default="blocked", init=False)
+
+
+GateEvent = Union[TokenEvent, BlockEvent]
+
+
+# ── The Gate ──────────────────────────────────────────────────────────────────
+
+class ShieldGate:
+    """
+    Orchestrates concurrent Guard check + LLM stream with a buffering gate.
+
+    Args:
+        guard:               PromptGuardTextGuard instance.
+        adapter:             LLMAdapter with stream_chat().
+        guard_timeout_sec:   Max seconds to wait for guard before passing anyway.
+                             (Safety valve — guard should always be < 300ms.)
+    """
+
+    def __init__(self, guard, adapter, guard_timeout_sec: float = 3.0):
+        self._guard   = guard
+        self._adapter = adapter
+        self._timeout = guard_timeout_sec
+
+    async def run(
+        self,
+        prompt:        str,
+        system_prompt: str = "",
+        trace=None,        # Optional[RequestTrace] — for pipeline telemetry
+    ) -> AsyncGenerator[GateEvent, None]:
+        """
+        Async generator — yields GateEvents to the SSE layer.
+
+        Yields either a single BlockEvent (if guard fires) or a stream of
+        TokenEvents followed by nothing (caller handles done/close).
+        """
+        t_start = time.perf_counter()
+
+        # ── Token buffer — accumulates LLM tokens while guard decides ─────
+        token_buffer:   List[str] = []
+        buffer_lock   = asyncio.Lock()
+        first_token_seen = False
+
+        # ── Task A: Guard (runs in thread pool — it's synchronous) ────────
+        async def run_guard() -> dict:
+            if trace:
+                trace.on_guard_start()
+            loop = asyncio.get_event_loop()
+            result = await loop.run_in_executor(None, self._guard.screen, prompt)
+            return result
+
+        # ── Task B: LLM stream — feeds token_buffer until gate opens ──────
+        async def run_stream():
+            nonlocal first_token_seen
+            if trace:
+                trace.on_llm_start()
+            try:
+                token_count = 0
+                total_chars = 0
+                async for token in self._adapter.stream_chat(prompt, system_prompt or None):
+                    if not first_token_seen:
+                        first_token_seen = True
+                        if trace:
+                            trace.on_first_token()
+                    async with buffer_lock:
+                        token_buffer.append(token)
+                    token_count += 1
+                    total_chars += len(token)
+                    # Emit a token-flow tick every 10 tokens for the dashboard
+                    if trace and token_count % 10 == 0:
+                        trace.on_token_tick(token_count, total_chars)
+            except asyncio.CancelledError:
+                pass  # Guard blocked — stream cancelled cleanly
+
+        # Start both tasks concurrently
+        guard_task  = asyncio.create_task(run_guard(),  name="shield-guard")
+        stream_task = asyncio.create_task(run_stream(), name="llm-stream")
+
+        # ── Wait for guard verdict ─────────────────────────────────────────
+        try:
+            guard_result = await asyncio.wait_for(
+                asyncio.shield(guard_task),
+                timeout=self._timeout,
+            )
+        except asyncio.TimeoutError:
+            log.error("[Gate] Guard timed out after %.1fs — defaulting to PASS", self._timeout)
+            guard_result = {"blocked": False, "threat_score": 0, "flags": [], "checks": {}}
+
+        guard_ms = round((time.perf_counter() - t_start) * 1000, 2)
+        pg_score = guard_result.get("checks", {}).get("prompt_guard", {}).get("malicious_score", 0.0)
+
+        # ── Guard says BLOCK ───────────────────────────────────────────────
+        if guard_result.get("blocked"):
+            stream_task.cancel()
+            try:
+                await stream_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+            log.warning(
+                "[Gate] Prompt BLOCKED — score=%.3f flags=%s latency=%.0fms",
+                pg_score, guard_result.get("flags", []), guard_ms,
+            )
+            if trace:
+                trace.on_guard_block(
+                    pg_score     = pg_score,
+                    threat_score = guard_result.get("threat_score", 100),
+                    reason       = guard_result.get("reason", "GUARD_BLOCKED"),
+                    flags        = guard_result.get("flags", []),
+                )
+            yield BlockEvent(
+                reason       = guard_result.get("reason", "GUARD_BLOCKED"),
+                threat_score = guard_result.get("threat_score", 100),
+                flags        = guard_result.get("flags", []),
+                pg_score     = pg_score,
+                guard_ms     = guard_ms,
+            )
+            return
+
+        # ── Guard says PASS — drain buffer then yield live tokens ──────────
+        log.info(
+            "[Gate] Prompt PASSED — score=%.3f latency=%.0fms — opening gate",
+            pg_score, guard_ms,
+        )
+        if trace:
+            trace.on_guard_pass(
+                pg_score     = pg_score,
+                threat_score = guard_result.get("threat_score", 0),
+                flags        = guard_result.get("flags", []),
+            )
+
+        # Drain anything buffered while guard was deciding
+        async with buffer_lock:
+            buffered = token_buffer.copy()
+            token_buffer.clear()
+
+        for token in buffered:
+            yield TokenEvent(text=token)
+
+        # Wait for stream task to complete, yielding live tokens as they arrive
+        # We poll the buffer so we can yield from the async generator context
+        while not stream_task.done():
+            await asyncio.sleep(0.005)   # 5ms poll — tight enough for streaming
+            async with buffer_lock:
+                live = token_buffer.copy()
+                token_buffer.clear()
+            for token in live:
+                yield TokenEvent(text=token)
+
+        # Final drain after stream task completes
+        async with buffer_lock:
+            for token in token_buffer:
+                yield TokenEvent(text=token)
+
+        # Propagate any stream errors
+        if not stream_task.cancelled() and stream_task.exception():
+            log.error("[Gate] LLM stream error: %s", stream_task.exception())

sidecar/pipeline_events.py

@@ -0,0 +1,171 @@
+"""
+sidecar/pipeline_events.py — Structured event bus for real-time data flow telemetry.
+
+Every stage of the sidecar pipeline emits a PipelineEvent into a shared
+in-process broadcast queue. The /v1/pipeline-stream SSE endpoint fans these
+out to all connected dashboard clients in real time.
+
+Event stages (in chronological order for a single request):
+  REQUEST_IN       — client prompt received
+  GUARD_START      — Prompt Guard model begins screening
+  LLM_START        — LLM stream begins (parallel to GUARD_START)
+  GUARD_PASS       — guard cleared the prompt
+  GUARD_BLOCK      — guard rejected the prompt
+  TOKEN_FLOW       — LLM tokens flowing (summary ticks, not every token)
+  SENTENCE_READY   — a complete sentence was emitted
+  MONITOR_START    — sentence submitted to background monitor
+  MONITOR_RESULT   — monitor returned a verdict for a sentence
+  STREAM_DONE      — LLM stream finished, all sentences emitted
+  REQUEST_DONE     — full request completed, final metrics available
+"""
+
+import queue
+import time
+import threading
+import uuid
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+
+
+# ── Event types ───────────────────────────────────────────────────────────────
+
+@dataclass
+class PipelineEvent:
+    stage:      str                        # one of the constants above
+    request_id: str
+    ts:         float  = field(default_factory=time.perf_counter)  # perf_counter seconds
+    wall:       str    = field(default_factory=lambda: time.strftime("%H:%M:%S"))
+    data:       Dict   = field(default_factory=dict)
+
+    def to_dict(self) -> Dict:
+        return {
+            "stage":      self.stage,
+            "request_id": self.request_id,
+            "ts":         round(self.ts * 1000, 2),   # ms since process start
+            "wall":       self.wall,
+            **self.data,
+        }
+
+
+# ── Global broadcast queue list ───────────────────────────────────────────────
+
+_subscribers: List[queue.Queue] = []
+_lock = threading.Lock()
+
+
+def subscribe() -> queue.Queue:
+    """Register a new SSE client. Returns its dedicated queue."""
+    q = queue.Queue(maxsize=200)
+    with _lock:
+        _subscribers.append(q)
+    return q
+
+
+def unsubscribe(q: queue.Queue) -> None:
+    """Remove an SSE client queue."""
+    with _lock:
+        try:
+            _subscribers.remove(q)
+        except ValueError:
+            pass
+
+
+def emit(event: PipelineEvent) -> None:
+    """Broadcast an event to all connected SSE clients."""
+    payload = event.to_dict()
+    with _lock:
+        dead = []
+        for q in _subscribers:
+            try:
+                q.put_nowait(payload)
+            except queue.Full:
+                dead.append(q)
+        for q in dead:
+            _subscribers.remove(q)
+
+
+# ── Request context helper ────────────────────────────────────────────────────
+
+class RequestTrace:
+    """
+    Tracks timing for a single request and emits PipelineEvents at each stage.
+    Used as a context object threaded through the pipeline.
+    """
+
+    def __init__(self):
+        self.request_id:  str   = str(uuid.uuid4())[:8]
+        self._t0:         float = time.perf_counter()
+        self._stage_start: Dict[str, float] = {}
+
+    def elapsed_ms(self) -> float:
+        return round((time.perf_counter() - self._t0) * 1000, 2)
+
+    def _since_stage(self, stage: str) -> float:
+        t = self._stage_start.get(stage)
+        if t is None:
+            return 0.0
+        return round((time.perf_counter() - t) * 1000, 2)
+
+    def _emit(self, stage: str, **kwargs):
+        self._stage_start.setdefault(stage, time.perf_counter())
+        emit(PipelineEvent(
+            stage      = stage,
+            request_id = self.request_id,
+            data       = {"elapsed_ms": self.elapsed_ms(), **kwargs},
+        ))
+
+    # ── Stage helpers ─────────────────────────────────────────────────────────
+
+    def on_request_in(self, prompt_preview: str):
+        self._emit("REQUEST_IN", prompt_preview=prompt_preview[:80])
+
+    def on_guard_start(self):
+        self._stage_start["guard"] = time.perf_counter()
+        self._emit("GUARD_START")
+
+    def on_llm_start(self):
+        self._stage_start["llm"] = time.perf_counter()
+        self._emit("LLM_START")
+
+    def on_guard_pass(self, pg_score: float, threat_score: int, flags: list):
+        guard_ms = self._since_stage("guard")
+        self._emit("GUARD_PASS",
+                   guard_ms=guard_ms, pg_score=pg_score,
+                   threat_score=threat_score, flags=flags)
+
+    def on_guard_block(self, pg_score: float, threat_score: int, reason: str, flags: list):
+        guard_ms = self._since_stage("guard")
+        self._emit("GUARD_BLOCK",
+                   guard_ms=guard_ms, pg_score=pg_score,
+                   threat_score=threat_score, reason=reason, flags=flags)
+
+    def on_first_token(self):
+        ttft = self._since_stage("llm")
+        self._emit("FIRST_TOKEN", ttft_ms=ttft)
+
+    def on_token_tick(self, token_count: int, chars: int):
+        self._emit("TOKEN_FLOW", token_count=token_count, chars=chars)
+
+    def on_sentence_ready(self, sentence_id: int, sentence_preview: str):
+        self._emit("SENTENCE_READY",
+                   sentence_id=sentence_id,
+                   sentence_preview=sentence_preview[:60])
+
+    def on_monitor_start(self, sentence_id: int):
+        self._emit("MONITOR_START", sentence_id=sentence_id)
+
+    def on_monitor_result(self, sentence_id: int, threat_score: int, flags: list, blocked: bool):
+        self._emit("MONITOR_RESULT",
+                   sentence_id=sentence_id, threat_score=threat_score,
+                   flags=flags, blocked=blocked)
+
+    def on_stream_done(self, total_tokens: int, sentence_count: int):
+        stream_ms = self._since_stage("llm")
+        self._emit("STREAM_DONE",
+                   stream_ms=stream_ms, total_tokens=total_tokens,
+                   sentence_count=sentence_count)
+
+    def on_request_done(self, threat_score: int, flags: list, blocked: bool):
+        self._emit("REQUEST_DONE",
+                   total_ms=self.elapsed_ms(),
+                   threat_score=threat_score, flags=flags, blocked=blocked)

sidecar/sentence_splitter.py

@@ -0,0 +1,118 @@
+"""
+sidecar/sentence_splitter.py — Streaming token accumulator with sentence boundary detection.
+
+Accumulates raw token chunks from the LLM stream and detects sentence
+boundaries. On each token it returns:
+  - A CHUNK event always (for immediate client rendering)
+  - A SENTENCE event when a sentence boundary is crossed (for shield monitoring)
+
+Design notes:
+  - Boundaries are detected on sentence-ending punctuation followed by
+    whitespace, or on double newlines (paragraph breaks).
+  - A minimum character threshold prevents very short "sentences" from
+    creating excessive monitor submissions (e.g. "OK." or "Yes.").
+  - The final flush() call drains any remaining buffer as a sentence.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import List
+
+
+# ── Event types ───────────────────────────────────────────────────────────────
+
+@dataclass
+class ChunkEvent:
+    """A raw token chunk — emitted immediately to the client."""
+    text: str
+    type: str = field(default="chunk", init=False)
+
+
+@dataclass
+class SentenceEvent:
+    """A complete sentence — emitted to the client AND submitted to the monitor."""
+    text:        str
+    sentence_id: int
+    type:        str = field(default="sentence", init=False)
+
+
+# ── Sentence boundary pattern ──────────────────────────────────────────────────
+#
+# Matches end-of-sentence punctuation (.  !  ?) followed by:
+#   a) whitespace (space / newline)
+#   b) end of string
+# Also matches double newlines (paragraph breaks).
+#
+_SENTENCE_END_RE = re.compile(r'(?<=[.!?])\s+|(?<=[.!?])$|\n\n')
+
+
+class SentenceSplitter:
+    """
+    Accumulates streaming tokens and fires sentence events at boundaries.
+
+    Args:
+        min_chars: Minimum buffer length before a boundary is declared.
+                   Prevents "Yes.", "OK." from triggering monitor overhead.
+    """
+
+    def __init__(self, min_chars: int = 20):
+        self._min_chars    = min_chars
+        self._buffer:      str = ""
+        self._sentence_id: int = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def feed(self, token: str) -> List[ChunkEvent | SentenceEvent]:
+        """
+        Feed a new token chunk. Returns a list of events to emit.
+
+        Always contains at least one ChunkEvent.
+        May contain a SentenceEvent if a boundary was crossed.
+        """
+        self._buffer += token
+        events: List[ChunkEvent | SentenceEvent] = [ChunkEvent(text=token)]
+
+        # Scan for sentence boundaries in the current buffer
+        while True:
+            match = _SENTENCE_END_RE.search(self._buffer)
+            if not match:
+                break
+
+            end_pos = match.end()
+            sentence_text = self._buffer[:end_pos].strip()
+
+            # Only declare a sentence if it's long enough
+            if len(sentence_text) >= self._min_chars:
+                self._sentence_id += 1
+                events.append(SentenceEvent(
+                    text=sentence_text,
+                    sentence_id=self._sentence_id,
+                ))
+                self._buffer = self._buffer[end_pos:]
+            else:
+                # Too short — don't split here, keep accumulating
+                break
+
+        return events
+
+    def flush(self) -> List[SentenceEvent]:
+        """
+        Flush any remaining buffer as a final sentence.
+        Call this after the stream ends.
+        """
+        events = []
+        remainder = self._buffer.strip()
+        if remainder:
+            self._sentence_id += 1
+            events.append(SentenceEvent(
+                text=remainder,
+                sentence_id=self._sentence_id,
+            ))
+            self._buffer = ""
+        return events
+
+    @property
+    def sentence_count(self) -> int:
+        return self._sentence_id

sidecar/stream_monitor.py

@@ -0,0 +1,142 @@
+"""
+sidecar/stream_monitor.py — Async sentence-level post-inference monitor.
+
+Wraps the synchronous TextMonitor in an async ThreadPoolExecutor so that
+per-sentence analysis runs concurrently in the background while the LLM
+stream continues flowing to the client.
+
+When a sentence crosses the threat threshold, a BlockSignal is returned
+so the SSE layer can push a block event to the client immediately.
+"""
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+log = logging.getLogger(__name__)
+
+
+# ── Event types ───────────────────────────────────────────────────────────────
+
+@dataclass
+class BlockSignal:
+    """Emitted when the post-monitor flags a sentence as harmful."""
+    sentence_id:  int
+    reason:       str
+    threat_score: int
+    flags:        List[str]
+    type:         str = field(default="block_signal", init=False)
+
+
+# ── Stream Monitor ─────────────────────────────────────────────────────────────
+
+class StreamMonitor:
+    """
+    Async wrapper around TextMonitor for sentence-level background screening.
+
+    Usage
+    -----
+    monitor = StreamMonitor(text_monitor_instance, block_threshold=40)
+
+    # Submit sentences as they complete (non-blocking):
+    task = await monitor.submit(sentence_id=1, sentence="...", prompt="...")
+
+    # At stream end — collect any pending block signals:
+    signals = await monitor.collect(timeout=1.0)
+
+    Args:
+        text_monitor:    Existing TextMonitor instance.
+        block_threshold: threat_score at or above which a BlockSignal is raised.
+        max_workers:     Thread pool size for concurrent sentence analysis.
+    """
+
+    def __init__(
+        self,
+        text_monitor,
+        block_threshold: int = 40,
+        max_workers:     int = 4,
+    ):
+        self._monitor   = text_monitor
+        self._threshold = block_threshold
+        self._executor  = ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="shield-monitor")
+        self._tasks:    List[asyncio.Future] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def submit(self, sentence_id: int, sentence: str, prompt: str) -> None:
+        """
+        Non-blocking: submit a sentence for background analysis.
+        The result is stored internally; call collect() to retrieve signals.
+        """
+        loop = asyncio.get_event_loop()
+        future = loop.run_in_executor(
+            self._executor,
+            self._analyze_sync,
+            sentence_id, sentence, prompt,
+        )
+        self._tasks.append(future)
+
+    async def collect(self, timeout: float = 1.5) -> List[BlockSignal]:
+        """
+        Wait for all pending monitor tasks (up to timeout) and return
+        any BlockSignals found.
+
+        Called at stream end to finalise the threat assessment.
+        """
+        if not self._tasks:
+            return []
+
+        signals: List[BlockSignal] = []
+        try:
+            results = await asyncio.wait_for(
+                asyncio.gather(*self._tasks, return_exceptions=True),
+                timeout=timeout,
+            )
+            for result in results:
+                if isinstance(result, BlockSignal):
+                    signals.append(result)
+                elif isinstance(result, Exception):
+                    log.warning("[StreamMonitor] Task error: %s", result)
+        except asyncio.TimeoutError:
+            log.warning("[StreamMonitor] collect() timed out after %.1fs — some sentences unscreened", timeout)
+
+        self._tasks.clear()
+        return signals
+
+    def reset(self) -> None:
+        """Clear pending tasks (e.g. between requests)."""
+        self._tasks.clear()
+
+    def shutdown(self) -> None:
+        """Gracefully shut down the thread pool."""
+        self._executor.shutdown(wait=False)
+
+    # ------------------------------------------------------------------
+    # Internal — runs in thread pool
+    # ------------------------------------------------------------------
+
+    def _analyze_sync(self, sentence_id: int, sentence: str, prompt: str) -> Optional[BlockSignal]:
+        """
+        Synchronous analysis — called inside ThreadPoolExecutor.
+        Returns a BlockSignal if the sentence is flagged, else None.
+        """
+        try:
+            result = self._monitor.analyze(prompt=prompt, response=sentence)
+            if result["threat_score"] >= self._threshold:
+                log.warning(
+                    "[StreamMonitor] Sentence %d flagged: score=%d flags=%s",
+                    sentence_id, result["threat_score"], result["flags"],
+                )
+                return BlockSignal(
+                    sentence_id  = sentence_id,
+                    reason       = result["reason"],
+                    threat_score = result["threat_score"],
+                    flags        = result["flags"],
+                )
+        except Exception as exc:
+            log.error("[StreamMonitor] Analysis error on sentence %d: %s", sentence_id, exc)
+        return None

start_sidecar.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# start_sidecar.sh — Launch the GenAI Shield Sidecar standalone
+#
+# Usage:
+#   ./start_sidecar.sh                     # default port 5050
+#   SIDECAR_PORT=8080 ./start_sidecar.sh   # custom port
+#   GEMINI_API_KEY=... ./start_sidecar.sh  # with API key inline
+
+set -e
+
+SIDECAR_PORT="${SIDECAR_PORT:-5050}"
+LOG_LEVEL="${LOG_LEVEL:-info}"
+
+echo "╔══════════════════════════════════════════════╗"
+echo "║   GenAI Shield Sidecar — Starting up         ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+echo "  Port:     $SIDECAR_PORT"
+echo "  Backend:  ${LLM_BACKEND:-gemini}"
+echo "  UI:       http://localhost:$SIDECAR_PORT"
+echo "  API Docs: http://localhost:$SIDECAR_PORT/docs"
+echo ""
+
+# Run from project root so imports resolve correctly
+cd "$(dirname "$0")"
+
+python -m uvicorn sidecar.app:app \
+    --host 0.0.0.0 \
+    --port "$SIDECAR_PORT" \
+    --log-level "$LOG_LEVEL" \
+    --no-access-log

templates/dataflow.html

@@ -0,0 +1,539 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>GenAI Shield — Data Flow</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&family=Inter:wght@400;600;700;800&display=swap" rel="stylesheet">
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+:root{
+  --bg:#07070f;--s1:#0f0f1a;--s2:#161625;--b:#1f1f35;
+  --acc:#6c63ff;--grn:#00d4aa;--red:#ff4757;--ylw:#ffa502;
+  --txt:#e0e0f0;--muted:#5a5a7a;
+  --mono:'JetBrains Mono',monospace;--sans:'Inter',sans-serif;
+}
+body{font-family:var(--sans);background:var(--bg);color:var(--txt);height:100vh;display:flex;flex-direction:column;overflow:hidden}
+
+/* Header */
+.hdr{padding:.75rem 1.5rem;border-bottom:1px solid var(--b);background:var(--s1);display:flex;align-items:center;justify-content:space-between;flex-shrink:0}
+.hdr-l{display:flex;align-items:center;gap:.75rem}
+.hdr-icon{width:34px;height:34px;border-radius:8px;background:linear-gradient(135deg,var(--acc),var(--grn));display:flex;align-items:center;justify-content:center;font-size:1rem}
+.hdr h1{font-size:.95rem;font-weight:700}
+.hdr-sub{font-family:var(--mono);font-size:.58rem;color:var(--muted);text-transform:uppercase}
+.hdr-r{display:flex;align-items:center;gap:.75rem}
+.dot{width:8px;height:8px;border-radius:50%;background:var(--grn);box-shadow:0 0 6px var(--grn);animation:pulse 2s ease-in-out infinite}
+@keyframes pulse{0%,100%{opacity:1}50%{opacity:.35}}
+.nav-link{font-family:var(--mono);font-size:.6rem;padding:4px 10px;border:1px solid var(--b);border-radius:4px;color:var(--muted);text-decoration:none;transition:color .2s,border-color .2s}
+.nav-link:hover{color:var(--acc);border-color:var(--acc)}
+
+/* Layout */
+.layout{flex:1;display:grid;grid-template-columns:1fr 320px;overflow:hidden}
+
+/* Pipeline canvas area */
+.canvas-wrap{padding:1.5rem;display:flex;flex-direction:column;gap:1rem;overflow:hidden}
+.section-title{font-family:var(--mono);font-size:.6rem;text-transform:uppercase;color:var(--muted);letter-spacing:.08em;margin-bottom:.5rem}
+
+/* Pipeline diagram */
+.pipeline{background:var(--s1);border:1px solid var(--b);border-radius:12px;padding:1.5rem;flex-shrink:0}
+.nodes{display:flex;align-items:center;gap:0;position:relative}
+
+.node{display:flex;flex-direction:column;align-items:center;gap:.5rem;flex:1;position:relative;z-index:2}
+.node-box{width:80px;height:80px;border-radius:12px;border:2px solid var(--b);background:var(--s2);display:flex;flex-direction:column;align-items:center;justify-content:center;gap:.25rem;cursor:default;transition:border-color .3s,box-shadow .3s;position:relative}
+.node-icon{font-size:1.4rem}
+.node-lbl{font-family:var(--mono);font-size:.55rem;text-align:center;color:var(--muted);text-transform:uppercase;line-height:1.3}
+.node-timer{font-family:var(--mono);font-size:.65rem;font-weight:700;color:var(--grn);min-height:1em;text-align:center}
+
+/* Node state classes */
+.node-box.active{border-color:var(--acc);box-shadow:0 0 16px rgba(108,99,255,.4)}
+.node-box.done{border-color:var(--grn);box-shadow:0 0 12px rgba(0,212,170,.25)}
+.node-box.blocked{border-color:var(--red);box-shadow:0 0 16px rgba(255,71,87,.4)}
+.node-box.warn{border-color:var(--ylw)}
+
+/* Connectors */
+.connector{flex:1;height:2px;background:var(--b);position:relative;z-index:1;align-self:center;margin-top:-40px}
+.connector-inner{height:100%;width:0;background:linear-gradient(90deg,var(--acc),var(--grn));transition:width .4s ease}
+.connector.active .connector-inner{width:100%}
+.connector.blocked .connector-inner{background:var(--red)}
+
+/* Packet animation */
+.packet{position:absolute;top:50%;transform:translateY(-50%);width:10px;height:10px;border-radius:50%;background:var(--acc);box-shadow:0 0 8px var(--acc);animation:travel .6s ease forwards;opacity:0}
+@keyframes travel{0%{left:0;opacity:1}100%{left:100%;opacity:0}}
+.packet.red{background:var(--red);box-shadow:0 0 8px var(--red)}
+.packet.grn{background:var(--grn);box-shadow:0 0 8px var(--grn)}
+
+/* Parallel row label */
+.parallel-note{font-family:var(--mono);font-size:.58rem;color:var(--acc);text-align:center;margin-top:.75rem}
+
+/* Metrics grid */
+.metrics-grid{display:grid;grid-template-columns:repeat(4,1fr);gap:.75rem}
+.metric-card{background:var(--s1);border:1px solid var(--b);border-radius:10px;padding:.875rem;display:flex;flex-direction:column;gap:.25rem}
+.metric-card.acc{border-color:rgba(108,99,255,.4)}
+.metric-card.grn{border-color:rgba(0,212,170,.4)}
+.metric-card.red{border-color:rgba(255,71,87,.4)}
+.metric-card.ylw{border-color:rgba(255,165,2,.4)}
+.metric-lbl{font-family:var(--mono);font-size:.55rem;text-transform:uppercase;color:var(--muted)}
+.metric-val{font-family:var(--mono);font-size:1.5rem;font-weight:700;line-height:1}
+.metric-sub{font-family:var(--mono);font-size:.58rem;color:var(--muted)}
+.metric-card.acc .metric-val{color:var(--acc)}
+.metric-card.grn .metric-val{color:var(--grn)}
+.metric-card.red .metric-val{color:var(--red)}
+.metric-card.ylw .metric-val{color:var(--ylw)}
+
+/* Charts row */
+.charts-row{display:grid;grid-template-columns:1fr 1fr;gap:.75rem;flex:1;min-height:0}
+.chart-card{background:var(--s1);border:1px solid var(--b);border-radius:10px;padding:1rem;display:flex;flex-direction:column;min-height:0}
+.chart-card canvas{flex:1;min-height:0}
+
+/* Right panel */
+.right-panel{border-left:1px solid var(--b);display:flex;flex-direction:column;overflow:hidden}
+.rp-header{padding:.875rem 1rem;border-bottom:1px solid var(--b);display:flex;align-items:center;justify-content:space-between;flex-shrink:0}
+.rp-title{font-family:var(--mono);font-size:.6rem;text-transform:uppercase;color:var(--muted)}
+.rp-count{font-family:var(--mono);font-size:.6rem;color:var(--acc)}
+.event-log{flex:1;overflow-y:auto;padding:.5rem}
+.event-log::-webkit-scrollbar{width:3px}
+.event-log::-webkit-scrollbar-thumb{background:var(--b);border-radius:2px}
+
+.evt{padding:.5rem .75rem;border-left:2px solid var(--b);margin-bottom:.375rem;border-radius:0 6px 6px 0;background:var(--s2);cursor:pointer;transition:border-color .2s}
+.evt:hover{border-left-color:var(--acc)}
+.evt-stage{font-family:var(--mono);font-size:.58rem;font-weight:700;text-transform:uppercase}
+.evt-meta{font-family:var(--mono);font-size:.55rem;color:var(--muted);margin-top:2px}
+.evt-detail{font-size:.7rem;color:var(--txt);margin-top:3px;word-break:break-all}
+
+.evt.REQUEST_IN    {border-left-color:#6c63ff} .evt.REQUEST_IN .evt-stage{color:#6c63ff}
+.evt.GUARD_START   {border-left-color:#a78bfa} .evt.GUARD_START .evt-stage{color:#a78bfa}
+.evt.LLM_START     {border-left-color:#38bdf8} .evt.LLM_START .evt-stage{color:#38bdf8}
+.evt.GUARD_PASS    {border-left-color:#00d4aa} .evt.GUARD_PASS .evt-stage{color:#00d4aa}
+.evt.GUARD_BLOCK   {border-left-color:#ff4757} .evt.GUARD_BLOCK .evt-stage{color:#ff4757}
+.evt.FIRST_TOKEN   {border-left-color:#00d4aa} .evt.FIRST_TOKEN .evt-stage{color:#00d4aa}
+.evt.TOKEN_FLOW    {border-left-color:#22d3ee} .evt.TOKEN_FLOW .evt-stage{color:#22d3ee}
+.evt.SENTENCE_READY{border-left-color:#a3e635} .evt.SENTENCE_READY .evt-stage{color:#a3e635}
+.evt.MONITOR_START {border-left-color:#fbbf24} .evt.MONITOR_START .evt-stage{color:#fbbf24}
+.evt.MONITOR_RESULT{border-left-color:#fb923c} .evt.MONITOR_RESULT .evt-stage{color:#fb923c}
+.evt.STREAM_DONE   {border-left-color:#00d4aa} .evt.STREAM_DONE .evt-stage{color:#00d4aa}
+.evt.REQUEST_DONE  {border-left-color:#6c63ff} .evt.REQUEST_DONE .evt-stage{color:#6c63ff}
+
+/* Threat badge */
+.tbadge{font-family:var(--mono);font-size:.52rem;font-weight:700;padding:1px 5px;border-radius:2px;display:inline-block}
+.clean{background:rgba(0,212,170,.12);color:var(--grn);border:1px solid rgba(0,212,170,.3)}
+.medium{background:rgba(255,165,2,.12);color:var(--ylw);border:1px solid rgba(255,165,2,.3)}
+.high{background:rgba(255,71,87,.12);color:var(--red);border:1px solid rgba(255,71,87,.3)}
+
+/* Empty state */
+.empty-state{padding:2rem;text-align:center;color:var(--muted);font-family:var(--mono);font-size:.7rem}
+</style>
+</head>
+<body>
+
+<header class="hdr">
+  <div class="hdr-l">
+    <div class="hdr-icon">🌊</div>
+    <div>
+      <h1>Data Flow <span style="color:var(--acc)">Monitor</span></h1>
+      <div class="hdr-sub">Real-time pipeline telemetry · Sidecar v2</div>
+    </div>
+  </div>
+  <div class="hdr-r">
+    <a class="nav-link" href="/sidecar">← Chat</a>
+    <a class="nav-link" href="/genai-monitoring">SIEM</a>
+    <div class="dot" id="conn-dot" title="Connecting..."></div>
+  </div>
+</header>
+
+<div class="layout">
+
+  <!-- Left: pipeline + metrics -->
+  <div class="canvas-wrap">
+
+    <!-- Pipeline diagram -->
+    <div class="pipeline">
+      <div class="section-title">Request Pipeline · Live</div>
+      <div class="nodes" id="nodes">
+
+        <!-- Client -->
+        <div class="node">
+          <div class="node-box" id="n-client">
+            <div class="node-icon">👤</div>
+            <div class="node-lbl">Client</div>
+          </div>
+          <div class="node-timer" id="t-client">—</div>
+        </div>
+
+        <div class="connector" id="c-gate"><div class="connector-inner"></div></div>
+
+        <!-- Shield Gate -->
+        <div class="node">
+          <div class="node-box" id="n-gate">
+            <div class="node-icon">🚪</div>
+            <div class="node-lbl">Shield Gate</div>
+          </div>
+          <div class="node-timer" id="t-gate">—</div>
+        </div>
+
+        <!-- Fork: guard + LLM (shown as two sub-connectors) -->
+        <div style="display:flex;flex-direction:column;gap:.25rem;flex:1.4">
+          <div style="display:flex;align-items:center;gap:0">
+            <div class="connector" id="c-guard" style="flex:1"><div class="connector-inner"></div></div>
+            <div class="node">
+              <div class="node-box" id="n-guard" style="width:68px;height:68px">
+                <div class="node-icon" style="font-size:1.1rem">🛡️</div>
+                <div class="node-lbl">Prompt Guard</div>
+              </div>
+              <div class="node-timer" id="t-guard">—</div>
+            </div>
+          </div>
+          <div style="display:flex;align-items:center;gap:0">
+            <div class="connector" id="c-llm" style="flex:1"><div class="connector-inner"></div></div>
+            <div class="node">
+              <div class="node-box" id="n-llm" style="width:68px;height:68px">
+                <div class="node-icon" style="font-size:1.1rem">🤖</div>
+                <div class="node-lbl">LLM API</div>
+              </div>
+              <div class="node-timer" id="t-llm">—</div>
+            </div>
+          </div>
+          <div class="parallel-note">⚡ parallel</div>
+        </div>
+
+        <div class="connector" id="c-monitor"><div class="connector-inner"></div></div>
+
+        <!-- Stream Monitor -->
+        <div class="node">
+          <div class="node-box" id="n-monitor">
+            <div class="node-icon">🔍</div>
+            <div class="node-lbl">Monitor</div>
+          </div>
+          <div class="node-timer" id="t-monitor">—</div>
+        </div>
+
+        <div class="connector" id="c-out"><div class="connector-inner"></div></div>
+
+        <!-- Output -->
+        <div class="node">
+          <div class="node-box" id="n-out">
+            <div class="node-icon">✅</div>
+            <div class="node-lbl">Output</div>
+          </div>
+          <div class="node-timer" id="t-out">—</div>
+        </div>
+
+      </div>
+    </div>
+
+    <!-- Metrics -->
+    <div>
+      <div class="section-title">Session Metrics</div>
+      <div class="metrics-grid">
+        <div class="metric-card acc">
+          <div class="metric-lbl">Total Requests</div>
+          <div class="metric-val" id="m-total">0</div>
+          <div class="metric-sub">since page load</div>
+        </div>
+        <div class="metric-card grn">
+          <div class="metric-lbl">Avg Guard ms</div>
+          <div class="metric-val" id="m-guard-avg">—</div>
+          <div class="metric-sub">Prompt Guard latency</div>
+        </div>
+        <div class="metric-card ylw">
+          <div class="metric-lbl">Avg TTFT ms</div>
+          <div class="metric-val" id="m-ttft-avg">—</div>
+          <div class="metric-sub">time to first token</div>
+        </div>
+        <div class="metric-card red">
+          <div class="metric-lbl">Blocked</div>
+          <div class="metric-val" id="m-blocked">0</div>
+          <div class="metric-sub">pre/post inference</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Charts -->
+    <div class="charts-row">
+      <div class="chart-card">
+        <div class="section-title">Guard Latency (ms) · last 20</div>
+        <canvas id="chart-guard"></canvas>
+      </div>
+      <div class="chart-card">
+        <div class="section-title">Total Request Time (ms) · last 20</div>
+        <canvas id="chart-total"></canvas>
+      </div>
+    </div>
+
+  </div>
+
+  <!-- Right: event log -->
+  <div class="right-panel">
+    <div class="rp-header">
+      <span class="rp-title">Pipeline Event Log</span>
+      <span class="rp-count" id="evt-count">0 events</span>
+    </div>
+    <div class="event-log" id="event-log">
+      <div class="empty-state" id="empty-msg">Waiting for requests…</div>
+    </div>
+  </div>
+
+</div>
+
+<script>
+// ── State ──────────────────────────────────────────────────────────────────────
+const state = {
+  total: 0, blocked: 0,
+  guardTimes: [], ttftTimes: [], totalTimes: [],
+  reqStart: {}, guardStart: {}, llmStart: {},
+};
+
+// ── Chart setup ────────────────────────────────────────────────────────────────
+const chartOpts = (color) => ({
+  type: 'line',
+  data: {
+    labels: Array(20).fill(''),
+    datasets: [{
+      data: Array(20).fill(null),
+      borderColor: color,
+      backgroundColor: color + '18',
+      borderWidth: 1.5,
+      fill: true,
+      tension: 0.4,
+      pointRadius: 2,
+      pointBackgroundColor: color,
+    }]
+  },
+  options: {
+    responsive: true, maintainAspectRatio: false, animation: false,
+    scales: {
+      x: { display: false },
+      y: { min: 0, grid: { color: '#1f1f35' }, ticks: { color: '#5a5a7a', font: { family: 'JetBrains Mono', size: 9 } } }
+    },
+    plugins: { legend: { display: false } }
+  }
+});
+
+const cGuard = new Chart(document.getElementById('chart-guard').getContext('2d'), chartOpts('#6c63ff'));
+const cTotal = new Chart(document.getElementById('chart-total').getContext('2d'), chartOpts('#00d4aa'));
+
+function pushChart(chart, val) {
+  chart.data.datasets[0].data.push(val);
+  chart.data.datasets[0].data.shift();
+  chart.data.labels.push('');
+  chart.data.labels.shift();
+  chart.update('none');
+}
+
+// ── Node helpers ────────────���──────────────────────────────────────────────────
+function nodeState(id, cls) {
+  const el = document.getElementById('n-' + id);
+  if (!el) return;
+  el.className = 'node-box ' + (cls || '');
+}
+function nodeTime(id, ms) {
+  const el = document.getElementById('t-' + id);
+  if (el) el.textContent = ms != null ? ms + 'ms' : '—';
+}
+function connActive(id, cls) {
+  const el = document.getElementById('c-' + id);
+  if (el) el.className = 'connector active ' + (cls || '');
+}
+function firePacket(connId, cls) {
+  const conn = document.getElementById('c-' + connId);
+  if (!conn) return;
+  const p = document.createElement('div');
+  p.className = 'packet ' + (cls || '');
+  conn.style.position = 'relative';
+  conn.appendChild(p);
+  setTimeout(() => p.remove(), 700);
+}
+function resetPipeline() {
+  ['client','gate','guard','llm','monitor','out'].forEach(id => nodeState(id, ''));
+  ['client','gate','guard','llm','monitor','out'].forEach(id => nodeTime(id, null));
+  ['gate','guard','llm','monitor','out'].forEach(id => {
+    const el = document.getElementById('c-' + id);
+    if (el) el.className = 'connector';
+  });
+  document.getElementById('n-out').querySelector('.node-icon').textContent = '✅';
+}
+
+// ── Metrics update ─────────────────────────────────────────────────────────────
+function updateMetrics() {
+  document.getElementById('m-total').textContent = state.total;
+  document.getElementById('m-blocked').textContent = state.blocked;
+  const avg = arr => arr.length ? Math.round(arr.slice(-20).reduce((a,b)=>a+b,0)/Math.min(arr.length,20)) : '—';
+  document.getElementById('m-guard-avg').textContent = avg(state.guardTimes);
+  document.getElementById('m-ttft-avg').textContent  = avg(state.ttftTimes);
+}
+
+// ── Event log ──────────────────────────────────────────────────────────────────
+let evtCount = 0;
+function logEvent(ev) {
+  const log = document.getElementById('event-log');
+  const empty = document.getElementById('empty-msg');
+  if (empty) empty.remove();
+
+  evtCount++;
+  document.getElementById('evt-count').textContent = evtCount + ' events';
+
+  const d = document.createElement('div');
+  d.className = 'evt ' + ev.stage;
+
+  let detail = '';
+  if (ev.prompt_preview) detail = `"${ev.prompt_preview.slice(0,50)}"`;
+  else if (ev.guard_ms)   detail = `Guard: ${ev.guard_ms}ms · PG: ${(ev.pg_score||0).toFixed(3)}`;
+  else if (ev.ttft_ms)    detail = `TTFT: ${ev.ttft_ms}ms`;
+  else if (ev.stream_ms)  detail = `Stream: ${ev.stream_ms}ms · ${ev.total_tokens||0} tokens`;
+  else if (ev.total_ms)   detail = `Total: ${ev.total_ms}ms`;
+  else if (ev.sentence_preview) detail = `"${ev.sentence_preview.slice(0,40)}"`;
+  else if (ev.token_count) detail = `${ev.token_count} tokens`;
+
+  const score = ev.threat_score;
+  const badge = score >= 60 ? `<span class="tbadge high">HIGH ${score}</span>`
+               : score >= 30 ? `<span class="tbadge medium">WARN ${score}</span>`
+               : score > 0   ? `<span class="tbadge clean">CLEAN ${score}</span>` : '';
+
+  d.innerHTML = `<div class="evt-stage">${ev.stage.replace(/_/g,' ')}</div>
+    <div class="evt-meta">${ev.wall} · req ${ev.request_id} · +${ev.elapsed_ms}ms ${badge}</div>
+    ${detail ? `<div class="evt-detail">${detail}</div>` : ''}`;
+
+  log.prepend(d);
+  if (log.children.length > 80) log.lastChild.remove();
+}
+
+// ── Pipeline stage handler ─────────────────────────────────────────────────────
+function handleStage(ev) {
+  logEvent(ev);
+  const rid = ev.request_id;
+
+  switch(ev.stage) {
+    case 'REQUEST_IN':
+      resetPipeline();
+      state.reqStart[rid] = ev.elapsed_ms;
+      nodeState('client', 'active');
+      connActive('gate');
+      firePacket('gate');
+      nodeState('gate', 'active');
+      break;
+
+    case 'GUARD_START':
+      state.guardStart[rid] = ev.elapsed_ms;
+      nodeState('guard', 'active');
+      connActive('guard');
+      firePacket('guard');
+      break;
+
+    case 'LLM_START':
+      state.llmStart[rid] = ev.elapsed_ms;
+      nodeState('llm', 'active');
+      connActive('llm');
+      firePacket('llm');
+      break;
+
+    case 'GUARD_PASS':
+      nodeState('guard', 'done');
+      nodeTime('guard', ev.guard_ms);
+      state.guardTimes.push(ev.guard_ms);
+      pushChart(cGuard, ev.guard_ms);
+      updateMetrics();
+      break;
+
+    case 'GUARD_BLOCK':
+      state.total++;
+      state.blocked++;
+      nodeState('guard', 'blocked');
+      nodeTime('guard', ev.guard_ms);
+      nodeState('gate',  'blocked');
+      nodeState('llm',   'blocked');
+      nodeState('out',   'blocked');
+      document.getElementById('n-out').querySelector('.node-icon').textContent = '🚫';
+      state.guardTimes.push(ev.guard_ms);
+      pushChart(cGuard, ev.guard_ms);
+      updateMetrics();
+      break;
+
+    case 'FIRST_TOKEN':
+      nodeState('llm', 'done');
+      nodeTime('llm', ev.ttft_ms);
+      state.ttftTimes.push(ev.ttft_ms);
+      updateMetrics();
+      break;
+
+    case 'TOKEN_FLOW':
+      firePacket('monitor', 'grn');
+      break;
+
+    case 'SENTENCE_READY':
+      connActive('monitor');
+      firePacket('monitor', 'grn');
+      nodeState('monitor', 'active');
+      break;
+
+    case 'MONITOR_START':
+      nodeState('monitor', 'active');
+      break;
+
+    case 'MONITOR_RESULT':
+      if (ev.blocked) {
+        nodeState('monitor', 'blocked');
+        nodeState('out', 'blocked');
+        document.getElementById('n-out').querySelector('.node-icon').textContent = '🚫';
+      } else {
+        nodeState('monitor', 'done');
+      }
+      break;
+
+    case 'STREAM_DONE':
+      nodeState('llm', 'done');
+      nodeTime('llm', ev.stream_ms);
+      break;
+
+    case 'REQUEST_DONE':
+      state.total++;
+      if (ev.blocked) state.blocked++;
+      nodeState('client', 'done');
+      nodeState('gate', 'done');
+      if (!ev.blocked) {
+        nodeState('monitor', 'done');
+        nodeState('out', 'done');
+        connActive('out', 'grn');
+        firePacket('out', 'grn');
+      }
+      nodeTime('out', ev.total_ms);
+      nodeTime('client', ev.total_ms);
+      state.totalTimes.push(ev.total_ms);
+      pushChart(cTotal, ev.total_ms);
+      updateMetrics();
+      break;
+  }
+}
+
+// ── SSE connection ─────────────────────────────────────────────────────────────
+function connect() {
+  const dot = document.getElementById('conn-dot');
+  dot.style.background = 'var(--ylw)';
+  dot.style.boxShadow  = '0 0 6px var(--ylw)';
+
+  // Try sidecar direct first, fall back to current host
+  const url = '/v1/pipeline-stream';
+  const es = new EventSource(url);
+
+  es.onopen = () => {
+    dot.style.background = 'var(--grn)';
+    dot.style.boxShadow  = '0 0 6px var(--grn)';
+    dot.title = 'Connected';
+  };
+
+  es.onmessage = e => {
+    if (!e.data || e.data.startsWith(':')) return;
+    try { handleStage(JSON.parse(e.data)); } catch {}
+  };
+
+  es.onerror = () => {
+    dot.style.background = 'var(--red)';
+    dot.style.boxShadow  = '0 0 6px var(--red)';
+    dot.title = 'Disconnected — retrying';
+    es.close();
+    setTimeout(connect, 3000);
+  };
+}
+
+connect();
+</script>
+</body>
+</html>

templates/genai.html

@@ -33,7 +33,6 @@
         <div class="container" style="padding: 0; max-width: none; display: flex; justify-content: space-between; align-items: center;">
             <div>
                 <h1 style="font-size: 1.5rem; margin: 0;">Risknox <span style="text-decoration: underline;">GenAI Shield V2</span></h1>
-                <p style="font-size: 0.65rem; font-weight: 800; text-transform: uppercase; color: var(--muted);">Powered by Llama Prompt Guard 2 · {{ model }}</p>
             </div>
             <a href="/genai-monitoring" class="btn secondary" style="font-size: 0.75rem;">Dashboard →</a>
         </div>

templates/sidecar.html

@@ -0,0 +1,676 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Risknox | GenAI Shield — Sidecar</title>
+    <meta name="description" content="GenAI Shield sidecar proxy with real-time streaming and sentence-level threat detection">
+    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&family=Inter:wght@400;600;700;800&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --bg:        #0a0a0f;
+            --surface:   #12121a;
+            --surface2:  #1a1a26;
+            --border:    #2a2a3d;
+            --accent:    #6c63ff;
+            --accent2:   #00d4aa;
+            --danger:    #ff4757;
+            --warn:      #ffa502;
+            --text:      #e8e8f0;
+            --muted:     #6b6b8a;
+            --mono:      'JetBrains Mono', monospace;
+            --sans:      'Inter', system-ui, sans-serif;
+        }
+
+        *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+        body {
+            font-family: var(--sans);
+            background: var(--bg);
+            color: var(--text);
+            height: 100vh;
+            display: flex;
+            flex-direction: column;
+            overflow: hidden;
+        }
+
+        /* ── Header ───────────────────────────────────────────────── */
+        .header {
+            padding: 0.875rem 1.5rem;
+            border-bottom: 1px solid var(--border);
+            background: var(--surface);
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            flex-shrink: 0;
+        }
+        .header-brand { display: flex; align-items: center; gap: 0.75rem; }
+        .shield-icon {
+            width: 36px; height: 36px;
+            background: linear-gradient(135deg, var(--accent), var(--accent2));
+            border-radius: 8px;
+            display: flex; align-items: center; justify-content: center;
+            font-size: 1.1rem;
+        }
+        .header h1 { font-size: 1rem; font-weight: 700; }
+        .header-sub {
+            font-family: var(--mono);
+            font-size: 0.6rem;
+            color: var(--muted);
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+        }
+        .header-actions { display: flex; align-items: center; gap: 0.75rem; }
+        .mode-badge {
+            font-family: var(--mono);
+            font-size: 0.6rem;
+            font-weight: 700;
+            padding: 3px 8px;
+            border-radius: 3px;
+            background: rgba(108, 99, 255, 0.15);
+            border: 1px solid rgba(108, 99, 255, 0.4);
+            color: var(--accent);
+            text-transform: uppercase;
+        }
+        .status-dot {
+            width: 8px; height: 8px;
+            border-radius: 50%;
+            background: var(--accent2);
+            box-shadow: 0 0 6px var(--accent2);
+            animation: pulse 2s ease-in-out infinite;
+        }
+        @keyframes pulse { 0%,100% { opacity:1; } 50% { opacity:0.4; } }
+
+        /* ── Chat area ────────────────────────────────────────────── */
+        .chat-area {
+            flex: 1;
+            overflow-y: auto;
+            padding: 1.5rem;
+            display: flex;
+            flex-direction: column;
+            gap: 1.5rem;
+        }
+        .chat-area::-webkit-scrollbar { width: 4px; }
+        .chat-area::-webkit-scrollbar-track { background: transparent; }
+        .chat-area::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }
+
+        /* ── Messages ─────────────────────────────────────────────── */
+        .msg { display: flex; gap: 0.75rem; max-width: 760px; width: 100%; }
+        .msg.user { align-self: flex-end; flex-direction: row-reverse; }
+        .msg.assistant { align-self: flex-start; }
+
+        .avatar {
+            width: 32px; height: 32px;
+            border-radius: 8px;
+            display: flex; align-items: center; justify-content: center;
+            font-weight: 700; font-size: 0.65rem;
+            flex-shrink: 0;
+            font-family: var(--mono);
+        }
+        .msg.user .avatar  { background: var(--accent);  color: #fff; }
+        .msg.assistant .avatar { background: var(--surface2); color: var(--accent2); border: 1px solid var(--border); }
+
+        .bubble {
+            padding: 0.875rem 1.125rem;
+            border-radius: 12px;
+            line-height: 1.65;
+            font-size: 0.9375rem;
+            max-width: calc(100% - 44px);
+        }
+        .msg.user .bubble {
+            background: var(--accent);
+            color: #fff;
+            border-bottom-right-radius: 3px;
+        }
+        .msg.assistant .bubble {
+            background: var(--surface);
+            border: 1px solid var(--border);
+            border-bottom-left-radius: 3px;
+            color: var(--text);
+            position: relative;
+        }
+
+        /* ── Streaming cursor ─────────────────────────────────────── */
+        .stream-cursor {
+            display: inline-block;
+            width: 2px;
+            height: 1em;
+            background: var(--accent2);
+            margin-left: 2px;
+            vertical-align: text-bottom;
+            border-radius: 1px;
+            animation: blink 0.8s step-end infinite;
+        }
+        @keyframes blink { 0%,100% { opacity:1; } 50% { opacity:0; } }
+
+        /* ── Shield monitoring bar ────────────────────────────────── */
+        .shield-bar {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            margin-top: 0.625rem;
+            font-family: var(--mono);
+            font-size: 0.6rem;
+            color: var(--muted);
+        }
+        .shield-bar .spinner {
+            width: 10px; height: 10px;
+            border: 1.5px solid var(--accent2);
+            border-top-color: transparent;
+            border-radius: 50%;
+            animation: spin 0.8s linear infinite;
+        }
+        @keyframes spin { to { transform: rotate(360deg); } }
+
+        /* ── Threat meta row ──────────────────────────────────────── */
+        .msg-meta {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            margin-top: 0.5rem;
+            flex-wrap: wrap;
+        }
+        .threat-badge {
+            font-family: var(--mono);
+            font-size: 0.6rem;
+            font-weight: 700;
+            padding: 2px 7px;
+            border-radius: 3px;
+            text-transform: uppercase;
+        }
+        .threat-clean    { background: rgba(0,212,170,0.12); color: var(--accent2); border: 1px solid rgba(0,212,170,0.3); }
+        .threat-medium   { background: rgba(255,165,2,0.12);  color: var(--warn);   border: 1px solid rgba(255,165,2,0.3); }
+        .threat-high     { background: rgba(255,71,87,0.12);  color: var(--danger); border: 1px solid rgba(255,71,87,0.3); }
+        .meta-chip {
+            font-family: var(--mono);
+            font-size: 0.57rem;
+            color: var(--muted);
+        }
+        .flag-chip {
+            font-family: var(--mono);
+            font-size: 0.57rem;
+            padding: 1px 5px;
+            border: 1px solid rgba(255,71,87,0.4);
+            color: var(--danger);
+            border-radius: 2px;
+        }
+
+        /* ── Block signal overlay ─────────────────────────────────── */
+        .block-signal-overlay {
+            margin-top: 0.625rem;
+            padding: 0.75rem 1rem;
+            background: rgba(255,71,87,0.08);
+            border: 1px solid rgba(255,71,87,0.4);
+            border-radius: 8px;
+            font-size: 0.8rem;
+        }
+        .block-signal-overlay strong { color: var(--danger); font-family: var(--mono); font-size: 0.7rem; }
+
+        /* Tainted text fade */
+        .tainted { opacity: 0.3; text-decoration: line-through; color: var(--danger); }
+
+        /* ── Blocked message ──────────────────────────────────────── */
+        .blocked-card {
+            max-width: 760px;
+            padding: 1rem 1.25rem;
+            background: rgba(255,71,87,0.07);
+            border: 1px solid rgba(255,71,87,0.4);
+            border-radius: 12px;
+            align-self: flex-end;
+        }
+        .blocked-card-title {
+            font-weight: 700;
+            font-size: 0.875rem;
+            color: var(--danger);
+            margin-bottom: 0.375rem;
+            display: flex; align-items: center; gap: 0.5rem;
+        }
+        .blocked-card-reason {
+            font-family: var(--mono);
+            font-size: 0.7rem;
+            color: var(--muted);
+            margin-bottom: 0.5rem;
+        }
+
+        /* ── Input area ───────────────────────────────────────────── */
+        .input-area {
+            padding: 1rem 1.5rem;
+            border-top: 1px solid var(--border);
+            background: var(--surface);
+            flex-shrink: 0;
+        }
+        .input-row {
+            max-width: 760px;
+            margin: 0 auto;
+            display: flex;
+            gap: 0.75rem;
+            align-items: flex-end;
+        }
+        .input-wrap {
+            flex: 1;
+            background: var(--surface2);
+            border: 1px solid var(--border);
+            border-radius: 10px;
+            padding: 0.75rem 1rem;
+            transition: border-color 0.2s;
+        }
+        .input-wrap:focus-within { border-color: var(--accent); }
+        textarea {
+            width: 100%;
+            background: transparent;
+            border: none;
+            outline: none;
+            font-family: var(--sans);
+            font-size: 0.9375rem;
+            color: var(--text);
+            resize: none;
+            min-height: 24px;
+            max-height: 160px;
+            line-height: 1.5;
+        }
+        textarea::placeholder { color: var(--muted); }
+        .send-btn {
+            width: 44px; height: 44px;
+            border-radius: 10px;
+            border: none;
+            background: var(--accent);
+            color: #fff;
+            cursor: pointer;
+            display: flex; align-items: center; justify-content: center;
+            transition: background 0.2s, transform 0.1s;
+            flex-shrink: 0;
+        }
+        .send-btn:hover  { background: #7c73ff; }
+        .send-btn:active { transform: scale(0.94); }
+        .send-btn:disabled { background: var(--border); cursor: not-allowed; }
+
+        /* ── Latency bar (below input) ────────────────────────────── */
+        .latency-row {
+            max-width: 760px;
+            margin: 0.5rem auto 0;
+            display: flex;
+            gap: 1rem;
+            font-family: var(--mono);
+            font-size: 0.58rem;
+            color: var(--muted);
+        }
+        .latency-seg { display: flex; align-items: center; gap: 0.3rem; }
+        .latency-dot { width: 6px; height: 6px; border-radius: 50%; }
+        .dot-guard   { background: var(--accent); }
+        .dot-model   { background: var(--accent2); }
+        .dot-monitor { background: var(--warn); }
+
+        /* ── Welcome state ────────────────────────────────────────── */
+        .welcome {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            text-align: center;
+            gap: 1rem;
+            color: var(--muted);
+            padding: 2rem;
+        }
+        .welcome-icon { font-size: 3rem; }
+        .welcome h2   { font-size: 1.25rem; color: var(--text); }
+        .welcome p    { font-size: 0.875rem; max-width: 400px; line-height: 1.6; }
+        .pill-row     { display: flex; gap: 0.5rem; flex-wrap: wrap; justify-content: center; }
+        .pill {
+            font-family: var(--mono);
+            font-size: 0.65rem;
+            padding: 4px 10px;
+            border-radius: 99px;
+            background: var(--surface2);
+            border: 1px solid var(--border);
+        }
+    </style>
+</head>
+<body>
+
+<header class="header">
+    <div class="header-brand">
+        <div class="shield-icon">🛡️</div>
+        <div>
+            <h1>GenAI Shield <span style="color:var(--accent)">Sidecar</span></h1>
+            <div class="header-sub">Parallel Guard · Sentence Streaming · Background Monitor</div>
+        </div>
+    </div>
+    <div class="header-actions">
+        <div class="mode-badge">Sidecar v2</div>
+        <div class="status-dot" id="status-dot" title="Guard ready"></div>
+    </div>
+</header>
+
+<div class="chat-area" id="chat-area">
+    <div class="welcome" id="welcome-screen">
+        <div class="welcome-icon">🛡️</div>
+        <h2>Sidecar Proxy Active</h2>
+        <p>Your prompt is guarded <em>before</em> the LLM sees it, and every sentence of the response is monitored <em>as it streams</em> — with zero added latency on the happy path.</p>
+        <div class="pill-row">
+            <span class="pill">⚡ Parallel guard + LLM</span>
+            <span class="pill">📡 Sentence-level SSE</span>
+            <span class="pill">🔍 Background monitor</span>
+            <span class="pill">🚫 Mid-stream block signal</span>
+        </div>
+    </div>
+</div>
+
+<div class="input-area">
+    <div class="input-row">
+        <div class="input-wrap">
+            <textarea
+                id="prompt-input"
+                rows="1"
+                placeholder="Enter a prompt — the shield and the LLM start together..."
+                onkeydown="if(event.key==='Enter'&&!event.shiftKey){event.preventDefault();sendMessage();}"
+                oninput="autoResize(this)"
+            ></textarea>
+        </div>
+        <button class="send-btn" id="send-btn" onclick="sendMessage()" title="Send">
+            <svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor">
+                <path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z"/>
+            </svg>
+        </button>
+    </div>
+    <div class="latency-row" id="latency-row" style="display:none">
+        <span class="latency-seg"><span class="latency-dot dot-guard"></span><span id="lat-guard">Guard: —</span></span>
+        <span class="latency-seg"><span class="latency-dot dot-model"></span><span id="lat-model">Stream: —</span></span>
+        <span class="latency-seg"><span class="latency-dot dot-monitor"></span><span id="lat-monitor">Monitor: background</span></span>
+    </div>
+</div>
+
+<script>
+// ── Config ────────────────────────────────────────────────────────────────────
+const SIDECAR_URL = '/v1/chat';   // proxied through Flask or direct to :5050
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const chatArea  = document.getElementById('chat-area');
+const input     = document.getElementById('prompt-input');
+const sendBtn   = document.getElementById('send-btn');
+const latRow    = document.getElementById('latency-row');
+
+function esc(s) {
+    return String(s)
+        .replace(/&/g,'&amp;')
+        .replace(/</g,'&lt;')
+        .replace(/>/g,'&gt;')
+        .replace(/\n/g,'<br>');
+}
+
+function autoResize(el) {
+    el.style.height = 'auto';
+    el.style.height = Math.min(el.scrollHeight, 160) + 'px';
+}
+
+function scrollBottom() {
+    chatArea.scrollTop = chatArea.scrollHeight;
+}
+
+function hideWelcome() {
+    const w = document.getElementById('welcome-screen');
+    if (w) w.remove();
+}
+
+function setLatency(guard, total) {
+    latRow.style.display = 'flex';
+    document.getElementById('lat-guard').textContent = `Guard: ${guard || '—'}ms`;
+    document.getElementById('lat-model').textContent = `Total: ${total || '—'}ms`;
+}
+
+// ── Append user bubble ─────────────────────────────────────────────────────────
+function appendUser(text) {
+    const div = document.createElement('div');
+    div.className = 'msg user';
+    div.innerHTML = `
+        <div class="avatar">U</div>
+        <div class="bubble">${esc(text)}</div>
+    `;
+    chatArea.appendChild(div);
+    scrollBottom();
+}
+
+// ── Append assistant streaming bubble ─────────────────────────────────────────
+function createAssistantBubble() {
+    const div = document.createElement('div');
+    div.className = 'msg assistant';
+
+    const bubbleId  = 'bubble-' + Date.now();
+    const metaId    = 'meta-'   + Date.now();
+    const shieldId  = 'shield-' + Date.now();
+
+    div.innerHTML = `
+        <div class="avatar">AI</div>
+        <div>
+            <div class="bubble" id="${bubbleId}">
+                <span class="stream-cursor"></span>
+            </div>
+            <div class="shield-bar" id="${shieldId}">
+                <div class="spinner"></div>
+                <span>Shield monitoring output…</span>
+            </div>
+            <div class="msg-meta" id="${metaId}" style="display:none"></div>
+        </div>
+    `;
+    chatArea.appendChild(div);
+    scrollBottom();
+
+    return {
+        getBubble:  () => document.getElementById(bubbleId),
+        getMeta:    () => document.getElementById(metaId),
+        getShield:  () => document.getElementById(shieldId),
+        bubbleId,
+        metaId,
+        shieldId,
+
+        // Sentence tracking for block signals
+        sentences: {},   // sentence_id → { start, end } char positions not tracked easily,
+                         // so we track spans instead
+        fullText: '',
+    };
+}
+
+// ── Block signal: taint sentences from sentence_id onward ─────────────────────
+function applyBlockSignal(bubbleEl, bubbleState, signalData) {
+    const sid = signalData.sentence_id;
+
+    // Mark all sentence spans from sid onward as tainted
+    const spans = bubbleEl.querySelectorAll(`[data-sid]`);
+    spans.forEach(span => {
+        const spanSid = parseInt(span.dataset.sid, 10);
+        if (spanSid >= sid) span.classList.add('tainted');
+    });
+
+    // Append block signal banner
+    const overlay = document.createElement('div');
+    overlay.className = 'block-signal-overlay';
+    overlay.innerHTML = `
+        <strong>🚫 OUTPUT BLOCKED AT SENTENCE ${sid}</strong>
+        <div style="margin-top:4px;font-size:0.75rem;color:var(--muted)">${esc(signalData.reason)}</div>
+        <div style="margin-top:6px">${(signalData.flags||[]).map(f => `<span class="flag-chip">${f}</span>`).join(' ')}</div>
+    `;
+    bubbleEl.parentElement.insertAdjacentElement('beforeend', overlay);
+}
+
+// ── Render done meta ──────────────────────────────────────────────────────────
+function renderDone(metaEl, shieldEl, doneData) {
+    // Hide shield spinner
+    shieldEl.style.display = 'none';
+
+    const score = doneData.threat_score || 0;
+    const cls   = score >= 60 ? 'threat-high' : score >= 30 ? 'threat-medium' : 'threat-clean';
+    const label = score >= 60 ? 'HIGH RISK'   : score >= 30 ? 'SUSPICIOUS'    : 'CLEAN';
+
+    let html = `<span class="threat-badge ${cls}">${label} · ${score}</span>`;
+    html    += `<span class="meta-chip">${doneData.latency_ms || 0}ms total · ${doneData.sentences || 0} sentences</span>`;
+    (doneData.flags || []).forEach(f => { html += `<span class="flag-chip">${f}</span>`; });
+
+    metaEl.innerHTML = html;
+    metaEl.style.display = 'flex';
+}
+
+// ── Append blocked card ───────────────────────────────────────────────────────
+function appendBlocked(data) {
+    const div = document.createElement('div');
+    div.className = 'blocked-card';
+    div.innerHTML = `
+        <div class="blocked-card-title">🚫 Input Rejected by Prompt Guard</div>
+        <div class="blocked-card-reason">${esc(data.reason || 'GUARD_BLOCKED')}</div>
+        <div style="margin-top:4px">
+            ${(data.flags||[]).map(f => `<span class="flag-chip">${f}</span>`).join(' ')}
+            <span class="meta-chip" style="margin-left:8px">PG score: ${(data.pg_score||0).toFixed(3)} · Guard: ${data.guard_ms||0}ms</span>
+        </div>
+    `;
+    chatArea.appendChild(div);
+    scrollBottom();
+}
+
+// ── Main send logic ───────────────────────────────────────────────────────────
+async function sendMessage() {
+    const prompt = input.value.trim();
+    if (!prompt) return;
+
+    hideWelcome();
+    input.value = '';
+    input.style.height = 'auto';
+    sendBtn.disabled = true;
+
+    appendUser(prompt);
+
+    const state  = createAssistantBubble();
+    const bubble = state.getBubble();
+    const meta   = state.getMeta();
+    const shield = state.getShield();
+
+    const tStart = performance.now();
+    let currentSentenceId = 0;
+    let blocked = false;
+    let guardMs = 0;
+
+    try {
+        const res = await fetch(SIDECAR_URL, {
+            method:  'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body:    JSON.stringify({ prompt, stream: true }),
+        });
+
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            shield.style.display = 'none';
+            bubble.innerHTML = `<span style="color:var(--danger)">Error: ${esc(err.detail || res.statusText)}</span>`;
+            sendBtn.disabled = false;
+            return;
+        }
+
+        const reader  = res.body.getReader();
+        const decoder = new TextDecoder();
+        let   rawBuf  = '';
+
+        // Remove blinking cursor initially placed
+        bubble.innerHTML = '';
+
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            rawBuf += decoder.decode(value, { stream: true });
+
+            // Parse SSE lines
+            const lines = rawBuf.split('\n');
+            rawBuf = lines.pop();  // keep incomplete line
+
+            for (const line of lines) {
+                if (!line.startsWith('data: ')) continue;
+                let ev;
+                try { ev = JSON.parse(line.slice(6)); } catch { continue; }
+
+                switch (ev.type) {
+
+                    // ── Raw token chunk → append immediately ──────────────
+                    case 'chunk': {
+                        // We actually render sentence spans, not raw chunks
+                        // Chunks are for the browser but we track sentences for guard
+                        // Simple approach: append text nodes directly
+                        bubble.appendChild(document.createTextNode(ev.text));
+                        scrollBottom();
+                        break;
+                    }
+
+                    // ── Complete sentence → wrap in span with data-sid ────
+                    case 'sentence': {
+                        // Replace plain text accumulated in bubble with a tracked span
+                        // Strategy: clear bubble's text nodes, re-render as spans
+                        currentSentenceId = ev.sentence_id;
+
+                        // Find last text node and replace with span
+                        const lastChild = bubble.lastChild;
+                        if (lastChild && lastChild.nodeType === Node.TEXT_NODE) {
+                            bubble.removeChild(lastChild);
+                        }
+                        const span = document.createElement('span');
+                        span.dataset.sid = ev.sentence_id;
+                        span.textContent = ev.text + ' ';
+                        bubble.appendChild(span);
+                        scrollBottom();
+                        break;
+                    }
+
+                    // ── Guard blocked the prompt (pre-inference) ───���──────
+                    case 'blocked': {
+                        blocked = true;
+                        guardMs = ev.guard_ms || 0;
+
+                        // Remove the assistant bubble we created
+                        bubble.closest('.msg').remove();
+                        appendBlocked(ev);
+                        setLatency(ev.guard_ms, ev.guard_ms);
+                        break;
+                    }
+
+                    // ── Mid-stream block signal (post-monitor) ────────────
+                    case 'block_signal': {
+                        applyBlockSignal(bubble, state, ev);
+                        break;
+                    }
+
+                    // ── Stream done ───────────────────────────────────────
+                    case 'done': {
+                        // Remove trailing cursor if present
+                        const cursor = bubble.querySelector('.stream-cursor');
+                        if (cursor) cursor.remove();
+
+                        renderDone(meta, shield, ev);
+                        setLatency(null, ev.latency_ms);
+                        break;
+                    }
+                }
+            }
+        }
+
+    } catch (err) {
+        shield.style.display = 'none';
+        bubble.innerHTML = `<span style="color:var(--danger)">Connection error: ${esc(err.message)}</span>`;
+    }
+
+    sendBtn.disabled = false;
+    input.focus();
+}
+
+// ── Health check on load ──────────────────────────────────────────────────────
+(async () => {
+    try {
+        const r = await fetch('/v1/health');
+        const d = await r.json();
+        if (!d.guard_ready) {
+            document.getElementById('status-dot').style.background = 'var(--warn)';
+            document.getElementById('status-dot').style.boxShadow  = '0 0 6px var(--warn)';
+            document.getElementById('status-dot').title = 'Guard not ready';
+        }
+    } catch {
+        document.getElementById('status-dot').style.background = 'var(--danger)';
+        document.getElementById('status-dot').title = 'Sidecar unreachable';
+    }
+})();
+</script>
+</body>
+</html>