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, managing task profiles, 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
• TaskProfilesClient

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, GroupsClient, and TaskProfilesClient 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.

Task profiles are immutable JSON blobs referenced by task submissions. Every TaskProfilesClient method takes a tenant flag: False (default) scopes reads to profiles created by the caller, True uses the tenant-wide routes (gated by the API gateway on the tenant-scope permission):

from qlam_core.plugins.task_profiles import TaskProfilesClient

with TaskProfilesClient(ctx) as client:
    profile = client.create({"name": "afm-sweep", "layers": 3})
    mine = client.list()
    tenant_wide = client.list_all(tenant=True)

Current-user profile

from qlam_core.sdk import get_user_info

# Uses current_context.defaults.auth_provider when provider is omitted
profile = get_user_info(ctx)
print(profile.email, profile.user_id, profile.roles)

OAuth providers fetch the context's api_base_url (/userinfo). Non-OAuth providers raise ConfigurationError. Unauthenticated OAuth raises OAuthAuthenticationError.

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