/**
 * Types mirroring docs/API.md (contract v1). Postgres aggregates may arrive as strings → `Num`; always go through `num()`/`fmt*`.
 * Unknown/extra keys are tolerated: the web layer only reads what it renders.
 */

export type Num = number | string | null;
export type Org = { id: string; slug: string; name: string } | null;

export type Quality = { score?: number; completeness?: number; primary_source_ratio?: number; freshness?: number; source_count?: number; conflicts?: number };
export type Counts = { relations?: number; events?: number; claims?: number };

export interface EntitySummary {
  id: string;
  entity_type: string;
  slug: string;
  name: string;
  description: string | null;
  status: string;
  organization: Org;
  attributes: Record<string, unknown>;
  quality: Quality;
  counts: Counts;
  first_seen_at: string;
  last_seen_at: string;
  updated_at: string;
}

export interface Page<T> {
  items: T[];
  total: number;
  limit: number;
  offset: number;
}

export type ProvenanceEntry = {
  source_id: string | null;
  source_name?: string;
  url: string | null;
  observed_at: string;
  tier: number;
  confidence: string;
  extractor: string;
  unit?: string;
};
export type Provenance = Record<string, ProvenanceEntry>;

export type Importance = 0 | 1 | 2 | 3;

export interface ChangeEvent {
  id: string;
  event_type: string;
  category: string;
  property: string | null;
  old_value: unknown;
  new_value: unknown;
  summary: string;
  importance: Importance;
  observed_at: string;
  effective_at: string | null;
  source_url: string | null;
  connector_name: string | null;
  entity: EntitySummary | null;
  meta: Record<string, unknown>;
}

export interface Price {
  id: string;
  model: EntitySummary;
  provider: EntitySummary;
  provider_model_id: string | null;
  input_per_mtok: Num;
  output_per_mtok: Num;
  cached_input_per_mtok: Num;
  cache_write_per_mtok: Num;
  batch_input_per_mtok: Num;
  batch_output_per_mtok: Num;
  per_image: Num;
  currency: string;
  context_length: Num;
  max_output_tokens: Num;
  features: Record<string, unknown>;
  observed_at: string;
  valid_from: string;
  valid_to: string | null;
  source_url: string | null;
  tier: number;
}

export interface BenchmarkResult {
  id: string;
  model: EntitySummary;
  benchmark: EntitySummary;
  score: number;
  metric: string | null;
  unit: string | null;
  higher_is_better: boolean;
  config: Record<string, unknown>;
  evaluated_at: string | null;
  observed_at: string;
  source_url: string | null;
  tier: number;
  confidence: string;
}

export interface Claim {
  id: string;
  property: string;
  value: unknown;
  unit: string | null;
  tier: number;
  confidence: string;
  status: string;
  extractor: string;
  observed_at: string;
  effective_at: string | null;
  valid_from: string;
  valid_to: string | null;
  source_url: string | null;
  source_name: string | null;
}

export interface SourceRef {
  source_id: string | null;
  source_name: string | null;
  domain: string | null;
  tier: number | null;
  url: string;
  doc_type: string;
  last_observed_at: string | null;
  snapshots: number;
}

export interface RelationGroup {
  predicate: string;
  direction: 'out' | 'in';
  items: EntitySummary[];
  total: number;
}

export interface Lineage {
  ancestors: EntitySummary[];
  descendants: EntitySummary[];
  quantizations: EntitySummary[];
}

export interface HardwareFitRow {
  hardware: EntitySummary;
  quantization: string;
  estimated_memory_gb: number;
  fits: boolean;
}

export interface EntityDetail extends EntitySummary {
  provenance: Provenance;
  aliases: string[];
  identifiers: { scheme: string; value: string }[];
  relations: RelationGroup[];
  sources: SourceRef[];
  timeline: ChangeEvent[];
  prices?: Price[];
  price_history?: Price[];
  results?: BenchmarkResult[];
  lineage?: Lineage;
  providers?: EntitySummary[];
  hardware_fit?: HardwareFitRow[];
  models?: Page<EntitySummary>;
  papers?: EntitySummary[];
  repositories?: EntitySummary[];
  // companies listing enrichments may also be present on detail
  model_count?: number;
  paper_count?: number;
}

export interface Health {
  status: 'ok' | 'degraded' | string;
  version: string;
  db: boolean;
  redis: boolean;
  llm: { available: boolean; reachable?: boolean };
  time: string;
}

export interface Stats {
  entities: Record<string, Num>;
  entities_total: Num;
  sources: Num;
  connectors: Num;
  connectors_enabled: Num;
  documents: Num;
  snapshots: Num;
  claims: Num;
  claims_current: Num;
  relations: Num;
  change_events: Num;
  change_events_24h: Num;
  change_events_7d: Num;
  benchmark_results: Num;
  prices_current: Num;
  prices_total: Num;
  review_pending: Num;
  llm_jobs: Num;
  llm_tokens: Num;
  last_snapshot_at: string | null;
  last_event_at: string | null;
  first_entity_at: string | null;
  archive: { raw_bytes: Num; raw_files: Num; text_bytes: Num; text_files: Num };
  computed_at: string;
  // ---- 1.1 additions (optional until the API stream lands)
  /** Change events observed in the last 24 h excluding historical backfill. */
  change_events_live_24h?: Num;
  /** How each counter is computed ("Models = canonical model releases; artifacts and folded variants excluded"). */
  definitions?: Record<string, string>;
  [k: string]: unknown;
}

export interface StatsHistory {
  items: { day: string; counts: Record<string, Num> }[];
}

/** Output of services.search.compile_query — shape is loose; we render what we recognise. */
export interface CompiledQuery {
  text?: string | null;
  q?: string | null;
  entity_type?: string | null;
  type?: string | null;
  filters?: Record<string, unknown>;
  [k: string]: unknown;
}

export interface SearchPayload {
  query: CompiledQuery;
  items: (EntitySummary & { rank: number })[];
  total: number;
}

export interface Suggestion {
  id: string;
  entity_type: string;
  slug: string;
  name: string;
  organization_name: string | null;
}

export interface FacetValue {
  value: string;
  count: Num;
}
export interface OrgFacet {
  slug: string;
  name: string;
  count: Num;
}
export interface ModelFacets {
  organizations?: OrgFacet[];
  openness?: FacetValue[];
  modalities?: FacetValue[];
  families?: FacetValue[];
  years?: FacetValue[];
  licenses?: FacetValue[];
  status?: FacetValue[];
}
export type ModelsPage = Page<EntitySummary> & { facets?: ModelFacets };

export type CompanyRow = EntitySummary & { model_count: Num; paper_count: Num };
export interface CompanyFacets {
  countries?: FacetValue[];
  kinds?: FacetValue[];
}
export type CompaniesPage = Page<CompanyRow> & { facets?: CompanyFacets };

export type ProviderRow = EntitySummary & { model_count: Num; price_count: Num; min_input_per_mtok: Num; min_output_per_mtok: Num };
export type BenchmarkRow = EntitySummary & { result_count: Num; model_count: Num; top: { model: EntitySummary; score: number } | null };

export interface PriceIndexPoint {
  day: string;
  median_input: Num;
  median_output: Num;
  min_input: Num;
  max_input?: Num;
  models: number;
  offers?: number;
}
export interface PriceIndex {
  days?: number;
  note?: string;
  series: PriceIndexPoint[];
  movers: ChangeEvent[];
}

export interface HardwareFitItem {
  model: EntitySummary;
  parameter_count: number;
  estimated_memory_gb: number;
  fits: boolean;
  headroom_gb: number;
  quantization: string;
  note: string;
}
export interface HardwareFit {
  inputs: Record<string, unknown>;
  estimated?: boolean;
  counts?: { fits?: Num; evaluated?: Num };
  assumptions: string[];
  items: HardwareFitItem[];
}

export interface ExploreType {
  entity_type: string;
  count: Num;
  label: string;
}

export interface DailyDigest {
  date: string;
  counts: Record<string, Num>;
  sections: { category: string; label: string; items: ChangeEvent[]; key?: string; total?: Num }[];
  new_models: EntitySummary[];
  total?: Num;
  labels?: Record<string, string>;
  previous_day?: string | null;
  next_day?: string | null;
  /** 2.0: number of historical backfill events left out of the digest (honesty line). */
  backfill_excluded?: Num;
}

/** 1.1 — `GET /frontier`: current leaders per benchmark family + recent frontier movements. Loose shape; render what is present. */
export interface FrontierPayload {
  leaders?: { benchmark: EntitySummary; model: EntitySummary; score: Num; metric?: string | null; since?: string | null; trust_level?: string | null }[];
  recent_frontier_movements?: ChangeEvent[];
  computed_at?: string;
  [k: string]: unknown;
}

/** 1.1 — `GET /open?days=`: open-weight releases in the window. */
export interface OpenModelsPayload {
  items: EntitySummary[];
  total?: Num;
  days?: number;
  [k: string]: unknown;
}

/** 1.1 — `GET /entities/{slug}/provenance/{property}`: the full evidence behind one displayed value. */
export interface ProvenanceDetail {
  slug?: string;
  property: string;
  value: unknown;
  unit?: string | null;
  claim_id?: string | null;
  source_id?: string | null;
  source_name?: string | null;
  domain?: string | null;
  url?: string | null;
  tier: number | null;
  confidence?: string | null;
  extractor?: string | null;
  observed_at?: string | null;
  valid_from?: string | null;
  valid_to?: string | null;
  status?: string | null;
  /** Other current/conflicting claims for the same property. */
  conflicts?: Claim[];
  history_count?: Num;
  snapshot_id?: string | null;
  [k: string]: unknown;
}

/** 1.1 — `GET /pulse`: live activity summary (events/hour, connectors running…). Loose. */
export interface PulsePayload {
  events_24h?: Num;
  events_live_24h?: Num;
  per_hour?: { hour: string; count: Num }[];
  [k: string]: unknown;
}

export interface ChangeCategories {
  items: { category: string; event_type: string; count: Num }[];
}

export interface TimelinePayload {
  items: { month: string; count?: number; events: ChangeEvent[] }[];
  total?: number;
}

/** Local watchlist item (`lib/watchlist.ts`, localStorage `aia-watchlist`). */
export interface WatchItem {
  slug: string;
  name: string;
  entity_type: string;
  org?: string | null;
  added_at?: string;
}

export interface CompareDimension {
  key: string;
  label: string;
  unit?: string;
  kind: 'number' | 'text' | 'list' | 'bool' | 'date';
  /** Where the value comes from: `attr` (claims) · `prices` · `results` (benchmark) — informational. */
  source?: string;
}
export interface ComparePayload {
  entity_type: string;
  dimensions: CompareDimension[];
  items: { entity: EntitySummary; values: Record<string, unknown>; provenance: Provenance; prices?: Price[]; results?: BenchmarkResult[] }[];
}

export interface DiffPayload {
  a: string;
  b: string;
  scope?: Record<string, unknown> | string;
  new_entities: EntitySummary[];
  gone_entities: EntitySummary[];
  property_changes: ChangeEvent[];
  price_changes: ChangeEvent[];
  benchmark_changes: ChangeEvent[];
  counts: Record<string, Num>;
}

export interface ConnectorHealth {
  name: string;
  label: string;
  health: string;
  last_success_at: string | null;
  interval_seconds: Num;
}
export interface SourceRow {
  key: string;
  name: string;
  domain: string;
  tier: number;
  kind: string;
  category: string;
  organization: Org;
  enabled: boolean;
  documents: Num;
  last_crawled_at: string | null;
  connectors: ConnectorHealth[];
}

export interface MetricDefinition {
  key?: string;
  name?: string;
  label?: string;
  description?: string;
  formula?: string;
  version?: string | number;
  unit?: string;
  [k: string]: unknown;
}
export interface Methodology {
  metrics: MetricDefinition[];
  confidence_levels: Record<string, string> | { key: string; label?: string; description?: string }[] | string[];
  tiers: Record<string, string> | { tier: number; label?: string; description?: string }[];
  event_types: Record<string, string> | { event_type: string; category?: string; label?: string; description?: string; importance?: number }[] | string[];
  extractors: Record<string, string> | { key?: string; name?: string; description?: string }[] | string[];
}

export type TrendingRow = EntitySummary & { views: Num };

export interface SitemapPayload {
  items: { slug: string; entity_type: string; updated_at: string }[];
  total: number;
}

export interface GraphNode {
  id: string;
  slug: string;
  name: string;
  entity_type: string;
  organization_name?: string | null;
}
export interface GraphEdge {
  source: string;
  target: string;
  predicate: string;
}
export interface GraphPayload {
  root?: string;
  nodes: GraphNode[];
  edges: GraphEdge[];
}

export interface AsOfPayload {
  id?: string;
  slug?: string;
  name?: string;
  entity_type?: string;
  existed: boolean;
  first_seen_at: string | null;
  date: string;
  attributes: Record<string, unknown>;
  claims: Claim[];
}

// ---- D1 (models/benchmarks/compare) ----
/** 1.1 shapes consumed by the models · artifacts · families · benchmarks · compare · licences pages. Mirrors docs/API.md §1.1. */
export type IdentityConfidence = 'high' | 'medium' | 'low';
export interface FamilyRef {
  id: string | null;
  slug: string;
  name: string;
}
/** `/models` row (1.1): canonical model, or an artifact when `include=artifacts`. */
export type ModelRow = EntitySummary & { identity_confidence?: IdentityConfidence; family?: FamilyRef | null; canonical?: EntitySummary | null; artifact_kind?: string | null };
export interface FacetValue11 {
  value: string;
  label?: string;
  count: Num;
  canonical?: boolean;
  category?: string;
  raw_labels?: string[];
  raw?: boolean;
}
export interface ModelFacets11 {
  organizations?: OrgFacet[];
  openness?: FacetValue11[];
  modalities?: FacetValue11[];
  families?: FacetValue11[];
  years?: FacetValue11[];
  licenses?: FacetValue11[];
  status?: FacetValue11[];
  trust?: FacetValue11[];
  definitions?: Record<string, string>;
}
export type ModelsPage11 = Page<ModelRow> & { facets?: ModelFacets11; universe?: string };

export interface DeploymentPrices {
  input: Num;
  cached_input: Num;
  cache_write: Num;
  output: Num;
  batch_input: Num;
  batch_output: Num;
  per_image: Num;
  per_request: Num;
  currency: string;
  unit: string;
  native_units: Record<string, unknown>;
}
export interface Deployment {
  id: string;
  model: EntitySummary;
  provider: EntitySummary;
  provider_model_id: string | null;
  context_length: Num;
  max_output_tokens: Num;
  prices: DeploymentPrices;
  features: Record<string, unknown>;
  status: 'active' | 'delisted' | string;
  observed_at: string;
  valid_from: string;
  valid_to: string | null;
  source_url: string | null;
  tier: number;
}
export interface Group {
  metric: string;
  config_key: string;
  label: string;
  n: number;
  model_count: number;
  config: Record<string, unknown>;
  higher_is_better: boolean;
  trust_mix: Record<string, number>;
}
export interface ModelRef {
  id: string;
  slug: string;
  name: string;
  entity_type: string;
  organization: Org;
  attributes: Record<string, unknown>;
}
export type Comparability = 'comparable' | 'partially-comparable' | 'not-comparable';
export interface LeaderboardRow {
  rank: number;
  model: ModelRef;
  score: number;
  metric: string;
  unit: string | null;
  higher_is_better: boolean;
  delta_rank: number | null;
  previous_rank: number | null;
  trust_level: string;
  trust_label: string;
  config: Record<string, unknown>;
  config_key: string;
  comparability: Comparability;
  comparability_reasons: string[];
  evaluated_at: string | null;
  observed_at: string;
  source_url: string | null;
  tier: number;
  result_id: string;
  n_rows: number;
}
export interface LicenseInfo {
  key: string;
  label: string;
  category: string;
  spdx: string | null;
  url: string | null;
  commercial_use: boolean | null;
  redistribution: boolean | null;
  derivatives: boolean | null;
  hosting_restrictions: boolean | null;
  attribution: boolean | null;
  acceptable_use: boolean | null;
  osi_approved: boolean;
  weights_downloadable: boolean;
}
export interface BenchmarkListItem {
  id: string;
  entity_type: string;
  slug: string;
  name: string;
  description?: string | null;
  category: string | null;
  family: string | null;
  variant: string | null;
  metric: string | null;
  unit: string | null;
  direction: 'higher' | 'lower' | string | null;
  attributes: Record<string, unknown>;
  result_count: Num;
  model_count: Num;
  leader: LeaderboardRow | null;
  second: LeaderboardRow | null;
  top: { model: EntitySummary; score: number } | null;
  primary_group: Group | null;
  groups: Group[];
  trust_mix: Record<string, number>;
  trust_labels: Record<string, string>;
  updated_at?: string;
}
export interface BenchmarksPayload {
  items: BenchmarkListItem[];
  total: Num;
  note?: string;
}
export interface BenchmarkDetail extends Omit<EntityDetail, 'model_count'> {
  family?: string | null;
  variant?: string | null;
  metric?: string | null;
  direction?: string | null;
  category?: string | null;
  groups?: Group[];
  primary_group?: Group | null;
  result_count?: Num;
  model_count?: Num;
  leaderboard?: LeaderboardRow[];
  trust_mix?: Record<string, number>;
}
export interface LeaderboardPayload {
  benchmark: EntitySummary;
  group: Group | null;
  groups: Group[];
  items: LeaderboardRow[];
  total: number;
  limit: number;
  offset: number;
  comparable_only: boolean;
  filters: Record<string, unknown>;
  history_available: boolean;
  methodology: string;
}
export interface FrontierPoint {
  date: string;
  model: ModelRef;
  score: number;
  trust_level: string;
  config: Record<string, unknown>;
  result_id: string;
}
export interface BenchmarkFrontierPayload {
  benchmark: EntitySummary;
  series: { group: Group; primary: boolean; points: FrontierPoint[]; current_leader: FrontierPoint | null }[];
  generated_at: string;
  methodology: string;
}
export interface MatrixColumn {
  id: string;
  slug: string;
  name: string;
  category: string | null;
  metric: string;
  config_key: string;
  group_label: string;
  higher_is_better: boolean;
  n_models: number;
}
export interface MatrixCell {
  score: number;
  rank: number;
  trust_level: string;
  config_key: string;
  comparability: Comparability;
  result_id: string;
}
export interface MatrixRow {
  model: { id: string; slug: string; name: string; organization: string | null; organization_slug: string | null; openness: string | null; release_date: string | null };
  cells: Record<string, MatrixCell | null>;
  n_cells: number;
  mean_rank: number | null;
}
export interface MatrixPayload {
  columns: MatrixColumn[];
  rows: MatrixRow[];
  total_rows: number;
  comparable_only: boolean;
  min_cells: number;
  methodology: string;
}
export interface ParetoPoint {
  id: string;
  model: { id: string; slug: string; name: string; organization: string | null; openness: string | null };
  x: number;
  y: number;
  rank: number;
  trust_level: string;
  config: Record<string, unknown>;
  provider?: EntitySummary | null;
  estimated?: boolean;
  pareto: boolean;
}
export interface ParetoPayload {
  benchmark: EntitySummary;
  group: Group | null;
  groups: Group[];
  x: { key: string; label: string };
  y: { key: string; label: string };
  points: ParetoPoint[];
  frontier: string[];
  methodology: string;
}
export interface FamilyRow {
  id: string | null;
  slug: string;
  name: string;
  canonical: boolean;
  entity_type: 'model_family' | string;
  organization: Org;
  model_count: Num;
  first_release: string | null;
  last_release: string | null;
  param_range: { min: Num; max: Num } | null;
  modalities: string[];
  licenses: { key: string; label: string; models: Num }[];
  benchmark_best: Record<string, { rank: number; model: string }>;
}
export interface FamilyMember {
  model: EntitySummary;
  key_facts: Record<string, unknown>;
  benchmark_ranks: Record<string, number>;
}
export interface FamilyDetail extends FamilyRow {
  summary: EntitySummary | null;
  members: FamilyMember[];
  artifacts_count: Num;
  providers: EntitySummary[];
  lineage: { source: string; target: string; predicate: string }[];
  timeline: { date: string | null; kind: string; model: { id: string; slug: string; name: string } }[];
  note: string | null;
}
export type FamiliesPage = Page<FamilyRow> & { note?: string };
export type LicenseRow = LicenseInfo & { aliases: string[]; models: Num };
export interface LicensesPayload {
  items: LicenseRow[];
  total: Num;
  categories: string[];
  unclassified: { raw: string; models: Num }[];
  note?: string;
}
export type LicenseDetail = LicenseInfo & { aliases: string[]; models: Page<EntitySummary> };

export interface ModelIdentity {
  canonical_model: boolean;
  official_checkpoints: string[];
  official_artifacts: number;
  third_party_artifacts: number;
  provider_deployments: number;
  folded_variants: number;
  api_aliases: string[];
  note?: string;
}
export interface ModelOpenness {
  category: string;
  raw: string | null;
  label: string;
  definition: string;
  dimensions: Record<string, boolean | null>;
  note?: string;
}
export type ModelLicence = (LicenseInfo & { raw: string | null; url_observed: string | null }) | { key: null; raw: string | null; note?: string };
export interface VersionTransition {
  from: unknown;
  to: unknown;
  valid_from: string;
  valid_to: string | null;
  effective_at: string | null;
  source_url: string | null;
  tier: number;
  claim_id: string;
  status: string;
}
export interface VersionHistoryItem {
  property: string;
  transitions: VersionTransition[];
  current: unknown;
}
export interface ModelBenchmarkBest {
  score: number;
  unit: string | null;
  trust_level: string;
  trust_label: string;
  config: Record<string, unknown>;
  evaluated_at: string | null;
  observed_at: string;
  source_url: string | null;
  tier: number;
  result_id: string;
}
export interface ModelBenchmarkGroup {
  config_key: string;
  comparability_group: string;
  n_rows: number;
  higher_is_better: boolean;
  best: ModelBenchmarkBest;
  trust_levels: string[];
}
export interface ModelBenchmarks {
  items: { id: string; slug: string; name: string; category: string | null; metrics: { metric: string; groups: ModelBenchmarkGroup[] }[] }[];
  total_rows: number;
  note?: string;
}
export type ArtifactKind = 'checkpoint' | 'quantization' | 'conversion' | 'packaging';
export type ArtifactSummary = EntitySummary & { artifact_kind?: ArtifactKind | string | null };
export type FamilyBlock = EntitySummary | { id: null; name: string; canonical: false; note?: string } | null;
/** Model (or artifact) detail with the 1.1 blocks. */
export interface ModelDetail extends EntityDetail {
  redirected_from?: { slug: string; id: string; entity_type: string } | null;
  family?: FamilyBlock;
  artifacts?: { items: { kind: string; items: ArtifactSummary[]; count: number }[]; total: number };
  deployments?: Deployment[];
  identity?: ModelIdentity;
  licence?: ModelLicence | null;
  openness?: ModelOpenness | null;
  version_history?: VersionHistoryItem[];
  benchmarks?: ModelBenchmarks;
  family_id?: string | null;
  identity_confidence?: IdentityConfidence;
  hardware_fit_assumptions?: string[];
  canonical?: EntitySummary | null;
  artifact_kind?: ArtifactKind | string | null;
}
export interface CompareDimension11 extends CompareDimension {
  higher_is_better?: boolean;
  benchmark?: string;
  metric?: string;
  config_key?: string;
  comparability?: Comparability;
  trust_levels?: string[];
}
export interface ComparabilityInfo {
  level: Comparability;
  reasons: string[];
  trust: Record<string, { level: string; label: string }>;
}
export interface ComparePayload11 {
  entity_type: string;
  dimensions: CompareDimension11[];
  items: { entity: EntitySummary; values: Record<string, unknown>; provenance: Provenance; prices?: Price[]; results?: BenchmarkResult[]; deployments?: Deployment[] }[];
  comparability: Record<string, ComparabilityInfo>;
  diff_only: boolean;
  note?: string;
}
export type DiffDelta = { absolute: number; percent: number | null } | { added: unknown[]; removed: unknown[] } | null;
export interface ModelDiffPayload {
  a: EntitySummary;
  b: EntitySummary;
  dimensions: (CompareDimension11 & { a: unknown; b: unknown; delta: DiffDelta })[];
  comparability: Record<string, ComparabilityInfo>;
  note?: string;
}
export interface Methodology11 extends Methodology {
  openness?: { categories: string[]; labels: Record<string, string>; definitions: Record<string, string>; dimensions: string[]; note?: string };
  trust_levels?: { key: string; label: string }[];
  comparability?: Record<string, unknown> & { comparable?: string; 'partially-comparable'?: string; 'not-comparable'?: string };
  licence_categories?: string[];
  counters?: Record<string, string>;
  hardware_fit?: unknown;
}
// ---- /D1 ----

// ---- D2 (intelligence) ----
// Reuses the D1 shapes above: Deployment · DeploymentPrices · Group · ModelRef · LeaderboardRow · LicenseInfo · ModelLicence · ParetoPoint · ParetoPayload.
export type DeploymentsPage = Page<Deployment> & { next_before?: string | null; current?: boolean };
/** 1.1 feed fields on events (`occurred_at = coalesce(effective_at, observed_at)`, backfill flag, semantic group). */
export type ChangeEventIntel = ChangeEvent & { occurred_at?: string; is_backfill?: boolean; group_key?: string | null; percent_change?: Num };
/** Event date to display: 1.1 `occurred_at`, else effective, else observed. */
export function eventDate(e: ChangeEventIntel): string {
  return e.occurred_at ?? e.effective_at ?? e.observed_at;
}

/** 1.1 `Fit` — every hardware-fit figure is an estimate (`estimated: true`). */
export interface FitBreakdown {
  weights_gb: number;
  weights_source: 'observed' | 'estimated' | string;
  overhead_gb: number;
  kv_cache_gb: number;
  kv_cache_method: 'architecture' | 'heuristic' | string;
  reserved_gb: number;
  context: number;
  batch: number;
}
export interface Fit {
  quantization: string;
  estimated: true | boolean;
  fits: boolean | null;
  estimated_memory_gb: Num;
  headroom_gb: Num;
  parameter_count?: Num;
  breakdown?: FitBreakdown;
  device?: { memory_gb: number; gpu_count: number; total_memory_gb: number };
  note?: string | null;
  multi_gpu_note?: string | null;
}


export type BenchmarkRef = { id: string; slug: string; name: string; category?: string | null; entity_type?: string };

/** `GET /frontier` (1.1) — every section is optional so partial payloads still render. */
export interface FrontierIntel {
  latest_major_models?: ChangeEventIntel[];
  benchmark_frontier?: { benchmark: BenchmarkRef; group: Group | null; leader: LeaderboardRow | null; second: LeaderboardRow | null; gap: Num }[];
  price_frontier?: {
    cheapest_output: Deployment | null;
    cheapest_output_1m_context: Deployment | null;
    frontier_models: Num;
    composition?: { recent_by_active_orgs?: Num; top10_on_a_benchmark?: Num; total?: Num; since?: string } | null;
  };
  context_frontier?: { model: EntitySummary; context_length: Num }[];
  open_weight_frontier?: { items: { model: EntitySummary; best_rank: Num; best_rank_on: string | null; parameter_count: Num; context_length: Num; ranks: Record<string, number> }[]; dimensions: string[]; note?: string };
  efficiency_frontier?: { quality: { benchmark: string; group: Group | null }; x: string; points: ParetoPoint[]; frontier: string[] };
  agentic_frontier?: { benchmark: BenchmarkRef; group: Group | null; leaders: LeaderboardRow[] }[];
  multimodal_frontier?: { model: ModelRef | EntitySummary; modalities: string[]; top10_on: string[] }[];
  recent_frontier_movements?: ChangeEventIntel[];
  generated_at?: string;
  methodology?: string;
}

/** AI Price Index (1.1) — v1 keys kept, new medians and sample sizes per day. */
export interface PriceIndexPointIntel extends PriceIndexPoint {
  median_frontier_output?: Num;
  median_frontier_input?: Num;
  median_open_output?: Num;
  median_embedding_input?: Num;
  min_frontier_output?: Num;
  sample?: { models?: Num; offers?: Num; frontier_models?: Num; frontier_offers?: Num; open_models?: Num; embedding_models?: Num };
}
export interface PriceDistribution {
  metric: string;
  unit: string;
  buckets: { from: Num; to: Num; label: string; offers: Num }[];
  offers: Num;
}
export interface CheapestFrontier {
  model: EntitySummary;
  provider: EntitySummary;
  output: Num;
  input: Num;
  context_length: Num;
  price_id?: string;
}
export interface PriceIndexIntel {
  days?: number;
  series: PriceIndexPointIntel[];
  movers: ChangeEventIntel[];
  cheapest_frontier?: CheapestFrontier | null;
  cheapest_frontier_1m_context?: CheapestFrontier | null;
  distribution?: PriceDistribution | null;
  new_listings_30d?: Num | ChangeEvent[];
  delistings_30d?: Num | ChangeEvent[];
  price_changes_30d?: Num | ChangeEvent[];
  frontier?: { composition?: Record<string, unknown>; methodology?: string };
  methodology?: string;
  note?: string;
}

/** `/providers` 1.1 aggregates. */
export interface PriceDistributionStats {
  min: Num;
  p25: Num;
  median: Num;
  p75: Num;
  max: Num;
  n: Num;
}
export type ProviderIntelRow = ProviderRow & {
  input_price_distribution?: PriceDistributionStats | null;
  output_price_distribution?: PriceDistributionStats | null;
  models_added_30d?: Num;
  models_removed_30d?: Num;
  price_changes_30d?: Num;
  organizations_covered?: Num;
  features_supported?: string[];
  feature_keys?: string[];
};

/** `GET /cost` and `GET /cost/context`. */
export interface CostItem {
  deployment: Deployment;
  cost: {
    per_request: Num;
    daily: Num;
    monthly: Num;
    annual: Num;
    effective_input_per_mtok: Num;
    effective_output_per_mtok: Num;
    per_request_fee: Num;
    inputs?: Record<string, unknown>;
    notes: string[];
  };
}
export interface CostPayload {
  model: EntitySummary | null;
  inputs: { input_tokens: Num; output_tokens: Num; requests_per_day: Num; cached_share: Num; batch: boolean };
  items: CostItem[];
  total: number;
  currency: string;
  methodology?: string;
  note?: string | null;
}
export interface CostContextPayload {
  tokens: number;
  items: { deployment: Deployment; context_length: Num; context_source: 'offer' | 'model attribute' | string; cost_usd: Num }[];
  total: number;
  currency: string;
  methodology?: string;
  note?: string | null;
}

/** `GET /run-locally`. */
export interface RunLocallyArtifact {
  artifact: EntitySummary;
  quant_format: string | null;
  file_size_gb: Num;
  weights_source: 'observed' | 'estimated' | string;
  fit: Fit;
}
export interface RunLocallyItem {
  model: EntitySummary;
  fit: Fit;
  artifacts: RunLocallyArtifact[];
  artifact_count: Num;
}
export interface RunLocallyPayload {
  inputs: Record<string, unknown>;
  estimated: boolean;
  assumptions: string[];
  counts: { fits?: Num; evaluated?: Num };
  items: RunLocallyItem[];
  note?: string;
}
/** `GET /hardware/{slug}/fit`. */
export interface HardwareSlugFit {
  hardware: EntitySummary;
  memory_options_gb: number[];
  inputs: Record<string, unknown>;
  estimated: boolean;
  assumptions: string[];
  runtimes: string[];
  counts: { fits?: Num; evaluated?: Num };
  items: ({ model: EntitySummary } & Fit)[];
  note?: string;
}

/** `GET /find-a-model`. */
export interface FinderMatch {
  model: EntitySummary;
  why: string[];
  observed: Record<string, unknown> & { benchmark_ranks?: Record<string, number>; best_rank?: Num; providers?: Num; cheapest_input_per_mtok?: Num; cheapest_output_per_mtok?: Num };
  estimated_fit?: Partial<Fit> | null;
  deployments?: Deployment[] | null;
}
export interface FinderPayload {
  matches: FinderMatch[];
  total: number;
  filters_applied: Record<string, unknown>;
  rules: Record<string, string>;
  note?: string;
}

/** `GET /open` (1.1). */
export interface OpenItem {
  model: EntitySummary;
  licence: ModelLicence;
  dimensions: Record<string, unknown>;
  best_results: { benchmark: string; rank: number }[];
  best_rank: Num;
  hardware_fit: { '4bit_64gb'?: Partial<Fit> | null; '8bit_128gb'?: Partial<Fit> | null; estimated?: boolean } | null;
  providers: Num;
  cheapest_output_per_mtok: Num;
}
export interface OpenPayload extends Page<OpenItem> {
  summary?: { by_category?: Record<string, Num>; by_license_top?: { key: string; label: string; models: Num }[]; new_30d?: Num };
  note?: string;
}

/** `GET /pulse` (1.1). */
export interface PulseCounter {
  value: Num;
  definition: string;
  median_percent?: Num | null;
  items?: unknown[] | null;
}
export interface PulseIntel {
  days: number;
  since: string;
  until: string;
  counters: Record<string, PulseCounter>;
  note?: string;
}
export interface PulseLeaderItem {
  benchmark: BenchmarkRef;
  previous: { model: ModelRef; score: Num } | null;
  current: { model: ModelRef; score: Num; metric?: string; group_label?: string; trust_level?: string; n_models?: Num; as_of?: string } | null;
}

/** `/methodology` 1.1 additions read by the intelligence pages. */
export interface MethodologyIntel {
  openness?: { categories: string[]; labels: Record<string, string>; definitions: Record<string, string>; dimensions: string[]; note?: string };
  hardware_fit?: { assumptions: string[]; bytes_per_param?: Record<string, number>; reserved_gb?: number };
  frontier?: string;
  find_a_model?: Record<string, string> | string;
  licence_categories?: string[];
  trust_levels?: { key: string; label: string }[];
  counters?: Record<string, string> | string[];
  [k: string]: unknown;
}

/** `/hardware` facets (1.1). */
export type HardwarePage = Page<EntitySummary> & { facets?: { kinds?: FacetValue[]; manufacturers?: FacetValue[] } };
// ---- /D2 ----

// ---- D3 (temporal/graph/admin) ----
/** 1.1 feed fields merged into the base event (declaration merging: additive, optional). */
export interface ChangeEvent {
  occurred_at?: string;
  is_backfill?: boolean;
  group_key?: string | null;
}
/** `GET /graph/explore` (1.1): typed neighbourhood explorer, one of seven modes. */
export type GraphExploreMode = 'lineage' | 'research' | 'company' | 'benchmark' | 'dataset' | 'provider' | 'hardware';
export interface ExploreNode {
  id: string;
  slug: string;
  name: string;
  entity_type: string;
  org: string | null;
  org_slug: string | null;
  level: number;
  artifact_kind: string | null;
  attributes: Record<string, unknown>;
}
export interface ExploreEdge {
  source: string;
  target: string;
  predicate: string;
  attributes?: Record<string, unknown>;
  tier?: number | null;
}
export interface GraphExplorePayload {
  root: string;
  mode: GraphExploreMode;
  depth: number;
  predicates: string[];
  nodes: ExploreNode[];
  edges: ExploreEdge[];
  truncated: boolean;
  counts: { nodes: Num; edges: Num; by_type: Record<string, Num> };
}

/** `GET /time-machine` (1.1). */
export interface TimeMachineModelRow {
  model: EntitySummary;
  attributes_as_of: Record<string, unknown>;
  observed_then: boolean;
  reconstructed: boolean;
}
export interface TimeMachineLeader {
  benchmark: { id: string; slug: string; name: string; category?: string | null };
  leader: { model: EntitySummary; score: number; metric: string | null; config_key?: string | null; group_label?: string | null; trust_level?: string | null; n_models?: Num; as_of?: string | null } | null;
}
export interface TimeMachinePayload {
  date: string;
  scope: string;
  first_entity_at: string | null;
  reconstructed: boolean;
  note: string | null;
  models?: { items: TimeMachineModelRow[]; total: Num; limit?: Num; note?: string };
  prices?: { items: Price[]; total: Num; note?: string };
  benchmarks?: { leaders: TimeMachineLeader[]; note?: string };
  hardware?: { items: { hardware: EntitySummary; reconstructed?: boolean }[]; total?: Num; note?: string };
}

/** `GET /diff` (1.1): v1 keys + the new sections. */
export interface DiffPayload11 extends DiffPayload {
  new_benchmark_leaders?: { benchmark: { id: string; slug: string; name: string; category?: string | null }; at_a: TimeMachineLeader['leader']; at_b: TimeMachineLeader['leader'] }[];
  provider_changes?: ChangeEvent[];
  hardware_changes?: ChangeEvent[];
  context_changes?: ChangeEvent[];
  retired_models?: (EntitySummary | ChangeEvent)[];
  include_artifacts?: boolean;
  include_backfill?: boolean;
  note?: string;
}

/** Today in AI 2.0 (`/changes/daily.today`). */
export type TodayItem = ChangeEvent & { sources?: Num; documents?: string[]; grouped_events?: Num; event_ids?: string[] };
export interface TodaySection {
  key: string;
  label: string;
  items: TodayItem[];
  total: Num;
}
export interface DailyDigest2 extends DailyDigest {
  today?: TodaySection[];
  date_field?: string;
  note?: string;
}
export type ChangesPage = Page<ChangeEvent> & { next_before?: string | null; date_field?: string; include_backfill?: boolean };
export interface TimelinePayload11 extends TimelinePayload {
  date_field?: string;
  include_backfill?: boolean;
}

/** Search compiler v2. */
export interface CompiledFilter {
  filter: string;
  label: string;
  value: unknown;
  source_span?: string | null;
}
export interface CompiledQuery2 extends CompiledQuery {
  compiled?: CompiledFilter[];
  sort?: string | null;
  residual?: string | null;
  unrecognised?: string[];
  semantic?: boolean;
  version?: number;
  note?: string | null;
}
export type SearchPayload2 = Omit<SearchPayload, 'query'> & { query: CompiledQuery2 };

/** `GET /claims/{id}` and `GET /entities/{slug}/claims`. */
export type ClaimRow = Claim & { snapshot_id?: string | null; run_id?: string | null; value_raw?: unknown; extractor_version?: string | null };
export interface ClaimDetail {
  claim: ClaimRow;
  entity: EntitySummary | null;
  property: string;
  chain: { previous: ClaimRow[]; superseding: ClaimRow[]; conflicting: ClaimRow[]; history_count: Num };
  source: { id: string | null; name: string | null; domain: string | null; tier: number | null; url: string | null; snapshot_id: string | null; observed_at: string | null } | null;
  extractor: { name: string | null; version: string | null; confidence: string | null } | null;
  run_id: string | null;
  evidence: { snapshot_id: string | null; document_url: string | null; archived: boolean; snapshot_observed_at: string | null; document_title: string | null; doc_type: string | null } | null;
  note?: string | null;
}
export interface EntityClaimsPayload {
  entity: EntitySummary;
  items: ClaimRow[];
  total: number;
  limit: number;
  offset: number;
  status: string;
}

/** `GET /methodology` fields D3 renders beyond D1's `Methodology11` (loose: rendered as-is). */
export interface MethodologyD3 extends Methodology11 {
  quality_version?: string;
  expected_fields?: Record<string, string[]>;
  status_vocabulary?: string[];
  anomaly_checks?: { check: string; severity: string; description: string }[];
  event_semantics?: Record<string, string>;
  frontier?: string | Record<string, unknown>;
  find_a_model?: Record<string, string>;
  principles?: string[];
}

export interface SourcesPayload {
  items: SourceRow[];
  total?: Num;
  tiers?: Record<string, string>;
}
export type SourceRow11 = SourceRow & { snapshots?: Num; claims?: Num; base_url?: string | null; robots_policy?: string | null; priority?: Num; notes?: string | null };

export interface TrendingPayload {
  days: number;
  kind: string;
  items: (EntitySummary & { views?: Num; events?: Num; last_event_at?: string | null })[];
  definition?: string;
}
// ---- /D3 ----