Skip to content

SDK Base

Base API class that all plugin clients inherit from.

Base API class for REST resources.

This module provides a base class that REST API implementations can inherit from to get common functionality like QPU mode resolution, logging, and executor setup.

BaseRestApi 

BaseRestApi(ctx: AppContext, resource: str)

Base class for REST API implementations.

This class provides common functionality for REST APIs: - HTTP executor setup - QPU mode resolution from config - Logging - Context management (supports with statement)

Subclasses should call super().init() and can use the provided resolver methods with the @auto_resolve decorator.

Example::

from qlam_core.sdk.base_api import BaseRestApi
from qlam_core.sdk.decorators import auto_resolve_qpu_mode

class TasksApi(BaseRestApi):
    def __init__(self, ctx: AppContext):
        super().__init__(ctx, resource="tasks")

    @auto_resolve_qpu_mode
    def list(self, qpu_mode: str | None = None, ...) -> List[Task]:
        # qpu_mode is automatically resolved if None
        res = self._exec.execute(TASKS_SPEC, "list", qpu_mode=qpu_mode, ...)
        return [Task.model_validate(item) for item in res.get("elements", [])]

# Usage with context manager:
with TasksApi(ctx) as api:
    tasks = api.list()

:param ctx: Application context with configuration and auth. :param resource: Resource name (e.g., "tasks", "compilations") for config resolution.

Source code in qlam_core/sdk/base_api.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def __init__(self, ctx: AppContext, resource: str):
    """Initialize the base API.

    :param ctx: Application context with configuration and auth.
    :param resource: Resource name (e.g., "tasks", "compilations") for config resolution.
    """
    self._ctx = ctx
    self._resource = resource
    self._logger = ctx.logger.getChild(f"api.{resource}")

    # Create executor for HTTP operations
    self._exec: HttpExecutor = http_executor(ctx, resource=resource, logger=self._logger)

    # Create resolver for configuration (QPU mode, etc.)
    self._resolver = ClientConfigResolver(ctx, plugin_name=resource)

__enter__ 

__enter__() -> 'BaseRestApi'

Enter context manager.

:return: Self for use in with statement.

Source code in qlam_core/sdk/base_api.py 
73
74
75
76
77
78
def __enter__(self) -> "BaseRestApi":
    """Enter context manager.

    :return: Self for use in with statement.
    """
    return self

__exit__ 

__exit__(exc_type, exc_val, exc_tb) -> None

Exit context manager.

Performs any necessary cleanup. Currently a no-op but can be extended by subclasses if needed.

:param exc_type: Exception type if an exception was raised. :param exc_val: Exception value if an exception was raised. :param exc_tb: Exception traceback if an exception was raised.

Source code in qlam_core/sdk/base_api.py 
80
81
82
83
84
85
86
87
88
89
90
91
def __exit__(self, exc_type, exc_val, exc_tb) -> None:
    """Exit context manager.

    Performs any necessary cleanup. Currently a no-op but can be
    extended by subclasses if needed.

    :param exc_type: Exception type if an exception was raised.
    :param exc_val: Exception value if an exception was raised.
    :param exc_tb: Exception traceback if an exception was raised.
    """
    # Cleanup if needed (e.g., close connections)
    pass

BaseRestApiWithoutQpuMode 

BaseRestApiWithoutQpuMode(ctx: AppContext, resource: str)

Base class for REST APIs that don't require QPU mode.

Some resources (e.g., user management, account settings) don't operate within a QPU context and don't need QPU mode resolution. Use this base class for those resources.

Example::

class UsersApi(BaseRestApiWithoutQpuMode):
    def __init__(self, ctx: AppContext):
        super().__init__(ctx, resource="users")

    def list(self, page: int = 0, size: int = 50) -> List[User]:
        res = self._exec.execute(USERS_SPEC, "list", page=page, size=size)
        return [User.model_validate(item) for item in res.get("elements", [])]

:param ctx: Application context with configuration and auth. :param resource: Resource name (e.g., "users", "accounts") for config resolution.

Source code in qlam_core/sdk/base_api.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def __init__(self, ctx: AppContext, resource: str):
    """Initialize the base API without QPU mode support.

    :param ctx: Application context with configuration and auth.
    :param resource: Resource name (e.g., "users", "accounts") for config resolution.
    """
    self._ctx = ctx
    self._resource = resource
    self._logger = ctx.logger.getChild(f"api.{resource}")

    # Create executor for HTTP operations
    self._exec: HttpExecutor = http_executor(ctx, resource=resource, logger=self._logger)

    # Create resolver for configuration (but not for QPU mode)
    self._resolver = ClientConfigResolver(ctx, plugin_name=resource)

SDK Auth

SDK helpers for authentication operations.

This module provides SDK-level authentication helpers intended for programmatic consumers (e.g., Bloqade). These functions are presentation-free and do not depend on CLI invocation.

get_credential 

get_credential(ctx: AppContext, provider: str) -> CredentialBase | None

Get the credential for an authentication provider.

Returns the provider-specific credential model (e.g. OAuthCredential, BasicCredential). A returned credential may have a non-authenticated status; callers should inspect the status field. Returns None only when the provider has no credential data at all.

:param ctx: Application context providing configuration and logging. :param provider: Provider name to retrieve the credential for. :return: Provider-specific credential model, or None. :raises ConfigurationError: If the provider is unknown or misconfigured.

Source code in qlam_core/sdk/auth.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def get_credential(ctx: AppContext, provider: str) -> CredentialBase | None:
    """Get the credential for an authentication provider.

    Returns the provider-specific credential model (e.g. ``OAuthCredential``,
    ``BasicCredential``).  A returned credential may have a non-authenticated
    status; callers should inspect the ``status`` field.  Returns ``None``
    only when the provider has no credential data at all.

    :param ctx: Application context providing configuration and logging.
    :param provider: Provider name to retrieve the credential for.
    :return: Provider-specific credential model, or None.
    :raises ConfigurationError: If the provider is unknown or misconfigured.
    """
    with AuthClient(ctx) as client:
        return client.get_credential(provider)

refresh_credentials 

refresh_credentials(ctx: AppContext, provider: str | None = None, *, force: bool = False) -> dict[str, bool]

Refresh cached credentials for one or more providers.

:param ctx: Application context providing configuration and logging. :param provider: Provider name to refresh. If None, refresh all configured providers that support non-interactive refresh. :param force: If True, refresh even when credentials appear valid. :return: Mapping of provider name to whether refresh occurred.

Source code in qlam_core/sdk/auth.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
def refresh_credentials(
    ctx: AppContext, provider: str | None = None, *, force: bool = False
) -> dict[str, bool]:
    """Refresh cached credentials for one or more providers.

    :param ctx: Application context providing configuration and logging.
    :param provider: Provider name to refresh. If None, refresh all configured
        providers that support non-interactive refresh.
    :param force: If True, refresh even when credentials appear valid.
    :return: Mapping of provider name to whether refresh occurred.
    """
    with AuthClient(ctx) as client:
        return client.refresh_credentials(provider, force=force)