openapi: 3.1.0
info:
  title: bijux-vex execution API
  version: v1
paths:
  /capabilities:
    get:
      summary: Capabilities
      operationId: capabilities_capabilities_get
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendCapabilitiesReport'
              examples:
                capabilities:
                  value:
                    backend: sqlite
                    contracts:
                    - deterministic
                    - non_deterministic
                    deterministic_query: true
                    supports_ann: false
                    replayable: true
                    metrics:
                    - l2
                    - cosine
                    max_vector_size: 4096
                    isolation_level: read_committed
                    execution_modes:
                    - strict
                    - bounded
                    - exploratory
                    ann_status: unavailable
                    storage_backends: []
                    vector_stores: []
                    plugins: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /artifacts:
    get:
      summary: List Artifacts
      operationId: list_artifacts_artifacts_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Artifacts Artifacts Get
              examples:
                artifacts:
                  value:
                    artifacts:
                    - art-1
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /runs:
    get:
      summary: List Runs
      operationId: list_runs_runs_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Runs Runs Get
              examples:
                runs:
                  value:
                    runs:
                    - run-1
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /create:
    post:
      summary: Create
      operationId: create_create_post
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequest'
            examples:
              create:
                value:
                  name: my-corpus
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Create Post
              examples:
                created:
                  value:
                    name: my-corpus
                    status: created
        '400':
          content:
            application/json:
              examples:
                refusal:
                  value:
                    error:
                      reason: determinism_violation
                      message: '[INV-000] Deterministic execution requires a deterministic
                        vector store'
                      remediation: Use deterministic inputs or switch to non_deterministic
                        contract with declared randomness.
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ingest:
    post:
      summary: Ingest
      operationId: ingest_ingest_post
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestRequest'
            examples:
              ingest:
                value:
                  documents:
                  - hello
                  vectors:
                  - - 0.0
                    - 1.0
                    - 0.0
                  vector_store: faiss
                  vector_store_uri: index.faiss
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Ingest Ingest Post
              examples:
                ingested:
                  value:
                    ingested: 1
        '400':
          content:
            application/json:
              examples:
                refusal:
                  value:
                    error:
                      reason: determinism_violation
                      message: '[INV-000] Deterministic execution requires a deterministic
                        vector store'
                      remediation: Use deterministic inputs or switch to non_deterministic
                        contract with declared randomness.
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /artifact:
    post:
      summary: Artifact
      operationId: artifact_artifact_post
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionArtifactRequest'
            examples:
              artifact:
                value:
                  execution_contract: deterministic
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Artifact Artifact Post
              examples:
                artifact:
                  value:
                    artifact_id: art-1
                    execution_contract: deterministic
                    execution_contract_status: stable
                    replayable: true
        '400':
          content:
            application/json:
              examples:
                refusal:
                  value:
                    error:
                      reason: determinism_violation
                      message: '[INV-000] Deterministic execution requires a deterministic
                        vector store'
                      remediation: Use deterministic inputs or switch to non_deterministic
                        contract with declared randomness.
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /execute:
    post:
      summary: Execute
      operationId: execute_execute_post
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionRequestPayload'
            examples:
              execute:
                value:
                  artifact_id: art-1
                  vector:
                  - 0.0
                  - 1.0
                  - 0.0
                  top_k: 3
                  execution_contract: deterministic
                  execution_intent: exact_validation
                  execution_mode: strict
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Execute Execute Post
              examples:
                execute:
                  value:
                    results:
                    - vec-1
                    correlation_id: req-1
                    execution_contract: deterministic
                    execution_contract_status: stable
                    replayable: true
                    execution_id: exec-1
        '422':
          content:
            application/json:
              examples:
                refusal:
                  value:
                    error:
                      reason: determinism_violation
                      message: '[INV-000] Deterministic execution requires a deterministic
                        vector store'
                      remediation: Use deterministic inputs or switch to non_deterministic
                        contract with declared randomness.
          description: Unprocessable Entity
  /explain:
    post:
      summary: Explain
      operationId: explain_explain_post
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExplainRequest'
            examples:
              explain:
                value:
                  result_id: res-1
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Explain Explain Post
              examples:
                explain:
                  value:
                    result_id: res-1
        '400':
          content:
            application/json:
              examples:
                refusal:
                  value:
                    error:
                      reason: determinism_violation
                      message: '[INV-000] Deterministic execution requires a deterministic
                        vector store'
                      remediation: Use deterministic inputs or switch to non_deterministic
                        contract with declared randomness.
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /replay:
    post:
      summary: Replay
      operationId: replay_replay_post
      parameters:
      - name: X-Correlation-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Correlation-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionRequestPayload'
            examples:
              replay:
                value:
                  artifact_id: art-1
                  request_text: hello
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Replay Replay Post
              examples:
                replay:
                  value:
                    matches: true
        '400':
          content:
            application/json:
              examples:
                refusal:
                  value:
                    error:
                      reason: determinism_violation
                      message: '[INV-000] Deterministic execution requires a deterministic
                        vector store'
                      remediation: Use deterministic inputs or switch to non_deterministic
                        contract with declared randomness.
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BackendCapabilitiesReport:
      properties:
        backend:
          type: string
          title: Backend
        contracts:
          items:
            type: string
          type: array
          title: Contracts
        deterministic_query:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Deterministic Query
        supports_ann:
          type: boolean
          title: Supports Ann
        replayable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Replayable
        metrics:
          items:
            type: string
          type: array
          title: Metrics
        max_vector_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Vector Size
        isolation_level:
          anyOf:
          - type: string
          - type: 'null'
          title: Isolation Level
        execution_modes:
          items:
            type: string
          type: array
          title: Execution Modes
        ann_status:
          type: string
          title: Ann Status
        storage_backends:
          items:
            $ref: '#/components/schemas/StorageBackendDescriptor'
          type: array
          title: Storage Backends
        vector_stores:
          items:
            $ref: '#/components/schemas/VectorStoreDescriptor'
          type: array
          title: Vector Stores
        plugins:
          additionalProperties:
            items:
              additionalProperties: true
              type: object
            type: array
          type: object
          title: Plugins
      additionalProperties: false
      type: object
      required:
      - backend
      - contracts
      - deterministic_query
      - supports_ann
      - replayable
      - metrics
      - max_vector_size
      - isolation_level
      - execution_modes
      - ann_status
      - storage_backends
      - vector_stores
      - plugins
      title: BackendCapabilitiesReport
    CreateRequest:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
      additionalProperties: false
      type: object
      required:
      - name
      title: CreateRequest
    ExecutionArtifactRequest:
      properties:
        execution_contract:
          $ref: '#/components/schemas/ExecutionContract'
        vector_store:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Store
        vector_store_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Store Uri
        vector_store_options:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Vector Store Options
      additionalProperties: false
      type: object
      required:
      - execution_contract
      title: ExecutionArtifactRequest
    ExecutionBudgetPayload:
      properties:
        max_latency_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Latency Ms
        max_memory_mb:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Memory Mb
        max_error:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Error
      additionalProperties: false
      type: object
      title: ExecutionBudgetPayload
    ExecutionContract:
      type: string
      enum:
      - deterministic
      - non_deterministic
      title: ExecutionContract
    ExecutionIntent:
      type: string
      enum:
      - exact_validation
      - reproducible_research
      - exploratory_search
      - production_retrieval
      title: ExecutionIntent
    ExecutionMode:
      type: string
      enum:
      - strict
      - bounded
      - exploratory
      title: ExecutionMode
    ExecutionRequestPayload:
      properties:
        artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifact Id
        request_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Text
        vector:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Vector
        top_k:
          type: integer
          exclusiveMinimum: 0.0
          title: Top K
          default: 5
        execution_contract:
          $ref: '#/components/schemas/ExecutionContract'
        execution_intent:
          $ref: '#/components/schemas/ExecutionIntent'
        execution_mode:
          $ref: '#/components/schemas/ExecutionMode'
          default: strict
        execution_budget:
          anyOf:
          - $ref: '#/components/schemas/ExecutionBudgetPayload'
          - type: 'null'
        randomness_profile:
          anyOf:
          - $ref: '#/components/schemas/RandomnessProfilePayload'
          - type: 'null'
        correlation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Correlation Id
        vector_store:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Store
        vector_store_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Store Uri
        vector_store_options:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Vector Store Options
      additionalProperties: false
      type: object
      required:
      - execution_contract
      - execution_intent
      title: ExecutionRequestPayload
    ExplainRequest:
      properties:
        result_id:
          type: string
          minLength: 1
          title: Result Id
        artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifact Id
      additionalProperties: false
      type: object
      required:
      - result_id
      title: ExplainRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IngestRequest:
      properties:
        documents:
          items:
            type: string
          type: array
          title: Documents
        vectors:
          anyOf:
          - items:
              items:
                type: number
              type: array
            type: array
          - type: 'null'
          title: Vectors
        embed_provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Embed Provider
        embed_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Embed Model
        cache_embeddings:
          anyOf:
          - type: string
          - type: 'null'
          title: Cache Embeddings
        correlation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Correlation Id
        idempotency_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency Key
        vector_store:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Store
        vector_store_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Vector Store Uri
        vector_store_options:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Vector Store Options
      additionalProperties: false
      type: object
      required:
      - documents
      title: IngestRequest
    RandomnessProfilePayload:
      properties:
        seed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seed
        sources:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Sources
        bounded:
          type: boolean
          title: Bounded
          default: false
      additionalProperties: false
      type: object
      title: RandomnessProfilePayload
    StorageBackendDescriptor:
      properties:
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        persistence:
          anyOf:
          - type: string
          - type: 'null'
          title: Persistence
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      additionalProperties: false
      type: object
      required:
      - name
      - status
      title: StorageBackendDescriptor
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VectorStoreDescriptor:
      properties:
        name:
          type: string
          title: Name
        available:
          type: boolean
          title: Available
        supports_exact:
          type: boolean
          title: Supports Exact
        supports_ann:
          type: boolean
          title: Supports Ann
        delete_supported:
          type: boolean
          title: Delete Supported
        filtering_supported:
          type: boolean
          title: Filtering Supported
        deterministic_exact:
          type: boolean
          title: Deterministic Exact
        experimental:
          type: boolean
          title: Experimental
        consistency:
          anyOf:
          - type: string
          - type: 'null'
          title: Consistency
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      additionalProperties: false
      type: object
      required:
      - name
      - available
      - supports_exact
      - supports_ann
      - delete_supported
      - filtering_supported
      - deterministic_exact
      - experimental
      title: VectorStoreDescriptor