qlam-core 0.2.0

Core library for QuEra Quantum Computing Services - config, auth, and HTTP client

qlam-core

Core Python SDK for QuEra Quantum Computing Services

qlam-core is a Python library for integrating QuEra quantum computing services into your applications. It handles authentication, configuration, and typed API clients for submitting tasks, managing compilations, and retrieving results.

Public qlam-core documentation is available at Third-Party SDKs (qlam-core).

Features

Feature	Description
Multi-flow OAuth 2.0	Device code, PKCE, and client credentials
Multi-context config	Multiple named contexts with easy switching
Type-safe API clients	Pydantic models with full type hints
Automatic token refresh	Seamless credential management
Shared ~/.qsh state	Reuses the standard config and credential storage layout

Installation

With pip:

pip install qlam-core

With uv:

# Install into the current environment
uv pip install qlam-core

# Or add it to a uv-managed project
uv add qlam-core

Requirements: Python 3.10+

Quick Start

First, ensure you have a configuration file at ~/.qsh/config.json. If you need a starting point, see Minimal Configuration below.

from qlam_core.common import AppContext
from qlam_core.plugins.tasks import TasksClient

# Create context (uses ~/.qsh/config.json)
ctx = AppContext()

# Use the Tasks API
with TasksClient(ctx) as client:
    tasks = client.list()
    print(f"Found {len(tasks)} tasks")

Core Concepts

AppContext

AppContext is the central object that manages configuration, authentication, and HTTP clients.

from qlam_core.common import AppContext

# Use default context from config
ctx = AppContext()

# Use a specific named context
ctx = AppContext(context_name="production")

print(ctx.config.api_base_url)
print(ctx.config.qpu)

API Clients

qlam-core includes typed clients for:

• TasksClient
• ResultsClient
• CompilationsClient
• DefinitionsClient

All clients follow the same pattern:

from qlam_core.plugins.tasks import TasksClient
from qlam_core.plugins.results import ResultsClient
from qlam_core.plugins.compilations import CompilationsClient
from qlam_core.plugins.definitions import DefinitionsClient

ctx = AppContext()

with TasksClient(ctx) as client:
    tasks = client.list()
    task = client.get(id="task-123")

Configuration

Config File Location

By default, qlam-core reads configuration from ~/.qsh/config.json.

qlam-core uses the standard ~/.qsh config and credential layout directly. If you already use qsh, the same config directory and credential storage are reused automatically.

Minimal Configuration

{
  "current_context": "production",
  "contexts": [
    {
      "name": "production",
      "qpu": "your-qpu",
      "defaults": {
        "api_base_url": "https://api.example.com",
        "qpu_mode": "your-qpu-mode",
        "visibility": "public",
        "auth_provider": "oauth-device"
      },
      "auth_providers": [
        {
          "name": "oauth-device",
          "provider": "oauth",
          "auth_base_url": "https://auth.example.com",
          "client_id": "your-client-id",
          "grant_type": "device_code",
          "scope": "openid email profile offline_access",
          "audience": "https://your-audience"
        }
      ]
    }
  ]
}

Environment Variables

Variable	Description
QSH_CONFIG_DIR	Override the configuration directory
QSH_CONFIG	Override the config file path directly
QSH_AUTH_TOKEN	Override the direct auth token
QSH_QPU	Override the configured QPU
QSH_VISIBILITY	Override API visibility (public or private)

Authentication

qlam-core supports OAuth-based authentication for interactive and service-to-service access:

• Device code flow
• Authorization code with PKCE
• Client credentials flow

It also supports direct token-based configuration for environments that inject credentials externally.

Direct token example:

{
  "contexts": [
    {
      "name": "production",
      "qpu": "your-qpu",
      "defaults": {
        "api_base_url": "https://api.example.com",
        "qpu_mode": "your-qpu-mode",
        "auth": {
          "token": "env:QSH_AUTH_TOKEN"
        }
      }
    }
  ]
}

License

Apache License 2.0