Metadata-Version: 2.4
Name: z4j-fastapi
Version: 1.6.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<2,>=1.4.0
Requires-Dist: z4j-core<2,>=1.4.0
Provides-Extra: all
Requires-Dist: z4j-apscheduler<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-arq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-arqcron<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-celery<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-celerybeat<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-dramatiq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-huey<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-hueyperiodic<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-rq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-rqscheduler<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-taskiq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-taskiqscheduler<2,>=1.4.0; extra == 'all'
Provides-Extra: arq
Requires-Dist: z4j-arq<2,>=1.4.0; extra == 'arq'
Requires-Dist: z4j-arqcron<2,>=1.4.0; extra == 'arq'
Provides-Extra: celery
Requires-Dist: z4j-celery<2,>=1.4.0; extra == 'celery'
Requires-Dist: z4j-celerybeat<2,>=1.4.0; extra == 'celery'
Provides-Extra: dramatiq
Requires-Dist: z4j-apscheduler<2,>=1.4.0; extra == 'dramatiq'
Requires-Dist: z4j-dramatiq<2,>=1.4.0; extra == 'dramatiq'
Provides-Extra: huey
Requires-Dist: z4j-huey<2,>=1.4.0; extra == 'huey'
Requires-Dist: z4j-hueyperiodic<2,>=1.4.0; extra == 'huey'
Provides-Extra: rq
Requires-Dist: z4j-rq<2,>=1.4.0; extra == 'rq'
Requires-Dist: z4j-rqscheduler<2,>=1.4.0; extra == 'rq'
Provides-Extra: taskiq
Requires-Dist: z4j-taskiq<2,>=1.4.0; extra == 'taskiq'
Requires-Dist: z4j-taskiqscheduler<2,>=1.4.0; extra == 'taskiq'
Description-Content-Type: text/markdown

# z4j-fastapi

[![PyPI version](https://img.shields.io/pypi/v/z4j-fastapi.svg?v=1.4.0)](https://pypi.org/project/z4j-fastapi/)
[![Python](https://img.shields.io/pypi/pyversions/z4j-fastapi.svg?v=1.4.0)](https://pypi.org/project/z4j-fastapi/)
[![License](https://img.shields.io/pypi/l/z4j-fastapi.svg?v=1.4.0)](https://github.com/z4jdev/z4j-fastapi/blob/main/LICENSE)

The FastAPI framework adapter for [z4j](https://z4j.com).

Adds the z4j agent into your FastAPI app via a single `add_z4j(app)`
call. Auto-discovers the engine adapter you have installed (Celery,
RQ, Dramatiq, Huey, arq, TaskIQ) and streams every task lifecycle
event to z4j. Operator control actions flow back the same
channel.

## What it ships

- **One-line install**, `add_z4j(app)` and the agent connects on the
  next uvicorn worker boot
- **Engine auto-discovery**, picks up whichever z4j engine adapter
  is installed alongside; cross-stack combos (FastAPI + arq,
  FastAPI + Celery) are first-class
- **`@z4j_meta` decorator**, optional per-task annotations
  (`priority="critical"`, `description="..."`) for dashboard
  filtering and SLO display
- **Service-user safe**, auto-relocates the local outbound buffer
  to `$TMPDIR/z4j-{uid}` when `$HOME` is unwritable (uvicorn under
  a service account, distroless images, etc.)

## Install

```bash
pip install z4j-fastapi z4j-celery z4j-celerybeat
```

Wire it into your app:

```python
from fastapi import FastAPI
from z4j_fastapi import add_z4j

app = FastAPI()
add_z4j(app)  # reads Z4J_AGENT_TOKEN, Z4J_BRAIN_URL, Z4J_PROJECT from env
```

Mint the agent token from the dashboard's Agents page.

## Reliability

- No exception from the agent ever propagates back into FastAPI
  request handlers or your worker code.
- Events buffer locally when z4j is unreachable; your application
  never blocks on network I/O.

## Documentation

Full docs at [z4j.dev/frameworks/fastapi/](https://z4j.dev/frameworks/fastapi/).

## License

Apache-2.0, see [LICENSE](LICENSE).

## Links

- Homepage: https://z4j.com
- Documentation: https://z4j.dev
- PyPI: https://pypi.org/project/z4j-fastapi/
- Issues: https://github.com/z4jdev/z4j-fastapi/issues
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Security: security@z4j.com (see [SECURITY.md](SECURITY.md))
