qlam-core 0.3.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 definitions, retrieving results, and administering tenants and users.

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
Tenant and user administration	Manage tenants, audiences, users, and role assignments
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
• TenantsClient
• UsersClient

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")

Administrative clients follow the same pattern:

from qlam_core.plugins.tenants import TenantsClient
from qlam_core.plugins.users import UsersClient

with TenantsClient(ctx) as client:
    tenant_page = client.list_page(size=10)

with UsersClient(ctx) as client:
    user_page = client.list_page(size=10)

TenantsClient and UsersClient use non-QPU-scoped endpoints, so they do not accept qpu_mode.

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