Table of Contents

EXECUTIVE SUMMARY

Palantir Gotham fused multi-source intelligence into entity graphs, pattern-of-life analysis, and predictive alerting behind proprietary walls. HADR brings that analytical paradigm to publicly available social-media data as open source with lawful-use-first governance: auditable algorithms, verifiable hashes, per-jurisdiction legal screening, and a cryptographically chained evidence ledger. Every legal match is a candidate for human review, never a verdict.

Since v0.3 the human review trail is itself part of the evidence — analyst annotations are sealed into the hash chain (§14) — and HADR opens to AI clients through an MCP server (§16), scriptable court-ready exports (§15), and temporal/alibi reasoning in the contradiction engine (§08). v0.4 adds non-verbal acoustic event spotting (scream · gunshot · glass · impact · siren), per-segment language ID with code-switch points, sentiment-arc analysis, PII-redacted exports, multi-analyst RBAC workspaces, and a temporal pattern-of-life heatmap — all 230 tests running offline, no keys, no network.

HADR is target-agnostic: subjects are YAML configuration artifacts, not code. Legal frameworks, model endpoints, and API credentials are data — never hardcoded. The same binary serves journalism, litigation support, compliance, research, and law-enforcement triage. Deterministic mock backends ship for every heavy dependency; the full pipeline runs offline before any live model is connected. MIT licensed. Bundled legal frameworks are example seeds, not legal advice.

DESIGN PRINCIPLES

Six principles govern every module.

• Target Agnosticity. Subjects are YAML profiles (HADR_HOME/config/targets/<id>.yaml) with name, jurisdiction, aliases, keywords, model overrides, and consent block. Swapping subjects is a data operation.
• Configuration-as-Data. Legal frameworks and model definitions are layered YAML: packaged defaults → user overrides in HADR_HOME/config/. Adding a jurisdiction or model endpoint requires editing YAML, not Python.
• Secrets-by-Reference. Model specs store env-var names (api_key_env), never values. Zero keys in the repo. Provider-agnostic OpenAI-compatible routing ships first-class DashScope/Qwen definitions (qwen3.8-max, qwen-audio, wan-3.0).
• Graceful Degradation. Every heavy dependency is optional; missing backends fall back to deterministic mocks. Jobs are marked done-mock or done accordingly.
• Tamper-Evidence. Each ledger entry chains via record_hash = SHA-256(prev_hash || canonical_fields). Genesis uses a 64-zero sentinel. hadr evidence verify recomputes the full chain including file hashes.
• Privacy-by-Default. Target profiles include a consent.lawful_basis field. Built-in scrapers refuse to circumvent access controls and identify via research User-Agent.

CAPABILITY MAPPING: CLOSED-PLATFORM CONCEPTS → HADR PRIMITIVES

Proprietary platforms optimize for institutional throughput; HADR optimizes for independent verifiability. The candidates-not-verdicts doctrine (§10) and ask-a-lawyer rule (§17) are architectural expressions of accountability.

SYSTEM ARCHITECTURE

Five stacked layers under hadr/:

┌──────────────────────────────────────────────────────────────────────┐
│  INGESTION   hadr/ingest/{local,youtube,twitch,tiktok,rss,social}    │
│              Rate-limited, UA-tagged, public-content-only            │
└──────────────────────────────┬───────────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│  BIOMETRIC & ASR   audio.py → diarize.py → asr.py → voiceprint.py   │
│                    ffmpeg 16 kHz mono · pyannote · faster-whisper    │
└──────────────────────────────┬───────────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│  INTELLIGENCE   llm.py · prompts.py · vectors.py · temporal.py       │
│                 forensic · legal · entities · claims + alibi checks  │
└──────────────────────────────┬───────────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│  EVIDENCE LEDGER   ledger.py (SHA-256 chain) · cutter.py (clips)     │
│                    annotations.py + export/ sealed into the chain    │
└──────────────────────────────┬───────────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│  SURFACE   FastAPI + React HUD · export SDK · MCP server (AI clients)│
└──────────────────────────────────────────────────────────────────────┘

Job flow: ingest → normalize (ffmpeg 16 kHz WAV) → diarize (optional) → transcribe (faster-whisper/mock) → voice-match (cosine) → analyze (forensic + legal LLM vectors) → cut clips at legal-match timestamps → append to evidence ledger → mark done/done-mock.

MULTIMODAL ACOUSTIC INTELLIGENCE

hadr/pipeline/acoustics.py (v0.2 design) extracts four features per speaker segment from the 16 kHz mono WAV: pitch variation (F0 autocorrelation), speech-rate proxy (voiced-frame density), silence ratio, and spectral brightness. These feed three composite indicators clamped to [0, 100]:

Librosa optional; falls back to numpy FFT. Scores stored as segment metadata and surfaced in dashboard psychometric gauges. These are statistical estimates, not verdicts; they prioritize human review.

Non-verbal event spotting (hadr/pipeline/audio_events.py, v0.4) scans the same 16 kHz WAV for sounds that carry no words but carry evidentiary weight: scream, gunshot, breaking glass, impact, siren. A YAMNet-class model runs through ONNX Runtime over sliding 15 600-sample windows (extra audio-events, operator-supplied weights under HADR_HOME/models — HADR never downloads a model). YAMNet emits per-class sigmoid probabilities, so scores are clipped rather than softmaxed; a 521-way softmax would bury every real hit under ~0.002. Overlapping windows are merged into one span per event keeping the peak score, because one scream is one exhibit, not five. Without the dependency or the weights, a deterministic transient detector (energy-envelope peak ratio, zero-crossing brightness, transient length — no RNG, no network) keeps the stage running and the ledger records which backend produced each hit. Hits are stamped onto the transcript segments they overlap: what happened while who was talking.

Language attribution (hadr/intel/langid.py, v0.4) labels every transcript segment with the language of its own text and records the code-switch points with their offsets — multilingual evidence is the normal case, and a translated exhibit without per-line attribution is hard to defend. lingua is the real backend (extra langid); the default is a deterministic stopword + diacritics scorer. Text it cannot attribute is reported as und, never guessed, and undetermined lines cannot create a language switch — transcript noise must not read as the subject changing languages.

VISUAL RECONNAISSANCE

ffmpeg extracts keyframes (default: 1 per 5 s + scene changes) stored as JPEG with individual SHA-256 hashes. Tesseract OCR (optional) processes frames through structured extraction: IBAN/bank accounts, payment receipts, usernames/handles, URLs/domains. Each observation links to its frame's ledger entry with confidence scores. Outputs feed the knowledge graph (§07) and contradiction engine (§08).

Financial graph edges (v0.3): structured OCR atoms are promoted to first-class graph nodes. Each IBAN/bank account becomes an account entity and a TRANSFERRED_TO edge from the subject (with co-occurring amounts quoted as provenance); each on-screen @handle becomes an account entity with a COMMUNICATED_WITH edge. Entities deduplicate across jobs. All such edges are observations with provenance quotes, never assertions of guilt.

KNOWLEDGE GRAPH & ENTITY NETWORK

Typed entity-relation graph accumulating across jobs. Entity types: Person, Organization, Location, Account, Asset — extracted via LLM forensic vector and visual OCR. Relations: TRANSFERRED_TO, THREATENED, MENTIONED, ALIAS_OF, LOCATED_AT, OWNS, CONTROLS, AFFILIATED_WITH. Candidates deduplicated via normalized names and alias tables.

Exports: JSON-LD, Cypher (Neo4j), GEXF (Gephi/NetworkX). OSINT lookups (off by default, opt-in per target): rate-limited public-data queries (WHOIS, social profiles, business registries) appended as sourced observations.

CONTRADICTION ENGINE & TEMPORAL REASONING

Claims extracted per segment with topic tags, numeric values, negation markers, and temporal anchors (v0.3): absolute dates (ISO, Hungarian dotted, English long-form), relative expressions normalised to calendar windows (HU + EN, incl. number-word forms like két hete / three days ago), and named locations. Historical claims indexed via lexical vector embeddings (sentence-transformers/mock). Contradictions flagged on: negation flip (same topic, opposite polarity), numeric mismatch (incompatible values), temporal inconsistency — either a presence conflict (overlapping time windows with disjoint locations, i.e. alibi contradiction) or a date mismatch (highly similar same-topic claims asserting different absolute dates).

Alibi cross-check API (POST /api/targets/{id}/alibi): assert a location + window and get every historical claim that places the subject elsewhere in that window. All detections are candidates for human review — temporal heuristics never produce verdicts.

Sentiment arc (hadr/intel/sentiment.py, v0.4) — one score per transcript segment (−1…+1) is not evidence; the shape is. A call that opens neutral and slides into contempt reads differently from one that starts hostile and de-escalates. GET /api/targets/{id}/sentiment-arc returns the trajectory across the whole dossier (mean/min/max per recording, slope as trend, volatility) plus inflections — the largest job-to-job breaks, with the timestamp of the collapse — and a coarse drift verdict. Per-segment scoring runs through the same LLM vector path as the forensic/legal passes (sentiment.j2), with a deterministic HU/EN/DE polarity lexicon as the offline engine and the backfill for any line the model failed to score; every point carries its source, so a reviewer always knows whether a number came from a model judgement or the fallback, and mixed is reported as such. Affect scores are a triage aid — where to listen first — never a finding about the subject's inner state. A canned offline "mood" would be a fabricated measurement, which is why the mock backend returns no model judgements at all and says so.

CRYPTOGRAPHIC CHAIN OF CUSTODY

hadr/evidence/ledger.py implements an append-only hash-chained ledger:

hadr evidence verify checks chain linkage, prev-hash continuity, and file integrity. hadr evidence export produces a self-contained JSON report. Ed25519 signing (hadr keys create + signed packages), optional RFC 3161 timestamps, and court-format bundles with a verifier annex ship since v0.2/v0.3 (§15). The chain also seals analyst annotations and every generated export, so the human review trail and the reporting history are tamper-evident too (§14).

LEGAL RISK MATRICES PER JURISDICTION

Legal frameworks are pluggable YAML (hadr/legal/schema.py): code, criminal_code_title, civil_code_title, verified_against, statutes[] (id, citation, category, severity, elements, keywords).

Each framework carries verified_against provenance. Legal matches are candidates for human review, never verdicts (§17). Add custom frameworks: hadr legal add ./my-country.yaml or paste YAML in Settings.

ALERTING, PATTERN-OF-LIFE & AUTOMATION

Pattern-of-Life: Three dimensions per-target across accumulated jobs: (1) Activity cadence — posting frequency distributions with platform-specific baselines; (2) Hour-of-day risk windows — temporal anomaly scoring amplified by concurrent stress indicators; (3) Psychometric & financial trend lines — moving averages of stress/aggression/financial signals plotted on the timeline radar. Minimum ~10 jobs for reliable baselines.

Live Webhooks: Felony-level legal matches or critical aggression trigger payloads to Telegram Bot API, Discord Webhook, or generic HTTPS. Payloads include target/job ID, statute/indicator, confidence, quote, and evidence link. Off by default, configured per-target.

Anomaly Index: Composite [0–100] from cadence deviation, stress trend, aggression trajectory, and legal severity shift. Configurable thresholds trigger proactive notifications independent of individual job results.

ANONYMITY & OPERATIONAL SECURITY

All network adapters support SOCKS5/Tor proxy (HADR_PROXY), User-Agent rotation, ≥2 s rate limiting, and exponential backoff. Balanced against ethics: lawful basis still required; public content only (no credential abuse); GDPR obligations apply regardless of operator anonymity; platform terms respected.

TACTICAL DASHBOARD

React + Vite + Tailwind HUD served by FastAPI at /. Views: Target Dossiers (profile cards with tabbed detail), Psychometric Gauges (color-coded thresholds + sparklines), Timeline Radar (chronological jobs/matches/contradictions/anomalies), Evidence Wall (ledger grid with thumbnails), Graph View (interactive entity-relation visualization), Pipeline Monitor (live progress + backend status), Settings (framework/model/webhook/proxy management). Design: charcoal #0c0e11, panels #111418, borders #262a30, text #e6eaef, amber #d9a441, red #e05561, system sans + ui-monospace.

The Evidence Wall also hosts the Analyst Review Trail (§14) and one-click Court PDF / Signed Bundle exports (§15).

ANALYST ANNOTATION & AUDIT LAYER

Human review is part of the evidence, not a side-channel. Every analyst decision — note, flag, approve, reject — is stored as an Annotation row and sealed into the hash chain as an annotation ledger entry whose meta (analyst id, kind, text, refs) is hashed into record_hash. hadr evidence verify therefore covers the review trail itself.

Annotations are append-only: "deleting" retracts — the row stays with status=retracted and an annotation-retraction tombstone entry supersedes it. Nothing is quietly altered. Annotations may reference a target, a job, a transcript segment, or a specific ledger entry, and support threading via parent_id. REST (/api/annotations) and the dashboard Review Trail both write through the same store. This is the architectural realisation of the candidates-not-verdicts doctrine: who reviewed what, when, is provable.

HEADLESS EXPORT SDK & COURT-READY BUNDLES

hadr/export/ turns a target dossier into reproducible artifacts, scriptable for CI and reporting pipelines (exit code 0/1):

Bundles pack raw evidence artifacts only (clips/transcripts/social) — generated reports are excluded so bundles never recursively pack each other — while the complete ledger travels inside dossier.json. Sealed exports get unique filenames so a later export can never invalidate an earlier hash. hadr evidence verify-package <zip> checks signature + artifact hashes with the public key alone. CLI: hadr export <target> -f bundle|pdf|jsonld|….

MCP INTEGRATION (AI CLIENT ACCESS)

hadr mcp (extra mcp, SDK v1 FastMCP and v2 MCPServer both supported) exposes HADR to any Model Context Protocol client — Claude Desktop, Cursor, Windsurf, agent harnesses — over stdio or streamable-HTTP.

Tools (12): list_targets · get_target · overview · query_graph · verify_evidence · list_evidence · list_contradictions · list_annotations · alibi · forecast · casefile · export_dossier. Resources: hadr://overview, hadr://targets, hadr://target/{id} (casefile), hadr://target/{id}/graph.

Every tool is a plain function over the PipelineContext (hadr/mcp/tools.py), so the entire MCP surface is unit-testable without a client. Read-only by design; writes stay on the authenticated REST/CLI surface.

ETHICS & GOVERNANCE

HADR's ethics policy (docs/ETHICS.md) is non-negotiable infrastructure. Lawful basis recording: every target requires consent.lawful_basis. Human review mandate: all LLM outputs are screening aids; qualified review required before any decision affecting rights. No harassment: analysis is documentation, not persecution. Data minimisation: keep only what you need; hadr target delete removes artifacts. Ask-a-lawyer doctrine: if unsure whether your use case is lawful, ask a lawyer before running HADR against a real person.

ROADMAP & OPEN RESEARCH

(Deepfake/lip-sync detection was evaluated and explicitly declined by the founder due to unreliable results on compressed social-media video.)

Shipped in v0.3 ✔ — Analyst Annotations in Ledger (§14) · Alibi & Geolocation Cross-Check (§08) · Financial Graph Edges from OCR (§06) · Court-Format Exports + Verifier Annex (§15) · Headless Export SDK (§15) · MCP Server Mode (§16) · Forensic-Prompt A/B Harness (hadr prompt-ab).

Shipped in v0.4 ✔ — Acoustic Event Detection: scream · gunshot · breaking glass · impact · siren, YAMNet-class ONNX with a deterministic offline fallback (§05) · Code-Switch & Language ID per transcript segment (§05) · Sentiment Arc: tone trajectory across a dossier with inflection points (§08) · PII Auto-Redaction of the export view — mask/hash/remove strategies with a false-positive guard, sealed into export metadata (§15) · Multi-Analyst Workspaces & RBAC — per-analyst API keys, viewer/analyst/admin roles, annotation ownership (§14) · Temporal Activity Heatmap — hour × weekday pattern-of-life matrix with anomaly flags (§08).

Open roadmap (v0.5+):

REFERENCES & APPENDIX

Component Table

CLI Reference

hadr init (workspace) · serve (dashboard :8000) · mcp (MCP server, extra mcp) · target create|list|show|delete|voice-add · ingest <uri> --target <id> · jobs list|run · evidence list|verify|export|package|verify-package · legal list|show|add · models list|add · export <target> -f json|jsonld|cypher|gexf|pdf|bundle · prompt-ab -v claims|entities|legal|forensic · casefile <target> · forecast <target> · graph show|export|osint · keys create · demo (offline mock pipeline)

Glossary

HADR Forensics is released under the MIT License. See LICENSE for terms.

v0.3 (2026). Adds the annotation/audit layer, temporal & alibi reasoning, OCR financial edges, the headless export SDK, MCP server mode, and the forensic prompt A/B harness.

v0.4 (2026). Adds acoustic event spotting, language ID & code-switch detection, the sentiment arc, PII auto-redaction, multi-analyst RBAC, and the temporal pattern-of-life heatmap — 230 offline tests.