narrative-harm-classifier 0.1.0__py3-none-any.whl

narrative_harm_classifier/__init__.py

@@ -0,0 +1,29 @@
+"""narrative_harm_classifier — narrative harm classification, escalation tracking, and benchmarking."""
+
+__version__ = "0.1.0"
+
+from narrative_harm_classifier.core.config import get_settings
+from narrative_harm_classifier.core.models import ClassificationResult, ClassifyRequest
+from narrative_harm_classifier.classifier.rules.engine import ClassificationEngine
+from narrative_harm_classifier.classifier.rules.azure_nlp import AzureNLPClient
+from narrative_harm_classifier.classifier.taxonomy.loader import load_taxonomy
+
+__all__ = [
+    "__version__",
+    "classify",
+    "ClassificationResult",
+    "ClassifyRequest",
+    "ClassificationEngine",
+]
+
+
+def classify(text: str, context: str | None = None) -> ClassificationResult:
+    """Convenience one-shot classification using the default taxonomy and settings."""
+    settings = get_settings()
+    taxonomy = load_taxonomy(settings.taxonomy_config_path)
+    azure_client = AzureNLPClient(
+        endpoint=settings.azure_text_analytics_endpoint,
+        key=settings.azure_text_analytics_key,
+    )
+    engine = ClassificationEngine(taxonomy=taxonomy, azure_client=azure_client)
+    return engine.classify(ClassifyRequest(text=text, context=context))

narrative_harm_classifier/api/main.py

@@ -0,0 +1,50 @@
+"""
+api/main.py — FastAPI application entry point.
+"""
+
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+import logging
+
+from narrative_harm_classifier.core.config import get_settings
+from narrative_harm_classifier.api.routes import classify, validate, health, tracking, benchmark
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings = get_settings()
+    logger.info(f"Starting {settings.app_name} v{settings.app_version}")
+    logger.info(f"Taxonomy: {settings.taxonomy_config_path} v{settings.taxonomy_version}")
+    yield
+    logger.info("Shutting down")
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.app_version,
+        description=(
+            "Narrative Harm Classification API\n\n"
+            "Implements the D2.4a classification specification with multi-dimensional "
+            "rule-based logic across targets, identities, harm mechanisms, and "
+            "decision thresholds. Azure Text Analytics integrated for optional NLP signal "
+            "amplification. Also provides escalation-chain tracking across sources over time "
+            "and a templated benchmark suite for credible precision/recall reporting."
+        ),
+        lifespan=lifespan,
+    )
+
+    app.include_router(health.router, tags=["Health"])
+    app.include_router(classify.router, prefix="/classify", tags=["Classification"])
+    app.include_router(validate.router, prefix="/validate", tags=["Validation"])
+    app.include_router(tracking.router, prefix="/tracking", tags=["Escalation Tracking"])
+    app.include_router(benchmark.router, prefix="/benchmark", tags=["Benchmark"])
+
+    return app
+
+
+app = create_app()

narrative_harm_classifier/api/routes/benchmark.py

@@ -0,0 +1,32 @@
+"""
+api/routes/benchmark.py — Templated benchmark endpoint.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from narrative_harm_classifier.core.config import get_settings, Settings
+from narrative_harm_classifier.classifier.factory import build_benchmark_runner
+from narrative_harm_classifier.classifier.validators.benchmark import BenchmarkRunner, BenchmarkReport
+
+router = APIRouter()
+
+
+def get_runner(settings: Settings = Depends(get_settings)) -> BenchmarkRunner:
+    return build_benchmark_runner(settings)
+
+
+@router.post(
+    "/run",
+    response_model=BenchmarkReport,
+    summary="Run the templated functional-test benchmark suite",
+    description=(
+        "Generates and runs a HateCheck-style templated test suite (explicit/implicit "
+        "positives, negation, counter-speech, obfuscated spelling, cross-group consistency, "
+        "and benign hard negatives). Returns aggregate and per-test-type precision/recall/FPR."
+    ),
+)
+def run_benchmark(runner: BenchmarkRunner = Depends(get_runner)) -> BenchmarkReport:
+    try:
+        return runner.run()
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

narrative_harm_classifier/api/routes/classify.py

@@ -0,0 +1,59 @@
+"""
+api/routes/classify.py — Classification endpoints.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+from narrative_harm_classifier.core.models import ClassifyRequest, ClassificationResult, BatchClassifyRequest, BatchClassificationResult
+from narrative_harm_classifier.core.config import get_settings, Settings
+from narrative_harm_classifier.classifier.taxonomy.loader import load_taxonomy
+from narrative_harm_classifier.classifier.rules.engine import ClassificationEngine
+from narrative_harm_classifier.classifier.factory import build_engine
+from datetime import datetime
+
+router = APIRouter()
+
+
+def get_engine(settings: Settings = Depends(get_settings)) -> ClassificationEngine:
+    return build_engine(settings)
+
+
+@router.post(
+    "/",
+    response_model=ClassificationResult,
+    summary="Classify a single text item",
+    description=(
+        "Runs multi-dimensional classification against the active taxonomy. "
+        "Returns harm category, confidence, matched signals, and decision rationale."
+    ),
+)
+def classify_text(
+    request: ClassifyRequest,
+    engine: ClassificationEngine = Depends(get_engine),
+) -> ClassificationResult:
+    try:
+        return engine.classify(request)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post(
+    "/batch",
+    response_model=BatchClassificationResult,
+    summary="Classify a batch of text items (max 100)",
+)
+def classify_batch(
+    request: BatchClassifyRequest,
+    engine: ClassificationEngine = Depends(get_engine),
+) -> BatchClassificationResult:
+    results = [engine.classify(item) for item in request.items]
+    harmful = sum(1 for r in results if r.is_harmful)
+    settings = get_settings()
+    taxonomy = load_taxonomy(settings.taxonomy_config_path)
+
+    return BatchClassificationResult(
+        results=results,
+        total=len(results),
+        harmful_count=harmful,
+        taxonomy_version=taxonomy.version,
+        processed_at=datetime.utcnow(),
+    )

narrative_harm_classifier/api/routes/health.py

@@ -0,0 +1,23 @@
+"""
+api/routes/health.py
+"""
+
+from fastapi import APIRouter, Depends
+from narrative_harm_classifier.core.config import get_settings, Settings
+from narrative_harm_classifier.classifier.taxonomy.loader import load_taxonomy
+
+router = APIRouter()
+
+
+@router.get("/health")
+def health(settings: Settings = Depends(get_settings)):
+    taxonomy = load_taxonomy(settings.taxonomy_config_path)
+    return {
+        "status": "ok",
+        "app": settings.app_name,
+        "version": settings.app_version,
+        "taxonomy_version": taxonomy.version,
+        "taxonomy_baseline": taxonomy.baseline_tag,
+        "priority_category": taxonomy.priority_category,
+        "azure_configured": bool(settings.azure_text_analytics_endpoint),
+    }

narrative_harm_classifier/api/routes/tracking.py

@@ -0,0 +1,81 @@
+"""
+api/routes/tracking.py — Escalation-chain tracking endpoints.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from narrative_harm_classifier.core.models import ClassifyRequest
+from narrative_harm_classifier.core.config import get_settings, Settings
+from narrative_harm_classifier.classifier.factory import build_tracker
+from narrative_harm_classifier.classifier.tracking.models import SourceProfile, Observation, ChainVerification
+from narrative_harm_classifier.classifier.tracking.tracker import EscalationTracker
+
+router = APIRouter()
+
+
+def get_tracker(settings: Settings = Depends(get_settings)) -> EscalationTracker:
+    return build_tracker(settings)
+
+
+@router.post(
+    "/{source_id}/observe",
+    response_model=Observation,
+    summary="Classify a text and record it against a tracked source",
+    description=(
+        "Classifies the text and appends it to the source's observation history, "
+        "used to compute escalation trend and risk level over time."
+    ),
+)
+def observe(
+    source_id: str,
+    request: ClassifyRequest,
+    tracker: EscalationTracker = Depends(get_tracker),
+) -> Observation:
+    return tracker.observe(source_id, request)
+
+
+@router.get(
+    "/{source_id}",
+    response_model=SourceProfile,
+    summary="Get a tracked source's escalation profile",
+)
+def get_profile(
+    source_id: str,
+    window: int = 20,
+    tracker: EscalationTracker = Depends(get_tracker),
+) -> SourceProfile:
+    profile = tracker.profile(source_id, window=window)
+    if profile.observation_count == 0:
+        raise HTTPException(status_code=404, detail=f"No observations recorded for source '{source_id}'")
+    return profile
+
+
+@router.get(
+    "",
+    response_model=list[SourceProfile],
+    summary="List all tracked sources, sorted by risk (highest first)",
+)
+def list_profiles(
+    window: int = 20,
+    tracker: EscalationTracker = Depends(get_tracker),
+) -> list[SourceProfile]:
+    return tracker.list_profiles(window=window)
+
+
+@router.get(
+    "/{source_id}/verify",
+    response_model=ChainVerification,
+    summary="Verify the tamper-evident hash chain for a source's observation history",
+    description=(
+        "Recomputes the hash chain over the full stored history and confirms it's intact. "
+        "Detects tampering with any historical record; does not prevent it."
+    ),
+)
+def verify_chain(
+    source_id: str,
+    tracker: EscalationTracker = Depends(get_tracker),
+) -> ChainVerification:
+    result = tracker.verify_chain(source_id)
+    if result.observation_count == 0:
+        raise HTTPException(status_code=404, detail=f"No observations recorded for source '{source_id}'")
+    return result

narrative_harm_classifier/api/routes/validate.py

@@ -0,0 +1,61 @@
+"""
+api/routes/validate.py — Validation endpoints.
+Runs held-out sample validation and returns performance reports.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException
+from narrative_harm_classifier.core.models import ValidationSample, ValidationReport
+from narrative_harm_classifier.core.config import get_settings, Settings
+from narrative_harm_classifier.classifier.factory import build_validator
+from narrative_harm_classifier.classifier.validators.performance import (
+    PerformanceValidator,
+    DEHUMANIZATION_VALIDATION_SAMPLES,
+)
+
+router = APIRouter()
+
+
+def get_validator(settings: Settings = Depends(get_settings)) -> PerformanceValidator:
+    return build_validator(settings)
+
+
+@router.post(
+    "/dehumanization",
+    response_model=ValidationReport,
+    summary="Run Phase 1 end-to-end validation for priority category: dehumanization",
+    description=(
+        "Validates the dehumanization category against the built-in held-out sample set. "
+        "Checks Precision ≥ 0.70, Recall ≥ 0.65, FPR ≤ 0.20. "
+        "This is the Phase 1 milestone validation gate."
+    ),
+)
+def validate_dehumanization(
+    validator: PerformanceValidator = Depends(get_validator),
+) -> ValidationReport:
+    try:
+        return validator.validate_category(
+            category_name="dehumanization",
+            samples=DEHUMANIZATION_VALIDATION_SAMPLES,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post(
+    "/custom",
+    response_model=ValidationReport,
+    summary="Run validation against a custom sample set",
+)
+def validate_custom(
+    category: str,
+    samples: list[ValidationSample],
+    validator: PerformanceValidator = Depends(get_validator),
+) -> ValidationReport:
+    if not samples:
+        raise HTTPException(status_code=400, detail="At least one sample required")
+    try:
+        return validator.validate_category(category_name=category, samples=samples)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

narrative_harm_classifier/classifier/counter_narrative.py

@@ -0,0 +1,65 @@
+"""
+classifier/counter_narrative.py — General counter-narrative guidance per harm mechanism.
+
+Deliberately general, templated guidance grounded in the public
+"acknowledge -> redirect -> inform" counter-messaging framework (the
+methodology behind projects like Moonshot CVE and the Redirect Method), not
+auto-generated bespoke rebuttal text for the specific input. Generating
+custom rebuttal text is a materially harder, riskier text-generation problem
+(prone to tone-deaf or factually wrong output) and is out of scope here —
+this gives a human moderator/responder a starting frame, not a script to
+paste verbatim.
+"""
+
+from typing import Optional
+
+_GUIDANCE: dict[str, str] = {
+    "animalization": (
+        "Dehumanizing comparisons (to animals, vermin, disease) are a documented precursor to "
+        "real-world violence against targeted groups. Effective counter-messaging typically: "
+        "(1) avoids repeating or amplifying the dehumanizing frame itself, (2) affirms the "
+        "target group's humanity with specific, concrete facts rather than abstract appeals, "
+        "(3) redirects toward the underlying grievance being exploited, if any."
+    ),
+    "demonization": (
+        "Framing a group as evil or supernaturally malevolent shuts down empathy and factual "
+        "engagement. Counter-messaging typically works better by naming the rhetorical move "
+        "explicitly (\"this frames an entire group as inherently evil\") and redirecting to "
+        "specific, falsifiable claims rather than arguing the moral framing directly."
+    ),
+    "objectification": (
+        "Reducing a group to objects or property strips away agency and interiority. "
+        "Counter-messaging typically centers first-person voices from the affected group and "
+        "concrete examples of agency, rather than abstract arguments against the framing."
+    ),
+    "criminalization": (
+        "Blanket criminal framing of a group is usually contradicted by the actual data. "
+        "Effective counter-messaging leads with accurate, sourced statistics and specific "
+        "counterexamples rather than general appeals not to stereotype."
+    ),
+    "direct_call_to_violence": (
+        "Explicit calls to violence should typically be escalated for human review and, where "
+        "applicable, reported to platform trust & safety or law enforcement channels rather than "
+        "countered by automated messaging alone. If counter-messaging is used at all, prioritize "
+        "de-escalation and directing at-risk viewers toward support resources over debating the "
+        "claim itself."
+    ),
+    "false_attribution": (
+        "Claims about a group's supposed hidden agenda are typically unfalsifiable by design. "
+        "Counter-messaging tends to work better by asking what specific, checkable evidence is "
+        "being offered (usually none) rather than trying to disprove an unfalsifiable claim "
+        "directly."
+    ),
+}
+
+_DEFAULT_GUIDANCE = (
+    "Consider whether a direct rebuttal, a redirect to factual information, or escalation to "
+    "human review is the most appropriate response before responding automatically."
+)
+
+
+def guidance_for(harm_mechanism: Optional[str]) -> Optional[str]:
+    """Return general counter-narrative guidance for a harm mechanism, or None if harmless."""
+    if not harm_mechanism:
+        return None
+    return _GUIDANCE.get(harm_mechanism, _DEFAULT_GUIDANCE)

narrative_harm_classifier/classifier/factory.py

@@ -0,0 +1,61 @@
+"""
+classifier/factory.py — Shared construction of engine/tracker/runner/validator.
+
+Every API route and every CLI command previously rebuilt "load taxonomy +
+build Azure client + build ClassificationEngine" independently (six
+near-identical copies across api/routes/*.py and cli.py). Centralizing it
+here means a change to how the engine is constructed (e.g. adding
+dog-whistle lexicon loading) happens once.
+"""
+
+from narrative_harm_classifier.core.config import Settings
+from narrative_harm_classifier.classifier.taxonomy.loader import load_taxonomy, TaxonomyConfig
+from narrative_harm_classifier.classifier.rules.engine import ClassificationEngine
+from narrative_harm_classifier.classifier.rules.azure_nlp import AzureNLPClient
+from narrative_harm_classifier.classifier.rules.dogwhistles import load_dogwhistles, DogwhistleLexicon
+from narrative_harm_classifier.classifier.tracking.store import get_store, TrackingStore
+from narrative_harm_classifier.classifier.tracking.tracker import EscalationTracker
+from narrative_harm_classifier.classifier.validators.benchmark import BenchmarkRunner
+from narrative_harm_classifier.classifier.validators.performance import PerformanceValidator
+
+
+def build_taxonomy(settings: Settings) -> TaxonomyConfig:
+    return load_taxonomy(settings.taxonomy_config_path)
+
+
+def build_azure_client(settings: Settings) -> AzureNLPClient:
+    return AzureNLPClient(
+        endpoint=settings.azure_text_analytics_endpoint,
+        key=settings.azure_text_analytics_key,
+    )
+
+
+def build_dogwhistle_lexicon(settings: Settings) -> DogwhistleLexicon:
+    return load_dogwhistles(settings.dogwhistles_path)
+
+
+def build_engine(settings: Settings) -> ClassificationEngine:
+    return ClassificationEngine(
+        taxonomy=build_taxonomy(settings),
+        azure_client=build_azure_client(settings),
+        patterns_dir=settings.patterns_dir,
+        dogwhistles=build_dogwhistle_lexicon(settings),
+    )
+
+
+def build_tracker(settings: Settings) -> EscalationTracker:
+    store: TrackingStore = get_store(settings.effective_tracking_db_url)
+    return EscalationTracker(engine=build_engine(settings), store=store)
+
+
+def build_benchmark_runner(settings: Settings) -> BenchmarkRunner:
+    taxonomy = build_taxonomy(settings)
+    return BenchmarkRunner(
+        engine=build_engine(settings),
+        taxonomy_version=taxonomy.version,
+        templates_path=settings.benchmark_templates_path,
+    )
+
+
+def build_validator(settings: Settings) -> PerformanceValidator:
+    return PerformanceValidator(engine=build_engine(settings), taxonomy=build_taxonomy(settings))

narrative_harm_classifier/classifier/provenance.py

@@ -0,0 +1,51 @@
+"""
+classifier/provenance.py — Deterministic content hashing and a tamper-evident
+hash chain for escalation-tracking observations.
+
+content_hash() is a pure function of (text, context, taxonomy_version): the
+same input always produces the same hash regardless of when it's computed,
+so it can be used to verify "this exact text was classified under this
+exact taxonomy version" independent of any particular run.
+
+record_hash() chains each Observation to the one before it (genesis
+GENESIS_HASH for the first record in a source's history), the same idea as
+a git commit chain or a minimal Merkle-style ledger: altering any historical
+record changes its hash, which no longer matches what every later record's
+hash was computed from — making tampering detectable, not prevented.
+"""
+
+import hashlib
+from datetime import datetime
+from typing import Optional
+
+GENESIS_HASH = "0" * 64
+
+
+def content_hash(text: str, context: Optional[str], taxonomy_version: str) -> str:
+    payload = f"{text}\x1f{context or ''}\x1f{taxonomy_version}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def record_hash(
+    prev_hash: str,
+    source_id: str,
+    text_excerpt: str,
+    is_harmful: bool,
+    harm_mechanism: Optional[str],
+    confidence: float,
+    observed_at: datetime,
+    content_hash_value: str,
+) -> str:
+    payload = "\x1f".join(
+        [
+            prev_hash,
+            source_id,
+            text_excerpt,
+            str(is_harmful),
+            harm_mechanism or "",
+            f"{confidence:.6f}",
+            observed_at.isoformat(),
+            content_hash_value,
+        ]
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

narrative_harm_classifier/classifier/rules/azure_nlp.py

@@ -0,0 +1,137 @@
+"""
+classifier/rules/azure_nlp.py — Azure Text Analytics connector.
+
+Wraps Azure Cognitive Services Text Analytics for:
+- Sentiment analysis (used as negative signal amplifier)
+- Named Entity Recognition (detects group/identity mentions)
+- Key phrase extraction (surface-level harm signal detection)
+
+Falls back gracefully when Azure credentials are not configured (dev mode).
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AzureNLPResult:
+    sentiment: str                    # positive | negative | neutral | mixed
+    sentiment_score_negative: float   # 0.0–1.0
+    entities: list[dict]              # [{text, category, confidence}]
+    key_phrases: list[str]
+    language: str
+    is_fallback: bool = False         # True when Azure not configured
+
+
+class AzureNLPClient:
+    """
+    Azure Text Analytics client with graceful dev-mode fallback.
+
+    In production: set AZURE_TEXT_ANALYTICS_ENDPOINT and AZURE_TEXT_ANALYTICS_KEY.
+    In dev/test: client operates in fallback mode with neutral scores.
+    """
+
+    def __init__(self, endpoint: str = "", key: str = ""):
+        self.endpoint = endpoint
+        self.key = key
+        self._client = None
+
+        if endpoint and key:
+            try:
+                from azure.ai.textanalytics import TextAnalyticsClient
+                from azure.core.credentials import AzureKeyCredential
+                self._client = TextAnalyticsClient(
+                    endpoint=endpoint,
+                    credential=AzureKeyCredential(key)
+                )
+                logger.info("Azure Text Analytics client initialized")
+            except ImportError:
+                logger.warning("azure-ai-textanalytics not installed — running in fallback mode")
+            except Exception as e:
+                logger.warning(f"Azure Text Analytics init failed: {e} — running in fallback mode")
+        else:
+            logger.info("Azure credentials not configured — running in fallback/dev mode")
+
+    @property
+    def is_configured(self) -> bool:
+        return self._client is not None
+
+    def analyze(self, text: str, language: str = "en") -> AzureNLPResult:
+        """Run sentiment + NER + key phrases in a single batched call."""
+        if not self.is_configured:
+            return self._fallback_result(text)
+
+        try:
+            from azure.ai.textanalytics import (
+                RecognizeEntitiesAction,
+                AnalyzeSentimentAction,
+                ExtractKeyPhrasesAction,
+            )
+
+            poller = self._client.begin_analyze_actions(
+                documents=[{"id": "1", "text": text, "language": language}],
+                actions=[
+                    AnalyzeSentimentAction(),
+                    RecognizeEntitiesAction(),
+                    ExtractKeyPhrasesAction(),
+                ],
+            )
+            results = list(poller.result())
+
+            sentiment_result = None
+            entity_result = None
+            keyphrase_result = None
+
+            for action_result in results[0]:
+                if action_result.kind == "SentimentAnalysis" and not action_result.is_error:
+                    sentiment_result = action_result
+                elif action_result.kind == "EntityRecognition" and not action_result.is_error:
+                    entity_result = action_result
+                elif action_result.kind == "KeyPhraseExtraction" and not action_result.is_error:
+                    keyphrase_result = action_result
+
+            sentiment = "neutral"
+            neg_score = 0.0
+            if sentiment_result:
+                sentiment = sentiment_result.sentiment
+                neg_score = sentiment_result.confidence_scores.negative
+
+            entities = []
+            if entity_result:
+                for ent in entity_result.entities:
+                    entities.append({
+                        "text": ent.text,
+                        "category": ent.category,
+                        "confidence": ent.confidence_score,
+                    })
+
+            key_phrases = []
+            if keyphrase_result:
+                key_phrases = list(keyphrase_result.key_phrases)
+
+            return AzureNLPResult(
+                sentiment=sentiment,
+                sentiment_score_negative=neg_score,
+                entities=entities,
+                key_phrases=key_phrases,
+                language=language,
+                is_fallback=False,
+            )
+
+        except Exception as e:
+            logger.error(f"Azure NLP analysis failed: {e}")
+            return self._fallback_result(text)
+
+    def _fallback_result(self, text: str) -> AzureNLPResult:
+        """Dev-mode fallback: neutral scores, no entities."""
+        return AzureNLPResult(
+            sentiment="neutral",
+            sentiment_score_negative=0.0,
+            entities=[],
+            key_phrases=[],
+            language="en",
+            is_fallback=True,
+        )