Metadata-Version: 2.4
Name: z4j-fastapi
Version: 1.1.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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.136.0
Requires-Dist: z4j-bare>=1.1.0
Requires-Dist: z4j-core>=1.1.0
Provides-Extra: all
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-arq>=1.0.1; extra == 'all'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'all'
Requires-Dist: z4j-celery>=1.0.2; extra == 'all'
Requires-Dist: z4j-celerybeat>=1.0.2; extra == 'all'
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'all'
Requires-Dist: z4j-huey>=1.0.1; extra == 'all'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'all'
Requires-Dist: z4j-rq>=1.0.1; extra == 'all'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'all'
Provides-Extra: arq
Requires-Dist: z4j-arq>=1.0.1; extra == 'arq'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'arq'
Provides-Extra: celery
Requires-Dist: z4j-celery>=1.0.2; extra == 'celery'
Requires-Dist: z4j-celerybeat>=1.0.2; extra == 'celery'
Provides-Extra: dramatiq
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'dramatiq'
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'dramatiq'
Provides-Extra: huey
Requires-Dist: z4j-huey>=1.0.1; extra == 'huey'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'huey'
Provides-Extra: rq
Requires-Dist: z4j-rq>=1.0.1; extra == 'rq'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'rq'
Provides-Extra: taskiq
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'taskiq'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'taskiq'
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

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

Pick your task engine and install with the matching extra. Each extra
pulls the engine adapter AND its companion scheduler in one shot, so
a fresh install never needs a second command.

```bash
pip install z4j-fastapi[arq]        # arq + arq-cron (async-native, recommended)
pip install z4j-fastapi[taskiq]     # TaskIQ + taskiq-scheduler (async, broker-flexible)
pip install z4j-fastapi[celery]     # Celery + celery-beat (sync stack)
pip install z4j-fastapi[rq]         # RQ + rq-scheduler
pip install z4j-fastapi[dramatiq]   # Dramatiq + APScheduler
pip install z4j-fastapi[huey]       # Huey + huey-periodic
pip install z4j-fastapi[all]        # every engine (CI / kitchen sink)
```

`pip install z4j-fastapi` (no extra) installs only the framework adapter.
That's useful if you already manage engine packages elsewhere; otherwise
always pick an engine extra.

## 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))
