z4j-fastapi 1.0.0__py3-none-any.whl

z4j_fastapi/__init__.py

@@ -0,0 +1,53 @@
+"""z4j-fastapi - FastAPI framework adapter for z4j.
+
+Public API:
+
+- :func:`z4j_lifespan` - returns a lifespan context manager that starts
+  and stops the z4j agent. Pass it to ``FastAPI(lifespan=...)``.
+- :func:`install_z4j` - manual install for apps that cannot use lifespan.
+- :func:`get_runtime` - retrieve the running agent runtime.
+- :class:`FastAPIFrameworkAdapter` - the framework adapter implementation.
+
+Typical usage (lifespan, recommended)::
+
+    from fastapi import FastAPI
+    from z4j_fastapi import z4j_lifespan
+
+    app = FastAPI(lifespan=z4j_lifespan(
+        brain_url="http://localhost:7700",
+        token="your-token",
+    ))
+
+Licensed under Apache License 2.0.
+"""
+
+from __future__ import annotations
+
+from z4j_fastapi.extension import get_runtime, install_z4j, z4j_lifespan
+from z4j_fastapi.framework import FastAPIFrameworkAdapter
+
+# Importing ``z4j_celery`` (if installed) registers the Celery
+# ``worker_init`` signal handler that auto-bootstraps the agent
+# inside Celery worker processes. Without this, FastAPI apps that
+# run their Celery workers via ``celery -A app:celery_app worker``
+# never register as z4j agents - the lifespan only fires under
+# uvicorn, not under the Celery worker command.
+#
+# This mirrors the Django AppConfig's auto-bootstrap behaviour so
+# FastAPI workers are first-class citizens in the agent registry.
+# If z4j_celery is not installed, the import is silently skipped
+# and nothing changes.
+try:
+    import z4j_celery  # noqa: F401  (imported for its side-effects)
+except ImportError:
+    pass
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "FastAPIFrameworkAdapter",
+    "__version__",
+    "get_runtime",
+    "install_z4j",
+    "z4j_lifespan",
+]

z4j_fastapi/extension.py

@@ -0,0 +1,376 @@
+"""FastAPI integration entry points.
+
+Provides two usage patterns for wiring z4j into a FastAPI application:
+
+**Pattern 1 - lifespan (recommended)**::
+
+    from fastapi import FastAPI
+    from z4j_fastapi import z4j_lifespan
+
+    app = FastAPI(lifespan=z4j_lifespan(
+        brain_url="http://localhost:7700",
+        token="your-token",
+        celery_app=celery_app,
+    ))
+
+**Pattern 2 - manual install**::
+
+    from fastapi import FastAPI
+    from z4j_fastapi import install_z4j
+
+    app = FastAPI()
+    install_z4j(app, brain_url="http://localhost:7700", token="your-token")
+
+Both patterns wrap all z4j work in try/except so that a failure inside
+z4j never crashes the FastAPI application. The host app is more
+important than our observability tool.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from z4j_bare.runtime import AgentRuntime
+
+from z4j_fastapi.framework import (
+    FastAPIFrameworkAdapter,
+    discover_engines,
+    discover_schedulers,
+    resolve_config,
+)
+
+logger = logging.getLogger("z4j.agent.fastapi.extension")
+
+# Module-level state - there is at most one runtime per process.
+_runtime: AgentRuntime | None = None
+
+
+def z4j_lifespan(
+    *,
+    brain_url: str | None = None,
+    token: str | None = None,
+    project_id: str | None = None,
+    celery_app: Any = None,
+    hmac_secret: str | None = None,
+    environment: str | None = None,
+    transport: str | None = None,
+    log_level: str | None = None,
+    engines: list[str] | None = None,
+    schedulers: list[str] | None = None,
+    tags: dict[str, str] | None = None,
+    dev_mode: bool | None = None,
+    strict_mode: bool | None = None,
+    autostart: bool | None = None,
+    heartbeat_seconds: int | None = None,
+    buffer_path: str | Path | None = None,
+    buffer_max_events: int | None = None,
+    buffer_max_bytes: int | None = None,
+    max_payload_bytes: int | None = None,
+    inner_lifespan: Callable[..., Any] | None = None,
+) -> Callable[..., AsyncIterator[None]]:
+    """Return a lifespan context manager that starts and stops z4j.
+
+    This is the recommended integration pattern for FastAPI >= 0.135.
+    Pass the return value directly to ``FastAPI(lifespan=...)``.
+
+    If the application already has its own lifespan, pass it as
+    ``inner_lifespan`` and z4j will wrap it::
+
+        app = FastAPI(lifespan=z4j_lifespan(
+            brain_url="...",
+            token="...",
+            inner_lifespan=my_existing_lifespan,
+        ))
+
+    Args:
+        brain_url: URL of the z4j brain.
+        token: Project-scoped bearer token.
+        project_id: Project slug (default ``"default"``).
+        celery_app: The Celery application instance, if using Celery.
+        hmac_secret: Shared HMAC secret for command verification.
+        environment: Environment label (e.g. ``"production"``).
+        transport: Transport mode (``"auto"``, ``"ws"``, ``"longpoll"``).
+        log_level: Agent log level.
+        engines: Engine adapter names to register.
+        schedulers: Scheduler adapter names to register.
+        tags: Per-deployment tags.
+        dev_mode: Enable development mode.
+        strict_mode: Fail fast on config problems.
+        autostart: Whether the runtime starts automatically.
+        heartbeat_seconds: Heartbeat interval.
+        buffer_path: On-disk SQLite buffer path.
+        buffer_max_events: Max buffered events.
+        buffer_max_bytes: Max buffer file size.
+        max_payload_bytes: Per-field truncation limit.
+        inner_lifespan: An existing lifespan to compose with.
+
+    Returns:
+        An async context manager suitable for ``FastAPI(lifespan=...)``.
+    """
+    config_kwargs: dict[str, Any] = {}
+    # Collect all non-None config kwargs.
+    _set_if_not_none(config_kwargs, "brain_url", brain_url)
+    _set_if_not_none(config_kwargs, "token", token)
+    _set_if_not_none(config_kwargs, "project_id", project_id)
+    _set_if_not_none(config_kwargs, "hmac_secret", hmac_secret)
+    _set_if_not_none(config_kwargs, "environment", environment)
+    _set_if_not_none(config_kwargs, "transport", transport)
+    _set_if_not_none(config_kwargs, "log_level", log_level)
+    _set_if_not_none(config_kwargs, "engines", engines)
+    _set_if_not_none(config_kwargs, "schedulers", schedulers)
+    _set_if_not_none(config_kwargs, "tags", tags)
+    _set_if_not_none(config_kwargs, "dev_mode", dev_mode)
+    _set_if_not_none(config_kwargs, "strict_mode", strict_mode)
+    _set_if_not_none(config_kwargs, "autostart", autostart)
+    _set_if_not_none(config_kwargs, "heartbeat_seconds", heartbeat_seconds)
+    _set_if_not_none(config_kwargs, "buffer_path", buffer_path)
+    _set_if_not_none(config_kwargs, "buffer_max_events", buffer_max_events)
+    _set_if_not_none(config_kwargs, "buffer_max_bytes", buffer_max_bytes)
+    _set_if_not_none(config_kwargs, "max_payload_bytes", max_payload_bytes)
+
+    @asynccontextmanager
+    async def _lifespan(app: Any) -> AsyncIterator[None]:
+        # Start z4j - wrapped so failures never crash the FastAPI app.
+        runtime = _safe_start(config_kwargs, celery_app)
+
+        try:
+            if inner_lifespan is not None:
+                async with inner_lifespan(app):
+                    yield
+            else:
+                yield
+        finally:
+            # Stop z4j on shutdown.
+            _safe_stop(runtime)
+
+    return _lifespan
+
+
+def install_z4j(
+    app: Any,
+    *,
+    brain_url: str | None = None,
+    token: str | None = None,
+    project_id: str | None = None,
+    celery_app: Any = None,
+    hmac_secret: str | None = None,
+    environment: str | None = None,
+    transport: str | None = None,
+    log_level: str | None = None,
+    engines: list[str] | None = None,
+    schedulers: list[str] | None = None,
+    tags: dict[str, str] | None = None,
+    dev_mode: bool | None = None,
+    strict_mode: bool | None = None,
+    autostart: bool | None = None,
+    heartbeat_seconds: int | None = None,
+    buffer_path: str | Path | None = None,
+    buffer_max_events: int | None = None,
+    buffer_max_bytes: int | None = None,
+    max_payload_bytes: int | None = None,
+) -> AgentRuntime | None:
+    """Install z4j agent into a FastAPI app (manual pattern).
+
+    This is the fallback pattern for applications that cannot use the
+    lifespan approach (e.g. because of legacy code). It starts the
+    runtime immediately and registers an ``atexit`` hook to stop it
+    when the process exits.
+
+    Audit H16: this path now hooks BOTH ``app.add_event_handler
+    ("shutdown", ...)`` AND ``atexit``. The shutdown event handler
+    is what fires under uvicorn / gunicorn's graceful SIGTERM
+    handling (i.e. K8s rolling restarts); ``atexit`` is the
+    fallback for processes that exit without ASGI lifespan
+    teardown. Either path runs the same ``runtime.stop(...)`` so
+    buffered events flush before the process dies.
+
+    Args:
+        app: The FastAPI application instance. Stored on ``app.state.z4j_runtime``
+             for access by middleware or route handlers.
+        brain_url: URL of the z4j brain.
+        token: Project-scoped bearer token.
+        project_id: Project slug.
+        celery_app: The Celery application instance, if using Celery.
+        hmac_secret: Shared HMAC secret for command verification.
+        environment: Environment label.
+        transport: Transport mode.
+        log_level: Agent log level.
+        engines: Engine adapter names.
+        schedulers: Scheduler adapter names.
+        tags: Per-deployment tags.
+        dev_mode: Enable development mode.
+        strict_mode: Fail fast on config problems.
+        autostart: Whether the runtime starts automatically.
+        heartbeat_seconds: Heartbeat interval.
+        buffer_path: On-disk SQLite buffer path.
+        buffer_max_events: Max buffered events.
+        buffer_max_bytes: Max buffer file size.
+        max_payload_bytes: Per-field truncation limit.
+
+    Returns:
+        The running AgentRuntime, or None if startup failed.
+    """
+    config_kwargs: dict[str, Any] = {}
+    _set_if_not_none(config_kwargs, "brain_url", brain_url)
+    _set_if_not_none(config_kwargs, "token", token)
+    _set_if_not_none(config_kwargs, "project_id", project_id)
+    _set_if_not_none(config_kwargs, "hmac_secret", hmac_secret)
+    _set_if_not_none(config_kwargs, "environment", environment)
+    _set_if_not_none(config_kwargs, "transport", transport)
+    _set_if_not_none(config_kwargs, "log_level", log_level)
+    _set_if_not_none(config_kwargs, "engines", engines)
+    _set_if_not_none(config_kwargs, "schedulers", schedulers)
+    _set_if_not_none(config_kwargs, "tags", tags)
+    _set_if_not_none(config_kwargs, "dev_mode", dev_mode)
+    _set_if_not_none(config_kwargs, "strict_mode", strict_mode)
+    _set_if_not_none(config_kwargs, "autostart", autostart)
+    _set_if_not_none(config_kwargs, "heartbeat_seconds", heartbeat_seconds)
+    _set_if_not_none(config_kwargs, "buffer_path", buffer_path)
+    _set_if_not_none(config_kwargs, "buffer_max_events", buffer_max_events)
+    _set_if_not_none(config_kwargs, "buffer_max_bytes", buffer_max_bytes)
+    _set_if_not_none(config_kwargs, "max_payload_bytes", max_payload_bytes)
+
+    runtime = _safe_start(config_kwargs, celery_app)
+    if runtime is not None:
+        # Stash on the app so middleware/routes can reach the runtime.
+        app.state.z4j_runtime = runtime
+        atexit.register(_atexit_stop)
+
+        # Audit H16: also hook the FastAPI shutdown event so SIGTERM
+        # under uvicorn / gunicorn / k8s gets a clean stop with
+        # buffer flush. The handler is best-effort; an exception
+        # here must never block the ASGI shutdown.
+        async def _on_app_shutdown() -> None:
+            try:
+                _safe_stop(runtime)
+            except Exception:  # noqa: BLE001
+                logger.exception(
+                    "z4j: error during FastAPI shutdown handler",
+                )
+
+        try:
+            app.add_event_handler("shutdown", _on_app_shutdown)
+        except Exception:  # noqa: BLE001
+            # Some FastAPI subclasses or test doubles may not
+            # support add_event_handler. Fall back to atexit only.
+            logger.debug(
+                "z4j: app.add_event_handler unavailable, "
+                "atexit-only shutdown",
+            )
+
+    return runtime
+
+
+def get_runtime() -> AgentRuntime | None:
+    """Return the running agent runtime, if any.
+
+    Used by tests and by application code that wants to flush the
+    buffer manually or check the runtime state.
+    """
+    return _runtime
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _safe_start(
+    config_kwargs: dict[str, Any],
+    celery_app: Any,
+) -> AgentRuntime | None:
+    """Build and start the runtime, catching all errors.
+
+    Returns the running runtime, or None if anything went wrong. Never
+    raises - z4j must not crash the host application.
+    """
+    # Allow tests and tooling to disable the autostart entirely.
+    if os.environ.get("Z4J_DISABLED", "").lower() in ("1", "true", "yes", "on"):
+        logger.info("z4j: Z4J_DISABLED is set; skipping agent startup")
+        return None
+
+    global _runtime
+    if _runtime is not None:
+        return _runtime  # already started in this process
+
+    try:
+        runtime = _build_and_start_runtime(config_kwargs, celery_app)
+    except Exception:  # noqa: BLE001
+        logger.exception("z4j: failed to start agent runtime; continuing without it")
+        return None
+
+    # Cooperate with other in-process install paths (e.g. a Celery
+    # worker_init signal in the same process also tries to install).
+    # Whoever registered first keeps the live WebSocket; we drop our
+    # freshly-built runtime if we lost the race.
+    from z4j_bare._process_singleton import try_register
+    active = try_register(runtime, owner="z4j_fastapi.extension")
+    if active is not runtime:
+        # We built + started a runtime, then lost the race. Stop
+        # the local copy so we don't leak a zombie WS connection.
+        try:
+            runtime.stop(timeout=2.0)
+        except Exception:  # noqa: BLE001
+            logger.exception("z4j: error stopping duplicate runtime")
+        _runtime = active
+        return active
+
+    _runtime = runtime
+    logger.info("z4j: agent runtime started for fastapi")
+    return runtime
+
+
+def _build_and_start_runtime(
+    config_kwargs: dict[str, Any],
+    celery_app: Any,
+) -> AgentRuntime:
+    """Resolve config, discover adapters, build the runtime, start it."""
+    config = resolve_config(**config_kwargs)
+    framework = FastAPIFrameworkAdapter(config)
+    engine_list = discover_engines(celery_app)
+    scheduler_list = discover_schedulers(celery_app)
+
+    runtime = AgentRuntime(
+        config=config,
+        framework=framework,
+        engines=engine_list,
+        schedulers=scheduler_list,
+    )
+    if config.autostart:
+        runtime.start()
+        framework.fire_startup()
+    return runtime
+
+
+def _safe_stop(runtime: AgentRuntime | None) -> None:
+    """Stop the runtime, swallowing errors. Never raises."""
+    global _runtime
+    if runtime is None:
+        return
+    try:
+        runtime.stop(timeout=5.0)
+    except Exception:  # noqa: BLE001
+        logger.exception("z4j: error during shutdown")
+    finally:
+        if _runtime is runtime:
+            _runtime = None
+
+
+def _atexit_stop() -> None:
+    """``atexit`` handler that flushes the buffer and stops the runtime."""
+    _safe_stop(_runtime)
+
+
+def _set_if_not_none(d: dict[str, Any], key: str, value: Any) -> None:
+    """Set ``d[key] = value`` only if ``value is not None``."""
+    if value is not None:
+        d[key] = value
+
+
+__all__ = ["get_runtime", "install_z4j", "z4j_lifespan"]

z4j_fastapi/framework.py

@@ -0,0 +1,381 @@
+"""The :class:`FastAPIFrameworkAdapter`.
+
+Implements :class:`z4j_core.protocols.FrameworkAdapter` for FastAPI.
+The adapter is constructed inside :func:`extension.install_z4j` or
+:func:`extension.z4j_lifespan`, which resolve configuration from
+explicit kwargs and environment variables, then hand the resulting
+Config to the adapter and the agent runtime.
+
+FastAPI has no app-level settings dict like Django's ``settings.Z4J``.
+Configuration comes from either:
+
+1. Explicit kwargs passed to ``install_z4j`` / ``z4j_lifespan``
+2. ``Z4J_*`` environment variables (same names as the Django adapter)
+3. Defaults declared on :class:`z4j_core.models.Config`
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from z4j_core.errors import ConfigError
+from z4j_core.models import Config, DiscoveryHints, RequestContext, User
+
+logger = logging.getLogger("z4j.agent.fastapi.framework")
+
+
+class FastAPIFrameworkAdapter:
+    """Framework adapter for FastAPI.
+
+    Implements the :class:`FrameworkAdapter` Protocol via duck typing
+    (no inheritance - see ``docs/patterns.md``). Lifecycle hooks are
+    stored as plain lists; :meth:`fire_startup` and :meth:`fire_shutdown`
+    invoke them when called by the extension module.
+
+    Attributes:
+        name: Always ``"fastapi"``.
+        _config: The resolved :class:`Config` for this process.
+    """
+
+    name: str = "fastapi"
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._startup_hooks: list[Callable[[], None]] = []
+        self._shutdown_hooks: list[Callable[[], None]] = []
+
+    # ------------------------------------------------------------------
+    # FrameworkAdapter Protocol
+    # ------------------------------------------------------------------
+
+    def discover_config(self) -> Config:
+        return self._config
+
+    def discovery_hints(self) -> DiscoveryHints:
+        return DiscoveryHints(framework_name="fastapi")
+
+    def current_context(self) -> RequestContext | None:
+        # FastAPI does not have a global "current request" by default.
+        # A future middleware could stash the Starlette request on a
+        # ContextVar (like the Django adapter does). For now, return
+        # None - the agent handles this gracefully.
+        return None
+
+    def current_user(self) -> User | None:
+        # Same rationale as current_context - no global user context
+        # in FastAPI without explicit middleware.
+        return None
+
+    def on_startup(self, hook: Callable[[], None]) -> None:
+        self._startup_hooks.append(hook)
+
+    def on_shutdown(self, hook: Callable[[], None]) -> None:
+        self._shutdown_hooks.append(hook)
+
+    def register_admin_view(self, view: Any) -> None:  # noqa: ARG002
+        # No-op. FastAPI does not have a built-in admin panel.
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers used by the extension module
+    # ------------------------------------------------------------------
+
+    def fire_startup(self) -> None:
+        """Invoke every registered startup hook in order.
+
+        Called once after the agent runtime has connected. Exceptions
+        from individual hooks are caught and logged so a single bad
+        hook does not abort the others.
+        """
+        for hook in self._startup_hooks:
+            try:
+                hook()
+            except Exception:  # noqa: BLE001
+                logger.exception("z4j fastapi startup hook failed")
+
+    def fire_shutdown(self) -> None:
+        """Invoke every registered shutdown hook in order.
+
+        Called once during application shutdown. Same exception
+        semantics as :meth:`fire_startup`.
+        """
+        for hook in self._shutdown_hooks:
+            try:
+                hook()
+            except Exception:  # noqa: BLE001
+                logger.exception("z4j fastapi shutdown hook failed")
+
+
+# ---------------------------------------------------------------------------
+# Configuration resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_config(
+    *,
+    brain_url: str | None = None,
+    token: str | None = None,
+    project_id: str | None = None,
+    hmac_secret: str | None = None,
+    environment: str | None = None,
+    transport: str | None = None,
+    log_level: str | None = None,
+    engines: list[str] | None = None,
+    schedulers: list[str] | None = None,
+    tags: dict[str, str] | None = None,
+    dev_mode: bool | None = None,
+    strict_mode: bool | None = None,
+    autostart: bool | None = None,
+    heartbeat_seconds: int | None = None,
+    buffer_path: str | Path | None = None,
+    buffer_max_events: int | None = None,
+    buffer_max_bytes: int | None = None,
+    max_payload_bytes: int | None = None,
+) -> Config:
+    """Build a :class:`Config` from explicit kwargs and environment variables.
+
+    Resolution priority (highest first):
+
+    1. Explicit keyword arguments (passed to ``install_z4j`` / ``z4j_lifespan``)
+    2. ``Z4J_*`` environment variables
+    3. Defaults declared on :class:`z4j_core.models.Config`
+
+    Raises:
+        ConfigError: Required values are missing or invalid.
+    """
+    from pydantic import ValidationError
+
+    env = os.environ
+    resolved: dict[str, Any] = {}
+
+    # Required fields — explicit kwarg takes priority over env var.
+    # Use ``is not None`` so an operator who passes an explicit
+    # empty string fails the non-empty required-field check below
+    # instead of silently sliding onto the env fallback. A falsy
+    # ``or`` would have treated ``brain_url=""`` the same as
+    # ``brain_url=None`` (not passed) — surfaced by audit pass 8
+    # 2026-04-21.
+    r_brain_url = brain_url if brain_url is not None else env.get("Z4J_BRAIN_URL")
+    r_token = token if token is not None else env.get("Z4J_TOKEN")
+    r_project_id = project_id if project_id is not None else env.get("Z4J_PROJECT_ID")
+
+    missing: list[str] = []
+    if not r_brain_url:
+        missing.append("brain_url (or Z4J_BRAIN_URL)")
+    if not r_token:
+        missing.append("token (or Z4J_TOKEN)")
+    if not r_project_id:
+        missing.append("project_id (or Z4J_PROJECT_ID)")
+    if missing:
+        raise ConfigError(
+            "missing required Z4J settings: " + ", ".join(missing),
+            details={"missing": missing},
+        )
+
+    resolved["brain_url"] = r_brain_url
+    resolved["token"] = r_token
+    resolved["project_id"] = r_project_id
+
+    # HMAC secret — same ``is not None`` discipline as the
+    # required fields. Explicit ``hmac_secret=""`` means the
+    # caller is deliberately opting out; we do not quietly
+    # rescue with an env fallback.
+    r_hmac_secret = (
+        hmac_secret if hmac_secret is not None else env.get("Z4J_HMAC_SECRET")
+    )
+    if r_hmac_secret:
+        resolved["hmac_secret"] = r_hmac_secret
+
+    # Optional string fields - kwarg > env > omit (use Config default)
+    _maybe_set_str(resolved, "environment", environment, env, "Z4J_ENVIRONMENT")
+    _maybe_set_str(resolved, "transport", transport, env, "Z4J_TRANSPORT")
+    _maybe_set_str(resolved, "log_level", log_level, env, "Z4J_LOG_LEVEL")
+
+    # List fields
+    if engines is not None:
+        resolved["engines"] = engines
+    elif "Z4J_ENGINES" in env:
+        resolved["engines"] = [
+            x.strip() for x in env["Z4J_ENGINES"].split(",") if x.strip()
+        ]
+
+    if schedulers is not None:
+        resolved["schedulers"] = schedulers
+    elif "Z4J_SCHEDULERS" in env:
+        resolved["schedulers"] = [
+            x.strip() for x in env["Z4J_SCHEDULERS"].split(",") if x.strip()
+        ]
+
+    # Tags
+    if tags is not None:
+        resolved["tags"] = tags
+
+    # Booleans
+    _maybe_set_bool(resolved, "dev_mode", dev_mode, env, "Z4J_DEV_MODE")
+    _maybe_set_bool(resolved, "strict_mode", strict_mode, env, "Z4J_STRICT_MODE")
+    _maybe_set_bool(resolved, "autostart", autostart, env, "Z4J_AUTOSTART")
+
+    # Integers
+    _maybe_set_int(resolved, "heartbeat_seconds", heartbeat_seconds, env, "Z4J_HEARTBEAT_SECONDS")
+    _maybe_set_int(resolved, "buffer_max_events", buffer_max_events, env, "Z4J_BUFFER_MAX_EVENTS")
+    _maybe_set_int(resolved, "buffer_max_bytes", buffer_max_bytes, env, "Z4J_BUFFER_MAX_BYTES")
+    _maybe_set_int(resolved, "max_payload_bytes", max_payload_bytes, env, "Z4J_MAX_PAYLOAD_BYTES")
+
+    # Path
+    if buffer_path is not None:
+        resolved["buffer_path"] = Path(buffer_path)
+    elif "Z4J_BUFFER_PATH" in env:
+        resolved["buffer_path"] = Path(env["Z4J_BUFFER_PATH"])
+
+    try:
+        return Config(**resolved)
+    except ValidationError as exc:
+        # Redact values from the error message (same pattern as Django adapter).
+        details = [
+            {
+                "loc": ".".join(str(p) for p in err["loc"]),
+                "type": err["type"],
+            }
+            for err in exc.errors()
+        ]
+        raise ConfigError(
+            f"invalid Z4J configuration ({len(details)} field(s))",
+            details={"errors": details},
+        ) from None
+    except (TypeError, ValueError) as exc:
+        raise ConfigError(
+            f"invalid Z4J configuration: {type(exc).__name__}",
+        ) from None
+
+
+# ---------------------------------------------------------------------------
+# Engine / scheduler discovery
+# ---------------------------------------------------------------------------
+
+
+def discover_engines(celery_app: Any = None) -> list[Any]:
+    """Try to import every supported engine adapter and instantiate it.
+
+    If ``celery_app`` is provided explicitly, it is passed straight to
+    the engine adapter. Otherwise, we skip Celery engine discovery -
+    FastAPI does not have a conventional auto-discoverable Celery app
+    like Django does.
+
+    Failure to import an adapter (because ``z4j-celery`` is not
+    installed) is silent - the user simply gets the engines they
+    pip-installed.
+    """
+    engines: list[Any] = []
+
+    celery_engine = _try_import_celery_engine(celery_app)
+    if celery_engine is not None:
+        engines.append(celery_engine)
+
+    if not engines:
+        logger.info(
+            "z4j: no queue engine adapters discovered; the agent will run "
+            "but will not capture task events. Install z4j-celery and pass "
+            "celery_app= to fix.",
+        )
+    return engines
+
+
+def discover_schedulers(celery_app: Any = None) -> list[Any]:
+    """Try to import every supported scheduler adapter."""
+    schedulers: list[Any] = []
+
+    beat = _try_import_celerybeat_scheduler(celery_app)
+    if beat is not None:
+        schedulers.append(beat)
+
+    return schedulers
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _try_import_celery_engine(celery_app: Any) -> Any:
+    """Best-effort import of CeleryEngineAdapter.
+
+    Unlike the Django adapter, FastAPI does not have a convention for
+    where the Celery app lives. The user must pass it explicitly.
+    """
+    if celery_app is None:
+        return None
+
+    try:
+        from z4j_celery.engine import CeleryEngineAdapter
+    except ImportError:
+        logger.warning(
+            "z4j: celery_app was provided but z4j-celery is not installed; "
+            "pip install z4j-celery to enable Celery integration.",
+        )
+        return None
+
+    return CeleryEngineAdapter(celery_app=celery_app)
+
+
+def _try_import_celerybeat_scheduler(celery_app: Any) -> Any:
+    """Best-effort import of CeleryBeatSchedulerAdapter."""
+    try:
+        from z4j_celerybeat.scheduler import CeleryBeatSchedulerAdapter
+    except ImportError:
+        return None
+
+    return CeleryBeatSchedulerAdapter(celery_app=celery_app)
+
+
+def _maybe_set_str(
+    resolved: dict[str, Any],
+    key: str,
+    kwarg_value: str | None,
+    env: os._Environ[str] | dict[str, str],
+    env_key: str,
+) -> None:
+    if kwarg_value is not None:
+        resolved[key] = kwarg_value
+    elif env_key in env:
+        resolved[key] = env[env_key]
+
+
+def _maybe_set_bool(
+    resolved: dict[str, Any],
+    key: str,
+    kwarg_value: bool | None,
+    env: os._Environ[str] | dict[str, str],
+    env_key: str,
+) -> None:
+    if kwarg_value is not None:
+        resolved[key] = kwarg_value
+    elif env_key in env:
+        resolved[key] = env[env_key].strip().lower() in ("1", "true", "yes", "on")
+
+
+def _maybe_set_int(
+    resolved: dict[str, Any],
+    key: str,
+    kwarg_value: int | None,
+    env: os._Environ[str] | dict[str, str],
+    env_key: str,
+) -> None:
+    if kwarg_value is not None:
+        resolved[key] = kwarg_value
+    elif env_key in env:
+        try:
+            resolved[key] = int(env[env_key])
+        except ValueError as exc:
+            raise ConfigError(f"{env_key} must be an integer: {exc}") from exc
+
+
+__all__ = [
+    "FastAPIFrameworkAdapter",
+    "discover_engines",
+    "discover_schedulers",
+    "resolve_config",
+]

z4j_fastapi-1.0.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: z4j-fastapi
+Version: 1.0.0
+Summary: z4j FastAPI framework adapter (Apache 2.0)
+Project-URL: Changelog, https://github.com/z4jdev/z4j-fastapi/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://z4j.dev
+Project-URL: Homepage, https://z4j.com
+Project-URL: Issues, https://github.com/z4jdev/z4j-fastapi/issues
+Project-URL: Source, https://github.com/z4jdev/z4j-fastapi
+Author: z4j contributors
+License: Apache-2.0
+License-File: LICENSE
+Keywords: celery,fastapi,task,z4j
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.135
+Requires-Dist: z4j-bare
+Requires-Dist: z4j-core
+Provides-Extra: celery
+Requires-Dist: z4j-celery; extra == 'celery'
+Description-Content-Type: text/markdown
+
+# z4j-fastapi
+
+[![PyPI version](https://img.shields.io/pypi/v/z4j-fastapi.svg)](https://pypi.org/project/z4j-fastapi/)
+[![Python](https://img.shields.io/pypi/pyversions/z4j-fastapi.svg)](https://pypi.org/project/z4j-fastapi/)
+[![License](https://img.shields.io/pypi/l/z4j-fastapi.svg)](https://github.com/z4jdev/z4j-fastapi/blob/main/LICENSE)
+
+
+**License:** Apache 2.0
+**Status:** v1.0.0 — first public release.
+
+FastAPI framework adapter for [z4j](https://z4j.com). Integrates via
+FastAPI's lifespan hook — one context manager wraps the agent's lifecycle
+with your app's startup and shutdown.
+
+## Install
+
+```bash
+# FastAPI + arq (the most common async-native pairing)
+pip install z4j-fastapi z4j-arq z4j-arqcron
+
+# FastAPI + Celery (when the sync stack is preferred)
+pip install z4j-fastapi z4j-celery z4j-celerybeat
+
+# FastAPI + Dramatiq / RQ / Huey / taskiq — all supported
+pip install z4j-fastapi z4j-dramatiq z4j-apscheduler
+pip install z4j-fastapi z4j-taskiq z4j-taskiqscheduler
+```
+
+## Configure
+
+Mount the z4j lifespan in your FastAPI app:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from z4j_fastapi import Z4JLifespan
+
+z4j = Z4JLifespan(
+    brain_url="https://z4j.internal",
+    token="z4j_agent_...",        # minted in the brain dashboard
+    project_id="my-project",
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with z4j(app):
+        yield
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Or, if you have no other lifespan logic:
+
+```python
+from z4j_fastapi import Z4JLifespan
+
+app = FastAPI(lifespan=Z4JLifespan(
+    brain_url="https://z4j.internal",
+    token="z4j_agent_...",
+    project_id="my-project",
+))
+```
+
+On `uvicorn` startup the agent connects to the brain and z4j's dashboard
+populates with every arq / Celery / Dramatiq / taskiq / Huey task your
+workers register.
+
+## What it does
+
+| Piece | Purpose |
+|---|---|
+| `Z4JLifespan(...)` | Async context manager matching FastAPI's lifespan contract |
+| Graceful shutdown | Flushes the event buffer on `await lifespan.aclose()` |
+| Async-native | Uses `asyncio.create_task` — never blocks the event loop |
+
+## Reliability
+
+`z4j-fastapi` follows the project-wide safety rule: **z4j never breaks
+your FastAPI app**. Agent failures are caught at the boundary and never
+propagate into your request handlers.
+
+## Documentation
+
+- [Quickstart (FastAPI)](https://z4j.dev/getting-started/quickstart-fastapi/)
+- [Install guide](https://z4j.dev/getting-started/install/)
+- [Architecture](https://z4j.dev/concepts/architecture/)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE). Your FastAPI application is never
+AGPL-tainted by importing `z4j_fastapi`.
+
+## Links
+
+- Homepage: <https://z4j.com>
+- Documentation: <https://z4j.dev>
+- Issues: <https://github.com/z4jdev/z4j-fastapi/issues>
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Security: `security@z4j.com` (see [SECURITY.md](SECURITY.md))

z4j_fastapi-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+z4j_fastapi/__init__.py,sha256=_Rg9I_w0U9ukVgVIrDdxr6V6d-LNYRtY8OPk_cFJJQc,1698
+z4j_fastapi/extension.py,sha256=JprMgF6goPaRkHietZdCMRrTcfKS9YSE5bv4dO5o7Wk,13949
+z4j_fastapi/framework.py,sha256=SWbcZ9YaWYdKc9HI6fic7FtbXHvF34Un1nkqTlMTxGw,13052
+z4j_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+z4j_fastapi-1.0.0.dist-info/METADATA,sha256=RA__6cCcfdB-074BWd4WEASYmzJ1r5cie1WI5AG_10c,4003
+z4j_fastapi-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+z4j_fastapi-1.0.0.dist-info/licenses/LICENSE,sha256=JUYyp0BTJLCIDk7IcFrLs93vJUYe8wL_t__I0iUc-8g,11314
+z4j_fastapi-1.0.0.dist-info/RECORD,,

z4j_fastapi-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

z4j_fastapi-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 z4j contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.