> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Circuit For Analytics

> Submit a QASM circuit and persist core analytics for MCP workflows.

Use this tool when the caller has ``experiment_id`` plus ``circuit_qasm``
and needs a persisted circuit before running, compressing, transpiling, or
inspecting related jobs. The endpoint computes and stores core analytics
such as qubit count, depth, and gate counts, and it deduplicates by circuit
hash within the authenticated user and experiment scope.

The returned object is a ``ContextCircuitModel``, which represents a
persisted Haiqu circuit entity for MCP and API workflows rather than a raw
Qiskit ``QuantumCircuit`` instance. This Haiqu model carries stable IDs,
experiment ownership, stored analytics, and MCP context so later tools can
reference the circuit directly without serializing or passing around the
in-memory Qiskit circuit object itself.

When to Use:
    - Call this when a workflow starts from inline QASM and needs a stable
      ``circuit_id`` for later MCP tools.
    - Call this before ``run_circuits_on_qpu_or_simulator`` or
      ``compress_circuit_with_state_compression`` when the circuit is not
      already stored.

Large circuits:
    There is no practical size limit on ``circuit_qasm``; payloads of
    thousands of QASM lines (tens of KB) are normal. Submit the requested
    circuit exactly as generated -- never substitute a smaller instance
    because the payload looks large. Send the QASM once here and pass the
    returned ``circuit_id`` to every later transpilation, compression, or
    run call so the payload never needs to be re-sent.

Constraints:
    - ``experiment_id`` must refer to an accessible experiment owned by the
      authenticated caller.
    - Circuit deduplication is hash-based within the caller and experiment
      scope, so this route may return an existing circuit instead of
      creating a new row.

Notes:
    - The response is the full ``ContextCircuitModel`` object, not a
      lightweight acknowledgment wrapper.
    - For agent-facing output, surface ``id``, ``name``, and the key
      analytics fields instead of repeating the raw QASM payload.

Args:
    user: Authenticated user resolved from the API key.
    data: Circuit payload containing the parent experiment ID, QASM source,
        and optional MCP context text.
    db: Active database session.

Returns:
    The created or reused circuit object.

Raises:
    HTTPException: Raised with ``400`` when the QASM payload cannot be
        parsed, or ``404`` when the parent experiment is not available to
        the caller.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json post /ai/submit_circuit_for_analytics
openapi: 3.1.0
info:
  title: Haiqu API
  summary: Haiqu RESTful API service.
  description: Cloud service providing the access to Haiqu cloud runtime
  contact:
    name: Haiqu Inc.
    url: https://haiqu.ai/
    email: info@haiqu.ai
  version: 1.4.0
servers: []
security: []
paths:
  /ai/submit_circuit_for_analytics:
    post:
      summary: Submit Circuit For Analytics
      description: >-
        Submit a QASM circuit and persist core analytics for MCP workflows.


        Use this tool when the caller has ``experiment_id`` plus
        ``circuit_qasm``

        and needs a persisted circuit before running, compressing, transpiling,
        or

        inspecting related jobs. The endpoint computes and stores core analytics

        such as qubit count, depth, and gate counts, and it deduplicates by
        circuit

        hash within the authenticated user and experiment scope.


        The returned object is a ``ContextCircuitModel``, which represents a

        persisted Haiqu circuit entity for MCP and API workflows rather than a
        raw

        Qiskit ``QuantumCircuit`` instance. This Haiqu model carries stable IDs,

        experiment ownership, stored analytics, and MCP context so later tools
        can

        reference the circuit directly without serializing or passing around the

        in-memory Qiskit circuit object itself.


        When to Use:
            - Call this when a workflow starts from inline QASM and needs a stable
              ``circuit_id`` for later MCP tools.
            - Call this before ``run_circuits_on_qpu_or_simulator`` or
              ``compress_circuit_with_state_compression`` when the circuit is not
              already stored.

        Large circuits:
            There is no practical size limit on ``circuit_qasm``; payloads of
            thousands of QASM lines (tens of KB) are normal. Submit the requested
            circuit exactly as generated -- never substitute a smaller instance
            because the payload looks large. Send the QASM once here and pass the
            returned ``circuit_id`` to every later transpilation, compression, or
            run call so the payload never needs to be re-sent.

        Constraints:
            - ``experiment_id`` must refer to an accessible experiment owned by the
              authenticated caller.
            - Circuit deduplication is hash-based within the caller and experiment
              scope, so this route may return an existing circuit instead of
              creating a new row.

        Notes:
            - The response is the full ``ContextCircuitModel`` object, not a
              lightweight acknowledgment wrapper.
            - For agent-facing output, surface ``id``, ``name``, and the key
              analytics fields instead of repeating the raw QASM payload.

        Args:
            user: Authenticated user resolved from the API key.
            data: Circuit payload containing the parent experiment ID, QASM source,
                and optional MCP context text.
            db: Active database session.

        Returns:
            The created or reused circuit object.

        Raises:
            HTTPException: Raised with ``400`` when the QASM payload cannot be
                parsed, or ``404`` when the parent experiment is not available to
                the caller.
      operationId: submit_circuit_for_analytics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextCircuitSubmitModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextCircuitModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ContextCircuitSubmitModel:
      properties:
        experiment_id:
          type: string
          title: Experiment Id
        circuit_qasm:
          type: string
          title: Circuit Qasm
          description: Quantum circuit source in QASM 2.0 or 3.0 format.
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Optional plain-text circuit description.
        context:
          type: string
          title: Context
      type: object
      required:
        - experiment_id
        - circuit_qasm
        - name
        - context
      title: ContextCircuitSubmitModel
      description: |-
        Define payload for creating an MCP circuit from QASM.

        Attributes:
            experiment_id: Parent experiment identifier.
            circuit_qasm: Quantum circuit source in QASM format.
            name: circuit name.
            description: Optional circuit description.
            context: Agent-facing reason for creating the circuit.
      examples:
        - circuit_qasm: |-
            OPENQASM 3;
            qubit[2] q;
            h q[0];
            cx q[0], q[1];
          context: >-
            Persist this Bell-state circuit so it can be executed and compared
            after compression.
          description: Simple entangling circuit used for analytics and run tests.
          experiment_id: exp-123
          name: Bell state
    ContextCircuitModel:
      properties:
        id:
          type: string
          title: Id
        hash:
          type: string
          title: Hash
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          default: ''
        creation_date:
          type: string
          format: date-time
          title: Creation Date
        user_id:
          type: integer
          title: User Id
        experiment_id:
          type: string
          title: Experiment Id
        tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Tags
          default: ''
        status:
          $ref: '#/components/schemas/CircuitStatus'
        generated:
          type: boolean
          title: Generated
        parameters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameters
        analytics:
          anyOf:
            - $ref: '#/components/schemas/CircuitAnalyticsModel'
            - type: 'null'
        transpilation_target:
          anyOf:
            - type: string
            - type: 'null'
          title: Transpilation Target
        transpilation_options:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Transpilation Options
        transpiled_circuit_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Transpiled Circuit Ids
        compressed_circuit_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Compressed Circuit Ids
        job_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Job Ids
        context:
          type: string
          title: Context
      type: object
      required:
        - id
        - hash
        - name
        - creation_date
        - user_id
        - experiment_id
        - status
        - generated
        - context
      title: ContextCircuitModel
      description: |-
        Extend a stored circuit model with MCP context text.

        Attributes:
            context: ai summary describing the circuit role in the workflow.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CircuitStatus:
      type: string
      enum:
        - Submitted
        - Running analytics computation
        - Core metrics computation is done
        - Advanced metrics computation is done
        - Evolution computation is done
        - Done
        - Error
      title: CircuitStatus
      description: Class for circuit analytics calculation job status.
    CircuitAnalyticsModel:
      properties:
        qubits:
          type: integer
          title: Qubits
        num_qubits_active:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Qubits Active
        num_parameters:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Parameters
        depth:
          type: integer
          title: Depth
        depth_2q:
          type: integer
          title: Depth 2Q
        gates_1q:
          type: integer
          title: Gates 1Q
        gates_2q:
          type: integer
          title: Gates 2Q
        other_gates:
          anyOf:
            - type: integer
            - type: 'null'
          title: Other Gates
        gates_total:
          type: integer
          title: Gates Total
        other_ops:
          type: integer
          title: Other Ops
        instructions_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Instructions Total
        operations_counts:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Operations Counts
        gate_size_distribution:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gate Size Distribution
        gate_diversity:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gate Diversity
        gate_diversity_basis_gates:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gate Diversity Basis Gates
        gate_count_distribution:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Gate Count Distribution
        program_communication:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Program Communication
          default: N/A
        critical_depth:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Critical Depth
          default: N/A
        entanglement_ratio:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Entanglement Ratio
          default: N/A
        parallelism:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Parallelism
          default: N/A
        liveness_per_qubit:
          anyOf:
            - items: {}
              type: array
            - type: string
            - type: 'null'
          title: Liveness Per Qubit
          default: N/A
        liveness:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Liveness
          default: N/A
        correlation_matrix:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Correlation Matrix
        kl_divergence:
          anyOf:
            - type: number
            - type: string
            - type: 'null'
          title: Kl Divergence
          default: N/A
        circuit_normalized:
          anyOf:
            - type: string
            - type: 'null'
          title: Circuit Normalized
      type: object
      required:
        - qubits
        - depth
        - depth_2q
        - gates_1q
        - gates_2q
        - gates_total
        - other_ops
      title: CircuitAnalyticsModel
      description: Data model for circuit metrics.
    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
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

````