> ## 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.

# AI Assisted Development

## AI Agents Orientation

If you drive the Haiqu SDK from an AI coding assistant (Claude Code, Cursor, Copilot, or any agent that reads repository context), point it at the bundled **agent orientation**. It is a compact, task-focused brief that teaches an agent the canonical login → `init` → build → transpile → run workflow, the import that actually works (`from haiqu.sdk import haiqu` — plain `import haiqu` resolves to an empty namespace package), and the traps that local Qiskit intuition gets wrong (for example, that every `device_id` dispatches to the cloud, that data-loading results are opaque `HaiquCircuitGate` handles, and that `run(...).result()` returns probability distributions rather than integer counts).

The orientation is installed alongside the package at `haiqu/sdk/AGENTS.md` and is also published at [https://github.com/haiqu-ai/haiqu-sdk/blob/main/haiqu/sdk/AGENTS.md](https://github.com/haiqu-ai/haiqu-sdk/blob/main/haiqu/sdk/AGENTS.md).

Most agents automatically discover an `AGENTS.md`file. To load it explicitly, feed this prompt to your AI agent:

```python theme={null}
# Load Haiqu SDK AGENTS.MD into context
 from importlib.resources import files
 orientation = files("haiqu.sdk").joinpath("AGENTS.md").read_text()
```

Keeping the orientation in the agent's context measurably reduces the most common failure modes — attempts at local execution, calling `qc.depth()` on opaque cloud gates, or expecting shot counts from `result()`.

## Accessing Common Workflows via Haiqu MCP

Get up and running with Haiqu MCP (Model Context Protocol) tools in your favourite IDE or AI chat.

<Tabs>
  <Tab title="VS Code + Claude">
    <Steps>
      <Step title="Prompt Claude to add the Haiqu MCP server">
        ```text theme={null}
        Would you kindly add a new MCP server: Haiqu
        URL: https://api.haiqu.ai/mcp
        Authorization: "MY-HAIQU-API-KEY"
        ```

        Claude will respond "I'll add that MCP server to your local config." and do the hard lifting for you. Restart Claude Code (or reconnect via `/mcp`) to pick up the new server.
      </Step>

      <Step title="or open Claude settings">
        Create a `~/.claude.json` file if it does not exist.
      </Step>

      <Step title="and configure the Haiqu MCP server">
        In `~/.claude.json`, add:

        ```json theme={null}
        "mcpServers": {
          "Haiqu": {
            "type": "http",
            "url": "https://api.haiqu.ai/mcp",
            "headers": {
              "Authorization": "HAIQU-API-KEY"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Claude's chat, ask “What Haiqu tools do you have available?” Claude should show the Haiqu MCP server as an available tool. The example output from the Claude chat:

        ```text theme={null}
        Based on the system context, here are the available Haiqu MCP tools:

        Experiments

        mcp__Haiqu__create_new_experiment — create a new experiment
        mcp__Haiqu__get_experiment_by_id — fetch experiment by ID
        mcp__Haiqu__get_experiment_by_name — fetch experiment by name
        mcp__Haiqu__list_experiments — list all experiments
        mcp__Haiqu__update_experiment — update experiment metadata

        ...

        Would you like me to use any of these?
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette.
        2. Search for “Open MCP settings”.
        3. Select Add custom MCP. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Haiqu MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "Haiqu": {
              "url": "https://api.haiqu.ai/mcp",
              "type": "http",
              "headers": {
                "authorization": "HAIQU-API-KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor’s chat, ask “What Haiqu tools do you have available?” Cursor should show the Haiqu MCP server as an available tool.
      </Step>
    </Steps>
  </Tab>
</Tabs>

The Haiqu documentation automatically generates [llms.txt](https://docs.haiqu.ai/llms.txt) file to help AI tools index and understand the SDK and API documentation.

## Use this documentation with AI tools

This documentation page generates an MCP server from guides and the SDK reference. It exposes a search tool for AI applications to query this documentation. To connect this documentation to AI tools do the following:

<Tabs>
  <Tab title="VS Code + Claude">
    <Steps>
      <Step title="Open Claude settings">
        Open `~/.claude.json` file.
      </Step>

      <Step title="Configure the Documentation MCP server">
        In `~/.claude.json`, add:

        ```json theme={null}
        "mcpServers": {
          "HaiquDocumentation": {
            "url": "https://docs.haiqu.ai/mcp"
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette.
        2. Search for “Open MCP settings”.
        3. Select Add custom MCP. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Documentation MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "HaiquDocumentation": {
              "url": "https://docs.haiqu.ai/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

To test, in AI chat, ask “What HaiquDocumentation guides do you have available?” It should show the HaiquDocumentation server as an available tool.

## Example vibe-quantum coding

In AI chat, ask "Show me the typical workflow with a simple quantum circuit." The AI  assistant should show the the complete workflow with creating a new experiment, quantum circuit, and running it on the simulator:

<Steps>
  <Step title="Step 1 — List devices">
    Identified aer\_simulator as the best target: available, 0 pending jobs, 1024 qubits.
  </Step>

  <Step title="Step 2 — Create experiment">
    ```text theme={null}
    Experiment: "Bell State Demo"
    ID: exp-6eddfc05-8336-4b9c-b5fb-dc91afb79293
    Experiments are containers for circuits, jobs, and artifacts. If one with the same name already exists, it's returned instead of duplicated.
    ```
  </Step>

  <Step title="Step 3 — Submit circuit (via QASM)">
    ```text theme={null}
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[2];
    creg c[2];
    h q[0];          // superposition on qubit 0
    cx q[0], q[1];   // entangle q0 → q1
    measure q[0] -> c[0];
    measure q[1] -> c[1];
    ```

    Circuits can be provided as QASM (auto-saved to the DB) or by existing circuit\_id.
  </Step>

  <Step title="Step 4 — Poll results">
    ```text theme={null}
    Status:  Done
    Device:  aer_simulator
    Shots:   1024
    Time:    0.09s

    Results:
      |00⟩  53.4%  (534 counts)
      |11⟩  46.6%  (490 counts)

    Hellinger fidelity: 0.9995
    ```

    The \~50/50 split between `|00⟩` and `|11⟩` is exactly what a Bell state (|Φ+⟩ = (|00⟩ + |11⟩)/√2) should produce. The near-perfect fidelity confirms the simulation is clean.
  </Step>
</Steps>