Qubitclient Vqa Review

API Reference

Installation

# Install qubitclient
pip install qubitclient[full]

Quick Start

from qubitclient.llm import QubitLLM
from qubitclient.llm.task import LLMTaskName

# Initialize LLM client
llm = QubitLLM()

# Run a task with an image
result = llm.run(
    LLMTaskName.DESCRIBE_PLOT,
    image_data="path/to/image.png",
    experiment_family=ExperimentFamily.T1
)

Client Initialization

from qubitclient.llm import QubitLLM, ExperimentFamily
from qubitclient.llm.task import LLMTaskName

LLM Task Names (LLMTaskName)

Experiment Families (ExperimentFamily)

Supported experiment families for task-specific prompts:

ExperimentFamily.T1                    # T1 relaxation time
ExperimentFamily.T1_FLUCTUATIONS       # T1 fluctuations
ExperimentFamily.T2FIT                 # T2 coherence time (not in QCalEval)
ExperimentFamily.RAMI                  # (not in QCalEval)
ExperimentFamily.RAB                   # (not in QCalEval)
ExperimentFamily.COUPLER_FLUX          # Coupler flux experiment
ExperimentFamily.CZ_BENCHMARKING       # CZ gate benchmarking
ExperimentFamily.DRAG                  # DRAG pulse optimization
ExperimentFamily.GMM                   # Gaussian mixture model
ExperimentFamily.MICROWAVE_RAMSEY      # Microwave Ramsey
ExperimentFamily.MOT_LOADING           # MOT loading
ExperimentFamily.PINCHOFF              # Pinchoff experiment
ExperimentFamily.PINGPONG              # Ping-pong experiment
ExperimentFamily.QUBIT_FLUX_SPECTROSCOPY   # Qubit flux spectroscopy
ExperimentFamily.QUBIT_SPECTROSCOPY        # Qubit spectroscopy
ExperimentFamily.QUBIT_SPECTROSCOPY_POWER_FREQUENCY  # Power-frequency spectroscopy
ExperimentFamily.RABI                  # Rabi oscillation
ExperimentFamily.RABI_HW               # Rabi hardware
ExperimentFamily.RAMSEY_CHARGE_TOMOGRAPHY   # Ramsey charge tomography
ExperimentFamily.RAMSEY_FREQ_CAL       # Ramsey frequency calibration
ExperimentFamily.RAMSEY_T2STAR         # Ramsey T2*
ExperimentFamily.RES_SPEC              # Resonator spectroscopy
ExperimentFamily.RYDBERG_RAMSEY        # Rydberg Ramsey
ExperimentFamily.RYDBERG_SPECTROSCOPY  # Rydberg spectroscopy
ExperimentFamily.TWEEZER_ARRAY         # Tweezer array

Running Tasks

Get Prompt Only (for custom execution)

# Get prompt data without running
prompt_data = llm.get_prompt(
    LLMTaskName.DESCRIBE_PLOT,
    image_data="path/to/image.png",
    experiment_family=ExperimentFamily.T1
)
# Returns: {"messages": [...], "images": [...], "response_schema": {...}}

# Execute with your own client
result = llm.chat(**prompt_data)

Run Task Directly

# Run task and get result directly
result = llm.run(
    LLMTaskName.DESCRIBE_PLOT,
    image_data="path/to/image.png",
    experiment_family=ExperimentFamily.T1
)
# Returns parsed JSON result

Image Input Formats

# Single image path
image_data = "path/to/image.png"

# Multiple images
image_data = ["path/to/img1.png", "path/to/img2.png"]

# Image bytes
with open("image.png", "rb") as f:
    image_data = f.read()

Fewshot Mode

Enable fewshot mode for improved accuracy with example images:

result = llm.run(
    LLMTaskName.EXTRACT_PARAMS,
    image_data="path/to/image.png",
    experiment_family=ExperimentFamily.T1,
    fewshot=True  # Uses built-in examples for this experiment family
)

Examples

Example 1: T1 Analysis - Describe Plot

from qubitclient.llm import QubitLLM
from qubitclient.llm.task import LLMTaskName

llm = QubitLLM()

result = llm.run(
    LLMTaskName.DESCRIBE_PLOT,
    image_data="t1_decay.png",
    experiment_family=ExperimentFamily.T1
)
# Returns: {"plot_type": "line", "x_axis": "Delay (s)", "y_axis": "Population", ...}

Example 2: Classify Experiment Outcome

result = llm.run(
    LLMTaskName.CLASSIFY_OUTCOME,
    image_data="rabi_oscillation.png",
    experiment_family=ExperimentFamily.RABI
)
# Returns: {"Classification": "Expected", "Confidence": 0.9, ...}

Example 3: Scientific Reasoning

result = llm.run(
    LLMTaskName.SCIENTIFIC_REASONING,
    image_data="ramsey_fringe.png",
    experiment_family=ExperimentFamily.RAMSEY_T2STAR
)
# Returns: "The data shows clear oscillation with T2* decay..."

Example 4: Assess Fit Reliability

result = llm.run(
    LLMTaskName.ASSESS_FIT,
    image_data="t1_fit.png",
    experiment_family=ExperimentFamily.T1
)
# Returns: {"Assessment": "Good", "R_squared": 0.98, ...}

Example 5: Extract Parameters

result = llm.run(
    LLMTaskName.EXTRACT_PARAMS,
    image_data="t1_decay.png",
    experiment_family=ExperimentFamily.T1
)
# Returns: {"T1": 15.3e-6, "offset": 0.02, "amplitude": 0.98}

Example 6: Evaluate Experiment Status

result = llm.run(
    LLMTaskName.EVALUATE_STATUS,
    image_data="t1_decay.png",
    experiment_family=ExperimentFamily.T1
)
# Returns: {"Status": "SUCCESS", "Notes": "Good T1 value within expected range"}

Example 7: Running Multiple Tasks on Same Image

from qubitclient.llm.task import LLMTaskName

image_path = "experiment_result.png"

# Get prompts for each task
q1_prompt = llm.get_prompt(LLMTaskName.DESCRIBE_PLOT, image_data=image_path, experiment_family=ExperimentFamily.T1)
q2_prompt = llm.get_prompt(LLMTaskName.CLASSIFY_OUTCOME, image_data=image_path, experiment_family=ExperimentFamily.T1)
q3_prompt = llm.get_prompt(LLMTaskName.SCIENTIFIC_REASONING, image_data=image_path, experiment_family=ExperimentFamily.T1)
q4_prompt = llm.get_prompt(LLMTaskName.ASSESS_FIT, image_data=image_path, experiment_family=ExperimentFamily.T1)
q5_prompt = llm.get_prompt(LLMTaskName.EXTRACT_PARAMS, image_data=image_path, experiment_family=ExperimentFamily.T1)
q6_prompt = llm.get_prompt(LLMTaskName.EVALUATE_STATUS, image_data=image_path, experiment_family=ExperimentFamily.T1)

# Execute each task
q1_result = llm.chat(**q1_prompt)
q2_result = llm.chat(**q2_prompt)
q3_result = llm.chat(**q3_prompt)
q4_result = llm.chat(**q4_prompt)
q5_result = llm.chat(**q5_prompt)
q6_result = llm.chat(**q6_prompt)

Configuration

The LLM client reads configuration from qubitclient.utils.env_load:

# Environment variables or config file
OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://api.openai.com/v1  # optional, for custom endpoints
OPENAI_MODEL=gpt-4o  # default model

Or pass directly:

llm = QubitLLM(
    api_key="your-key",
    base_url="https://api.openai.com/v1",
    model="gpt-4o"
)

Streaming Response

# Get streaming generator
prompt_data = llm.get_prompt(
    LLMTaskName.SCIENTIFIC_REASONING,
    image_data="image.png",
    experiment_family=ExperimentFamily.T1
)

for chunk in llm.chat(stream=True, **prompt_data):
    print(chunk, end="")

Custom Model

# Use different model for a specific call
result = llm.chat(
    messages=[{"role": "user", "content": "Describe this plot"}],
    images="image.png",
    model="gpt-4o-mini"  # override default model
)