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://docs.z4j.com/reference/compatibility/.
What it ships
- Agent runtime, connect, authenticate, supervise, reconnect with bounded backoff
- Outbound buffer, captured events are written to a bounded local SQLite ring before going out on the wire and survive short brain outages and agent restarts. At the configured count or byte limit, the oldest buffered rows are evicted and the loss is logged.
- 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)
import os
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",
hmac_secret=os.environ["Z4J_HMAC_SECRET"],
)
Reliability
- Invalid or missing configuration and unsafe buffer initialization fail the
explicit
install_agent()call; after successful startup, transport work runs off the host application's request and task paths. - Engine adapters use bounded in-process event queues and the runtime uses a bounded SQLite buffer. Queue overflow drops new events; buffer pressure evicts the oldest rows. Both paths log the loss.
- The supervisor retries transient network and TLS failures with bounded backoff. Authentication, configuration, and protocol-version failures are terminal so they do not create reconnect storms.
Documentation
Full docs at docs.z4j.com/frameworks/bare/.
License
Apache-2.0, see LICENSE.
Links
- Homepage: https://z4j.com
- Documentation: https://docs.z4j.com
- 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
Metadata
1 maintainer
Release files for z4j-bare 1.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| z4j_bare-1.12.0.tar.gz | 294.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| z4j_bare-1.12.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 487.8 kB
Release files / z4j_bare-1.12.0.tar.gz
| Download URL | z4j_bare-1.12.0.tar.gz |
|---|---|
| Size | 294.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd63907cc0ce5bda325c9c7d4fbfd3e92a7c6996b0924f87e2d7e1b82b79dc78
|
|
BLAKE2b-256 checksum How to use checksums |
45c945d5364c139812b48aaec0d108d3c4e433a622ed3e55cf8fe3534ec9cdbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / z4j_bare-1.12.0-py3-none-any.whl
| Download URL | z4j_bare-1.12.0-py3-none-any.whl |
|---|---|
| Size | 193.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81eef902708ef176abf0ecec7f3669b727236745d24db94ff190f9195a14d4d8
|
|
BLAKE2b-256 checksum How to use checksums |
67cfd3b1fe92b0f24b692e5e39939c9f0d5d425bac9436e8ad8e6aed4f9d5436
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
