Metadata-Version: 2.4
Name: albus-sdk
Version: 0.17.0
Summary: Official Python SDK for the Albus API.
Author: Albus
License-Expression: MIT
Project-URL: homepage, https://albus.sh
Project-URL: repository, https://github.com/albusgroup/albus-python
Project-URL: documentation, https://github.com/albusgroup/albus-python#readme
Project-URL: issues, https://github.com/albusgroup/albus-python/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic<2.13,>=2.11.2
Dynamic: license-file

# albus-sdk

Official, type-safe Python SDK for the Albus API.

[![Built by Speakeasy](https://img.shields.io/badge/Built_by-SPEAKEASY-374151?style=for-the-badge&labelColor=f3f4f6)](https://www.speakeasy.com/?utm_source=albus-sdk&utm_campaign=python)
[![License: MIT](https://img.shields.io/badge/LICENSE_//_MIT-3b5bdb?style=for-the-badge&labelColor=eff6ff)](https://opensource.org/licenses/MIT)

## Quickstart

Install the SDK from PyPI:

```bash
pip install albus-sdk
```

Session operations use an organization API key:

```python
import os

from albus_sdk import Albus, models


with Albus(
    api_key=os.environ["ALBUS_API_KEY"],
) as albus:
    response = albus.sessions.list_sessions()
    print(response.sessions)
```

Run or resume a session by ID, and wait for the assistant response:

```python
import os

from albus_sdk import Albus, models


with Albus(
    api_key=os.environ["ALBUS_API_KEY"],
    timeout_ms=130_000,
) as albus:
    response = albus.sessions.run_session(
        id="support-triage-1",
        user_prompt="Summarize the latest ticket.",
        agent_name="support-triage",
        agent=models.AgentConfig(
            model=models.Model(name="gemini-3.6-flash"),
        ),
        wait_timeout_seconds=120,
    )
    message = response.result.message
    if message is None:
        print("the invocation has not answered yet")
    else:
        print(message.content)
```

`message` is the single assistant message the invocation produced, and is absent
when the invocation has not answered yet; read it later with
`albus.sessions.get_session`, which returns the session's full `messages`
history.

Pass 0 for `wait_timeout_seconds` to return as soon as the invocation is
accepted, and omit it to wait up to 30 minutes for the response. Waiting
long-polls, so construct the client with a `timeout_ms` above the longest
wait — it is a client-wide setting, and the underlying HTTP client otherwise
gives up after its own 5-second default.

`AsyncAlbus` exposes the same operations as coroutines:

```python
import asyncio
import os

from albus_sdk import AsyncAlbus, models


async def main() -> None:
    async with AsyncAlbus(
        api_key=os.environ["ALBUS_API_KEY"],
    ) as albus:
        response = await albus.auth.whoami()
        print(response)


asyncio.run(main())
```

`api_key` is the only credential. When it is not passed, the SDK reads
`ALBUS_API_KEY` from the environment; when that is unset too, it sends
requests as the user signed in with `albus login`, acting in the organization
that session selected. `Albus()` is therefore sufficient on a machine with
either configured. Production requests use `https://albus.sh/api` by default.

<!-- Start Summary [summary] -->
## Summary

Albus API: Albus service REST API
<!-- End Summary [summary] -->

<!-- Start Table of Contents [toc] -->
## Table of Contents
<!-- $toc-max-depth=2 -->
* [albus-sdk](#albus-sdk)
  * [Quickstart](#quickstart)
  * [SDK Installation](#sdk-installation)
  * [IDE Support](#ide-support)
  * [SDK Example Usage](#sdk-example-usage)
  * [Authentication](#authentication)
  * [Available Resources and Operations](#available-resources-and-operations)
  * [Retries](#retries)
  * [Error Handling](#error-handling)
  * [Server Selection](#server-selection)
  * [Custom HTTP Client](#custom-http-client)
  * [Resource Management](#resource-management)
  * [Debugging](#debugging)
* [Development](#development)
  * [Regeneration](#regeneration)
  * [Checks](#checks)
  * [Releases](#releases)
  * [Maturity](#maturity)
  * [Contributions](#contributions)

<!-- End Table of Contents [toc] -->

<!-- Start SDK Installation [installation] -->
## SDK Installation

> [!NOTE]
> **Python version upgrade policy**
>
> Once a Python version reaches its [official end of life date](https://devguide.python.org/versions/), a 3-month grace period is provided for users to upgrade. Following this grace period, the minimum python version supported in the SDK will be updated.

The SDK can be installed with *uv*, *pip*, or *poetry* package managers.

### uv

*uv* is a fast Python package installer and resolver, designed as a drop-in replacement for pip and pip-tools. It's recommended for its speed and modern Python tooling capabilities.

```bash
uv add albus-sdk
```

### PIP

*PIP* is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line.

```bash
pip install albus-sdk
```

### Poetry

*Poetry* is a modern tool that simplifies dependency management and package publishing by using a single `pyproject.toml` file to handle project metadata and dependencies.

```bash
poetry add albus-sdk
```

### Shell and script usage with `uv`

You can use this SDK in a Python shell with [uv](https://docs.astral.sh/uv/) and the `uvx` command that comes with it like so:

```shell
uvx --from albus-sdk python
```

It's also possible to write a standalone Python script without needing to set up a whole project like so:

```python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "albus-sdk",
# ]
# ///

from albus_sdk import Albus

sdk = Albus(
  # SDK arguments
)

# Rest of script here...
```

Once that is saved to a file, you can run it with `uv run script.py` where
`script.py` can be replaced with the actual file name.
<!-- End SDK Installation [installation] -->

<!-- Start IDE Support [idesupport] -->
## IDE Support

### PyCharm

Generally, the SDK will work well with most IDEs out of the box. However, when using PyCharm, you can enjoy much better integration with Pydantic by installing an additional plugin.

- [PyCharm Pydantic Plugin](https://docs.pydantic.dev/latest/integrations/pycharm/)
<!-- End IDE Support [idesupport] -->

<!-- Start SDK Example Usage [usage] -->
## SDK Example Usage

### Example

```python
# Synchronous Example
from albus_sdk import Albus
import os


with Albus(
    api_key=os.getenv("ALBUS_API_KEY", ""),
) as albus:

    res = albus.secrets.list_secrets()

    # Handle response
    print(res)
```

</br>

An Async SDK client can also be used to make asynchronous requests by importing it and asyncio.

```python
# Asynchronous Example
from albus_sdk import AsyncAlbus
import asyncio
import os

async def main():

    async with AsyncAlbus(
        api_key=os.getenv("ALBUS_API_KEY", ""),
    ) as albus:

        res = await albus.secrets.list_secrets()

        # Handle response
        print(res)

asyncio.run(main())
```
<!-- End SDK Example Usage [usage] -->

<!-- Start Authentication [security] -->
## Authentication

### Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name      | Type | Scheme      | Environment Variable |
| --------- | ---- | ----------- | -------------------- |
| `api_key` | http | HTTP Bearer | `ALBUS_API_KEY`      |

To authenticate with the API the `api_key` parameter must be set when initializing the SDK client instance. For example:
```python
# Synchronous Example
from albus_sdk import Albus
import os


with Albus(
    api_key=os.getenv("ALBUS_API_KEY", ""),
) as albus:

    res = albus.secrets.list_secrets()

    # Handle response
    print(res)
```

</br>

An Async SDK client can also be used to make asynchronous requests by importing it and asyncio.

```python
# Asynchronous Example
from albus_sdk import AsyncAlbus
import asyncio
import os

async def main():

    async with AsyncAlbus(
        api_key=os.getenv("ALBUS_API_KEY", ""),
    ) as albus:

        res = await albus.secrets.list_secrets()

        # Handle response
        print(res)

asyncio.run(main())
```
<!-- End Authentication [security] -->

<!-- Start Available Resources and Operations [operations] -->
## Available Resources and Operations

<details open>
<summary>Available methods</summary>

### [Agents](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/agents/README.md)

* [list_agents](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/agents/README.md#list_agents) - List agents
* [get_agent](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/agents/README.md#get_agent) - Get an agent
* [get_agent_revision](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/agents/README.md#get_agent_revision) - Get an agent revision

### [Auth](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/auth/README.md)

* [whoami](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/auth/README.md#whoami) - Get the authenticated caller

### [Billing](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/billing/README.md)

* [create_checkout](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/billing/README.md#create_checkout) - Buy prepaid credits
* [get_credit_balance](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/billing/README.md#get_credit_balance) - Read your credit balance
* [list_credit_ledger](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/billing/README.md#list_credit_ledger) - List your credit history
* [get_spend](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/billing/README.md#get_spend) - Get your spend breakdown

### [Health](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/health/README.md)

* [health](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/health/README.md#health) - Check service health

### [Invites](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/invites/README.md)

* [list_invites](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/invites/README.md#list_invites) - List pending invitations
* [create_invite](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/invites/README.md#create_invite) - Invite a user by email
* [revoke_invite](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/invites/README.md#revoke_invite) - Revoke a pending invitation

### [Memories](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/memories/README.md)

* [list_memory_groups](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/memories/README.md#list_memory_groups) - List memory groups
* [list_memories](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/memories/README.md#list_memories) - List a group's memories
* [delete_memory_group](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/memories/README.md#delete_memory_group) - Delete a group's memories
* [delete_memory](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/memories/README.md#delete_memory) - Delete one memory

### [Models](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/models/README.md)

* [list_models](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/models/README.md#list_models) - List models

### [Organization](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/organizationsdk/README.md)

* [get_organization](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/organizationsdk/README.md#get_organization) - Get the current organization
* [update_organization](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/organizationsdk/README.md#update_organization) - Rename the current organization
* [list_organization_members](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/organizationsdk/README.md#list_organization_members) - List organization members
* [remove_organization_member](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/organizationsdk/README.md#remove_organization_member) - Remove an organization member
* [set_organization_member_role](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/organizationsdk/README.md#set_organization_member_role) - Set an organization member's role

### [Secrets](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/secrets/README.md)

* [list_secrets](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/secrets/README.md#list_secrets) - List secrets
* [create_secret](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/secrets/README.md#create_secret) - Create a secret
* [get_secret](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/secrets/README.md#get_secret) - Get a secret
* [update_secret](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/secrets/README.md#update_secret) - Update a secret
* [delete_secret](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/secrets/README.md#delete_secret) - Delete a secret

### [Sessions](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md)

* [list_sessions](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md#list_sessions) - List sessions
* [get_session](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md#get_session) - Get a session with its messages
* [run_session](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md#run_session) - Run or resume a session
* [delete_session](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md#delete_session) - Delete a session
* [cancel_session](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md#cancel_session) - Cancel a session's running invocation
* [get_session_audit](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/sessions/README.md#get_session_audit) - List a session's audit log

### [Tokens](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/tokens/README.md)

* [list_tokens](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/tokens/README.md#list_tokens) - List API tokens
* [create_token](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/tokens/README.md#create_token) - Create an API token
* [get_token](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/tokens/README.md#get_token) - Get API token metadata
* [delete_token](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/tokens/README.md#delete_token) - Revoke an API token

### [Traces](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/traces/README.md)

* [list_traces](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/traces/README.md#list_traces) - Search traces
* [get_trace](https://github.com/albusgroup/albus-python/blob/master/docs/sdks/traces/README.md#get_trace) - Get one invocation's trace

</details>
<!-- End Available Resources and Operations [operations] -->

<!-- Start Retries [retries] -->
## Retries

Only `run_session` supports retries. Configure its default retry policy with
`retry_config` when constructing the SDK, or pass `retry_config` directly to a
single `run_session` invocation. Omit it to inherit the SDK default; pass
`None` to disable retries for that invocation.
<!-- End Retries [retries] -->

<!-- Start Error Handling [errors] -->
## Error Handling

[`AlbusError`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/albuserror.py) is the base class for all HTTP error responses. It has the following properties:

| Property           | Type             | Description                                                                             |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------- |
| `err.message`      | `str`            | Error message                                                                           |
| `err.status_code`  | `int`            | HTTP response status code eg `404`                                                      |
| `err.headers`      | `httpx.Headers`  | HTTP response headers                                                                   |
| `err.body`         | `str`            | HTTP body. Can be empty string if no body is returned.                                  |
| `err.raw_response` | `httpx.Response` | Raw HTTP response                                                                       |
| `err.data`         |                  | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |

### Example
```python
# Synchronous Example
from albus_sdk import Albus, errors
import os


with Albus(
    api_key=os.getenv("ALBUS_API_KEY", ""),
) as albus:
    res = None
    try:

        res = albus.secrets.list_secrets()

        # Handle response
        print(res)


    except errors.AlbusError as e:
        # The base class for HTTP error responses
        print(e.message)
        print(e.status_code)
        print(e.body)
        print(e.headers)
        print(e.raw_response)

        # Depending on the method different errors may be thrown
        if isinstance(e, errors.ErrUnauthorized):
            print(e.data.message)  # str
```

</br>

An Async SDK client can also be used to make asynchronous requests by importing it and asyncio.

```python
# Asynchronous Example
from albus_sdk import AsyncAlbus, errors
import asyncio
import os

async def main():

    async with AsyncAlbus(
        api_key=os.getenv("ALBUS_API_KEY", ""),
    ) as albus:
        res = None
        try:

            res = await albus.secrets.list_secrets()

            # Handle response
            print(res)


            except errors.AlbusError as e:
                # The base class for HTTP error responses
                print(e.message)
                print(e.status_code)
                print(e.body)
                print(e.headers)
                print(e.raw_response)

                # Depending on the method different errors may be thrown
                if isinstance(e, errors.ErrUnauthorized):
                    print(e.data.message)  # str

asyncio.run(main())
```

### Error Classes
**Primary errors:**
* [`AlbusError`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/albuserror.py): The base class for HTTP error responses.
  * [`ErrUnauthorized`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errunauthorized.py): Status code `401`. *

<details><summary>Less common errors (16)</summary>

<br />

**Network errors:**
* [`httpx.RequestError`](https://www.python-httpx.org/exceptions/#httpx.RequestError): Base class for request errors.
    * [`httpx.ConnectError`](https://www.python-httpx.org/exceptions/#httpx.ConnectError): HTTP client was unable to make a request to a server.
    * [`httpx.TimeoutException`](https://www.python-httpx.org/exceptions/#httpx.TimeoutException): HTTP request timed out.


**Inherit from [`AlbusError`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/albuserror.py)**:
* [`ErrBadRequest`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errbadrequest.py): Status code `400`. Applicable to 20 of 39 methods.*
* [`ErrNotFound`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errnotfound.py): Status code `404`. Applicable to 17 of 39 methods.*
* [`ErrForbidden`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errforbidden.py): Forbidden - the caller is not an admin. Status code `403`. Applicable to 9 of 39 methods.*
* [`ErrConflict`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errconflict.py): Status code `409`. Applicable to 5 of 39 methods.*
* [`ErrUnavailable`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errunavailable.py): Status code `503`. Applicable to 2 of 39 methods.*
* [`ErrInsufficientCredit`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errinsufficientcredit.py): The organization has no credit balance remaining. Status code `402`. Applicable to 1 of 39 methods.*
* [`ErrInvocationCanceled`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errinvocationcanceled.py): The invocation was canceled instead of producing a response (only possible while waiting for a response, or when replaying a canceled invocation). Status code `410`. Applicable to 1 of 39 methods.*
* [`ErrLocked`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errlocked.py): Another invocation is currently running for this session. Status code `423`. Applicable to 1 of 39 methods.*
* [`ErrInvocationFailed`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errinvocationfailed.py): The invocation failed instead of producing a response (only possible while waiting for a response, or when replaying a failed invocation). The body carries the failure kind and detail. Status code `502`. Applicable to 1 of 39 methods.*
* [`HealthResponseError`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/healthresponseerror.py): Service is healthy. Status code `503`. Applicable to 1 of 39 methods.*
* [`ErrTimeout`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/errtimeout.py): Timed out waiting for the assistant response. Status code `504`. Applicable to 1 of 39 methods.*
* [`ResponseValidationError`](https://github.com/albusgroup/albus-python/blob/master/./src/albus_sdk/errors/responsevalidationerror.py): Type mismatch between the response data and the expected Pydantic model. Provides access to the Pydantic validation error via the `cause` attribute.

</details>

\* Check [the method documentation](#available-resources-and-operations) to see if the error is applicable.
<!-- End Error Handling [errors] -->

<!-- Start Server Selection [server] -->
## Server Selection

### Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the `server_url: str` optional parameter when initializing the SDK client instance. For example:
```python
# Synchronous Example
from albus_sdk import Albus
import os


with Albus(
    server_url="https://albus.sh/api/v1",
    api_key=os.getenv("ALBUS_API_KEY", ""),
) as albus:

    res = albus.secrets.list_secrets()

    # Handle response
    print(res)
```

</br>

An Async SDK client can also be used to make asynchronous requests by importing it and asyncio.

```python
# Asynchronous Example
from albus_sdk import AsyncAlbus
import asyncio
import os

async def main():

    async with AsyncAlbus(
        server_url="https://albus.sh/api/v1",
        api_key=os.getenv("ALBUS_API_KEY", ""),
    ) as albus:

        res = await albus.secrets.list_secrets()

        # Handle response
        print(res)

asyncio.run(main())
```
<!-- End Server Selection [server] -->

<!-- Start Custom HTTP Client [http-client] -->
## Custom HTTP Client

The Python SDK makes API calls using the [httpx](https://www.python-httpx.org/) HTTP library.  In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with your own HTTP client instance.
Depending on whether you are using the sync or async version of the SDK, you can pass an instance of `HttpClient` or `AsyncHttpClient` respectively, which are Protocol's ensuring that the client has the necessary methods to make API calls.
This allows you to wrap the client with your own custom logic, such as adding custom headers, logging, or error handling, or you can just pass an instance of `httpx.Client` or `httpx.AsyncClient` directly.

For example, you could specify a header for every request that this sdk makes as follows:
```python
from albus_sdk import Albus
import httpx

http_client = httpx.Client(headers={"x-custom-header": "someValue"})
s = Albus(client=http_client)
```

or you could wrap the client with your own custom logic:
```python
from albus_sdk import Albus
from albus_sdk.httpclient import AsyncHttpClient
import httpx

class CustomClient(AsyncHttpClient):
    client: AsyncHttpClient

    def __init__(self, client: AsyncHttpClient):
        self.client = client

    async def send(
        self,
        request: httpx.Request,
        *,
        stream: bool = False,
        auth: Union[
            httpx._types.AuthTypes, httpx._client.UseClientDefault, None
        ] = httpx.USE_CLIENT_DEFAULT,
        follow_redirects: Union[
            bool, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
    ) -> httpx.Response:
        request.headers["Client-Level-Header"] = "added by client"

        return await self.client.send(
            request, stream=stream, auth=auth, follow_redirects=follow_redirects
        )

    def build_request(
        self,
        method: str,
        url: httpx._types.URLTypes,
        *,
        content: Optional[httpx._types.RequestContent] = None,
        data: Optional[httpx._types.RequestData] = None,
        files: Optional[httpx._types.RequestFiles] = None,
        json: Optional[Any] = None,
        params: Optional[httpx._types.QueryParamTypes] = None,
        headers: Optional[httpx._types.HeaderTypes] = None,
        cookies: Optional[httpx._types.CookieTypes] = None,
        timeout: Union[
            httpx._types.TimeoutTypes, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
        extensions: Optional[httpx._types.RequestExtensions] = None,
    ) -> httpx.Request:
        return self.client.build_request(
            method,
            url,
            content=content,
            data=data,
            files=files,
            json=json,
            params=params,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            extensions=extensions,
        )

s = Albus(async_client=CustomClient(httpx.AsyncClient()))
```
<!-- End Custom HTTP Client [http-client] -->

<!-- Start Resource Management [resource-management] -->
## Resource Management

The `Albus` and `AsyncAlbus` classes implement the context manager protocol and register finalizer functions to close the underlying HTTPX clients they use under the hood. This will close HTTP connections, release memory and free up other resources held by the SDKs. In short-lived Python programs and notebooks that make a few SDK method calls, resource management may not be a concern. However, in longer-lived programs, it is beneficial to create SDK instances via [context managers][context-manager] and reuse them across the application.

[context-manager]: https://docs.python.org/3/reference/datamodel.html#context-managers

```python
from albus_sdk import Albus, AsyncAlbus
import os
def main():

    with Albus(
        api_key=os.getenv("ALBUS_API_KEY", ""),
    ) as albus:
        # Rest of application here...


# Or when using async:
async def amain():

    async with AsyncAlbus(
        api_key=os.getenv("ALBUS_API_KEY", ""),
    ) as albus:
        # Rest of application here...
```
<!-- End Resource Management [resource-management] -->

<!-- Start Debugging [debug] -->
## Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass your own logger class directly into your SDK.
```python
from albus_sdk import Albus
import logging

logging.basicConfig(level=logging.DEBUG)
s = Albus(debug_logger=logging.getLogger("albus_sdk"))
```

You can also enable a default debug logger by setting an environment variable `ALBUS_DEBUG` to true.
<!-- End Debugging [debug] -->

<!-- Placeholder for Future Speakeasy SDK Sections -->

# Development

## Regeneration

Regeneration requires `uv`, Speakeasy authentication, and the Speakeasy CLI
version pinned in `.speakeasy/workflow.yaml`.

Run the generator with the SDK version to produce:

```bash
./tools/generate 0.1.0
```

The source is the authoritative `api/openapi.yaml` in the Albus repository,
where this SDK is developed; pass a path as a second argument only to preview
against a different specification.

The command copies the exact specification snapshot into this repository,
generates the SDK without uploading the specification, normalizes known
generator metadata, and runs the complete local check. Review and commit the
specification, generated code, documentation, and lock files together.

## Checks

Install `uv` and the pinned Speakeasy CLI, then run the complete local check:

```bash
./tools/check
```

This lints the OpenAPI snapshot, checks the generated package with MyPy and
Pyright, runs the handwritten tests, builds both package formats, validates
their metadata, and installs the wheel on Python 3.10 and 3.14.

## Releases

Publishing is manual during the MVP. Follow [RELEASING.md](https://github.com/albusgroup/albus-python/blob/master/RELEASING.md) to
validate and publish a generated version with the guarded local script.

## Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage
to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally
looking for the latest version.

## Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation.
We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

### SDK Created by [Speakeasy](https://www.speakeasy.com/?utm_source=albus-sdk&utm_campaign=python)
