Configuration and Sync
======================

Call :func:`taimoe.platform.init` once per process. It creates and binds a
:class:`~taimoe.platform.TaimoeRegistry`, configures observability, performs one
synchronous configuration refresh, starts background polling, and optionally
enables framework instrumentation.

.. code-block:: python

   from taimoe.platform import init

   registry = init(
       platform_url="https://platform.example.com",
       api_key="...",
       runtime_name="support-prod",
       runtime_id="support-prod",
       framework="google-adk",
       poll_interval_seconds=300,
       instrument=True,
   )

Environment variables
---------------------

==========================  =============================================================
Variable                    Purpose
==========================  =============================================================
``TAIMOE_VIRTUAL_KEY``      Preferred Platform and Gateway credential.
``TAIMOE_PLATFORM_URL``     Platform base URL. Production deployments should set it explicitly.
``TAIMOE_RUNTIME_NAME``     Enables runtime-bound batch synchronization.
``TAIMOE_RUNTIME_TOKEN``    Deprecated alias for ``TAIMOE_VIRTUAL_KEY``.
==========================  =============================================================

If no Platform URL is supplied, the SDK uses ``http://localhost:8000`` for local
development. Do not rely on this default in production.

Synchronization modes
---------------------

Runtime-bound
~~~~~~~~~~~~~

Pass ``runtime_name`` when a long-running service has a registered Runtime.
One poll retrieves every active Agent configuration bound to that Runtime.

Runtime-less
~~~~~~~~~~~~

Omit ``runtime_name`` when an application only consumes named Agent
configuration. Calling ``taimoe.agent("support")`` subscribes that name to the
per-Agent syncer. This is suitable for local tools, ``adk web``, and processes
that cannot expose discovery endpoints.

The modes can coexist. A runtime-bound process can still subscribe to an Agent
that is not part of its Runtime batch.

Startup and degraded mode
-------------------------

``init()`` attempts one refresh before returning. If the Platform cannot be
reached, initialization continues and the background syncer retries later.
Instructions use a visible bootstrap message until configuration arrives;
requesting a missing model raises ``TaimoeConfigUnavailableError`` instead of
guessing an alias.

Use ``on_sync_error`` for operational reporting and
``registry.sync_once(ignore_errors=False)`` in CI when synchronization failure
must fail the process. Call ``registry.stop_sync()`` during an orderly shutdown.

Initialization is idempotent: a second call returns the existing Registry and
logs a warning rather than replacing process-wide state.