Skip to content
Python
3.5 KB
Raw Blame
/** RCL v2 contract only. No route/capability is enabled by exporting these types. */
export type RetrievalIntent =
  | "artifact"
  | "fact"
  | "decision"
  | "timeline"
  | "resume";
export type RetrievalChannel =
  | "lexical"
  | "semantic"
  | "object"
  | "governed_semantic";
export type RetrievalLimit =
  | "count_budget"
  | "character_budget"
  | "timeout_budget"
  | "metadata_budget"
  | "candidate_budget"
  | "coverage_budget";

export interface ContextHintsV2 {
  task_text?: string;
  /** Relevance hints only, never evidence-read authorization. */
  already_seen_refs?: string[];
}
export interface ContextSearchRequestV2 {
  operation?: "search";
  query: string;
  kinds?: Array<"raw" | "memory">;
  raw_source_ids?: string[] | null;
  intent?: "auto" | RetrievalIntent;
  context_hints?: ContextHintsV2;
  enhancement?: "local" | "auto";
  limit?: number;
  character_budget?: number;
  timeout_ms?: number;
}
export interface ContextExpandRequestV2 {
  operation: "expand";
  expand_ref: string;
  character_budget?: number;
  message_limit?: number;
  timeout_ms?: number;
}
export type ContextRequestV2 = ContextSearchRequestV2 | ContextExpandRequestV2;

export interface RetrievalTimeRange {
  start: string;
  end: string;
}
/** Unicode code-point offsets, not JavaScript UTF-16 string indices. */
export interface EvidenceSpanV2 {
  start_cp: number;
  end_cp: number;
  text: string;
}
export interface RawEvidenceV2 {
  kind: "raw";
  evidence_id: string;
  revision: number;
  source_id: string;
  conversation_id: string;
  role: string;
  written_by: "person" | "agent" | "tool" | "unknown";
  event_time: string | null;
  spans: EvidenceSpanV2[];
  matched_by: Array<"lexical" | "semantic" | "object">;
  expand_ref: string | null;
}
export interface GovernedEvidenceV2 {
  kind: "memory";
  memory_id: string;
  revision: number;
  content: string;
  memory_kind: string;
  updated_at: string;
  evidence_ids: string[];
  matched_by: Array<"lexical" | "governed_semantic">;
}
export type EvidenceItemV2 = RawEvidenceV2 | GovernedEvidenceV2;
export interface ObjectReferenceV2 {
  kind: "url" | "path" | "explicit_id";
  evidence_id: string;
  revision: number;
  span: EvidenceSpanV2;
}
export interface EvidenceGroupV2 {
  group_id: string;
  answer_target: RetrievalIntent;
  object_refs: ObjectReferenceV2[];
  decision_status:
    | "supported"
    | "ambiguous"
    | "missing_confirmation"
    | "conflicting"
    | "coverage_limited";
  missing_requirements: string[];
  items: EvidenceItemV2[];
}
export interface RetrievalPathV2 {
  status:
    | "ok"
    | "empty"
    | "not_requested"
    | "not_authorized"
    | "unavailable"
    | "degraded";
  reason: string | null;
  returned_count: number;
  searched_channels: RetrievalChannel[];
  coverage: "complete" | "partial" | "not_searched" | "unavailable";
  truncated_by: RetrievalLimit[];
}
export interface RetrievalResponseV2 {
  schema_version: 2;
  request_id: string;
  state: "grounded" | "empty" | "partial" | "unavailable";
  paths: { raw: RetrievalPathV2; memory: RetrievalPathV2 };
  plan: {
    intent: RetrievalIntent;
    interpreted_time_range: RetrievalTimeRange | null;
    time_origin: "none" | "explicit" | "rule" | "model";
    unresolved_constraints: string[];
  };
  groups: EvidenceGroupV2[];
  enhancement: {
    attempted: boolean;
    used: boolean;
    reason: string | null;
    model_profile_revision: number | null;
    usage_state: "not_attempted" | "known" | "unknown";
  };
  budget: { used_characters: number; total_ms: number; truncated: boolean };
  adoption: "unknown";
}