Metadata-Version: 2.4
Name: z4j-core
Version: 1.5.1
Summary: z4j domain core - models, protocols, transport, redaction, policy (Apache 2.0)
Project-URL: Changelog, https://github.com/z4jdev/z4j-core/blob/main/CHANGELOG.md
Project-URL: Documentation, https://z4j.dev
Project-URL: Homepage, https://z4j.com
Project-URL: Issues, https://github.com/z4jdev/z4j-core/issues
Project-URL: Source, https://github.com/z4jdev/z4j-core
Author: z4j contributors
License: Apache-2.0
License-File: LICENSE
Keywords: control-plane,queue,task,z4j
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic[email]>=2.13.3
Requires-Dist: typing-extensions>=4.15.0
Description-Content-Type: text/markdown

# z4j-core

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

The z4j domain core, shared models, protocols, transport, redaction, policy.

Pure-Python dependency for every z4j package. No framework / engine /
database imports, so it can be vendored into agent processes without
dragging server runtime weight. End users do not install this package
directly; it ships as a transitive dependency of z4j or any
agent package.

## What's in here

- **Pydantic models**, `Task`, `Worker`, `Queue`, `Schedule`,
  `Event`, `Command`, `Agent`, plus the wire-frame envelope types
- **Adapter protocols**, `QueueEngineAdapter`, `SchedulerAdapter`,
  `FrameworkAdapter`. Every framework / engine / scheduler package
  implements one or more of these.
- **Wire protocol**, frame definitions and the HMAC envelope used
  by z4j ↔ agent WebSocket transport (signed v2 protocol)
- **Redaction engine**, strips secrets from logged event payloads
  (URLs, headers, kwargs, exceptions) before they hit the brain
- **Policy types**, role-based action enums (Viewer / Operator /
  Admin), used by the brain's RBAC layer
- **Error hierarchy**, shared exception classes so agents and brain
  agree on what counts as `AuthorizationError` vs `NotFoundError`
  vs `ConflictError`

## Install

```bash
pip install z4j-core
```

End users normally get this as a transitive dependency. Direct
installation is appropriate when you're building a custom adapter
against the protocols.

## Stability

The wire protocol is `v=2` and additive within the 1.x major.
Adapter protocols (`QueueEngineAdapter`, etc.) are stable contracts
within the 1.x major; new optional methods may be added.

## Documentation

Full docs at [z4j.dev/concepts/architecture/](https://z4j.dev/concepts/architecture/).

## License

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

## Links

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