API Documentation

Returns the authenticated user's H behavioral profile (Layers 1–4). Layer 5 is computed and stored but never returned.

{
  "layer1": {
    "irs_avg": 0.12,
    "irs_max": 0.45,
    "irs_trend": "stable",
    "sessions_tracked": 0,
    "history": [{"ts": "2026-05-25T10:00:00Z", "session_id": "uuid", "composite": 0.1, ...}]
  },
  "layer2": {
    "validation_seeking": 0.0,
    "agency_erosion": 0.0,
    "trust_over": 0.0,
    "trust_under": 0.0,
    "dependency": 0.0
  },
  "layer3": {
    "cognitive_rigidity": 0.0,
    "reality_anchoring": 0.0,
    "distortion": 0.0,
    "semantic_compression": 0.0
  },
  "layer4": {
    "legibility_adaptation": 0.0,
    "reciprocity_expect": 0.0,
    "social_substitution": 0.0
  },
  "meta": {
    "total_turns": 0,
    "total_sessions": 0,
    "professional_access": false,
    "consent_granted_at": null
  }
}

• irs_trend — "stable" / "rising" / "falling" over last 10 turns
• All layer metrics are running averages — each /analyze call updates them incrementally via LLM-based H scoring (hybrid: CF fast/Anthropic Haiku)
• Layer 5 (manipulation, ideological drift, radicalization) is stored internally but excluded from all API responses

Grant or revoke professional access to this user's behavioral profile.

{ "professional_id": "<uuid>", "action": "grant" }

action must be "grant" or "revoke".

{"ok": true, "action": "grant", "professional_id": "uuid"}

Compute the Retrieval Drift Score (RDS) for a query given its conversational context. RDS = 1 − Jaccard(docs retrieved with context, docs retrieved without context). RDS = 0 means context had no effect; RDS = 1 means the two retrievals share zero documents.

Request

{
  "query":   "What damages can we claim?",
  "context": [
    "Our supplier missed the delivery deadline.",
    "That sounds like a breach of contract."
  ],
  "domain":             "legal",
  "top_k":              5,
  "check_consistency":  false,
  "discover_stable":    false,
  "n_variants":         3,
  "save_text":          false,
  "enable_clean_twin":  false
}

context — list of strings from previous conversation turns (any order, plain text).

domain — one of: legal, finance, health, math, ethics, technology, history, science, politics, fantasy.

check_consistency — when true, generates n_variants paraphrases of the query and computes how stable the retrieval results are across them. Returns consistency_score.

discover_stable — when true, tries up to n_variants reformulations and returns the one that produces the lowest RDS (most stable retrieval). Returns stable_query.

Response

{
  "rds":      0.833,
  "jaccard":  0.167,
  "rbo":      0.121,
  "rds_rank": 0.879,
  "verdict":  "drift",
  "domain":  "legal",
  "context_docs": [
    {"doc_id": "legal_039", "label": "pro-B", "text_snippet": "Consequential damages under UCC…", "score": 0.84}
  ],
  "topic_docs": [
    {"doc_id": "legal_002", "label": "neutral", "text_snippet": "Breach of contract elements…", "score": 0.91}
  ],
  "augmented_query":    "supplier missed delivery breach of contract What damages can we claim?",
  "topic_query":        "What damages can we claim?",
  "framing_score":      0.96,
  "pressure_class":     "rhetorical_framing",
  "framing_direction":  null,
  "rdm_triggered":      true,
  "attack_class":       "compound",
  "attack_signals":     ["framing_only", "topical_drift"],
  "competing_affinity": 0.14,
  "affinity_steering_risk": true,
  "consistency_score":  0.82,
  "consistency_variants": 3,
  "stable_query":       "What are the rules governing damages breach of contract?",
  "consistency_detail": [
    {"query": "How is damages breach of contract typically handled?", "rds": 0.2, "verdict": "stable"},
    {"query": "What are the rules governing damages breach of contract?", "rds": 0.0, "verdict": "stable"},
    {"query": "Explain damages breach of contract in practical terms.", "rds": 0.4, "verdict": "weak_signal"}
  ]
}

verdict — drift (RDS ≥ 0.70), weak_signal (RDS ≥ 0.35), or stable. The verdict is computed on set-level RDS for backward compatibility.

rbo / rds_rank — rank-aware drift. RBO (Rank-Biased Overlap, Webber et al. 2010, p=0.9) compares the two ranked lists with top-weighted emphasis: the same documents in a different order score < 1.0. rds_rank = 1 − RBO catches reorder-only steering that set-level RDS reports as 0 (see docs/rag/RDM_W0_DECISION_MEMO.md).

save_text (request) — privacy default: when false, the persisted session stores a SHA-256 digest of the query and no context/topic text; scores and verdicts are always persisted.

context_docs vs topic_docs — side-by-side view of which documents each retrieval path found. Different labels (pro-A vs pro-B vs neutral) in the two lists indicate directional bias.

framing_score — P(semantic_drift) + P(rhetorical_framing) from the CF (Framing Pressure Classifier). Range 0.0–1.0. High = strong framing pressure in the user language.

pressure_class — Top CF class: neutral / semantic_drift / rhetorical_framing. Validated on legal, health, and finance domains.

rdm_triggered — true when framing_score ≥ 0.5. The RDM pipeline was automatically activated: topic extraction was forced and RDS was computed to measure the actual retrieval bias effect.

attack_class — compound attack taxonomy combining FPC, RDS, and rds_rank: clean | framing_only (FPC fires, RDS low) | topical_drift (RDS ≥ 0.50) | rank_steering (rds_rank high, RDS low) | vocab_injection (requires both stacks) | compound (≥ 2 signals). See docs/rag/RDM_W4_HARDENING.md.

attack_signals — list of active signal names that contributed to attack_class. null when clean.

competing_affinity — pre-retrieval steering precursor (W6): cosine of the conversation context vocabulary to the opposing-label corpus centroid. The only precursor carrying signal for vocabulary-injection steering (the framing detector does not). null for domains without a competing label.

affinity_steering_risk — true when competing_affinity ≥ the calibrated threshold; a triage flag (confirm with attack_class: vocab_injection), not a verdict.

consistency_score — 0.0–1.0. Measures retrieval stability across paraphrases of the same query. High (→ 1.0) = the KB has a stable answer regardless of phrasing. Low (→ 0.0) = the KB is uncertain or ambiguous on this topic. Only present when check_consistency or discover_stable is true.

stable_query — the paraphrase variant that produced the lowest RDS across the tested set. Present only when discover_stable is true. Use this reformulation to reduce framing-induced retrieval instability.

consistency_detail — per-variant breakdown: [{query, rds, verdict}]. Each entry is one paraphrase tested.

enable_clean_twin (request) — W4c clean-twin monitor (issue #2003). When true, a third retrieval runs the final query alone (no conversational context) and computes the displacement between the augmented and clean retrievals. Adds ~1 retrieval call latency. clean_shift is null when false.

clean_shift — only present when enable_clean_twin=true. Object with: set_shift (1 − Jaccard between augmented and clean docs), rank_shift (1 − RBO), noise_floor (calibrated benign floor 0.4668 for dense stack), alert (bool — fires when set_shift > 2 × noise_floor, i.e. > 0.934), alert_ratio (multiples of floor), latency_ms (wall-clock overhead of the extra retrieval). Validated on in-domain injection: indemnification 0.833 (1.78×), tortious_liability 1.000 (2.14×) — both above threshold.

Returns the benchmark correlation summary: per-domain RDS statistics (avg, drift rate) and the PSA precursor correlation results (Spearman ρ between ABI and RDS).

{
  "domains": [
    {"domain": "legal", "n_conversations": 300, "avg_rds": 0.960,
     "drift_rate": 0.469, "weak_rate": 0.107, "stable_rate": 0.424}
  ],
  "correlation_summary": [
    {"domain": "legal", "n_pairs": 50, "spearman_rho": 0.413,
     "precursor_precision": 0.98, "precursor_recall": 1.00,
     "precursor_f1": 0.99, "precursor_confirmed": true}
  ],
  "benchmark_summary": {}
}

precursor_confirmed: true means Spearman ρ ≥ 0.40 and recall ≥ 0.50 — the PSA behavioral signal reliably predicts whether retrieval will drift before the query arrives.

Standalone Framing Pressure Classifier (FPC). Scores a single query for rhetorical framing bias without computing RDS — no corpus lookup required. Use this as a lightweight pre-filter before deciding whether to run the full /rag/score pipeline. CF is a MiniLM 3-class classifier (neutral / semantic_drift / rhetorical_framing), multilingual (en, it, fr, de, es). Validated on legal, health, and finance domains. Model: val_acc=95.7%, semantic_drift recall=95.3%, rhetorical_framing recall=100.0%.

Request — query passed as URL parameter, no body required.

POST /api/v2/rag/fpc?query=Given+that+the+supplier+clearly+breached+the+contract%2C+what+damages+apply%3F

Response

{
  "framing_score":     0.96,
  "pressure_class":    "rhetorical_framing",
  "rdm_triggered":     true,
  "framing_direction": null
}

framing_score — P(semantic_drift) + P(rhetorical_framing). Range 0.0–1.0.

pressure_class — top CF class: neutral, semantic_drift, or rhetorical_framing.

rdm_triggered — true when framing_score ≥ 0.50. Threshold at which the full RDM pipeline should activate.

framing_direction — reserved for future use (directional bias detection). Always null in current version.

Returns paginated list of RDM scoring sessions. Each session is a /rag/score call stored in the database with its query, verdict, RDS, and FPC result.

GET /api/v2/rag/sessions?page=1&per_page=50&domain=legal&verdict=drift

{
  "items": [
    {"session_id": "uuid", "domain": "legal", "query": "...", "rds": 0.83,
     "verdict": "drift", "framing_score": 0.96, "rdm_triggered": true, "created_at": "..."}
  ],
  "total": 142, "page": 1, "per_page": 50, "total_pages": 3
}

Filter params: domain, verdict (drift / weak_signal / stable), rdm_triggered (true/false).

Aggregate statistics over all RDM sessions: drift rate by domain, FPC trigger rate, average RDS, and framing pressure distribution. Pre-computed — O(1) read.

{
  "total_sessions": 1420,
  "drift_rate": 0.34,
  "fpc_trigger_rate": 0.41,
  "avg_rds": 0.61,
  "by_domain": [
    {"domain": "legal", "sessions": 480, "drift_rate": 0.47, "avg_framing_score": 0.72}
  ],
  "pressure_distribution": {"neutral": 0.59, "semantic_drift": 0.23, "rhetorical_framing": 0.18}
}

Traffic-fitted RDS-per-length curve from shadow-mode observations. Each /score call silently increments per-(n_turns, pool) aggregates at write time; pools are all and benign (FPC-low proxy). Read-only — never drives alerting.

{
  "curve": [
    {"n_turns": 1, "pool": "benign", "n_obs": 142, "mean_rds": 0.02,
     "std_rds": 0.05, "synthetic_baseline": 0.0, "updated_at": "..."}
  ],
  "total_observations": 311,
  "benign_observations": 198,
  "benign_proxy": "pressure_class == 'neutral' (FPC-low, plan on #1976)"
}

Clears the anchor metadata (record_hash/prev_hash/beacon_value) of forensic records that fail verification — pre-fix rows whose stored hash cannot reproduce and whose raw query was not retained (unverifiable by construction). Score fields are untouched. Lets /verify-chain reflect the intact post-fix chain. Idempotent.

{
  "checked": 29,
  "repaired": 20,
  "remaining_anchored": 9,
  "repaired_ids": ["53aeca72-...", "..."]
}

Runs the LLM-in-the-loop experiment as a background task: for each scenario it retrieves legal precedents twice (clean query vs adversarial context+query), feeds each set — text only, corpus labels hidden — to a downstream LLM (model_key, default llama-70b), and records the predicted prevailing side of the appeal — appellant (reversal) vs appellee (affirmance). Proves adversarial framing flips the generated recommendation, not just the retrieved set. The LLM is a downstream demonstration target, never part of the inference path. Poll /llm-in-loop/status for the aggregate (flip_rate, steer_alignment).

{
  "running": false,
  "result": {"model": "llama-70b", "n_valid": 15,
             "flip_rate": 0.40, "steer_alignment": 1.0,
             "mean_rds": 0.58, "per_scenario": [...]}
}