lib/api-spec/openapi.yaml

openapi: 3.1.0
info:
  # Do not change the title, if the title changes, the import paths will be broken
  title: Api
  version: 0.1.0
  description: Io HST Search Engine API
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: search
    description: Io search synthesis
  - name: model
    description: Io neural model inference
  - name: feedback
    description: User feedback for evolutionary learning
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      description: Returns server health status
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /search:
    post:
      operationId: search
      tags: [search]
      summary: Search and synthesize
      description: Runs the HST search engine across 200+ sources and returns a synthesized answer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchInput"
      responses:
        "200":
          description: Synthesized search result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"
        "400":
          description: Bad request

  /model/generate:
    post:
      operationId: modelGenerate
      tags: [model]
      summary: Generate text from Io neural model
      description: Runs inference on the Io HST checkpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ModelInput"
      responses:
        "200":
          description: Generated text
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelResult"
        "503":
          description: Model not available

  /feedback:
    post:
      operationId: submitFeedback
      tags: [feedback]
      summary: Submit thumbs up/down for a search answer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedbackInput"
      responses:
        "200":
          description: Recorded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackResult"
        "400":
          description: Bad request

  /feedback/stats:
    get:
      operationId: feedbackStats
      tags: [feedback]
      summary: Aggregate feedback stats
      responses:
        "200":
          description: Stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackStats"

  /model/finetune:
    post:
      operationId: modelFineTune
      tags: [model]
      summary: Start light CPU fine-tuning of the Io checkpoint
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FineTuneInput"
      responses:
        "200":
          description: Started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FineTuneState"
        "400":
          description: Bad request

  /model/finetune/status:
    get:
      operationId: modelFineTuneStatus
      tags: [model]
      summary: Fine-tune status
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FineTuneState"

  /model/status:
    get:
      operationId: modelStatus
      tags: [model]
      summary: Model status
      responses:
        "200":
          description: Model status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelStatus"

components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
      required:
        - status

    SearchInput:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
        target:
          type: integer
          minimum: 1
          maximum: 12
          default: 6

    SearchResult:
      type: object
      required:
        - answer
        - sources
        - query
      properties:
        answer:
          type: string
        sources:
          type: array
          items:
            type: string
        topUrl:
          type: ["string", "null"]
        query:
          type: string
        intent:
          type: string
        selfReferential:
          type: boolean
        sourceCount:
          type: integer
        processingMs:
          type: integer

    ModelInput:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 1500
        maxTokens:
          type: integer
          minimum: 1
          maximum: 1024
          default: 200
        temperature:
          type: number
          minimum: 0.01
          maximum: 2.0
          default: 0.85
        topK:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        topP:
          type: number
          minimum: 0.01
          maximum: 1.0
          default: 0.95
        repetitionPenalty:
          type: number
          minimum: 1.0
          maximum: 2.0
          default: 1.15
        presencePenalty:
          type: number
          minimum: 0.0
          maximum: 2.0
          default: 0.0
        nSamples:
          type: integer
          minimum: 1
          maximum: 8
          default: 1

    ModelResult:
      type: object
      required:
        - text
        - step
      properties:
        text:
          type: string
        step:
          type: integer
        checkpoint:
          type: string
        coherenceScore:
          type: number
        bestOfN:
          type: integer
        bestScore:
          type: number
        error:
          type: ["string", "null"]

    FeedbackInput:
      type: object
      required:
        - query
        - rating
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
        rating:
          type: string
          enum: [up, down]
        sources:
          type: array
          items:
            type: string
        answer:
          type: string
          maxLength: 8000

    FeedbackResult:
      type: object
      required:
        - ok
        - ts
      properties:
        ok:
          type: boolean
        ts:
          type: integer

    FeedbackStats:
      type: object
      required:
        - totalFeedback
        - totalUp
        - totalDown
        - sources
      properties:
        totalFeedback:
          type: integer
        totalUp:
          type: integer
        totalDown:
          type: integer
        sources:
          type: array
          items:
            type: object
            required: [source, up, down, multiplier]
            properties:
              source:
                type: string
              up:
                type: integer
              down:
                type: integer
              multiplier:
                type: number

    FineTuneInput:
      type: object
      properties:
        steps:
          type: integer
          minimum: 1
          maximum: 200
          default: 30
        lr:
          type: number
          minimum: 0.0000001
          maximum: 0.001
          default: 0.00001
        seqLen:
          type: integer
          minimum: 64
          maximum: 1024
          default: 256

    FineTuneState:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [idle, running, success, failed]
        startedAt:
          type: ["integer", "null"]
        finishedAt:
          type: ["integer", "null"]
        steps:
          type: integer
        currentStep:
          type: integer
        loss:
          type: ["number", "null"]
        avgLoss:
          type: ["number", "null"]
        error:
          type: ["string", "null"]
        checkpointOut:
          type: ["string", "null"]
        activeCheckpoint:
          type: string
        fineTunedExists:
          type: boolean
        guideStats:
          type: object
          additionalProperties: true
        log:
          type: array
          items:
            type: object
            additionalProperties: true
        ok:
          type: boolean

    ModelStatus:
      type: object
      required:
        - available
        - message
      properties:
        available:
          type: boolean
        message:
          type: string
        step:
          type: ["integer", "null"]
        checkpoint:
          type: ["string", "null"]