Author code plugins

"""A minimal fictional HTTP route plugin.

``@tai42_app.http.custom_route`` registers a Starlette handler and its
self-describing OpenAPI metadata in one call — ``summary``, ``tags``, and
``response_model`` are required so the route describes itself to the API
reference. Load the module under ``routers_modules``.
"""

from starlette.requests import Request
from starlette.responses import JSONResponse, Response
from tai42_contract.app import tai42_app


@tai42_app.http.custom_route(
    "/api/weather/regions",
    methods=["GET"],
    summary="List available weather regions",
    tags=["weather"],
    response_model=None,
)
async def regions(request: Request) -> Response:
    return JSONResponse({"data": ["north", "south"]})

middlewares_modules:
  - your_package.middleware

"""A minimal fictional lifecycle plugin.

Register a handler with ``@tai42_app.lifecycle.on_startup``, ``on_shutdown``, or
``on_reload`` to run code at process startup, shutdown, or after an in-place
reload. An ``on_reload`` handler re-runs after every reload — use it for dynamic
loaders that ``on_startup`` ran once. Load the module under ``lifecycle_modules``.
"""

from tai42_contract.app import tai42_app

_warm: dict[str, str] = {}


@tai42_app.lifecycle.on_startup
def warm_caches() -> None:
    _warm["region_index"] = "loaded"


@tai42_app.lifecycle.on_reload
def reload_caches() -> None:
    _warm["region_index"] = "reloaded"

"""A minimal fictional pooled client.

A pooled client shares one connection per event loop across tool calls. Subclass
the kit's ``PooledClient`` (which implements the contract ``BaseClient``), then
open it through ``tai42_app.clients.client_ctx`` from inside a tool, route, or
lifecycle handler. The context manager yields a connected client, pooled per loop
and connection params (or one-shot with ``fresh=True``).
"""

from tai42_contract.app import tai42_app
from tai42_kit.clients import PooledClient


class GeoConnection:
    """The live connection object the pool hands out."""

    async def lookup(self, name: str) -> str:
        return f"region:{name}"


class GeoClient(PooledClient[GeoConnection]):
    async def _create(self, **kwargs: object) -> GeoConnection:
        return GeoConnection()

    async def _close(self, client: GeoConnection) -> None:
        return None


async def resolve_region(name: str) -> str:
    async with tai42_app.clients.client_ctx(GeoClient) as connection:
        return await connection.lookup(name)