cats-scoring 1.3.0__py3-none-any.whl

cats/__init__.py

@@ -0,0 +1,3 @@
+"""CATS (Contextual Ambiguity & Trust Scoring) — production-ready trust evaluation API."""
+
+__version__ = "1.3.0"

cats/api/__init__.py

@@ -0,0 +1 @@
+"""API layer: FastAPI routes, schemas, and request handling."""

cats/api/main.py

@@ -0,0 +1,145 @@
+import logging
+import time
+from contextlib import asynccontextmanager
+
+import structlog
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, Response
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+
+from cats.api.routes.evaluate import router as evaluate_router
+from cats.audit.logger import purge_expired_audits
+from cats.core.config import settings
+from cats.core.db import AsyncSessionLocal
+from cats.core.metrics import HTTP_LATENCY, HTTP_REQUESTS
+from cats.core.security import init_jwt_keys, init_redis
+from cats.signals.coherence import init_nlp
+
+# N-06: JSON structured logging. Use structlog-native processors + a filtering
+# bound logger so level filtering works without a stdlib logging backend (the
+# stdlib `filter_by_level` processor calls isEnabledFor(), which PrintLogger
+# lacks, and would crash on every log call).
+structlog.configure(
+    processors=[
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.JSONRenderer(),
+    ],
+    wrapper_class=structlog.make_filtering_bound_logger(getattr(logging, settings.log_level.upper(), logging.INFO)),
+    logger_factory=structlog.PrintLoggerFactory(),
+    cache_logger_on_first_use=True,
+)
+logger = structlog.get_logger()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("startup", env=settings.environment)
+    init_jwt_keys()  # S-01
+    await init_redis()  # S-03
+    init_nlp(settings.spacy_model)  # N-01: singleton
+
+    # Q-03: max_instances=1 prevents overlapping purge jobs
+    sched = AsyncIOScheduler()
+    sched.add_job(_purge_job, "cron", hour=2, minute=0, max_instances=1, coalesce=True, misfire_grace_time=3600)
+    sched.start()
+    yield
+    sched.shutdown()
+    logger.info("shutdown")
+
+
+async def _purge_job():
+    async with AsyncSessionLocal() as db:
+        await purge_expired_audits(db)
+
+
+app = FastAPI(title="CATS API", version="1.2.0", lifespan=lifespan)
+
+if settings.cors_origins:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[o.strip() for o in settings.cors_origins.split(",")],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+app.include_router(evaluate_router, prefix="/v1/cats", tags=["cats"])
+
+
+# N-07: Prometheus request metrics. Label by the matched route template (not the
+# raw path) to keep label cardinality bounded.
+@app.middleware("http")
+async def _prometheus_middleware(request: Request, call_next):
+    start = time.perf_counter()
+    response = await call_next(request)
+    route = request.scope.get("route")
+    path = getattr(route, "path", None) or "unmatched"
+    HTTP_REQUESTS.labels(request.method, path, response.status_code).inc()
+    HTTP_LATENCY.labels(request.method, path).observe(time.perf_counter() - start)
+    return response
+
+
+# A-03: RFC 7807 Problem Details
+@app.exception_handler(RequestValidationError)
+async def _val_err(request: Request, exc: RequestValidationError):
+    return JSONResponse(
+        status_code=422,
+        content={
+            "type": "about:blank",
+            "title": "Validation Error",
+            "status": 422,
+            "detail": exc.errors(),
+            "instance": str(request.url),
+        },
+    )
+
+
+@app.exception_handler(Exception)
+async def _generic_err(request: Request, exc: Exception):
+    logger.error("unhandled", error=str(exc), path=str(request.url))
+    return JSONResponse(
+        status_code=500,
+        content={
+            "type": "about:blank",
+            "title": "Internal Server Error",
+            "status": 500,
+            "detail": "Unexpected error",
+            "instance": str(request.url),
+        },
+    )
+
+
+# Q-02: deep health check
+@app.get("/health")
+async def health():
+    from cats.core.db import engine
+    from cats.core.security import redis_client
+    from cats.signals.coherence import nlp
+
+    checks: dict = {"api": "ok"}
+    try:
+        await redis_client.ping()
+        checks["redis"] = "ok"
+    except Exception as e:
+        checks["redis"] = f"error:{e}"
+    try:
+        from sqlalchemy import text
+
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+            checks["database"] = "ok"
+    except Exception as e:
+        checks["database"] = f"error:{e}"
+    checks["nlp"] = "ok" if nlp else "not_loaded"
+
+    overall = "healthy" if all(v == "ok" for v in checks.values()) else "degraded"
+    return {"status": overall, "checks": checks}
+
+
+@app.get("/metrics")
+async def metrics():
+    return Response(generate_latest(), media_type=CONTENT_TYPE_LATEST)

cats/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API route handlers."""

cats/api/routes/evaluate.py

@@ -0,0 +1,162 @@
+import asyncio
+import uuid
+from functools import partial
+
+import structlog
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from cats.api.schemas import (
+    BatchEvaluateRequest,
+    BatchEvaluateResponse,
+    ContestRequest,
+    ContestResponse,
+    EvaluateRequest,
+    EvaluateResponse,
+    ExplainResponse,
+    StatsResponse,
+)
+from cats.audit.logger import log_contest, log_evaluation
+from cats.core.db import get_db
+from cats.core.metrics import EVALUATIONS, TRUST_SCORE
+from cats.core.models import TrustScore
+from cats.core.security import api_key_bearer, get_client_ip, get_tenant
+from cats.pipeline.normalizer import normalize_messages
+from cats.scoring.engine import aggregate_score, determine_band, requires_human_review
+from cats.scoring.explainer import generate_explanation
+from cats.scoring.weights import get_dynamic_weights
+from cats.signals.coherence import compute_coherence
+from cats.signals.gaming import compute_gaming
+from cats.signals.silence import compute_silence
+from cats.signals.types import SignalResult
+from cats.signals.volatility import compute_volatility
+
+logger = structlog.get_logger()
+router = APIRouter()
+
+
+async def _evaluate_item(item: EvaluateRequest, request: Request, db: AsyncSession) -> EvaluateResponse:
+    """Run the 4-signal pipeline for one source and stage the result + audit row.
+
+    Does not commit: the caller commits so /evaluate and /batch control the
+    transaction boundary (a batch is all-or-nothing).
+    """
+    trace_id = str(uuid.uuid4())
+    tenant_id = get_tenant(request)
+    msgs = normalize_messages([m.model_dump() for m in item.messages])
+    context = item.context or {}
+
+    loop = asyncio.get_running_loop()
+    raw_signals = await asyncio.gather(
+        loop.run_in_executor(None, compute_coherence, msgs),
+        loop.run_in_executor(None, compute_volatility, msgs),
+        loop.run_in_executor(None, partial(compute_silence, msgs, context.get("source_type", "social"))),
+        loop.run_in_executor(None, compute_gaming, msgs),
+    )
+    signals: list[SignalResult] = list(raw_signals)
+    weights = get_dynamic_weights(context)
+    score = aggregate_score(signals, weights)
+    band = determine_band(score)
+    review = requires_human_review(score, band, signals)
+
+    EVALUATIONS.labels(band=band).inc()
+    TRUST_SCORE.observe(score)
+
+    db.add(
+        TrustScore(
+            tenant_id=tenant_id,
+            trace_id=trace_id,
+            source_id=item.source_id,
+            score=score,
+            band=band,
+            signals={s.name: {"value": s.value, "confidence": s.confidence} for s in signals},
+            weights=weights,
+            context_data=context,
+        )
+    )
+    await log_evaluation(
+        db,
+        trace_id,
+        {"source_id": item.source_id, "score": score, "band": band},
+        ip=get_client_ip(request),
+        tenant_id=tenant_id,
+    )
+
+    return EvaluateResponse(
+        trace_id=trace_id,
+        score=score,
+        band=band,
+        requires_review=review,
+        signals=[
+            {"name": s.name, "value": s.value, "confidence": s.confidence, "metadata": s.metadata} for s in signals
+        ],
+    )
+
+
+@router.post("/evaluate", response_model=EvaluateResponse, dependencies=[Depends(api_key_bearer)])
+async def evaluate(req: EvaluateRequest, request: Request, db: AsyncSession = Depends(get_db)):
+    result = await _evaluate_item(req, request, db)
+    await db.commit()
+    return result
+
+
+@router.post("/batch", response_model=BatchEvaluateResponse, dependencies=[Depends(api_key_bearer)])
+async def batch_evaluate(req: BatchEvaluateRequest, request: Request, db: AsyncSession = Depends(get_db)):
+    # Sequential per item (signals within an item already run in parallel); a
+    # single commit keeps the batch atomic.
+    results = [await _evaluate_item(item, request, db) for item in req.items]
+    await db.commit()
+    return BatchEvaluateResponse(count=len(results), results=results)
+
+
+@router.get("/explain/{trace_id}", response_model=ExplainResponse, dependencies=[Depends(api_key_bearer)])
+async def explain(trace_id: str, request: Request, db: AsyncSession = Depends(get_db)):
+    r = await db.execute(
+        select(TrustScore).where(TrustScore.trace_id == trace_id, TrustScore.tenant_id == get_tenant(request))
+    )
+    ts = r.scalars().first()
+    if not ts:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Trace ID not found")
+    sigs = [SignalResult(name=n, value=d["value"], confidence=d["confidence"]) for n, d in ts.signals.items()]
+    return ExplainResponse(trace_id=trace_id, explanation=generate_explanation(ts.score, ts.band, sigs, ts.weights))
+
+
+@router.post("/contest/{trace_id}", response_model=ContestResponse, dependencies=[Depends(api_key_bearer)])
+async def contest(trace_id: str, body: ContestRequest, request: Request, db: AsyncSession = Depends(get_db)):
+    tenant_id = get_tenant(request)
+    r = await db.execute(select(TrustScore).where(TrustScore.trace_id == trace_id, TrustScore.tenant_id == tenant_id))
+    if not r.scalars().first():
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Trace ID not found")
+    cid = await log_contest(db, trace_id, body.reason, tenant_id=tenant_id)  # D-02: returns cid
+    return ContestResponse(contest_id=cid, status="pending")
+
+
+@router.post("/review/{trace_id}", dependencies=[Depends(api_key_bearer)])
+async def review(trace_id: str, request: Request, db: AsyncSession = Depends(get_db)):
+    tenant_id = get_tenant(request)
+    r = await db.execute(select(TrustScore).where(TrustScore.trace_id == trace_id, TrustScore.tenant_id == tenant_id))
+    if not r.scalars().first():
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Trace ID not found")
+    await log_evaluation(
+        db, trace_id, {"event": "human_review_requested"}, ip=get_client_ip(request), tenant_id=tenant_id
+    )
+    await db.commit()
+    return {"message": "Review logged", "trace_id": trace_id}
+
+
+@router.get("/stats", response_model=StatsResponse, dependencies=[Depends(api_key_bearer)])
+async def stats(request: Request, db: AsyncSession = Depends(get_db)):
+    tenant_id = get_tenant(request)
+    total = await db.scalar(select(func.count(TrustScore.id)).where(TrustScore.tenant_id == tenant_id))
+    avg = await db.scalar(select(func.avg(TrustScore.score)).where(TrustScore.tenant_id == tenant_id))
+    bands_raw = await db.execute(
+        select(TrustScore.band, func.count(TrustScore.id))
+        .where(TrustScore.tenant_id == tenant_id)
+        .group_by(TrustScore.band)
+    )
+    return StatsResponse(
+        total_evaluations=total or 0,
+        average_score=avg or 0.0,
+        band_distribution={r[0]: r[1] for r in bands_raw.all()},
+    )

cats/api/schemas.py

@@ -0,0 +1,69 @@
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class MessageSchema(BaseModel):
+    timestamp: str = Field(..., description="ISO 8601 UTC (e.g. 2024-01-15T10:00:00Z)")
+    text: str = Field(..., min_length=1, max_length=10_000)
+    metadata: Optional[Dict[str, Any]] = None
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp(cls, v: str) -> str:
+        from datetime import datetime
+
+        try:
+            datetime.fromisoformat(v.replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError("timestamp must be ISO 8601 UTC")
+        return v
+
+
+class EvaluateRequest(BaseModel):
+    source_id: str = Field(..., min_length=1, max_length=256)
+    messages: List[MessageSchema] = Field(..., min_length=1, max_length=500)
+    context: Optional[Dict[str, Any]] = None
+
+
+class EvaluateResponse(BaseModel):
+    trace_id: str
+    score: float
+    band: str
+    requires_review: bool
+    signals: List[Dict[str, Any]]
+
+
+class BatchEvaluateRequest(BaseModel):
+    items: List[EvaluateRequest] = Field(..., min_length=1, max_length=50)
+
+
+class BatchEvaluateResponse(BaseModel):
+    count: int
+    results: List[EvaluateResponse]
+
+
+class ExplainResponse(BaseModel):
+    trace_id: str
+    explanation: Dict[str, Any]
+
+
+class ContestRequest(BaseModel):
+    reason: str = Field(..., min_length=10, max_length=2000)
+
+
+class ContestResponse(BaseModel):
+    contest_id: int
+    status: str
+
+
+class StatsResponse(BaseModel):
+    total_evaluations: int
+    average_score: float
+    band_distribution: Dict[str, int]
+
+
+class HealthResponse(BaseModel):
+    status: str
+    checks: Dict[str, str]
+    version: str = "1.2.0"

cats/audit/__init__.py

@@ -0,0 +1 @@
+"""Audit logging and GDPR compliance."""

cats/audit/logger.py

@@ -0,0 +1,120 @@
+import base64
+import json
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import structlog
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from cats.core.config import settings
+from cats.core.models import AuditLog, Contest
+
+logger = structlog.get_logger()
+
+_gcm: Optional[AESGCM] = None
+
+
+def _get_gcm() -> AESGCM:
+    global _gcm
+    if _gcm is None:
+        key = base64.b64decode(settings.audit_encryption_key)
+        if len(key) != 32:
+            raise ValueError("AUDIT_ENCRYPTION_KEY must be exactly 32 bytes (256-bit) base64-encoded")
+        _gcm = AESGCM(key)
+    return _gcm
+
+
+def _encrypt(data: dict) -> str:
+    nonce = os.urandom(12)
+    ct = _get_gcm().encrypt(nonce, json.dumps(data).encode(), None)
+    return base64.b64encode(nonce + ct).decode()
+
+
+def _decrypt(blob: str) -> dict:
+    raw = base64.b64decode(blob)
+    return json.loads(_get_gcm().decrypt(raw[:12], raw[12:], None).decode())
+
+
+async def log_evaluation(
+    db: AsyncSession,
+    trace_id: str,
+    data: dict,
+    user_id: Optional[str] = None,
+    ip: Optional[str] = None,
+    tenant_id: str = "default",
+) -> None:
+    db.add(
+        AuditLog(
+            tenant_id=tenant_id,
+            trace_id=trace_id,
+            event_type="evaluation",
+            encrypted_data=_encrypt(data),
+            user_id=user_id,
+            ip_address=ip,
+            timestamp=datetime.now(timezone.utc),
+        )
+    )
+    await db.flush()
+
+
+async def log_contest(
+    db: AsyncSession,
+    trace_id: str,
+    reason: str,
+    user_id: Optional[str] = None,
+    tenant_id: str = "default",
+) -> int:
+    c = Contest(
+        tenant_id=tenant_id,
+        trace_id=trace_id,
+        reason=reason,
+        status="pending",
+        user_id=user_id,
+        created_at=datetime.now(timezone.utc),
+    )
+    db.add(c)
+    await db.commit()
+    await db.refresh(c)
+    return c.id
+
+
+async def get_audit_log(db: AsyncSession, trace_id: str) -> Optional[dict]:
+    r = await db.execute(select(AuditLog).where(AuditLog.trace_id == trace_id).order_by(AuditLog.timestamp.desc()))
+    a = r.scalars().first()
+    if not a:
+        return None
+    return {
+        "trace_id": a.trace_id,
+        "event_type": a.event_type,
+        "data": _decrypt(a.encrypted_data),
+        "timestamp": a.timestamp.isoformat(),
+    }
+
+
+def _get_redis():
+    from cats.core.security import redis_client
+
+    if redis_client is None:
+        raise RuntimeError("Redis not initialized — call init_redis() first")
+    return redis_client
+
+
+async def purge_expired_audits(db: AsyncSession) -> None:
+    redis = _get_redis()
+    acquired = await redis.set("cats:purge_lock", "1", nx=True, ex=300)
+    if not acquired:
+        logger.info("purge_skipped", reason="lock_held")
+        return
+    try:
+        cutoff = datetime.now(timezone.utc) - timedelta(days=settings.audit_retention_days)
+        res = await db.execute(select(AuditLog).where(AuditLog.timestamp < cutoff))
+        old = res.scalars().all()
+        for row in old:
+            await db.delete(row)
+        await db.commit()
+        logger.info("purge_done", deleted=len(old))
+    finally:
+        await redis.delete("cats:purge_lock")

cats/calibration/__init__.py

@@ -0,0 +1,24 @@
+"""CATS weight calibration.
+
+Tooling to empirically calibrate the signal weight matrix against a labelled
+dataset, replacing the initial hand-picked estimates flagged in WP 4.1.
+
+The optimisation uses a small, dependency-free genetic algorithm (see
+``cats.calibration.ga``). Because CATS scores are *ordinal* rankings (WP 4.3),
+the objective maximises a rank-agreement metric (Spearman / pairwise
+concordance) rather than absolute error.
+"""
+
+from cats.calibration.calibrate import CalibrationOutput, calibrate
+from cats.calibration.dataset import LabeledSample, load_dataset
+from cats.calibration.ga import GAConfig, GAResult, GeneticOptimizer
+
+__all__ = [
+    "calibrate",
+    "CalibrationOutput",
+    "load_dataset",
+    "LabeledSample",
+    "GeneticOptimizer",
+    "GAConfig",
+    "GAResult",
+]

cats/calibration/__main__.py

@@ -0,0 +1,4 @@
+from cats.calibration.calibrate import main
+
+if __name__ == "__main__":
+    main()