Metadata-Version: 2.4
Name: qlam-core
Version: 0.2.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: 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 retrieving results.

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

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

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