openapi: 3.1.0
info:
  title: Swifin Akoose (Swifin Edition) Public API
  version: 1.0.0
  description: |
    Machine-readable Akoose language tools on Swifin for Custom GPTs and translators.

    Language: Akoose (Bakossi, Cameroon), ISO 639-3 code `bss`.
    Orthography: Swifin Edition — basic Latin A–Z / a–z only (no IPA special letters or tone marks).
    Human hub: https://app.swifin.com/akoose
    Legacy path aliases: /api/public/ekoose/* (same handlers).

    Prefer lexicon / engine-dataset for headwords. Use translate for sentences when enabled.
    Prefer review_status native_verified|editorial_verified. Never treat engine_inferred as authoritative.
    Orthography spec: https://app.swifin.com/akoose/orthography
    Governance: https://app.swifin.com/akoose/governance
    Discovery: https://app.swifin.com/llms.txt
  contact:
    name: Swifin Akoose
    url: https://app.swifin.com/akoose
servers:
  - url: https://app.swifin.com
    description: Production Swifin app
  # Schema document itself (import this URL into Custom GPT Actions):
  # https://app.swifin.com/api/public/akoose/chatgpt-actions.openapi.yaml
  # Mirror: https://app.swifin.com/akoose/chatgpt-actions.openapi.yaml
paths:
  /api/public/akoose/lexicon:
    get:
      operationId: searchAkooseLexicon
      summary: Search the public Akoose lexicon
      description: |
        Returns merged Swifin Edition lexicon rows (English ↔ Akoose gloss).
        Optional `q` filters by substring on English or Akoose.
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
            maxLength: 200
          description: Case-insensitive substring filter on English or Akoose gloss
      responses:
        "200":
          description: Lexicon entries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LexiconResponse"
        "500":
          description: Server error

  /api/public/akoose/engine-dataset:
    get:
      operationId: getAkooseEngineDataset
      summary: Full language engine dataset (best for GPT knowledge / RAG)
      description: |
        Single JSON document with vocabulary/lexemes, optional phrase-bank metadata,
        and starter grammar rules. Prefer this for Custom GPT knowledge ingestion.
        Cache-Control public max-age=120 on the server.
      responses:
        "200":
          description: Engine dataset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EngineDatasetResponse"
        "500":
          description: Server error

  /api/public/akoose/orthography:
    get:
      operationId: getAkooseOrthographySpec
      summary: Swifin Akoose Orthography Standard (SAS 1.0)
      description: |
        Formal SAS 1.0 positioning, five rules, and Traditional ↔ Swifin mappings.
        Complements Cameroon General Alphabet orthography; does not obsolete it.
      responses:
        "200":
          description: SAS 1.0 public spec
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /api/public/akoose/transliterate:
    post:
      operationId: transliterateAkoose
      summary: Deterministic Traditional ⇄ Swifin Edition conversion
      description: |
        Software transliteration under SAS 1.0 — not an LLM.
        traditional-to-swifin is deterministic. swifin-to-traditional may return
        candidates when digraphs are ambiguous (e.g. ng = ŋ or n+g).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransliterateRequest"
      responses:
        "200":
          description: Transliteration result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransliterateResponse"
        "400":
          description: Invalid text or direction

  /api/public/akoose/translate:
    post:
      operationId: translateAkoose
      summary: Translate between English and Akoose (Swifin Edition)
      description: |
        On-demand translation via Swifin's public translator.
        Requires PUBLIC_AKOOSE_TRANSLATE_ENABLED (or legacy PUBLIC_EKOOSE_TRANSLATE_ENABLED)
        and OPENAI_API_KEY on the deployment. Rate-limited per client IP.
        Lexicon headwords are still preferred for single words when exact matches exist.
        Do not use this for orthography conversion — use transliterateAkoose instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TranslateRequest"
      responses:
        "200":
          description: Translation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranslateResponse"
        "400":
          description: Invalid text or direction
        "429":
          description: Rate limit exceeded
        "503":
          description: Translator disabled or not configured
        "502":
          description: Empty model output

components:
  schemas:
    LexiconEntry:
      type: object
      required:
        - en
        - bss
      properties:
        en:
          type: string
          description: English headword or short phrase
        bss:
          type: string
          description: Akoose gloss in Swifin Edition (A–Z preferred)
        pos:
          type: string
          description: Part of speech when known
        engine:
          type: object
          additionalProperties: true
          description: Optional phrase-bank / music / verification metadata

    LexiconResponse:
      type: object
      required:
        - ok
        - edition
        - count
        - entries
      properties:
        ok:
          type: boolean
        edition:
          type: string
          example: swifin
        count:
          type: integer
        entries:
          type: array
          items:
            $ref: "#/components/schemas/LexiconEntry"

    TransliterateRequest:
      type: object
      required:
        - text
        - direction
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 4000
        direction:
          type: string
          enum:
            - traditional-to-swifin
            - swifin-to-traditional

    TransliterateResponse:
      type: object
      required:
        - ok
        - sas_version
        - direction
        - input
        - output
        - candidates
        - ambiguous
      properties:
        ok:
          type: boolean
        edition:
          type: string
          example: swifin
        sas_version:
          type: string
          example: "1.0"
        direction:
          type: string
        input:
          type: string
        output:
          type: string
          description: Primary conversion result
        candidates:
          type: array
          items:
            type: string
          description: Reverse candidates when ambiguous
        ambiguous:
          type: boolean
        notes:
          type: array
          items:
            type: string

    EngineDatasetResponse:
      type: object
      required:
        - ok
        - edition
        - generatedAt
        - generated_at
        - dataset_version
        - orthography
        - lexemes
        - count
      properties:
        ok:
          type: boolean
        edition:
          type: string
          example: swifin
        generatedAt:
          type: string
          format: date-time
          description: Deprecated alias of generated_at (kept for older consumers)
        generated_at:
          type: string
          format: date-time
        dataset_version:
          type: string
          example: "1.1.0"
          description: Semver-ish schema/content contract for GPT/RAG consumers
        orthography:
          type: string
          enum:
            - swifin-edition
        language:
          type: object
          properties:
            name:
              type: string
            iso639_3:
              type: string
              example: bss
            homeland:
              type: string
            orthography_label:
              type: string
        trust:
          type: object
          description: Guidance for filtering authoritative glosses
          additionalProperties: true
        provenance_counts:
          type: object
          additionalProperties:
            type: integer
        layers:
          type: object
          additionalProperties:
            type: string
        grammar_rules:
          type: array
          items:
            type: object
            additionalProperties: true
        lexemes:
          type: array
          items:
            $ref: "#/components/schemas/EngineDatasetLexeme"
        count:
          type: integer

    EngineDatasetLexeme:
      type: object
      required:
        - english
        - akoose
      properties:
        english:
          type: string
        akoose:
          type: string
          description: Swifin Edition surface form
        bss:
          type: string
        bss_swifin:
          type: string
        pos:
          type: string
        type:
          type: string
        context:
          type: array
          items:
            type: string
        verified:
          type: boolean
        engine_inferred:
          type: boolean
          description: Heuristic metadata only — not native-verified
        lexicon_source:
          type: string
          enum:
            - swifin_seed
            - public_data_import
            - en_supplement
            - custom
        provenance:
          type: string
          enum:
            - reviewed_swifin
            - curated_seed
            - custom_lexicon
            - public_import
            - en_supplement_pending
            - unknown
        confidence:
          type: string
          enum:
            - high
            - medium
            - low
            - none
        orthography:
          type: string
          enum:
            - swifin-edition
        music:
          type: object
          additionalProperties: true
        example_en:
          type: string
        example_bss:
          type: string
        notes:
          type: string
    TranslateRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 4000
          description: Source text to translate
        direction:
          type: string
          enum:
            - en-to-bss
            - bss-to-en
          default: en-to-bss
          description: en-to-bss = English → Akoose; bss-to-en = Akoose → English

    TranslateResponse:
      type: object
      required:
        - ok
        - edition
        - direction
        - translated
      properties:
        ok:
          type: boolean
        edition:
          type: string
          example: swifin
        direction:
          type: string
          enum:
            - en-to-bss
            - bss-to-en
        translated:
          type: string
          description: Translation in Swifin Edition (A–Z) when direction is en-to-bss