SDK Base and Auth Helpers

Base API class that plugin clients inherit from, plus presentation-free authentication helpers for credentials, token refresh, and the current user profile.

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()

Initialize the base API.

Parameters:

Name	Type	Description	Default
`ctx`	`AppContext`	Application context with configuration and auth.	required
`resource`	`str`	Resource name (e.g., "tasks", "compilations") for config resolution.	required

Source code in qlam_core/sdk/base_api.py

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__() -> BaseRestApiT

Enter context manager.

Returns:

Type	Description
`BaseRestApiT`	Self for use in with statement.

Source code in qlam_core/sdk/base_api.py

def __enter__(self: BaseRestApiT) -> BaseRestApiT:
    """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.

Parameters:

Name	Description	Default
`exc_type`	Exception type if an exception was raised.	required
`exc_val`	Exception value if an exception was raised.	required
`exc_tb`	Exception traceback if an exception was raised.	required

Source code in qlam_core/sdk/base_api.py

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", [])]

Initialize the base API without QPU mode support.

Parameters:

Name	Type	Description	Default
`ctx`	`AppContext`	Application context with configuration and auth.	required
`resource`	`str`	Resource name (e.g., "users", "accounts") for config resolution.	required

Source code in qlam_core/sdk/base_api.py

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)

enter

__enter__() -> BaseRestApiWithoutQpuModeT

Enter context manager and return self.

Source code in qlam_core/sdk/base_api.py

def __enter__(self: BaseRestApiWithoutQpuModeT) -> BaseRestApiWithoutQpuModeT:
    """Enter context manager and return self."""
    return self

exit

__exit__(exc_type, exc_val, exc_tb) -> None

Exit context manager.

Reserved for future cleanup hooks to keep parity with BaseRestApi.

Source code in qlam_core/sdk/base_api.py

def __exit__(self, exc_type, exc_val, exc_tb) -> None:
    """Exit context manager.

    Reserved for future cleanup hooks to keep parity with BaseRestApi.
    """
    pass

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.

Parameters:

Name	Type	Description	Default
`ctx`	`AppContext`	Application context providing configuration and logging.	required
`provider`	`str`	Provider name to retrieve the credential for.	required

Returns:

Type	Description
`CredentialBase \| None`	Provider-specific credential model, or None.

Raises:

Type	Description
`ConfigurationError`	If the provider is unknown or misconfigured.

Source code in qlam_core/sdk/auth.py

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)

get_user_info

get_user_info(ctx: AppContext, provider: str | None = None) -> UserInfo

Return the current authenticated user profile from {api}/userinfo.

Presentation-free SDK helper mirroring AuthClient.get_user_info. The profile is fetched from the context's api_base_url (/userinfo). When provider is omitted, uses the current context's defaults.auth_provider.

Parameters:

Name	Type	Description	Default
`ctx`	`AppContext`	Application context providing configuration and logging.	required
`provider`	`str \| None`	Auth provider name, or None to use the context default.	`None`

Returns:

Type	Description
`UserInfo`	Typed user profile from the provider.

Source code in qlam_core/sdk/auth.py

def get_user_info(ctx: AppContext, provider: str | None = None) -> UserInfo:
    """Return the current authenticated user profile from ``{api}/userinfo``.

    Presentation-free SDK helper mirroring
    [`AuthClient.get_user_info`][qlam_core.auth.client.AuthClient.get_user_info].
    The profile is fetched from the context's ``api_base_url`` (``/userinfo``).
    When ``provider`` is omitted, uses the current context's
    ``defaults.auth_provider``.

    :param ctx: Application context providing configuration and logging.
    :param provider: Auth provider name, or None to use the context default.
    :return: Typed user profile from the provider.
    """
    with AuthClient(ctx) as client:
        return client.get_user_info(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.

Parameters:

Name	Type	Description	Default
`ctx`	`AppContext`	Application context providing configuration and logging.	required
`provider`	`str \| None`	Provider name to refresh. If None, refresh all configured providers that support non-interactive refresh.	`None`
`force`	`bool`	If True, refresh even when credentials appear valid.	`False`

Returns:

Type	Description
`dict[str, bool]`	Mapping of provider name to whether refresh occurred.

Source code in qlam_core/sdk/auth.py

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)