Kagura AI Bm25 Drift API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Bm25 Drift API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: bm25-drift
  description: 'Admin: BM25 IDF drift observability (Issue #343). Cron is disabled by default and scheduled for production enablement in v0.14.0 alongside Privacy Policy (#359) and right-to-erasure (#360).'
paths:
  /api/v1/admin/bm25-drift:
    get:
      tags:
      - bm25-drift
      summary: List Drift Logs
      description: 'List BM25 IDF drift log rows. Admin-only.


        Sorted by measured_at DESC. Filterable by psi_status and context_id.'
      operationId: list_drift_logs_api_v1_admin_bm25_drift_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: context_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Context Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bm25DriftListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/bm25-drift/{row_id}:
    get:
      tags:
      - bm25-drift
      summary: Get Drift Log Detail
      description: 'Detail view including top_divergent_terms. Admin-only.


        Emits an audit log event on every read so historical access is

        reconstructable from logs alone.'
      operationId: get_drift_log_detail_api_v1_admin_bm25_drift__row_id__get
      parameters:
      - name: row_id
        in: path
        required: true
        schema:
          type: integer
          title: Row Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bm25DriftDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/bm25-drift/run:
    post:
      tags:
      - bm25-drift
      summary: Run Drift Now
      description: 'Manually trigger a drift measurement. Admin-only.


        For dev/staging verification while the production cron is disabled

        (v0.12.1 ships infrastructure-only; production enablement = v0.14.0).

        Each requested context is enqueued as an `asyncio.create_task` and

        runs against an independent DB session.'
      operationId: run_drift_now_api_v1_admin_bm25_drift_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bm25DriftRunRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bm25DriftRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/bm25-drift/{row_id}/reveal-terms:
    post:
      tags:
      - bm25-drift
      summary: Reveal Drift Terms
      description: 'Resolve mmh3-hashed term indices in top_divergent_terms to plaintext.


        Reads pre-tokenized fields from the Qdrant payload (see

        QDRANT_TOKEN_PAYLOAD_FIELDS) populated by memory_service, recomputes

        mmh3 hashes via utils.sparse_vector.hash_token, and matches against

        the stored indices. Falls back to re-tokenizing summary text only

        for legacy points written before the token payload fields existed.

        Streams Qdrant pages and breaks as soon as every requested hash is

        resolved, so memory stays bounded for million-point contexts.

        Rate-limited per user. Every terminal branch (success / 404 /

        rate-limited) writes an AuditLog row; term content is never logged.'
      operationId: reveal_drift_terms_api_v1_admin_bm25_drift__row_id__reveal_terms_post
      parameters:
      - name: row_id
        in: path
        required: true
        schema:
          type: integer
          title: Row Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bm25DriftRevealRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bm25DriftRevealResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Bm25DriftRunRequest:
      properties:
        context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Context Id
      type: object
      title: Bm25DriftRunRequest
      description: "Body for POST /admin/bm25-drift/run.\n\nAttributes:\n    context_id: Target context. When null, runs against every active\n        context (matches the cron behaviour). For dev/staging\n        verification — production cron remains disabled until v0.14.0."
    Bm25DriftRevealRequest:
      properties:
        reason:
          type: string
          minLength: 10
          title: Reason
          description: Justification for viewing plaintext terms (audit-logged)
      type: object
      required:
      - reason
      title: Bm25DriftRevealRequest
      description: Body for POST /admin/bm25-drift/{row_id}/reveal-terms.
    Bm25DriftRunResponse:
      properties:
        scheduled_context_count:
          type: integer
          title: Scheduled Context Count
      type: object
      required:
      - scheduled_context_count
      title: Bm25DriftRunResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Bm25DriftDetailResponse:
      properties:
        row:
          $ref: '#/components/schemas/Bm25DriftDetail'
      type: object
      required:
      - row
      title: Bm25DriftDetailResponse
    Bm25DriftDetail:
      properties:
        id:
          title: Id
        context_id:
          title: Context Id
        context_name:
          title: Context Name
        measured_at:
          title: Measured At
        psi:
          title: Psi
        psi_status:
          title: Psi Status
        m_memory_points:
          title: M Memory Points
        r_resource_points:
          title: R Resource Points
        num_terms:
          title: Num Terms
        context_deleted:
          title: Context Deleted
        top_divergent_terms:
          title: Top Divergent Terms
      type: object
      required:
      - id
      - context_id
      - measured_at
      - psi
      - psi_status
      - m_memory_points
      - r_resource_points
      - num_terms
      title: Bm25DriftDetail
      description: Drift log row, detail-view shape (includes top_divergent_terms).
    Bm25DriftSummary:
      properties:
        id:
          title: Id
        context_id:
          title: Context Id
        context_name:
          title: Context Name
        measured_at:
          title: Measured At
        psi:
          title: Psi
        psi_status:
          title: Psi Status
        m_memory_points:
          title: M Memory Points
        r_resource_points:
          title: R Resource Points
        num_terms:
          title: Num Terms
      type: object
      required:
      - id
      - context_id
      - measured_at
      - psi
      - psi_status
      - m_memory_points
      - r_resource_points
      - num_terms
      title: Bm25DriftSummary
      description: Drift log row, list-view shape (no top_divergent_terms).
    Bm25DriftRevealResponse:
      properties:
        id:
          title: Id
        context_id:
          title: Context Id
        context_name:
          title: Context Name
        measured_at:
          title: Measured At
        psi:
          title: Psi
        psi_status:
          title: Psi Status
        m_memory_points:
          title: M Memory Points
        r_resource_points:
          title: R Resource Points
        num_terms:
          title: Num Terms
        context_deleted:
          title: Context Deleted
        top_divergent_terms:
          title: Top Divergent Terms
        resolved_terms:
          title: Resolved Terms
      type: object
      required:
      - id
      - context_id
      - measured_at
      - psi
      - psi_status
      - m_memory_points
      - r_resource_points
      - num_terms
      - resolved_terms
      title: Bm25DriftRevealResponse
      description: Drift detail + resolved plaintext terms.
    Bm25DriftListResponse:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/Bm25DriftSummary'
          type: array
          title: Rows
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - rows
      - total
      - limit
      - offset
      title: Bm25DriftListResponse