> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Assessment

# 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:**

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

**Response 202:**

```json theme={null}
{
  "run_id": integer,
  "status": "running"
}
```

**Response 409 (run in flight):**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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)

```json theme={null}
{
  "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/{run_id}

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)

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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/{score_family}

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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/{score_family}

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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
[
  {
    "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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