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, users, and groups.

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

Features

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
• GroupsClient

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
from qlam_core.plugins.groups import GroupsClient

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

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

with GroupsClient(ctx) as client:
    group_page = client.list_page(size=10)
    by_id = client.list_page(
        id=["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
        size=1,
    )

TenantsClient, UsersClient, and GroupsClient use non-QPU-scoped endpoints, so they do not accept qpu_mode. GroupsClient list helpers also accept optional name, is_shared, and repeatable id filters.

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",
        "group": "00000000-0000-0000-0000-000000000001",
        "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"
        }
      ]
    }
  ]
}

Optional defaults.group (and plugins.<name>.group) is a name or UUID used by qsh create/submit commands when --group is omitted. Python clients such as TasksClient.create do not apply it automatically, and list commands never use it as an implicit filter.

Environment Variables

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