Credibility & Acceptance API

R&D uses this API to assess whether a backtest strategy meets deployability criteria and to perform acceptance calibration. The credibility harness runs verdict gates against a corpus of historical backtests (outcome snapshots) to compute per-dimension scores (Spearman correlation, win rates, tier stability, regime concentration). The operator triggers a full run against a known window and corpus, then reads back dimensions + a high-level verdict (deployable/marginal/insufficient_data/reject) for gating strategy launches. Base path: /api/internal/ (requires X-Internal-Secret header for service-principal auth).
Note: All acceptance/calibration endpoints are internal-only (no Supabase JWT path today). The credibility run trigger also routes under /api/internal/credibility/v1/.... No timeframe parameter — verdicts are daily-only.

Credibility Runs (Trigger & History)

POST /credibility/v1/runs

Trigger a single data-backed credibility run (reserves the single-flight slot, spawns the heavy tail detached, returns 202 immediately). Only one run can be in progress at a time; concurrent attempts return 409. Parameters:

x-internal-caller (header, optional): caller identifier stamped on the run row (defaults to “admin”)

Request body:

{
  "corpus_id": "behavioral-v1" | "integrity-v1",
  "window_id": "W1" | "W2" | "W3" | "W4" | "W4_control",
  "ch_read_mode": "final" | "no_final" (default: "final")
}

Response 202:

{
  "run_id": integer,
  "status": "running"
}

Response 409 (run in flight):

{
  "detail": "a data-backed run is already in progress",
  "run_id": integer | null,
  "triggered_by": string | null,
  "started_at": ISO-8601 timestamp | null
}

Response 400 (invalid corpus/window/read-mode):

{
  "detail": "unknown corpus_id '...' | unknown window_id '...' | invalid ch_read_mode '...'"
}

GET /credibility/v1/runs/latest

Fetch the most-recent run for a mode, with dimensions + presentation + engine-staleness flag. Parameters:

run_mode (query, optional): "data_backed" | "ci_hermetic" (default: "data_backed")

Response 200: (shape inferred from handler — no declared response_model)

{
  "id": integer,
  "run_mode": "data_backed" | "ci_hermetic",
  "engine_git_sha": string,
  "suite_version": "1.0",
  "triggered_by": string,
  "status": "running" | "completed" | "failed",
  "started_at": ISO-8601 timestamp,
  "completed_at": ISO-8601 timestamp | null,
  "corpus_id": string,
  "corpus_version": string,
  "window_id": string,
  "ch_read_mode": "final" | "no_final",
  "config_hash": string,
  "symbol_count": integer,
  "date_range_start": ISO-8601 date,
  "date_range_end": ISO-8601 date,
  "dimensions": [
    {
      "dimension": string,
      "gate": string,
      "status": "pass" | "fail" | "insufficient_data",
      "metrics": { /* dimension-specific metrics */ },
      "message": string | null
    }
  ],
  "presentation": {
    "verdict": "deployable" | "marginal" | "insufficient_data" | "reject",
    "summary": string,
    "gates_passed": integer,
    "gates_failed": integer,
    "gates_total": integer
  },
  "engine_stale": boolean
}

GET /credibility/v1/runs/

Fetch a single run by ID with dimensions + presentation (404 if unknown). Parameters:

run_id (path, required): integer

Response 200: (shape inferred from handler — no declared response_model)
Same as /runs/latest response above.

GET /credibility/v1/runs

List run history for one lens (mode, corpus, read-mode, window). Includes failed runs. Dimensions are batched in a single query. Parameters:

run_mode (query, optional): "data_backed" | "ci_hermetic" (default: "data_backed")
corpus_id (query, optional): "behavioral-v1" | "integrity-v1" (default: "behavioral-v1")
ch_read_mode (query, optional): "final" | "no_final" (default: "final")
window_id (query, optional): "W1" | "W2" | "W3" | "W4" | "W4_control" (default: "W1")
limit (query, optional): integer (default: 20)

Response 200: (shape inferred from handler — no declared response_model)

{
  "runs": [
    {
      "id": integer,
      "run_mode": string,
      "corpus_id": string,
      "window_id": string,
      "ch_read_mode": string,
      "status": string,
      "started_at": ISO-8601 timestamp,
      "completed_at": ISO-8601 timestamp | null,
      "triggered_by": string,
      "dimensions": [
        {
          "dimension": string,
          "gate": string,
          "status": "pass" | "fail" | "insufficient_data",
          "metrics": object,
          "message": string | null
        }
      ]
    }
  ]
}

Acceptance Metrics (Phase 4 Learning Loop)

Read-only endpoints that compute acceptance gate metrics over a date range. These feed calibration analysis and deployability verdicts.

GET /acceptance/report

Generate full acceptance report across all score families (composite of quality, directional, stability, regime checks + gate results). Parameters:

start_date (query, required): YYYY-MM-DD
end_date (query, required): YYYY-MM-DD

Response 200:

{
  "start_date": "2026-06-01",
  "end_date": "2026-06-14",
  "total_snapshots": integer,
  "score_quality": [
    {
      "score_family": string,
      "spearman": [
        {
          "score_family": string,
          "horizon": "1d" | "5d" | "10d",
          "overall": number | null,
          "bullish_only": number | null,
          "bearish_only": number | null,
          "p_value_overall": number | null,
          "p_value_bullish": number | null,
          "p_value_bearish": number | null,
          "sample_size": integer
        }
      ],
      "tier_win_rates": [
        {
          "tier": "EXCELLENT" | "GOOD" | "MODERATE" | "POOR",
          "win_rate": number | null,
          "sample_size": integer,
          "avg_return": number | null
        }
      ],
      "tier_monotonic": boolean | null,
      "sample_size": integer
    }
  ],
  "directional": {
    "bullish_spearman_5d": number | null,
    "bearish_spearman_5d": number | null,
    "bullish_excellent_win_rate": number | null,
    "bearish_excellent_win_rate": number | null,
    "bullish_sample_size": integer,
    "bearish_sample_size": integer
  } | null,
  "stability": {
    "tier_churn_pct": number | null,
    "percentile_drift_p90": number | null,
    "clean_cohort_size": integer,
    "event_excluded_count": integer
  } | null,
  "regime_concentration": {
    "regimes": [
      {
        "regime": string,
        "excellent_share": number,
        "universe_share": number,
        "concentration_ratio": number,
        "breach": boolean
      }
    ],
    "any_breach": boolean,
    "max_concentration_ratio": number
  } | null,
  "gates": [
    {
      "gate_name": string,
      "target": number,
      "actual": number | null,
      "passed": boolean,
      "description": string
    }
  ],
  "all_gates_passed": boolean
}

GET /acceptance/score-quality/

Compute score quality (Spearman correlation + tier win rates + monotonicity) for a single score family. Parameters:

score_family (path, required): string (e.g., "confluence_net_v5")
start_date (query, required): YYYY-MM-DD
end_date (query, required): YYYY-MM-DD

Response 200:

{
  "score_family": "confluence_net_v5",
  "spearman": [
    {
      "score_family": string,
      "horizon": "1d" | "5d" | "10d",
      "overall": number | null,
      "bullish_only": number | null,
      "bearish_only": number | null,
      "p_value_overall": number | null,
      "p_value_bullish": number | null,
      "p_value_bearish": number | null,
      "sample_size": integer
    }
  ],
  "tier_win_rates": [
    {
      "tier": "EXCELLENT" | "GOOD" | "MODERATE" | "POOR",
      "win_rate": number | null,
      "sample_size": integer,
      "avg_return": number | null
    }
  ],
  "tier_monotonic": boolean | null,
  "sample_size": integer
}

GET /acceptance/stability

Compute tier stability and churn analysis (tier transitions between consecutive snapshots, percentile drift). Parameters:

start_date (query, required): YYYY-MM-DD
end_date (query, required): YYYY-MM-DD

Response 200:

{
  "tier_churn_pct": number | null,
  "percentile_drift_p90": number | null,
  "clean_cohort_size": integer,
  "event_excluded_count": integer
}

GET /acceptance/regime-concentration

Check concentration of “EXCELLENT” tier outcomes within each market regime to detect single-regime overfitting. Parameters:

start_date (query, required): YYYY-MM-DD
end_date (query, required): YYYY-MM-DD

Response 200:

{
  "regimes": [
    {
      "regime": "BULL_HIGH_VOL" | "BULL_LOW_VOL" | "NEUTRAL_HIGH_VOL" | "NEUTRAL_LOW_VOL" | "BEAR_HIGH_VOL" | "BEAR_LOW_VOL",
      "excellent_share": number,
      "universe_share": number,
      "concentration_ratio": number,
      "breach": boolean
    }
  ],
  "any_breach": boolean,
  "max_concentration_ratio": number
}

GET /acceptance/tier-monotonicity/

Compute mean return by tier (EXCELLENT → GOOD → MODERATE → POOR) to verify monotonic score quality. Parameters:

score_family (path, required): string
start_date (query, required): YYYY-MM-DD
end_date (query, required): YYYY-MM-DD

Response 200:

{
  "score_family": "confluence_net_v5",
  "tiers": [
    {
      "tier": "EXCELLENT" | "GOOD" | "MODERATE" | "POOR",
      "mean_return_5d": number | null,
      "sample_size": integer
    }
  ],
  "is_monotonic": boolean | null
}

GET /acceptance/snapshot-status

Get status of the snapshot collection system (total collected, unique symbols/days, pending evaluations). Parameters: none Response 200:

{
  "total_snapshots": integer,
  "unique_symbols": integer,
  "unique_days": integer,
  "latest_snapshot_date": "2026-06-14" | null,
  "pending_evaluations": integer,
  "evaluated_count": integer
}

GET /acceptance/gate-status

Quick pass/fail check for all acceptance gates over the last 14 days (no date-range param). Computes Spearman (overall, bullish, bearish), EXCELLENT tier win rate, and tier churn in a single query. Parameters: none Response 200:

{
  "window_days": 14,
  "total_snapshots": integer,
  "gates": [
    {
      "gate": "spearman_5d" | "bull_spearman_5d" | "bear_spearman_5d" | "excellent_win_rate" | "tier_churn",
      "value": number | null,
      "threshold": number,
      "passed": boolean
    }
  ],
  "all_passed": boolean
}

Calibration (Weight & Confidence Tuning)

Phase 4 endpoints for fine-tuning confluencence component weights and confidence curve buckets post-acceptance.

POST /calibration/weight-analysis

Compute Spearman correlations per component (institutional levels, patterns, trends) within each regime and propose renormalized weight adjustments. Parameters:

regime (query, optional): regime name or null for all-regime analysis

Response 200:

[
  {
    "regime": "BULL_HIGH_VOL",
    "entries": [
      {
        "component": "vwap_proximity",
        "current_weight": 0.25,
        "proposed_weight": 0.28,
        "adjustment_pct": 12.0,
        "regime": "BULL_HIGH_VOL",
        "spearman_correlation": 0.32 | null
      }
    ],
    "renormalized": true,
    "analysis_window_days": 90,
    "sample_size": 1250
  }
]

POST /calibration/confidence-curve

Compute confidence calibration curve (buckets: 0-10, 10-20, …, 90-100) with expected vs. actual accuracy and calibration factors. Parameters:

regime (query, optional): regime name or null for overall curve

Response 200:

{
  "regime": "BULL_HIGH_VOL" | null,
  "buckets": [
    {
      "bucket_min": 0.0,
      "bucket_max": 10.0,
      "expected_accuracy": 0.55,
      "actual_accuracy": 0.52 | null,
      "sample_size": integer,
      "calibration_gap": -0.03 | null,
      "calibration_factor": 0.95 | null
    }
  ],
  "overall_accuracy": number | null
}

GET /calibration/data-readiness

Check whether sufficient snapshot outcome data exists for calibration analysis (min trading days, min snapshots with outcomes). Parameters: none Response 200:

{
  "trading_days_available": integer,
  "total_snapshots": integer,
  "snapshots_with_outcomes": integer,
  "min_days_required": 15,
  "is_ready": boolean,
  "readiness_pct": number
}

Key Schemas

TriggerRunBody — Input to kick off a credibility run.

{
  "corpus_id": "behavioral-v1" | "integrity-v1",
  "window_id": "W1" | "W2" | "W3" | "W4" | "W4_control",
  "ch_read_mode": "final" | "no_final"
}

Verdict outcomes (from presentation in run responses):

deployable — All acceptance gates passed, can launch live.
marginal — Some gates marginal but not rejected; suitable for paper-trading or limited-size live.
insufficient_data — Not enough outcome snapshots to gate on.
reject — One or more critical gates failed; does not meet acceptance bar.

Tier assignments (from _assign_tier logic in gate-status endpoint):

EXCELLENT — |score| >= 70
GOOD — |score| >= 55
MODERATE — |score| >= 40
POOR — |score| < 40 or null

Regime grid (canonical 2×3 from daily_regime_labels):

BULL_HIGH_VOL, BULL_LOW_VOL
NEUTRAL_HIGH_VOL, NEUTRAL_LOW_VOL
BEAR_HIGH_VOL, BEAR_LOW_VOL

Start

Operating

API

API reference

Runbooks

Assessment

Credibility & Acceptance API

Credibility Runs (Trigger & History)

POST /credibility/v1/runs

GET /credibility/v1/runs/latest

GET /credibility/v1/runs/

GET /credibility/v1/runs

Acceptance Metrics (Phase 4 Learning Loop)

GET /acceptance/report

GET /acceptance/score-quality/

GET /acceptance/stability

GET /acceptance/regime-concentration

GET /acceptance/tier-monotonicity/

GET /acceptance/snapshot-status

GET /acceptance/gate-status

Calibration (Weight & Confidence Tuning)

POST /calibration/weight-analysis

POST /calibration/confidence-curve

GET /calibration/data-readiness

Key Schemas

​Credibility & Acceptance API

​Credibility Runs (Trigger & History)

​POST /credibility/v1/runs

​GET /credibility/v1/runs/latest

​GET /credibility/v1/runs/

​GET /credibility/v1/runs

​Acceptance Metrics (Phase 4 Learning Loop)

​GET /acceptance/report

​GET /acceptance/score-quality/

​GET /acceptance/stability

​GET /acceptance/regime-concentration

​GET /acceptance/tier-monotonicity/

​GET /acceptance/snapshot-status

​GET /acceptance/gate-status

​Calibration (Weight & Confidence Tuning)

​POST /calibration/weight-analysis

​POST /calibration/confidence-curve

​GET /calibration/data-readiness

​Key Schemas

Credibility & Acceptance API

Credibility Runs (Trigger & History)

POST /credibility/v1/runs

GET /credibility/v1/runs/latest

GET /credibility/v1/runs/

GET /credibility/v1/runs

Acceptance Metrics (Phase 4 Learning Loop)

GET /acceptance/report

GET /acceptance/score-quality/

GET /acceptance/stability

GET /acceptance/regime-concentration

GET /acceptance/tier-monotonicity/

GET /acceptance/snapshot-status

GET /acceptance/gate-status

Calibration (Weight & Confidence Tuning)

POST /calibration/weight-analysis

POST /calibration/confidence-curve

GET /calibration/data-readiness

Key Schemas