mahastrategies-com GPU Heuristic Optimization API

openapi: 3.2.0
info:
  title: Maha Strategies MPS GPU Heuristic Optimization API
  version: '0.1'
  description: 'The Maha Provenance Standard (MPS) API runs claim-level provenance audits over prose. Every factual claim in a passage is excerpted, tagged (VERIFIED, SOURCED, BOUNDARY, ILLUSTRATIVE, UNVERIFIED), and returned with a rationale and a recommended action — so agents and editors can verify before they publish.


    ## Local bridge (CLI)


    Install the open-source local bridge and point Claude Code, Cursor, or any MCP client at it:


    ```sh

    npm install -g @mahastrategies/maha-mcp-bridge

    maha login # verify and store your credential

    maha serve # start the stdio MCP server

    ```


    Raw rows and credentials stay local; only locally-redacted context reaches the agent''s cloud model.


    ## Authentication


    Commercial endpoints use bearer credentials:


    ```

    Authorization: Bearer mhaic_your_credential_here

    ```


    Credentials are shown **exactly once** at purchase. Store them in a secret manager; never commit them, log them, or place them in URLs. Each credential is scoped to the MPS audit capability only — it cannot touch any other service. Lost credentials cannot be recovered, only replaced.


    The free preflight endpoint (`POST /api/audit`) needs no credential and is limited per visitor per day.


    ## The credit system


    Paid audits are prepaid. Each successful audit consumes one `mps_audit_invocation` credit; failed audits are refunded automatically in the same ledger.


    When a credential runs out of credits, the API responds with **`402 Payment Required`**:


    ```json

    {

    "error": { "code": "payment_required", "message": "This prepaid credential has no audit credits remaining." },

    "purchase": { "href": "/mps/audit-access", "checkoutEndpoint": "/api/mps-credits/checkout", "unit": "mps_audit_invocation" }

    }

    ```


    Treat `402` as a routine signal, not an error: follow `purchase.href` to buy another pack, or call the checkout endpoint programmatically. Balances live in an append-only double-entry ledger — every grant, consumption, refund, and manual correction is a permanent, hash-chained row.


    ## Idempotency and webhook resilience


    **Requests**: every audit takes a `clientRequestId` you choose (8–120 characters). Retrying with the same id and the same text returns the original result with `idempotentReplay: true` — never a duplicate charge. The same id with *different* text returns `409 Conflict`. Safe retry loop: keep the same id until you get a terminal status.


    **Payments**: Stripe webhooks are processed exactly once. Each event id is claimed atomically in the same database transaction that moves credits, so a redelivered webhook can never double-credit a balance — duplicates get `200 OK` with `"duplicate": true` and change nothing. A crash between claim and grant rolls both back together. You never need to reconcile double-grants; the ledger cannot express them.'
  contact:
    name: Maha Strategies
    url: https://www.mahastrategies.com/contact
servers:
- url: https://www.mahastrategies.com
tags:
- name: GPU Heuristic Optimization
  description: Bounded asynchronous QUBO/Ising optimization using the benchmarked bounded-bond tensor-network heuristic.
paths:
  /api/v1/jobs/tensor-network:
    post:
      tags:
      - GPU Heuristic Optimization
      operationId: createTensorNetworkJob
      summary: Create a bounded-bond tensor-network QUBO/Ising job
      description: Contracts the binary factor network in variable order and truncates the transfer frontier to the declared bond dimension. Exact enumeration is used only below the declared threshold; truncated results are heuristic and never claim optimality.
      security:
      - credential: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TensorNetworkJobRequest'
      responses:
        '200':
          description: Idempotent replay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TensorNetworkJob'
        '202':
          description: Job queued; poll the returned pollUrl.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TensorNetworkJob'
        '400':
          description: Invalid or unbenchmarked tensor-network configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: Insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Job queue unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
  /api/v1/jobs/{jobId}:
    get:
      tags:
      - GPU Heuristic Optimization
      operationId: getOptimizationJob
      summary: Poll an optimization job owned by the current API key
      security:
      - credential: []
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
          pattern: ^job_[a-f0-9]{32}$
      responses:
        '200':
          description: Credential-safe job state; submitted problem data is never echoed.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TensorNetworkJob'
                - $ref: '#/components/schemas/GeometricRegistrationJob'
        '400':
          description: Malformed job ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Job not found for this API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    QuboTerm:
      type: object
      required:
      - i
      - j
      - value
      additionalProperties: false
      properties:
        i:
          type: integer
          minimum: 0
          maximum: 255
        j:
          type: integer
          minimum: 0
          maximum: 255
        value:
          type: number
    TensorNetworkJob:
      type: object
      required:
      - jobId
      - kind
      - status
      - clientRequestId
      - inputHash
      - acceptedConfiguration
      - credits
      - result
      - methodBoundary
      properties:
        jobId:
          type: string
          pattern: ^job_[a-f0-9]{32}$
        kind:
          type: string
          const: tensor-network
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
        clientRequestId:
          type: string
        inputHash:
          type: string
          pattern: ^[a-f0-9]{64}$
        acceptedConfiguration:
          type: object
        credits:
          type: object
        result:
          type:
          - object
          - 'null'
        diagnostics:
          type:
          - object
          - 'null'
        error:
          type:
          - object
          - 'null'
        pollUrl:
          type: string
        quotedCredits:
          type: integer
        problemStored:
          type: boolean
          const: false
        methodBoundary:
          type: string
    GeometricRegistrationJob:
      type: object
      required:
      - jobId
      - kind
      - status
      - clientRequestId
      - inputHash
      - acceptedConfiguration
      - credits
      - result
      - methodBoundary
      properties:
        jobId:
          type: string
          pattern: ^job_[a-f0-9]{32}$
        kind:
          type: string
          const: geometric-registration
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
        clientRequestId:
          type: string
        inputHash:
          type: string
          pattern: ^[a-f0-9]{64}$
        acceptedConfiguration:
          type: object
        credits:
          type: object
        result:
          type:
          - object
          - 'null'
          description: Rotation matrix, translation vector, RMSE, maximum error, and determinant.
        diagnostics:
          type:
          - object
          - 'null'
        error:
          type:
          - object
          - 'null'
        pollUrl:
          type: string
        quotedCredits:
          type: integer
        problemStored:
          type: boolean
          const: false
        methodBoundary:
          type: string
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
    TensorNetworkJobRequest:
      type: object
      required:
      - clientRequestId
      - problem
      additionalProperties: false
      properties:
        clientRequestId:
          type: string
          minLength: 8
          maxLength: 120
        problem:
          type: object
          required:
          - formulation
          - size
          - terms
          additionalProperties: false
          properties:
            formulation:
              type: string
              enum:
              - qubo
              - ising
            size:
              type: integer
              minimum: 1
              maximum: 256
            terms:
              type: array
              minItems: 1
              maxItems: 32896
              items:
                $ref: '#/components/schemas/QuboTerm'
        solver:
          type: object
          additionalProperties: false
          properties:
            bondDimension:
              type: integer
              minimum: 2
              maximum: 4096
              default: 256
            exactThreshold:
              type: integer
              minimum: 0
              maximum: 18
              default: 18
        target:
          type: string
          const: gpu
          default: gpu
        timeoutSeconds:
          type: integer
          minimum: 1
          maximum: 600
          default: 120
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.