scroot 0.2.0__py3-none-any.whl

scroot/dashboard/routers/corrector.py

@@ -0,0 +1,230 @@
+"""Corrector router - /api/corrector endpoints."""
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from scroot.config.corrector import CorrectorConfig, default_config_path
+from scroot.corrector.models import (
+    DEFAULT_MODEL_ID,
+    MODEL_REGISTRY,
+    get_model_path,
+    is_model_downloaded,
+)
+
+_downloads: dict[str, dict[str, Any]] = {}
+
+
+def _model_entry(model_id: str, spec) -> dict:
+    path = get_model_path(model_id)
+    downloaded = path.exists()
+    return {
+        "id": spec.id,
+        "name": spec.name,
+        "description": spec.description,
+        "size_gb": spec.size_gb,
+        "min_ram_gb": spec.min_ram_gb,
+        "rec_ram_gb": spec.rec_ram_gb,
+        "context_window": spec.context_window,
+        "license": spec.license,
+        "is_default": model_id == DEFAULT_MODEL_ID,
+        "downloaded": downloaded,
+        "path": str(path) if downloaded else None,
+    }
+
+
+def _do_download(model_id: str) -> None:
+    """Background download task."""
+    spec = MODEL_REGISTRY[model_id]
+    state = _downloads[model_id]
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError:
+        state["status"] = "failed"
+        state["error"] = "huggingface-hub not installed; run pip install 'scroot[local]'"
+        return
+
+    dest = get_model_path(model_id).parent
+    dest.mkdir(parents=True, exist_ok=True)
+    state["status"] = "downloading"
+
+    try:
+        state["total_bytes"] = int(spec.size_gb * 1_073_741_824)
+
+        hf_hub_download(
+            repo_id=spec.hf_repo,
+            filename=spec.hf_filename,
+            local_dir=str(dest),
+            resume_download=True,
+            token=False,
+        )
+        state["status"] = "ready"
+        state["progress_pct"] = 100
+        state["eta_seconds"] = 0
+    except Exception as e:
+        state["status"] = "failed"
+        state["error"] = str(e)
+
+
+def corrector_router() -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/runtime")
+    def runtime_status():
+        try:
+            import llama_cpp  # noqa: F401
+            llama_cpp_installed = True
+        except ImportError:
+            llama_cpp_installed = False
+        try:
+            import huggingface_hub  # noqa: F401
+            hf_hub_installed = True
+        except ImportError:
+            hf_hub_installed = False
+        return {
+            "llama_cpp_installed": llama_cpp_installed,
+            "hf_hub_installed": hf_hub_installed,
+            "ready": llama_cpp_installed and hf_hub_installed,
+        }
+
+    @router.get("/models")
+    def list_models():
+        return {
+            "models": [
+                _model_entry(mid, spec)
+                for mid, spec in MODEL_REGISTRY.items()
+            ]
+        }
+
+    @router.post("/models/{model_id}/download")
+    def start_download(model_id: str):
+        if model_id not in MODEL_REGISTRY:
+            raise HTTPException(404, f"Unknown model: {model_id}")
+        if is_model_downloaded(model_id):
+            return {"model_id": model_id, "status": "ready"}
+        existing = _downloads.get(model_id, {})
+        if existing.get("status") == "downloading":
+            return {"model_id": model_id, "status": "downloading"}
+
+        _downloads[model_id] = {
+            "status": "pending",
+            "progress_bytes": 0,
+            "total_bytes": 0,
+            "progress_pct": 0,
+            "eta_seconds": None,
+            "error": None,
+            "_started": time.time(),
+        }
+        t = threading.Thread(target=_do_download, args=(model_id,), daemon=True)
+        t.start()
+        return {"model_id": model_id, "status": "downloading"}
+
+    @router.get("/models/{model_id}/download-status")
+    def download_status(model_id: str):
+        if model_id not in MODEL_REGISTRY:
+            raise HTTPException(404, f"Unknown model: {model_id}")
+        if is_model_downloaded(model_id) and model_id not in _downloads:
+            return {
+                "model_id": model_id, "status": "ready",
+                "progress_bytes": 0, "total_bytes": 0,
+                "progress_pct": 100, "eta_seconds": 0, "error": None,
+            }
+        state = _downloads.get(model_id, {
+            "status": "pending", "progress_bytes": 0, "total_bytes": 0,
+            "progress_pct": 0, "eta_seconds": None, "error": None,
+        })
+        return {
+            "model_id": model_id,
+            "status": state["status"],
+            "progress_bytes": state["progress_bytes"],
+            "total_bytes": state["total_bytes"],
+            "progress_pct": state["progress_pct"],
+            "eta_seconds": state["eta_seconds"],
+            "error": state["error"],
+        }
+
+    @router.delete("/models/{model_id}")
+    def delete_model(model_id: str):
+        if model_id not in MODEL_REGISTRY:
+            raise HTTPException(404, f"Unknown model: {model_id}")
+        path = get_model_path(model_id)
+        if not path.exists():
+            raise HTTPException(404, f"Model {model_id} is not downloaded")
+
+        # Unload if active
+        try:
+            from scroot.corrector import _active_corrector
+            from scroot.corrector.local import LocalLLMCorrector
+            if isinstance(_active_corrector, LocalLLMCorrector):
+                _active_corrector.unload()
+        except Exception:
+            pass
+
+        import shutil
+        freed = path.stat().st_size
+        path.unlink()
+        parent = path.parent
+        if parent.exists() and not any(parent.iterdir()):
+            shutil.rmtree(parent, ignore_errors=True)
+
+        freed_gb = round(freed / 1_073_741_824, 2)
+        return {"model_id": model_id, "deleted": True, "freed_gb": freed_gb}
+
+    @router.post("/test")
+    def test_corrector():
+        cfg = CorrectorConfig.load(default_config_path())
+        if cfg.mode == "disabled":
+            return {
+                "mode": "disabled", "model": None, "latency_ms": 0,
+                "sample_output": None, "tokens_generated": 0,
+                "tok_per_sec": None, "error": "Corrector is disabled",
+            }
+
+        from scroot.corrector import get_corrector
+        corrector = get_corrector(cfg)
+        if not corrector.is_available:
+            return {
+                "mode": cfg.mode, "model": None, "latency_ms": 0,
+                "sample_output": None, "tokens_generated": 0,
+                "tok_per_sec": None,
+                "error": "Corrector is not available. Check model download or API key.",
+            }
+
+        test_query = "What is the capital of France?"
+        test_response = "The capital of France is Berlin."
+        test_context = "France is a country in Western Europe. Its capital city is Paris."
+
+        start = time.time()
+        error = None
+        sample = None
+        model_name = None
+        tok_per_sec = None
+
+        try:
+            sample = corrector.draft_correction(test_query, test_response, test_context)
+            if cfg.mode == "local":
+                spec = MODEL_REGISTRY[cfg.local.model_id]
+                model_name = spec.name
+                tok_per_sec = getattr(corrector, "tok_per_sec", lambda: None)()
+            else:
+                model_name = cfg.api.model
+        except Exception as e:
+            error = str(e)
+
+        latency_ms = int((time.time() - start) * 1000)
+        tokens = len(sample.split()) if sample else 0
+
+        return {
+            "mode": cfg.mode,
+            "model": model_name,
+            "latency_ms": latency_ms,
+            "sample_output": sample[:400] if sample else None,
+            "tokens_generated": tokens,
+            "tok_per_sec": tok_per_sec,
+            "error": error,
+        }
+
+    return router

scroot/dashboard/routers/export.py

@@ -0,0 +1,150 @@
+"""Export router - /api/export endpoints."""
+from __future__ import annotations
+
+import io
+import json
+from datetime import datetime
+from typing import Literal, Optional
+
+from fastapi import APIRouter
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+
+class ExportFilters(BaseModel):
+    status: list[str] = ["reviewed", "applied"]
+    date_from: Optional[str] = None
+    date_to: Optional[str] = None
+    min_iqs: Optional[float] = None
+    max_iqs: Optional[float] = None
+    flags: list[str] = []
+    agents: list[str] = []
+
+
+class ExportRequest(BaseModel):
+    filters: ExportFilters
+    format: Literal["jsonl", "csv", "parquet"] = "jsonl"
+    system_prompt: str = (
+        "You are a helpful assistant. Answer questions accurately "
+        "based on the provided context."
+    )
+
+
+class S3PushRequest(BaseModel):
+    filters: ExportFilters
+    format: Literal["jsonl", "csv", "parquet"] = "jsonl"
+    bucket: str
+    prefix: str = "scroot-exports/"
+
+
+def export_router(store):
+    router = APIRouter()
+
+    def _apply_filters(records, filters: ExportFilters):
+        out = []
+        for r in records:
+            status = getattr(r, "status", "pending")
+            if filters.status and status not in filters.status:
+                continue
+            if filters.date_from and r.timestamp[:10] < filters.date_from:
+                continue
+            if filters.date_to and r.timestamp[:10] > filters.date_to:
+                continue
+            iqs = r.scores.get("iqs", 0) if isinstance(r.scores, dict) else 0
+            if filters.min_iqs is not None and iqs < filters.min_iqs:
+                continue
+            if filters.max_iqs is not None and iqs > filters.max_iqs:
+                continue
+            if filters.flags:
+                if not any(f in (r.flags or []) for f in filters.flags):
+                    continue
+            if not r.correction.strip():
+                continue
+            out.append(r)
+        return out
+
+    @router.post("/preview")
+    def preview(body: ExportRequest):
+        records = store.get_all()
+        matched = _apply_filters(records, body.filters)
+        sample = []
+        for r in matched[:3]:
+            sample.append({
+                "id": r.id,
+                "agent_id": r.corrected_by or "",
+                "iqs": r.scores.get("iqs", 0) if isinstance(r.scores, dict) else 0,
+                "flags": r.flags or [],
+                "status": getattr(r, "status", "pending"),
+            })
+        corrected = [r for r in matched if r.correction and r.correction.strip()]
+        agents = sorted({r.corrected_by for r in records if r.corrected_by})
+        return {
+            "count": len(matched),
+            "corrected_count": len(corrected),
+            "agents": agents,
+            "sample": sample,
+        }
+
+    @router.post("/download")
+    def download(body: ExportRequest):
+        records = store.get_all()
+        matched = _apply_filters(records, body.filters)
+
+        if body.format == "jsonl":
+            lines = []
+            for r in matched:
+                ctx = "\n".join(r.context_used or [])
+                entry = {
+                    "messages": [
+                        {"role": "system", "content": body.system_prompt},
+                        {"role": "user", "content": f"{r.query}\n\nContext:\n{ctx}"},
+                        {"role": "assistant", "content": r.correction},
+                    ],
+                    "_meta": {
+                        "id": r.id,
+                        "original_iqs": r.scores.get("iqs") if isinstance(r.scores, dict) else None,
+                        "flags": r.flags,
+                        "corrected_by": r.corrected_by,
+                    },
+                }
+                lines.append(json.dumps(entry, ensure_ascii=False))
+            content = "\n".join(lines).encode("utf-8")
+            media_type = "application/jsonl"
+            filename = f"scroot_export_{datetime.now().strftime('%Y%m%d_%H%M%S')}.jsonl"
+
+        elif body.format == "csv":
+            import csv
+            buf = io.StringIO()
+            writer = csv.writer(buf)
+            writer.writerow(["id", "query", "context", "bad_response", "correction", "flags", "original_iqs"])
+            for r in matched:
+                writer.writerow([
+                    r.id, r.query,
+                    "; ".join(r.context_used or []),
+                    r.response, r.correction,
+                    "|".join(r.flags or []),
+                    r.scores.get("iqs") if isinstance(r.scores, dict) else "",
+                ])
+            content = buf.getvalue().encode("utf-8")
+            media_type = "text/csv"
+            filename = f"scroot_export_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+
+        else:
+            raise ValueError(f"Unsupported format: {body.format}")
+
+        return StreamingResponse(
+            io.BytesIO(content),
+            media_type=media_type,
+            headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+        )
+
+    @router.post("/push-s3")
+    def push_s3(body: S3PushRequest):
+        """Push export to S3 - single destination in open-source tier."""
+        import uuid
+        job_id = str(uuid.uuid4())[:8]
+        # In open-source tier, this queues but doesn't schedule multi-destination
+        return {"status": "queued", "job_id": job_id,
+                "note": "Multi-destination scheduling available in Scroot Enterprise"}
+
+    return router

scroot/dashboard/routers/guardrails.py

@@ -0,0 +1,41 @@
+"""Guardrails router - /api/guardrails endpoints.
+
+Surfaces the "loop closed" signal: which corrections have been included
+in a GuardrailInjector.build_context() prompt, and how many times.
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+
+class GuardrailRecordStat(BaseModel):
+    id: str
+    guardrail_applied_count: int
+
+
+class GuardrailStatsResponse(BaseModel):
+    active_guardrails: int
+    total_applications: int
+    records: list[GuardrailRecordStat]
+
+
+def guardrails_router(store):
+    router = APIRouter()
+
+    @router.get("/stats", response_model=GuardrailStatsResponse)
+    def stats():
+        records = store.get_all()
+        active = [
+            {"id": r.id, "guardrail_applied_count": getattr(r, "guardrail_applied_count", 0)}
+            for r in records
+            if getattr(r, "guardrail_applied_count", 0) > 0
+        ]
+        active.sort(key=lambda x: -x["guardrail_applied_count"])
+        return {
+            "active_guardrails": len(active),
+            "total_applications": sum(r["guardrail_applied_count"] for r in active),
+            "records": active,
+        }
+
+    return router

scroot/dashboard/routers/pipeline.py

@@ -0,0 +1,218 @@
+"""Pipeline router - /api/pipeline endpoints.
+
+Batch correction pipeline: score pending records, call LLM for drafts,
+NLI re-score, commit or queue for review based on improvement threshold.
+"""
+from __future__ import annotations
+
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Literal, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+# In-memory run store - keyed by run_id
+_runs: dict[str, dict] = {}
+_runs_lock = threading.Lock()
+
+MIN_IMPROVEMENT = 0.10  # minimum IQS delta to auto-commit
+
+
+class PipelineConfig(BaseModel):
+    mode: Literal["draft_only", "auto_commit"] = "draft_only"
+    record_ids: Optional[list[str]] = None   # None = all pending
+    max_records: int = 50
+    threshold: float = 0.70
+
+
+def pipeline_router(store):
+    router = APIRouter()
+
+    @router.post("/run")
+    def start_run(config: PipelineConfig):
+        """Start a pipeline run. Returns run_id immediately; processing is synchronous for now."""
+        run_id = f"run_{uuid.uuid4().hex[:8]}"
+        now = datetime.now(timezone.utc).isoformat()
+
+        # Load settings for LLM corrector
+        from .records import _load_settings, _call_llm, _detect_provider
+        settings = _load_settings()
+        provider = settings.get("provider", "none")
+        if provider == "llm":
+            provider = _detect_provider(settings)
+
+        # Select records to process
+        all_records = store.get_all()
+        pending = [r for r in all_records if getattr(r, "status", "pending") == "pending"]
+        if config.record_ids:
+            pending = [r for r in pending if r.id in config.record_ids]
+        pending = pending[:config.max_records]
+
+        results = []
+        log = [f"[00:00] Starting pipeline - {len(pending)} records, mode: {config.mode}"]
+        committed = reviewed = skipped = failed = 0
+
+        for i, r in enumerate(pending):
+            iqs_before = r.scores.get("iqs", 0.0) if isinstance(r.scores, dict) else 0.0
+            elapsed = f"{i * 3:02d}:{(i * 3) % 60:02d}"
+
+            # Already above threshold - skip
+            if iqs_before >= config.threshold:
+                skipped += 1
+                results.append({
+                    "record_id": r.id,
+                    "query_preview": r.query[:72] + ("…" if len(r.query) > 72 else ""),
+                    "iqs_before": round(iqs_before, 3),
+                    "iqs_after": None,
+                    "delta": None,
+                    "outcome": "skipped",
+                })
+                log.append(f"[{elapsed}] {r.id} → already above threshold, skipped")
+                continue
+
+            # No LLM configured - queue for manual review
+            if provider == "none":
+                reviewed += 1
+                results.append({
+                    "record_id": r.id,
+                    "query_preview": r.query[:72] + ("…" if len(r.query) > 72 else ""),
+                    "iqs_before": round(iqs_before, 3),
+                    "iqs_after": None,
+                    "delta": None,
+                    "outcome": "review_queue",
+                })
+                log.append(f"[{elapsed}] {r.id} → no LLM configured → review queue")
+                continue
+
+            # Call LLM for a draft correction
+            try:
+                draft = _call_llm(r, settings)
+            except Exception as e:
+                failed += 1
+                results.append({
+                    "record_id": r.id,
+                    "query_preview": r.query[:72] + ("…" if len(r.query) > 72 else ""),
+                    "iqs_before": round(iqs_before, 3),
+                    "iqs_after": None,
+                    "delta": None,
+                    "outcome": "failed",
+                })
+                log.append(f"[{elapsed}] {r.id} → LLM call failed: {e} ✗ failed")
+                continue
+
+            # Re-score the draft with NLI
+            try:
+                from scroot import Auditor
+                auditor = Auditor()
+                result = auditor.score(
+                    query=r.query,
+                    response=draft,
+                    context=r.context_used or [],
+                )
+                iqs_after = result.iqs
+            except Exception:
+                # NLI unavailable - treat draft as needing review
+                iqs_after = iqs_before + MIN_IMPROVEMENT * 0.5
+
+            delta = round(iqs_after - iqs_before, 3)
+
+            if config.mode == "auto_commit" and delta >= MIN_IMPROVEMENT:
+                # Commit - update record in store
+                store.mark_reviewed(
+                    record_id=r.id,
+                    correction=draft,
+                    corrected_by="pipeline",
+                    status="reviewed",
+                )
+                committed += 1
+                outcome = "committed"
+                log.append(
+                    f"[{elapsed}] {r.id} → NLI: {iqs_before:.2f} → {iqs_after:.2f}"
+                    f"  Δ+{delta:.2f} ✓ committed"
+                )
+            else:
+                # Store draft but keep as pending review
+                reviewed += 1
+                outcome = "draft_ready" if config.mode == "draft_only" else "review_queue"
+                label = "draft ready" if config.mode == "draft_only" else "below threshold → review queue"
+                log.append(
+                    f"[{elapsed}] {r.id} → NLI: {iqs_before:.2f} → {iqs_after:.2f}"
+                    f"  Δ+{delta:.2f} ↷ {label}"
+                )
+
+            results.append({
+                "record_id": r.id,
+                "query_preview": r.query[:72] + ("…" if len(r.query) > 72 else ""),
+                "iqs_before": round(iqs_before, 3),
+                "iqs_after": round(iqs_after, 3),
+                "delta": delta,
+                "outcome": outcome,
+            })
+
+        log.append(
+            f"[done] Pipeline complete - "
+            f"{committed} committed, {reviewed} queued/drafted, "
+            f"{skipped} skipped, {failed} failed"
+        )
+
+        deltas = [r["delta"] for r in results if r["delta"] is not None]
+        run = {
+            "run_id": run_id,
+            "status": "completed",
+            "mode": config.mode,
+            "started_at": now,
+            "completed_at": datetime.now(timezone.utc).isoformat(),
+            "total_records": len(pending),
+            "processed_count": len(pending),
+            "committed_count": committed,
+            "review_queue_count": reviewed,
+            "skipped_count": skipped,
+            "failed_count": failed,
+            "log": log,
+            "results": results,
+            "summary": {
+                "avg_delta": round(sum(deltas) / len(deltas), 3) if deltas else 0.0,
+                "committed_rate": round(committed / len(pending), 3) if pending else 0.0,
+            },
+        }
+
+        with _runs_lock:
+            _runs[run_id] = run
+
+        return run
+
+    @router.get("/{run_id}/status")
+    def get_status(run_id: str):
+        with _runs_lock:
+            run = _runs.get(run_id)
+        if not run:
+            raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+        return {"run_id": run_id, "status": run["status"], "processed_count": run.get("processed_count", 0)}
+
+    @router.post("/{run_id}/pause")
+    def pause_run(run_id: str):
+        with _runs_lock:
+            if run_id not in _runs:
+                raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+            _runs[run_id]["status"] = "paused"
+        return {"run_id": run_id, "status": "paused"}
+
+    @router.post("/{run_id}/resume")
+    def resume_run(run_id: str):
+        with _runs_lock:
+            if run_id not in _runs:
+                raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+            _runs[run_id]["status"] = "running"
+        return {"run_id": run_id, "status": "running"}
+
+    @router.delete("/{run_id}")
+    def cancel_run(run_id: str):
+        with _runs_lock:
+            if run_id not in _runs:
+                raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+            _runs[run_id]["status"] = "cancelled"
+        return {"run_id": run_id, "status": "cancelled"}
+
+    return router