Typed REST Client
=================

:class:`taimoe.platform.TaimoeClient` provides synchronous and asynchronous
operations through one client class. Async methods use the ``*_async`` suffix.

.. code-block:: python

   from taimoe.platform import TaimoeClient

   with TaimoeClient(
       base_url="https://platform.example.com",
       api_key="...",
       org="acme",
       timeout=10,
       max_retries=2,
   ) as client:
       knowledge_bases = client.knowledge_bases.list(team="support")
       config = client.agents.get_runtime_config_by_name("support")

.. code-block:: python

   async with TaimoeClient(
       base_url="https://platform.example.com", api_key="..."
   ) as client:
       knowledge_bases = await client.knowledge_bases.list_async(team="support")

Resources
---------

.. list-table::
   :header-rows: 1

   * - Resource
     - Operations
   * - ``client.agents``
     - Fetch runtime config, create Agents, bind or unbind Knowledge Bases.
   * - ``client.runtimes``
     - Pull Runtime-scoped Agent configuration.
   * - ``client.knowledge_bases``
     - List, resolve by slug, and run a test query.
   * - ``client.observability``
     - Submit one span or a span batch.

Retry and correlation
---------------------

The client reuses sync and async HTTP connection pools. It generates an
``X-Request-ID`` for every request and retries network errors plus retryable
HTTP responses with bounded exponential backoff. ``Retry-After`` is honored up
to the SDK maximum delay. Set ``max_retries=0`` to fail after the first attempt.

Canonical errors
----------------

HTTP and transport failures are converted into ``TaimoeAPIError`` subclasses,
including authentication, permission, validation, rate limit, deadline,
not-found, conflict, and service-unavailable errors. Canonical response codes
take precedence over HTTP status when both are available. Error strings retain
status and request ID for support correlation.

The resource client includes Console-management operations that may not be part
of the curated Public REST API contract. Treat the SDK's Alpha status and your
Platform version as compatibility requirements; pin a minor version in
production.