z4j-bare
The framework-free agent runtime for z4j.
Bootstraps a z4j agent inside any Python process, Celery worker, RQ worker, Dramatiq actor, plain script, custom service, and connects it to z4j over an authenticated WebSocket. Used directly when there's no framework adapter (z4j-django / z4j-flask / z4j-fastapi); used indirectly by those framework adapters too.
Compatibility
Python 3.11+. No framework or engine pinned; pair with whichever engine adapter your worker runs (z4j-celery, z4j-rq, z4j-dramatiq, z4j-huey, z4j-arq, z4j-taskiq) and that adapter carries the engine-version floor.
Full per-adapter matrix at https://z4j.dev/reference/compatibility/.
What it ships
- Agent runtime, connect, authenticate, supervise, reconnect with bounded backoff
- Outbound buffer, every event written to a local SQLite ring before going out on the wire; durable across short brain outages and agent restarts
- Engine signal hooks, wired up by whichever engine adapter you install (z4j-celery, z4j-rq, etc.); the runtime drains them into the buffer
- Schedule inventory, emits a full snapshot at boot, on a periodic timer (default 15 min), and on demand from the brain's Sync now command. Existing schedules show up automatically.
- Command dispatcher, receives operator actions from the brain (retry, cancel, restart, schedule.fire, schedule.resync, etc.) and routes them to the right adapter
Install
pip install z4j-bare
Most users install a framework adapter (z4j-django / z4j-flask / z4j-fastapi) which pulls z4j-bare automatically.
Quick start (framework-free worker)
from z4j_bare import install_agent
from z4j_celery import CeleryEngineAdapter
install_agent(
engines=[CeleryEngineAdapter(celery_app=app)],
brain_url="https://brain.example.com",
token="z4j_agent_...",
project_id="my-project",
)
Reliability
- No exception from the agent ever propagates back into your worker / signal handler / request path. Every brain interaction is wrapped in a top-level try/except.
- Events buffer locally when z4j is unreachable. Workers never block on network I/O.
- Supervisor reconnects on every transient failure (network, TLS, protocol mismatch) with bounded backoff.
Documentation
Full docs at z4j.dev/frameworks/bare/.
License
Apache-2.0, see LICENSE.
Links
- Homepage: https://z4j.com
- Documentation: https://z4j.dev
- PyPI: https://pypi.org/project/z4j-bare/
- Issues: https://github.com/z4jdev/z4j-bare/issues
- Changelog: CHANGELOG.md
- Security: security@z4j.com (see SECURITY.md)
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file z4j_bare-1.8.0.tar.gz.
File metadata
- Download URL: z4j_bare-1.8.0.tar.gz
- Upload date:
- Size: 259.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4e6a94047da3be89600f3602566214257d0825b6590a61b6c973737972504b01
|
|
| MD5 |
ae324f566d9c345521ae598e79eacf95
|
|
| BLAKE2b-256 |
e4993253733376649429e8cf0faf3b6526a8b1747d4a9dbb3d823a290e0ed78b
|
File details
Details for the file z4j_bare-1.8.0-py3-none-any.whl.
File metadata
- Download URL: z4j_bare-1.8.0-py3-none-any.whl
- Upload date:
- Size: 183.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1e74b20b5e70641a833eba480fd94b990f99a7b7277b6de7f172abd9469718d0
|
|
| MD5 |
958ad5af3525e59d408cffb9c0db5416
|
|
| BLAKE2b-256 |
3136b8348c3e8eb6415f2ded202730a1aee3ec934786f1051cc7ab6432a8dbf5
|
