z4j-core

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.

Compatibility

Python 3.11+. Pure-Python, no framework or database imports.

Full per-adapter matrix at https://docs.z4j.com/reference/compatibility/.

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, scrubs values that match the built-in or operator-configured patterns from event payloads (URLs, headers, kwargs, exceptions) before they hit the brain
• Policy helpers, the project-role order, the role-to-action table and a pure policy engine over them. The brain takes that vocabulary from here, so the table is defined once, and the brain enforces its API RBAC in its own domain layer.
• Error hierarchy, shared exception classes so agents and brain agree on what counts as AuthorizationError vs NotFoundError vs ConflictError

Install

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; its frame models ignore additive fields. Product-version skew is narrower than the wire format alone, so upgrade the active z4j packages together according to the compatibility policy. Adapter interfaces are structural Python protocols; adding a method can therefore require coordinated adapter updates even when the wire format is unchanged.

Documentation

Full docs at docs.z4j.com/concepts/architecture/.

License

Apache-2.0, see LICENSE.

Links

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

Dependency compatibility

The shared models support Pydantic 2.9.2+ on Python 3.11 to 3.13 and Pydantic 2.12+ on Python 3.14+, with typing-extensions>=4.12.2. The latter Python branch needs upstream Pydantic runtime/wheel support. Z4J's development lockfile selects the current reviewed versions; it does not force host applications onto those exact versions. The project's CI workflow defines framework-compatibility lanes that run the z4j-core unit tests (strict validation, redaction and wire protocol) at the declared Pydantic and typing-extensions minimums as well as at the current dependency profile.