Metadata-Version: 2.4
Name: qlam-core
Version: 0.3.0
Summary: Core library for QuEra Quantum Computing Services - config, auth, and HTTP client
Author-email: Nicolas Tobar <ntobar@quera.com>, Kyle Mueller <kmueller@quera.com>
License-Expression: Apache-2.0
Project-URL: Documentation, https://queracomputing.github.io/qlam-docs/latest/guides/third-party/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: pydantic~=2.7
Requires-Dist: email-validator>=2.3.0
Requires-Dist: httpx~=0.24
Requires-Dist: requests-oauth2client~=1.7
Requires-Dist: segno~=1.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.20.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# 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)](https://queracomputing.github.io/qlam-docs/latest/guides/third-party/).

## 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`:

```bash
pip install qlam-core
```

With `uv`:

```bash
# 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](#minimal-configuration) below.

```python
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.

```python
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:

```python
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:

```python
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

```json
{
  "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:

```json
{
  "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
