lcbp3/specs/200-fullstacks/232-typhoon-ocr-integration/contracts/api-contracts.md

API Contracts: Typhoon OCR Integration

Feature: 232-typhoon-ocr-integration Date: 2026-05-30 Phase: Phase 1 - Design & Contracts

OCR Engine Selection API

GET /api/ocr-engines

Description: List available OCR engines with their status and parameters

Permission: system.manage_all required

Response:

{
  "data": [
    {
      "id": "019505a1-7c3e-7000-8000-abc123def456",
      "engineName": "Tesseract",
      "engineType": "tesseract",
      "isActive": true,
      "vramRequirementMB": 0,
      "processingTimeLimitSeconds": 30,
      "concurrentLimit": 5,
      "fallbackEngineId": null
    },
    {
      "id": "019505a1-7c3e-7000-8000-xyz789uvw012",
      "engineName": "Typhoon OCR-3B",
      "engineType": "typhoon_ocr",
      "isActive": true,
      "vramRequirementMB": 3500,
      "processingTimeLimitSeconds": 60,
      "concurrentLimit": 1,
      "fallbackEngineId": "019505a1-7c3e-7000-8000-abc123def456"
    }
  ]
}

POST /api/ocr-engines/:engineId/select

Description: Select OCR engine for document processing

Permission: system.manage_all required

Request Body:

{
  "documentPublicId": "019505a1-7c3e-7000-8000-doc123uuid456"
}

Response:

{
  "data": {
    "engineId": "019505a1-7c3e-7000-8000-xyz789uvw012",
    "engineName": "Typhoon OCR-3B",
    "documentPublicId": "019505a1-7c3e-7000-8000-doc123uuid456",
    "status": "processing",
    "estimatedTimeSeconds": 60
  }
}

Error Responses:

• 403 Forbidden: User lacks system.manage_all permission
• 404 Not Found: Engine or document not found
• 503 Service Unavailable: Ollama service unavailable, fallback to Tesseract

AI Model Management API

GET /api/ai-models

Description: List available AI models with their status and parameters

Permission: system.manage_all required

Response:

{
  "data": [
    {
      "id": "019505a1-7c3e-7000-8000-model1uuid",
      "modelName": "gemma4:e4b",
      "modelType": "llm",
      "ollamaModelName": "gemma4:e4b",
      "vramRequirementMB": 4500,
      "isActive": true,
      "useCases": ["document_analysis", "rag"],
      "quantization": "Q8_0"
    },
    {
      "id": "019505a1-7c3e-7000-8000-model2uuid",
      "modelName": "typhoon2.1-gemma3-4b",
      "modelType": "llm",
      "ollamaModelName": "typhoon2.1-gemma3-4b",
      "vramRequirementMB": 4500,
      "isActive": true,
      "useCases": ["document_analysis", "ocr_extraction"],
      "quantization": "Q4_0"
    }
  ]
}

POST /api/ai-models

Description: Add new AI model configuration

Permission: system.manage_all required

Request Body:

{
  "modelName": "typhoon2.1-gemma3-4b",
  "modelType": "llm",
  "ollamaModelName": "typhoon2.1-gemma3-4b",
  "vramRequirementMB": 4500,
  "useCases": ["document_analysis", "ocr_extraction"],
  "quantization": "Q4_0"
}

Response:

{
  "data": {
    "id": "019505a1-7c3e-7000-8000-model2uuid",
    "modelName": "typhoon2.1-gemma3-4b",
    "modelType": "llm",
    "ollamaModelName": "typhoon2.1-gemma3-4b",
    "vramRequirementMB": 4500,
    "isActive": true,
    "useCases": ["document_analysis", "ocr_extraction"],
    "quantization": "Q4_0",
    "createdAt": "2026-05-30T12:00:00Z"
  }
}

Error Responses:

• 403 Forbidden: User lacks system.manage_all permission
• 400 Bad Request: Invalid model parameters or VRAM would exceed limit
• 503 Service Unavailable: Ollama service unavailable

PATCH /api/ai-models/:modelId/activate

Description: Activate or deactivate AI model

Permission: system.manage_all required

Request Body:

{
  "isActive": true
}

Response:

{
  "data": {
    "id": "019505a1-7c3e-7000-8000-model2uuid",
    "isActive": true,
    "updatedAt": "2026-05-30T12:00:00Z"
  }
}

VRAM Monitoring API

GET /api/ai/vram/status

Description: Get current VRAM usage and loaded models

Permission: system.manage_all required

Response:

{
  "data": {
    "totalVRAMMB": 8192,
    "usedVRAMMB": 4500,
    "usagePercent": 55,
    "thresholdPercent": 90,
    "loadedModels": [
      {
        "modelId": "019505a1-7c3e-7000-8000-model1uuid",
        "modelName": "gemma4:e4b",
        "vramUsageMB": 4500
      }
    ],
    "canLoadModel": true,
    "lastUpdated": "2026-05-30T12:00:00Z"
  }
}

OCR Processing API (Extended)

POST /api/ocr/process

Description: Process document with selected OCR engine

Permission: system.manage_all required

Request Body:

{
  "documentPublicId": "019505a1-7c3e-7000-8000-doc123uuid456",
  "engineId": "019505a1-7c3e-7000-8000-xyz789uvw012",
  "useCache": true
}

Response:

{
  "data": {
    "documentPublicId": "019505a1-7c3e-7000-8000-doc123uuid456",
    "engineId": "019505a1-7c3e-7000-8000-xyz789uvw012",
    "engineName": "Typhoon OCR-3B",
    "status": "completed",
    "text": "Extracted text content...",
    "processingTimeSeconds": 45,
    "cacheHit": false,
    "fallbackUsed": false,
    "confidence": 0.95
  }
}

Error Responses:

• 403 Forbidden: User lacks system.manage_all permission
• 404 Not Found: Document or engine not found
• 503 Service Unavailable: Ollama service unavailable, fallback to Tesseract
• 504 Gateway Timeout: Processing exceeded time limit

Common Response Patterns

Success Response

{
  "data": { ... }
}

Error Response

{
  "error": {
    "message": "User-friendly error message",
    "userMessage": "เกิดข้อผิดพลาดในการประมวลผล OCR",
    "recoveryAction": "กรุณาลองใหม่หรือติดต่อผู้ดูแลระบบ",
    "errorCode": "OCR_PROCESSING_FAILED",
    "statusCode": 503
  }
}

Rate Limiting

All AI-related endpoints are protected by ThrottlerGuard per ADR-016:

• OCR endpoints: 10 requests per minute
• AI Model Management: 5 requests per minute
• VRAM Monitoring: 20 requests per minute

Idempotency

All POST/PUT/PATCH endpoints require Idempotency-Key header per ADR-016:

Idempotency-Key: <UUID>