cats-scoring 1.3.0__tar.gz

cats_scoring-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leapfrog-LSA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cats_scoring-1.3.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: cats-scoring
+Version: 1.3.0
+Summary: Contextual Ambiguity & Trust Scoring — trust intelligence for OSINT sources
+Author: Leapfrog-LSA
+License: MIT
+Project-URL: Homepage, https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring
+Project-URL: Documentation, https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/tree/main/docs
+Project-URL: Changelog, https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/blob/main/CHANGELOG.md
+Keywords: osint,trust-scoring,source-reliability,disinformation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.6
+Requires-Dist: pydantic-settings<3.0,>=2.2
+Requires-Dist: spacy<4.0,>=3.7
+Requires-Dist: textblob<1.0,>=0.18
+Requires-Dist: structlog<25.0,>=24.1
+Requires-Dist: httpx<1.0,>=0.27
+Provides-Extra: sbert
+Requires-Dist: sentence-transformers<4.0,>=2.7; extra == "sbert"
+Provides-Extra: bert
+Requires-Dist: transformers<5.0,>=4.40; extra == "bert"
+Requires-Dist: torch<3.0,>=2.2; extra == "bert"
+Dynamic: license-file
+
+# CATS — Contextual Ambiguity & Trust Scoring
+
+> **Trust intelligence for OSINT sources — not fact-checking, but source reliability over time.**
+
+[![CI](https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/actions/workflows/ci.yml/badge.svg)](https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/actions) [![Coverage](https://codecov.io/gh/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/branch/main/graph/badge.svg)](https://codecov.io/gh/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE/) [![GDPR](https://img.shields.io/badge/GDPR-Art.13--22%20documented-blue)](docs/compliance.md) [![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-documented-blue)](docs/compliance.md)
+
+***
+
+## What is CATS?
+
+| ❌ Fact-checking             | ✅ CATS                                                         |
+| --------------------------- | -------------------------------------------------------------- |
+| "Is this information true?" | **"How reliable is this source, in this context, right now?"** |
+
+CATS analyses the _behavioural patterns_ of a source over time — narrative consistency, sentiment volatility, temporal gaps, and signs of algorithmic manipulation — and returns a transparent, explainable trust score.
+
+***
+
+## Signals
+
+| Signal         | What it measures                            | Method                                                     |
+| -------------- | ------------------------------------------- | ---------------------------------------------------------- |
+| **Coherence**  | Entity/argument consistency across messages | spaCy NER + Jaccard (or optional Sentence-BERT) similarity |
+| **Volatility** | Abrupt narrative tone changes               | TextBlob (or optional BERT) sentiment spike detection      |
+| **Silence**    | Anomalous temporal gaps in publishing       | Gap analysis vs. source-type thresholds                    |
+| **Gaming**     | Signs of algorithmic manipulation           | Repetition + TTR + burst + vocab diversity                 |
+
+***
+
+## Try it in 5 lines (no infrastructure)
+
+No database, no Redis, no API keys — the signal pipeline as a plain library call:
+
+```python
+from cats.lite import score
+
+result = score([
+    {"timestamp": "2026-01-01T08:00:00Z", "text": "Il governo annuncia un piano economico."},
+    {"timestamp": "2026-01-01T12:00:00Z", "text": "I sindacati commentano il piano."},
+    {"timestamp": "2026-01-02T09:00:00Z", "text": "Il parlamento discute la legge di bilancio."},
+], source_type="news")
+
+print(result["trust_score"], result["band"], result["explanation"]["primary_driver"])
+```
+
+Install with `pip install -r requirements.txt` (plus `make nlp-download` for full-fidelity coherence — without it the NER backend degrades to a neutral value). The full API below adds persistence, auditing and GDPR endpoints.
+
+Or try it in the browser: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/blob/main/examples/cats_lite_demo.ipynb)
+
+***
+
+## Quick Start (full deployment)
+
+```bash
+# 1. Clone and configure
+git clone https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring.git && cd CATS-Contextual-Ambiguity-Trust-Scoring
+cp .env.example .env          # fill in secrets (see .env.example)
+
+# 2. Install
+make dev-install              # deps + pre-commit hooks
+make nlp-download             # spaCy it_core_news_lg + TextBlob corpora
+
+# 3. Start services and run
+make docker-up                # PostgreSQL 16 + Redis 7
+make db-migrate               # Alembic migrations
+uvicorn cats.api.main:app --reload
+
+# 4. Test
+make test
+```
+
+> **Generate a secure AUDIT\_ENCRYPTION\_KEY**: `make generate-key`
+
+***
+
+## API Example
+
+```bash
+curl -s -X POST http://localhost:8000/v1/cats/evaluate \
+  -H "Authorization: Bearer $CATS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_id": "twitter:example_handle",
+    "messages": [
+      {"timestamp": "2026-01-01T08:00:00Z", "text": "Governo annuncia piano economico."},
+      {"timestamp": "2026-01-01T09:00:00Z", "text": "Protesta dei lavoratori in piazza."},
+      {"timestamp": "2026-01-01T10:00:00Z", "text": "Parlamento discute la legge di bilancio."}
+    ],
+    "context": {"source_type": "social"}
+  }' | jq
+```
+
+```json
+{
+  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
+  "score": 68.4,
+  "band": "medium_high",
+  "requires_review": false,
+  "signals": [
+    {"name": "coherence",  "value": 71.2, "confidence": 0.3},
+    {"name": "volatility", "value": 55.0, "confidence": 0.15},
+    {"name": "silence",    "value": 0.0,  "confidence": 0.1},
+    {"name": "gaming",     "value": 12.8, "confidence": 0.06}
+  ]
+}
+```
+
+***
+
+## Trust Score Bands
+
+| Score  | Band          | Recommended Action            |
+| ------ | ------------- | ----------------------------- |
+| 80–100 | `high`        | Usable for OSINT              |
+| 60–79  | `medium_high` | Cross-validate key claims     |
+| 40–59  | `medium`      | Human review recommended      |
+| 20–39  | `low`         | Human review required         |
+| 0–19   | `very_low`    | Do not use without validation |
+
+> ⚠️ Scores are **ordinal rankings**, not absolute probabilities (WP 4.3).
+
+***
+
+## Architecture
+
+![CATS — 9-phase OSINT evaluation pipeline](.gitbook/assets/cats_scheme.png)
+
+```
+Client (HTTPS + Bearer token)
+        │
+   nginx (TLS 1.3 · rate 30 req/min)
+        │
+   FastAPI — 9-phase pipeline
+   ├─ POST /v1/cats/evaluate
+   ├─ POST /v1/cats/batch                ← evaluate up to 50 sources at once
+   ├─ GET  /v1/cats/explain/{trace_id}   ← GDPR Art.14/22
+   ├─ POST /v1/cats/contest/{trace_id}   ← GDPR Art.22
+   ├─ GET  /v1/cats/stats
+   └─ GET  /health  /metrics
+        │                │
+     Redis 7          PostgreSQL 16
+  (rate limiting)   (AES-256 audit log)
+                    + APScheduler purge
+```
+
+The nginx reverse proxy (TLS, rate limiting, security headers) is configured in [`deploy/nginx.conf`](deploy/nginx.conf) and started by `make docker-up`.
+
+See [docs/architecture.md](docs/architecture.md) for full signal and security details.
+
+***
+
+## Documentation
+
+| Document                                     | Description                                         |
+| -------------------------------------------- | --------------------------------------------------- |
+| [docs/api.md](docs/api.md)                   | Full API reference                                  |
+| [docs/architecture.md](docs/architecture.md) | Signal algorithms, weight matrix, security design   |
+| [docs/compliance.md](docs/compliance.md)     | GDPR + EU AI Act compliance                         |
+| [docs/eu\_ai\_act/](docs/eu_ai_act/)         | EU AI Act conformity scaffold (Annex IV, Art. 9/10) |
+| [docs/calibration.md](docs/calibration.md)   | Empirical weight calibration (genetic search)       |
+| [CHANGELOG.md](CHANGELOG.md)                 | Version history                                     |
+| [CONTRIBUTING.md](CONTRIBUTING.md)           | Development guide                                   |
+| [SECURITY.md](SECURITY.md)                   | Vulnerability reporting                             |
+
+***
+
+## Known Limitations (WP 4.1)
+
+* **NLP accuracy \~55–62% (default)**: spaCy NER + TextBlob; optional BERT sentiment and Sentence-BERT coherence backends are available for higher accuracy (see `.env.example`)
+* **Uncalibrated parameters**: thresholds are initial estimates; signal weights can now be empirically tuned with [`cats.calibration`](docs/calibration.md), but band thresholds remain unvalidated
+* **Small validation set (July 2026)**: calibration/validation currently rests on 50 RSS-labelled sources; see [calibration findings](docs/calibration_findings_2026-07.md) for the honest numbers (full-dataset concordance 0.78, holdout 0.71) and their caveats
+* **Italian-optimised**: using `it_core_news_lg`; other languages degrade accuracy
+* **Ordinal scoring only**: not suitable as sole basis for autonomous decisions
+
+***
+
+## Roadmap
+
+| Version  | Status | Key features                                                                                                       |
+| -------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| **v1.0** | ✅      | spaCy NER · 9-phase pipeline · GDPR API · Docker                                                                   |
+| **v1.1** | ✅      | BERT Italian sentiment · multi-tenant PostgreSQL · batch endpoint · Prometheus `/metrics` · nginx                  |
+| **v1.2** | ✅      | Sentence-BERT coherence · explainer attribution · weight calibration                                               |
+| **v1.3** | ✅      | Signal-polarity fix in aggregation · distant-supervision dataset (MBFC + disinfo networks) · snapshot accumulation |
+| v2.0     | 2027   | AUC-ROC ≥ 0.78 · full EU AI Act Annex IV technical documentation                                                   |
+
+***
+
+## License
+
+[MIT](LICENSE/) — technical@cats-system.org

cats_scoring-1.3.0/README.md

@@ -0,0 +1,191 @@
+# CATS — Contextual Ambiguity & Trust Scoring
+
+> **Trust intelligence for OSINT sources — not fact-checking, but source reliability over time.**
+
+[![CI](https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/actions/workflows/ci.yml/badge.svg)](https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/actions) [![Coverage](https://codecov.io/gh/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/branch/main/graph/badge.svg)](https://codecov.io/gh/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE/) [![GDPR](https://img.shields.io/badge/GDPR-Art.13--22%20documented-blue)](docs/compliance.md) [![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-documented-blue)](docs/compliance.md)
+
+***
+
+## What is CATS?
+
+| ❌ Fact-checking             | ✅ CATS                                                         |
+| --------------------------- | -------------------------------------------------------------- |
+| "Is this information true?" | **"How reliable is this source, in this context, right now?"** |
+
+CATS analyses the _behavioural patterns_ of a source over time — narrative consistency, sentiment volatility, temporal gaps, and signs of algorithmic manipulation — and returns a transparent, explainable trust score.
+
+***
+
+## Signals
+
+| Signal         | What it measures                            | Method                                                     |
+| -------------- | ------------------------------------------- | ---------------------------------------------------------- |
+| **Coherence**  | Entity/argument consistency across messages | spaCy NER + Jaccard (or optional Sentence-BERT) similarity |
+| **Volatility** | Abrupt narrative tone changes               | TextBlob (or optional BERT) sentiment spike detection      |
+| **Silence**    | Anomalous temporal gaps in publishing       | Gap analysis vs. source-type thresholds                    |
+| **Gaming**     | Signs of algorithmic manipulation           | Repetition + TTR + burst + vocab diversity                 |
+
+***
+
+## Try it in 5 lines (no infrastructure)
+
+No database, no Redis, no API keys — the signal pipeline as a plain library call:
+
+```python
+from cats.lite import score
+
+result = score([
+    {"timestamp": "2026-01-01T08:00:00Z", "text": "Il governo annuncia un piano economico."},
+    {"timestamp": "2026-01-01T12:00:00Z", "text": "I sindacati commentano il piano."},
+    {"timestamp": "2026-01-02T09:00:00Z", "text": "Il parlamento discute la legge di bilancio."},
+], source_type="news")
+
+print(result["trust_score"], result["band"], result["explanation"]["primary_driver"])
+```
+
+Install with `pip install -r requirements.txt` (plus `make nlp-download` for full-fidelity coherence — without it the NER backend degrades to a neutral value). The full API below adds persistence, auditing and GDPR endpoints.
+
+Or try it in the browser: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring/blob/main/examples/cats_lite_demo.ipynb)
+
+***
+
+## Quick Start (full deployment)
+
+```bash
+# 1. Clone and configure
+git clone https://github.com/Leapfrog-LSA/CATS-Contextual-Ambiguity-Trust-Scoring.git && cd CATS-Contextual-Ambiguity-Trust-Scoring
+cp .env.example .env          # fill in secrets (see .env.example)
+
+# 2. Install
+make dev-install              # deps + pre-commit hooks
+make nlp-download             # spaCy it_core_news_lg + TextBlob corpora
+
+# 3. Start services and run
+make docker-up                # PostgreSQL 16 + Redis 7
+make db-migrate               # Alembic migrations
+uvicorn cats.api.main:app --reload
+
+# 4. Test
+make test
+```
+
+> **Generate a secure AUDIT\_ENCRYPTION\_KEY**: `make generate-key`
+
+***
+
+## API Example
+
+```bash
+curl -s -X POST http://localhost:8000/v1/cats/evaluate \
+  -H "Authorization: Bearer $CATS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_id": "twitter:example_handle",
+    "messages": [
+      {"timestamp": "2026-01-01T08:00:00Z", "text": "Governo annuncia piano economico."},
+      {"timestamp": "2026-01-01T09:00:00Z", "text": "Protesta dei lavoratori in piazza."},
+      {"timestamp": "2026-01-01T10:00:00Z", "text": "Parlamento discute la legge di bilancio."}
+    ],
+    "context": {"source_type": "social"}
+  }' | jq
+```
+
+```json
+{
+  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
+  "score": 68.4,
+  "band": "medium_high",
+  "requires_review": false,
+  "signals": [
+    {"name": "coherence",  "value": 71.2, "confidence": 0.3},
+    {"name": "volatility", "value": 55.0, "confidence": 0.15},
+    {"name": "silence",    "value": 0.0,  "confidence": 0.1},
+    {"name": "gaming",     "value": 12.8, "confidence": 0.06}
+  ]
+}
+```
+
+***
+
+## Trust Score Bands
+
+| Score  | Band          | Recommended Action            |
+| ------ | ------------- | ----------------------------- |
+| 80–100 | `high`        | Usable for OSINT              |
+| 60–79  | `medium_high` | Cross-validate key claims     |
+| 40–59  | `medium`      | Human review recommended      |
+| 20–39  | `low`         | Human review required         |
+| 0–19   | `very_low`    | Do not use without validation |
+
+> ⚠️ Scores are **ordinal rankings**, not absolute probabilities (WP 4.3).
+
+***
+
+## Architecture
+
+![CATS — 9-phase OSINT evaluation pipeline](.gitbook/assets/cats_scheme.png)
+
+```
+Client (HTTPS + Bearer token)
+        │
+   nginx (TLS 1.3 · rate 30 req/min)
+        │
+   FastAPI — 9-phase pipeline
+   ├─ POST /v1/cats/evaluate
+   ├─ POST /v1/cats/batch                ← evaluate up to 50 sources at once
+   ├─ GET  /v1/cats/explain/{trace_id}   ← GDPR Art.14/22
+   ├─ POST /v1/cats/contest/{trace_id}   ← GDPR Art.22
+   ├─ GET  /v1/cats/stats
+   └─ GET  /health  /metrics
+        │                │
+     Redis 7          PostgreSQL 16
+  (rate limiting)   (AES-256 audit log)
+                    + APScheduler purge
+```
+
+The nginx reverse proxy (TLS, rate limiting, security headers) is configured in [`deploy/nginx.conf`](deploy/nginx.conf) and started by `make docker-up`.
+
+See [docs/architecture.md](docs/architecture.md) for full signal and security details.
+
+***
+
+## Documentation
+
+| Document                                     | Description                                         |
+| -------------------------------------------- | --------------------------------------------------- |
+| [docs/api.md](docs/api.md)                   | Full API reference                                  |
+| [docs/architecture.md](docs/architecture.md) | Signal algorithms, weight matrix, security design   |
+| [docs/compliance.md](docs/compliance.md)     | GDPR + EU AI Act compliance                         |
+| [docs/eu\_ai\_act/](docs/eu_ai_act/)         | EU AI Act conformity scaffold (Annex IV, Art. 9/10) |
+| [docs/calibration.md](docs/calibration.md)   | Empirical weight calibration (genetic search)       |
+| [CHANGELOG.md](CHANGELOG.md)                 | Version history                                     |
+| [CONTRIBUTING.md](CONTRIBUTING.md)           | Development guide                                   |
+| [SECURITY.md](SECURITY.md)                   | Vulnerability reporting                             |
+
+***
+
+## Known Limitations (WP 4.1)
+
+* **NLP accuracy \~55–62% (default)**: spaCy NER + TextBlob; optional BERT sentiment and Sentence-BERT coherence backends are available for higher accuracy (see `.env.example`)
+* **Uncalibrated parameters**: thresholds are initial estimates; signal weights can now be empirically tuned with [`cats.calibration`](docs/calibration.md), but band thresholds remain unvalidated
+* **Small validation set (July 2026)**: calibration/validation currently rests on 50 RSS-labelled sources; see [calibration findings](docs/calibration_findings_2026-07.md) for the honest numbers (full-dataset concordance 0.78, holdout 0.71) and their caveats
+* **Italian-optimised**: using `it_core_news_lg`; other languages degrade accuracy
+* **Ordinal scoring only**: not suitable as sole basis for autonomous decisions
+
+***
+
+## Roadmap
+
+| Version  | Status | Key features                                                                                                       |
+| -------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| **v1.0** | ✅      | spaCy NER · 9-phase pipeline · GDPR API · Docker                                                                   |
+| **v1.1** | ✅      | BERT Italian sentiment · multi-tenant PostgreSQL · batch endpoint · Prometheus `/metrics` · nginx                  |
+| **v1.2** | ✅      | Sentence-BERT coherence · explainer attribution · weight calibration                                               |
+| **v1.3** | ✅      | Signal-polarity fix in aggregation · distant-supervision dataset (MBFC + disinfo networks) · snapshot accumulation |
+| v2.0     | 2027   | AUC-ROC ≥ 0.78 · full EU AI Act Annex IV technical documentation                                                   |
+
+***
+
+## License
+
+[MIT](LICENSE/) — technical@cats-system.org

cats_scoring-1.3.0/cats/__init__.py

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

cats_scoring-1.3.0/cats/api/__init__.py

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

cats_scoring-1.3.0/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_scoring-1.3.0/cats/api/routes/__init__.py

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