// FE-facing contract for the Compliance Advisor "Case" (Clarity Gate).
// Matches the SDK<->FE contract (board 2026-07-01 / memory advisor-clarity-gate-contract).
// The FE renders ONLY these structured fields; it never extracts structure from the answer text.
// The only exception is rendering the deliberate [n] citation markers, mapped via `citations`.

export interface SuggestedContext {
  id: string // e.g. "datenschutz"
  label: string // e.g. "Datenschutz"
}

export interface ClarityInfo {
  is_underspecified: boolean
  concentration: number
  suggested_contexts?: SuggestedContext[] // clarify mode
  dominant_context?: string // answer mode
}

/** A retrieved evidence unit. (`evidence[]` item shape — confirm with SDK; see board rückfrage.) */
export interface EvidenceUnit {
  evidence_id: string
  document: string
  section?: string
  paragraph?: string
  snippet?: string
  url?: string
  regulation_code?: string // preferred key for family grouping (from /retrieve)
  context?: string // knowledge space / domain
}

/** Numbered [n] <-> evidence coupling, produced by the SDK (not parsed from the answer). */
export interface Citation {
  citation_id: string
  number?: number // 1-based marker number ([n])
  evidence_id: string
  document: string
  section?: string | null
  paragraph?: string | null
  footnote?: string | null
  figure?: string | null
}

/** C8 / visual evidence — `visual_type` generalizes beyond figures (flowchart/bpmn/state_machine/...). */
export interface VisualEvidence {
  visual_id: string
  visual_type: string
  caption?: string
  document: string
  context?: string
  image_ref?: string
  vision_summary?: string
}

export interface Footnote {
  footnote_id?: string
  ref?: string
  document?: string
  section?: string
  text?: string
}

export type AdvisorMode = 'clarify' | 'answer'

export interface AdvisorResponse {
  mode: AdvisorMode
  question: string
  clarity: ClarityInfo
  general_answer?: string | null // L1 (clarify mode)
  answer?: string | null // L2 (answer mode)
  scoped_query?: string | null
  evidence: EvidenceUnit[]
  citations: Citation[]
  visual_evidence: VisualEvidence[]
  footnotes: Footnote[]
}

export interface AdvisorRequest {
  question: string
  context?: string | null
}