openapi: 3.1.0
info:
  title: IB-Link APIs
  version: "1.0.0"
  description: |
    OpenAPI specification that consolidates IB-Link's Documents API / Retriever API / Audio API.


tags:
  - name: Documents
    description: Document processing / embeddings / search
  - name: Retriever
    description: Vector/Hybrid search
  - name: Audio
    description: Speech transcription (OpenAI-compatible) / translation / status

paths:
  /documents/process:
    post:
      tags: [Documents]
      summary: Document processing (asynchronous)
      description: Creates an asynchronous ingestion job with embedding generation.
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DocumentProcessRequest'}
            examples:
              default:
                value:
                  files:
                    - "C:/documents/report.pdf"
                    - file_path: "C:/images/diagram.png"
                      enable_ocr: true
                  directories: ["C:/documents/project"]
                  d_app_id: "my-app-123"
                  project_id: "project-456"
                  chunk_size: 500
                  chunk_overlap: 50
                  enable_ocr: false
                  batch_processing: true
                  duplicate_strategy: skip
                  force_update: false
      responses:
        "202":
          description: Job created successfully
          content:
            application/json:
              schema: {$ref: '#/components/schemas/JobAccepted'}
        "400": {$ref: '#/components/responses/BadRequest'}
        "500": {$ref: '#/components/responses/ServerError'}

  /documents/status:
    post:
      tags: [Documents]
      summary: Processing status / queue / quotas / health check
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DocumentStatusRequest'}
            examples:
              processing:
                value:
                  status_type: processing
                  job_id: "my-app-123_project-456_job_20250129_143022"
                  include_files: true
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DocumentStatusResponse'}
        "400": {$ref: '#/components/responses/BadRequest'}

  /documents/search:
    post:
      tags: [Documents]
      summary: Semantic search
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DocumentSearchRequest'}
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DocumentSearchResponse'}

  /documents/extract:
    post:
      tags: [Documents]
      summary: Content extraction (no embedding generation)
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DocumentExtractRequest'}
      responses:
        "200":
          description: Extraction result
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DocumentExtractResponse'}

  /documents/list:
    post:
      tags: [Documents]
      summary: List documents/projects
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DocumentListRequest'}
      responses:
        "200":
          description: List
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DocumentListResponse'}

  /documents/delete:
    delete:
      tags: [Documents]
      summary: Document deletion
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DocumentDeleteRequest'}
      responses:
        "200":
          description: Deletion result
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DocumentDeleteResponse'}

  /documents/info:
    get:
      tags: [Documents]
      summary: API information
      servers: [{ url: http://localhost:8500/iblink/v1 }]
      responses:
        "200":
          description: Information
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DocumentsInfo'}

  /retriever:
    post:
      tags: [Retriever]
      summary: Vector/Hybrid search
      servers: [{ url: http://localhost:6500/iblink/v1 }]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/RetrieverRequest'}
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RetrieverResponse'}

  /retriever/health:
    get:
      tags: [Retriever]
      summary: Health check
      servers: [{ url: http://localhost:6500/iblink/v1 }]
      responses:
        "200":
          description: Health
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RetrieverHealth'}

  /retriever/info:
    get:
      tags: [Retriever]
      summary: API information
      servers: [{ url: http://localhost:6500/iblink/v1 }]
      responses:
        "200":
          description: Information
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RetrieverInfo'}

  /health:
    get:
      tags: [Audio]
      summary: Audio API health
      servers: [{ url: http://localhost:8000 }]
      responses:
        "200":
          description: Health
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AudioHealth'}

  /status:
    get:
      tags: [Audio]
      summary: Audio API status
      servers: [{ url: http://localhost:8000 }]
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AudioStatus'}

  /v1/audio/transcriptions:
    post:
      tags: [Audio]
      summary: Transcription (OpenAI-compatible)
      description: Send audio via multipart/form-data.
      servers: [{ url: http://localhost:8000 }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file (wav/mp3/m4a, etc.)
                model:
                  type: string
                  default: whisper-large-v3-turbo
                language:
                  type: string
                  description: e.g., "en" / "ja" / "auto"
                response_format:
                  type: string
                  enum: [json, text, srt, vtt, verbose_json]
                prompt:
                  type: string
                temperature:
                  type: number
                  format: float
                  minimum: 0
                  maximum: 1
      responses:
        "200":
          description: Transcription result
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AudioTranscriptVerbose'}
            text/plain:
              schema:
                type: string
        "400": {$ref: '#/components/responses/BadRequest'}

  /v1/audio/translations:
    post:
      tags: [Audio]
      summary: Speech translation (to English)
      servers: [{ url: http://localhost:8000 }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file: { type: string, format: binary }
                model: { type: string, default: whisper-large-v3-turbo }
                response_format:
                  type: string
                  enum: [json, text, srt, vtt, verbose_json]
      responses:
        "200":
          description: Translation result
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AudioTranscriptVerbose'}
            text/plain:
              schema: { type: string }

components:
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}

  schemas:
    # ---- Common ----
    Error:
      type: object
      properties:
        error:
          anyOf:
            - type: string
            - type: object
              properties:
                message: { type: string }
                type: { type: string }
                code: { type: string }
        message: { type: string }
        timestamp: { type: string, format: date-time }

    # ---- Documents ----
    DocumentProcessRequest:
      type: object
      properties:
        files:
          type: array
          items:
            anyOf:
              - type: string
              - type: object
                properties:
                  file_path: { type: string }
                  enable_ocr: { type: boolean }
        directories:
          type: array
          items: { type: string }
        d_app_id: { type: string }
        project_id: { type: string }
        chunk_size: { type: integer }
        chunk_overlap: { type: integer }
        enable_ocr: { type: boolean }
        batch_processing: { type: boolean }
        duplicate_strategy:
          type: string
          enum: [skip, update, add, sync]
        force_update: { type: boolean }
      required: [d_app_id, project_id]

    JobAccepted:
      type: object
      properties:
        job_id: { type: string }
        status: { type: string, enum: [queued, processing, completed, failed] }
        message: { type: string }
        status_url: { type: string }
        created_at: { type: string, format: date-time }

    DocumentStatusRequest:
      type: object
      properties:
        status_type:
          type: string
          enum: [processing, queue, quota, health, dependency, jobs]
        job_id: { type: string }
        include_files: { type: boolean }
        d_app_id: { type: string }
      required: [status_type]

    DocumentStatusResponse:
      type: object
      additionalProperties: true
      description: Dynamic depending on status type

    DocumentSearchRequest:
      type: object
      properties:
        query: { type: string }
        d_app_id: { type: string }
        project_id: { type: string }
        directories:
          type: array
          items: { type: string }
        limit: { type: integer, default: 10 }
        similarity_threshold: { type: number }
      required: [query]

    DocumentSearchHit:
      type: object
      properties:
        document_id: { type: string }
        content: { type: string }
        similarity_score: { type: number }
        file_name: { type: string }
        file_path: { type: string }
        page_range: { type: string }

    DocumentSearchResponse:
      type: object
      properties:
        query: { type: string }
        results:
          type: array
          items: { $ref: '#/components/schemas/DocumentSearchHit' }
        total_results: { type: integer }

    DocumentExtractRequest:
      type: object
      properties:
        files:
          type: array
          items:
            anyOf:
              - type: string
              - type: object
                properties:
                  file_path: { type: string }
                  enable_ocr: { type: boolean }
        d_app_id: { type: string }
        project_id: { type: string }
        include_metadata: { type: boolean }

    DocumentExtractItem:
      type: object
      properties:
        file_name: { type: string }
        content: { type: string }
        content_length: { type: integer }
        metadata:
          type: object
          additionalProperties: true

    DocumentExtractResponse:
      type: object
      properties:
        status: { type: string }
        extracted_files:
          type: array
          items: { $ref: '#/components/schemas/DocumentExtractItem' }

    DocumentListRequest:
      type: object
      properties:
        list_type:
          type: string
          enum: [documents, projects]
        d_app_id: { type: string }
        project_id: { type: string }
        file_extension: { type: string }

    DocumentListItem:
      type: object
      properties:
        document_id: { type: string }
        file_name: { type: string }
        file_size: { type: integer }
        created_at: { type: string, format: date-time }

    DocumentListResponse:
      type: object
      properties:
        documents:
          type: array
          items: { $ref: '#/components/schemas/DocumentListItem' }
        total_count: { type: integer }

    DocumentDeleteRequest:
      type: object
      properties:
        d_app_id: { type: string }
        project_id: { type: string }
        file_paths:
          type: array
          items: { type: string }
        delete_all: { type: boolean, default: false }
      required: [d_app_id]

    DocumentDeleteResponse:
      type: object
      properties:
        status: { type: string }
        deleted_count: { type: integer }
        message: { type: string }

    DocumentsInfo:
      type: object
      properties:
        service: { type: string }
        version: { type: string }
        description: { type: string }
        supported_file_types:
          type: array
          items: { type: string }
        database:
          type: object
          properties:
            provider: { type: string }

    # ---- Retriever ----
    RetrieverRequest:
      type: object
      properties:
        text: { type: string, description: "Search query" }
        d_app_id: { type: string }
        project_id: { type: string }
        limit: { type: integer, default: 10 }
        search_mode:
          type: string
          enum: [vector, hybrid, hybrid_rrf]
          default: vector
        files_directories:
          type: array
          items: { type: string }
        file_paths:
          type: array
          items: { type: string }
        documents_id:
          type: array
          items: { type: string }
        vector_weight: { type: number, default: 0.7 }
        text_weight: { type: number, default: 0.3 }
        rrf_k: { type: integer, default: 60 }
        enable_phrase_matching: { type: boolean, default: true }
      required: [text]

    RetrieverHitMetadata:
      type: object
      properties:
        source: { type: string }
        directory: { type: string }
        file_path: { type: string }
        chunk_index: { type: integer }
        page_range: { type: string }
        start_page: { type: integer }
        end_page: { type: integer }
        chunk_category: { type: string }
        document_id: { type: string }
        vector_score: { type: number }
        text_score: { type: number }
        text_rank: { type: number }

    RetrieverHit:
      type: object
      properties:
        id: { type: string }
        text: { type: string }
        score: { type: number }
        metadata: { $ref: '#/components/schemas/RetrieverHitMetadata' }

    RetrieverResponse:
      type: object
      properties:
        query: { type: string }
        d_app_id: { type: string }
        project_id: { type: string }
        total_results: { type: integer }
        total_unfiltered_results: { type: integer }
        filtered_directories:
          type: array
          items: { type: string }
        filtered_file_paths:
          type: array
          items: { type: string }
        results:
          type: array
          items: { $ref: '#/components/schemas/RetrieverHit' }

    RetrieverHealth:
      type: object
      properties:
        status: { type: string }
        timestamp: { type: string, format: date-time }
        service: { type: string }
        version: { type: string }
        port: { type: integer }
        dependencies:
          type: object
          additionalProperties: true

    RetrieverInfo:
      type: object
      additionalProperties: true

    # ---- Audio ----
    AudioHealth:
      type: object
      properties:
        status: { type: string }
        timestamp: { type: string, format: date-time }

    AudioStatus:
      type: object
      properties:
        status: { type: string }
        uptime: { type: integer }
        total_requests: { type: integer }
        active_connections: { type: integer }
        config:
          type: object
          properties:
            model: { type: string }
            npu_enabled: { type: boolean }
            target_runtime: { type: string }

    AudioTranscriptVerbose:
      type: object
      properties:
        task: { type: string }
        language: { type: string }
        duration: { type: number }
        text: { type: string }
        segments:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              seek: { type: integer }
              start: { type: number }
              end: { type: number }
              text: { type: string }
              tokens:
                type: array
                items: { type: integer }
              temperature: { type: number }
              avg_logprob: { type: number }
              compression_ratio: { type: number }
              no_speech_prob: { type: number }