generated: '2026-07-20'
method: derived
source: openapi/nace-ai-ndi-openapi.json
api: NDI Service
description: >-
  Entity graph derived from the NDI OpenAPI schemas. NDI is a stateless
  document-intelligence API: a staged File is processed by a Job (parse/ground/
  categorize/extract) whose typed Result is discriminated by result_type.
id_conventions:
  file_id: UUID; referenced as source_url "ndi://file/<uuid>"
  job_id: UUID
  idempotency_key: caller-supplied string, max 128 chars
entities:
- name: File
  schema: UploadResponse
  key: file_id
  fields: [file_id, file_name, expires_at]
  notes: Staged via POST /upload; reusable across parse/categorize/ground/extract.
- name: Job
  schema: JobStatus
  key: job_id
  fields: [job_id, action, status, result, error, created_at, started_at, completed_at]
  status_enum: [pending, running, succeeded, failed]
  action_enum: [parse, ground, categorize, extract]
- name: JobSummary
  schema: JobSummary
  key: job_id
  notes: Light row in JobList (no result payloads).
- name: ParseResult
  schema: ParseResult
  discriminator: result_type=parse
  produces: [ParsedFile, ParsedTable, ParsedSheet]
- name: GroundResult
  schema: GroundResult
  discriminator: result_type=ground
  produces: [GroundItemResult, VisualRegionMatch, TextRangeMatch, SpreadsheetRangeMatch, AudioRangeMatch, JsonlRecordMatch]
- name: CategorizeResult
  schema: CategorizeResult
  discriminator: result_type=categorize
  produces: [CategorizedSegment, CategorizedSheet]
- name: ExtractResult
  schema: ExtractResult
  discriminator: result_type=extract
  produces: [structured JSON matching caller schema]
- name: Taxonomy
  schema: Taxonomy
  fields: [categories]
  notes: Optional category vocabulary supplied to categorize.
relationships:
- from: Job
  to: File
  type: belongs_to
  via: request.file.source_url (ndi://file/<file_id>)
- from: Job
  to: JobStatus
  type: has_one
  via: result (populated when status=succeeded; discriminated by result_type)
- from: Job
  to: JobError
  type: has_one
  via: error (populated when status=failed)
- from: JobList
  to: JobSummary
  type: has_many
  via: jobs[]
- from: GroundResult
  to: GroundItemResult
  type: has_many
  via: results[]
- from: GroundItemResult
  to: Match
  type: has_many
  via: matches[] (oneOf visual_region|text_range|spreadsheet_range|audio_range|jsonl_record)
- from: CategorizeResult
  to: CategorizedSegment
  type: has_many
  via: items[] (oneOf document_segment|sheet)
- from: CategorizeJobRequest
  to: Taxonomy
  type: has_one
  via: taxonomy (optional; defaults to NDI taxonomy)