Skip to content

Plugins

API clients for interacting with QLAM services.

Tasks Client

Tasks Client - Clean Python API for task operations.

This module provides a typed, presentation-free API for task management. It uses the executor abstraction to perform HTTP operations and returns strongly-typed Pydantic models.

Usage

.. code-block:: python

from qlam_core.plugins.tasks.api.client import TasksClient
from qlam_core.common.context import AppContext

ctx = AppContext()

# Direct usage
client = TasksClient(ctx)
tasks = client.list()

# Context manager usage
with TasksClient(ctx) as client:
    tasks = client.list()

TasksClient 

TasksClient(ctx: AppContext)

Bases: BaseRestApi, ListMixin[Task], ReadMixin[Task], WriteMixin[TaskCreationRequest, Task]


              flowchart TD
              qlam_core.plugins.tasks.api.client.TasksClient[TasksClient]
              qlam_core.sdk.base_api.BaseRestApi[BaseRestApi]
              qlam_core.plugins.common.mixins.ListMixin[ListMixin]
              qlam_core.plugins.common.mixins.ReadMixin[ReadMixin]
              qlam_core.plugins.common.mixins.WriteMixin[WriteMixin]

                              qlam_core.sdk.base_api.BaseRestApi --> qlam_core.plugins.tasks.api.client.TasksClient
                
                qlam_core.plugins.common.mixins.ListMixin --> qlam_core.plugins.tasks.api.client.TasksClient
                
                qlam_core.plugins.common.mixins.ReadMixin --> qlam_core.plugins.tasks.api.client.TasksClient
                
                qlam_core.plugins.common.mixins.WriteMixin --> qlam_core.plugins.tasks.api.client.TasksClient
                


              click qlam_core.plugins.tasks.api.client.TasksClient href "" "qlam_core.plugins.tasks.api.client.TasksClient"
              click qlam_core.sdk.base_api.BaseRestApi href "" "qlam_core.sdk.base_api.BaseRestApi"
              click qlam_core.plugins.common.mixins.ListMixin href "" "qlam_core.plugins.common.mixins.ListMixin"
              click qlam_core.plugins.common.mixins.ReadMixin href "" "qlam_core.plugins.common.mixins.ReadMixin"
              click qlam_core.plugins.common.mixins.WriteMixin href "" "qlam_core.plugins.common.mixins.WriteMixin"

Client for task operations.

This API provides explicit methods for task management that return Pydantic v2 models. It's presentation-free and can be used by any frontend (CLI, Web, GUI) or directly by Python consumers.

All methods automatically resolve QPU mode from configuration when not explicitly provided, using the @auto_resolve_qpu_mode decorator.

The client uses composition of mixins to provide standard CRUD operations
  • ListMixin: Provides list, list_page, iter_pages, list_all
  • ReadMixin: Provides get
  • WriteMixin: Provides create

Resource-specific operations (like cancel) are implemented directly in this class.

Example

.. code-block:: python

# Create client
client = TasksClient(ctx)

# List operations (from ListMixin)
page = client.list_page(page=0, size=50)
all_tasks = client.list_all(max_items=1000)

# Read operations (from ReadMixin)
task = client.get(id="abc-123")

# Write operations (from WriteMixin)
request = TaskCreationRequest(...)
new_task = client.create(body=request)

# Resource-specific operations
cancelled = client.cancel(id="abc-123")

:param ctx: Application context with configuration and auth.

Source code in qlam_core/plugins/tasks/api/client.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def __init__(self, ctx: AppContext):
    """Initialize the tasks API.

    :param ctx: Application context with configuration and auth.
    """
    super().__init__(ctx, resource="tasks")

    # Configure mixins with tasks-specific details
    self._configure_list_mixin(
        spec=TASKS_SPEC,
        list_model=Task,
        list_command="list",
    )

    self._configure_read_mixin(
        spec=TASKS_SPEC,
        get_model=Task,
        get_command="gettask",
        id_param="id",
    )

    self._configure_write_mixin(
        spec=TASKS_SPEC,
        create_request_model=TaskCreationRequest,
        create_response_model=Task,
        create_command="create",
    )

cancel 

cancel(qpu_mode: str | None = None, id: str | None = None) -> None

Request cancellation of a running task.

This method is a thin wrapper around the /cancel endpoint:

  • On success (HTTP 202), it returns None, indicating that the cancellation request was accepted and is being processed.
  • On failure (HTTP status >= 400 or network error), it propagates the underlying exception (typically :class:qlam_core.cli.errors.APIError).
Source code in qlam_core/plugins/tasks/api/client.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@auto_resolve_qpu_mode
def cancel(
    self,
    qpu_mode: str | None = None,
    id: str | None = None,  # noqa: A002
) -> None:
    """Request cancellation of a running task.

    This method is a thin wrapper around the ``/cancel`` endpoint:

    - On success (HTTP 202), it returns ``None``, indicating that the
      cancellation request was accepted and is being processed.
    - On failure (HTTP status >= 400 or network error), it propagates
      the underlying exception (typically :class:`qlam_core.cli.errors.APIError`).
    """
    self._exec.execute(TASKS_SPEC, "cancel", qpu_mode=qpu_mode, id=id)

Results Client

Results Client - API for retrieving task results.

Provides access to sanitized results via the Results Transformer by default, and unsanitized (raw) results via the Result Manager when requested.

ResultsClient 

ResultsClient(ctx: AppContext)

Bases: BaseRestApi


              flowchart TD
              qlam_core.plugins.results.api.client.ResultsClient[ResultsClient]
              qlam_core.sdk.base_api.BaseRestApi[BaseRestApi]

                              qlam_core.sdk.base_api.BaseRestApi --> qlam_core.plugins.results.api.client.ResultsClient
                


              click qlam_core.plugins.results.api.client.ResultsClient href "" "qlam_core.plugins.results.api.client.ResultsClient"
              click qlam_core.sdk.base_api.BaseRestApi href "" "qlam_core.sdk.base_api.BaseRestApi"

Client for task results retrieval.

:param ctx: Application context with configuration and auth.

Source code in qlam_core/plugins/results/api/client.py 
21
22
23
24
25
26
def __init__(self, ctx: AppContext):
    """Initialize the results API.

    :param ctx: Application context with configuration and auth.
    """
    super().__init__(ctx, resource="results")

get 

get(qpu_mode: str | None = None, id: str | None = None, *, raw_source: bool = False, page: int = 0, size: int | None = None, sort: str | None = None, shots_page: int | None = None, shots_size: int | None = None) -> JsonDict

Get task results.

  • Default (sanitized): Results Transformer endpoint (requires qpu_mode).
  • Raw (unsanitized): Result Manager endpoint (--raw flag).
  • If sort is omitted, backend defaults are preserved.
Source code in qlam_core/plugins/results/api/client.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@auto_resolve_qpu_mode
def get(
    self,
    qpu_mode: str | None = None,
    id: str | None = None,  # noqa: A002
    *,
    raw_source: bool = False,
    page: int = 0,
    size: int | None = None,
    sort: str | None = None,
    shots_page: int | None = None,
    shots_size: int | None = None,
) -> JsonDict:
    """Get task results.

    - Default (sanitized): Results Transformer endpoint (requires qpu_mode).
    - Raw (unsanitized): Result Manager endpoint (--raw flag).
    - If ``sort`` is omitted, backend defaults are preserved.
    """
    spec = RESULT_MANAGER_SPEC if raw_source else RESULT_TRANSFORMER_SPEC

    kwargs: JsonDict = {
        "task_id": id,
        "page": page,
        "size": size,
        "shots_page": shots_page,
        "shots_size": shots_size,
    }
    if sort is not None:
        kwargs["sort"] = sort

    # Only include qpu_mode for the transformer endpoint
    if not raw_source:
        kwargs["qpu_mode"] = qpu_mode

    return self._exec.execute(spec, "gettaskresult", **kwargs)

Compilations Client

Compilations API - Clean Python API for compilation operations.

This module provides a typed, presentation-free API for compilation management. It uses the executor abstraction to perform HTTP operations and returns strongly-typed Pydantic models.

CompilationsClient 

CompilationsClient(ctx: AppContext)

Bases: BaseRestApi, ListMixin[PublicCompilation], ReadMixin[PrivateCompilation], WriteMixin[V2QpuModeCompilationsPostRequest, PrivateCompilation]


              flowchart TD
              qlam_core.plugins.compilations.api.client.CompilationsClient[CompilationsClient]
              qlam_core.sdk.base_api.BaseRestApi[BaseRestApi]
              qlam_core.plugins.common.mixins.ListMixin[ListMixin]
              qlam_core.plugins.common.mixins.ReadMixin[ReadMixin]
              qlam_core.plugins.common.mixins.WriteMixin[WriteMixin]

                              qlam_core.sdk.base_api.BaseRestApi --> qlam_core.plugins.compilations.api.client.CompilationsClient
                
                qlam_core.plugins.common.mixins.ListMixin --> qlam_core.plugins.compilations.api.client.CompilationsClient
                
                qlam_core.plugins.common.mixins.ReadMixin --> qlam_core.plugins.compilations.api.client.CompilationsClient
                
                qlam_core.plugins.common.mixins.WriteMixin --> qlam_core.plugins.compilations.api.client.CompilationsClient
                


              click qlam_core.plugins.compilations.api.client.CompilationsClient href "" "qlam_core.plugins.compilations.api.client.CompilationsClient"
              click qlam_core.sdk.base_api.BaseRestApi href "" "qlam_core.sdk.base_api.BaseRestApi"
              click qlam_core.plugins.common.mixins.ListMixin href "" "qlam_core.plugins.common.mixins.ListMixin"
              click qlam_core.plugins.common.mixins.ReadMixin href "" "qlam_core.plugins.common.mixins.ReadMixin"
              click qlam_core.plugins.common.mixins.WriteMixin href "" "qlam_core.plugins.common.mixins.WriteMixin"

Typed API for compilation operations.

This API provides explicit methods for compilation management that return Pydantic v2 models. It's presentation-free and can be used by any frontend (CLI, Web, GUI) or directly by Python consumers.

All methods automatically resolve QPU mode from configuration when not explicitly provided, using the @auto_resolve_qpu_mode decorator.

The client uses composition of mixins to provide standard CRUD operations
  • ListMixin: Provides list, list_page, iter_pages, list_all
  • ReadMixin: Provides get
  • WriteMixin: Provides create
Example

.. code-block:: python

# Create client
client = CompilationsClient(ctx)

# List operations
page = client.list_page(page=0, size=50)
all_compilations = client.list_all(max_items=1000)

# Read operations
compilation = client.get(id="abc-123")

# Write operations
request = V2QpuModeCompilationsPostRequest(...)
new_compilation = client.create(body=request)

:param ctx: Application context with configuration and auth.

Source code in qlam_core/plugins/compilations/api/client.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def __init__(self, ctx: AppContext):
    """Initialize the compilations API.

    :param ctx: Application context with configuration and auth.
    """
    super().__init__(ctx, resource="compilations")

    # Configure mixins with compilations-specific details
    self._configure_list_mixin(
        spec=COMPILATIONS_SPEC,
        list_model=PublicCompilation,
        list_command="list",
    )

    self._configure_read_mixin(
        spec=COMPILATIONS_SPEC,
        get_model=PrivateCompilation,
        get_command="getcompilation",
        id_param="id",
    )

    self._configure_write_mixin(
        spec=COMPILATIONS_SPEC,
        create_request_model=V2QpuModeCompilationsPostRequest,
        create_response_model=PrivateCompilation,
        create_command="create",
    )

Definitions Client

Definitions API - Clean Python API for task definition operations.

This module provides a typed, presentation-free API for task definition management. It uses the executor abstraction to perform HTTP operations and returns strongly-typed Pydantic models.

DefinitionsClient 

DefinitionsClient(ctx: AppContext)

Bases: BaseRestApi, ListMixin[TaskDefinitionResponse], ReadMixin[TaskDefinitionResponse], WriteMixin[TaskDefinitionRequest, TaskDefinitionResponse]


              flowchart TD
              qlam_core.plugins.definitions.api.client.DefinitionsClient[DefinitionsClient]
              qlam_core.sdk.base_api.BaseRestApi[BaseRestApi]
              qlam_core.plugins.common.mixins.ListMixin[ListMixin]
              qlam_core.plugins.common.mixins.ReadMixin[ReadMixin]
              qlam_core.plugins.common.mixins.WriteMixin[WriteMixin]

                              qlam_core.sdk.base_api.BaseRestApi --> qlam_core.plugins.definitions.api.client.DefinitionsClient
                
                qlam_core.plugins.common.mixins.ListMixin --> qlam_core.plugins.definitions.api.client.DefinitionsClient
                
                qlam_core.plugins.common.mixins.ReadMixin --> qlam_core.plugins.definitions.api.client.DefinitionsClient
                
                qlam_core.plugins.common.mixins.WriteMixin --> qlam_core.plugins.definitions.api.client.DefinitionsClient
                


              click qlam_core.plugins.definitions.api.client.DefinitionsClient href "" "qlam_core.plugins.definitions.api.client.DefinitionsClient"
              click qlam_core.sdk.base_api.BaseRestApi href "" "qlam_core.sdk.base_api.BaseRestApi"
              click qlam_core.plugins.common.mixins.ListMixin href "" "qlam_core.plugins.common.mixins.ListMixin"
              click qlam_core.plugins.common.mixins.ReadMixin href "" "qlam_core.plugins.common.mixins.ReadMixin"
              click qlam_core.plugins.common.mixins.WriteMixin href "" "qlam_core.plugins.common.mixins.WriteMixin"

Typed API for task definition operations.

This API provides explicit methods for task definition management that return Pydantic v2 models. It's presentation-free and can be used by any frontend (CLI, Web, GUI) or directly by Python consumers.

All methods automatically resolve QPU mode from configuration when not explicitly provided, using the @auto_resolve_qpu_mode decorator.

The client uses composition of mixins to provide standard CRUD operations
  • ListMixin: Provides list, list_page, iter_pages, list_all
  • ReadMixin: Provides get
  • WriteMixin: Provides create
Example

.. code-block:: python

# Create client
client = DefinitionsClient(ctx)

# List operations
page = client.list_page(page=0, size=50)
all_definitions = client.list_all(max_items=1000)

# Read operations
definition = client.get(id="abc-123")

# Write operations
definition = TaskDefinitionRequest(...)
new_definition = client.create(body=definition)

:param ctx: Application context with configuration and auth.

Source code in qlam_core/plugins/definitions/api/client.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def __init__(self, ctx: AppContext):
    """Initialize the definitions API.

    :param ctx: Application context with configuration and auth.
    """
    super().__init__(ctx, resource="definitions")

    # Configure mixins with definitions-specific details
    self._configure_list_mixin(
        spec=DEFINITIONS_SPEC,
        list_model=TaskDefinitionResponse,
        list_command="list",
    )

    self._configure_read_mixin(
        spec=DEFINITIONS_SPEC,
        get_model=TaskDefinitionResponse,
        get_command="getdefinition",
        id_param="id",
    )

    self._configure_write_mixin(
        spec=DEFINITIONS_SPEC,
        create_request_model=TaskDefinitionRequest,
        create_response_model=TaskDefinitionResponse,
        create_command="create",
    )