Metadata-Version: 2.4
Name: z4j-core
Version: 2026.4.0a1
Summary: z4j domain core - models, protocols, transport, redaction, policy (Apache 2.0)
Project-URL: Homepage, https://z4j.com
Project-URL: Source, https://github.com/z4jdev/z4j
Project-URL: Documentation, https://z4j.com/docs
Project-URL: Issues, https://github.com/z4jdev/z4j/issues
Project-URL: Changelog, https://github.com/z4jdev/z4j/blob/main/CHANGELOG.md
Author: z4j contributors
License: Apache-2.0
License-File: LICENSE
Keywords: control-plane,queue,task,z4j
Classifier: Development Status :: 3 - Alpha
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.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.13
Requires-Dist: pydantic[email]>=2.9
Requires-Dist: typing-extensions>=4.12
Description-Content-Type: text/markdown

# z4j-core

**License:** Apache 2.0
**Status:** Phase 1 — early implementation

The pure domain core of z4j. **Imports nothing framework- or
engine-specific** — only Pydantic and the Python standard library. This
is enforced by `import-linter` in CI. Any PR that tries to import
Django, Celery, Redis, SQLAlchemy, FastAPI, etc. from `z4j_core` will
fail the build.

## Why this matters

Every other package in the z4j monorepo depends on `z4j-core`. The
brain uses its domain models and wire protocol; every adapter
implements one of its Protocols. Keeping this package free of
framework coupling is what lets us:

1. Ship v1 with Django + Celery only, then add Flask / FastAPI / RQ /
   Dramatiq as peer packages without touching the core
2. Test the entire domain layer with no database, no broker, no HTTP
3. Evolve the protocol without rewriting the dashboard or the brain
4. Let contributors add a new engine adapter over a weekend without
   understanding any of the rest of the system

## What's in here

| Module | Purpose |
|---|---|
| `z4j_core.models` | Pydantic v2 domain models (Project, Agent, Task, Queue, Worker, Schedule, Command, Event, AuditEntry, User, Config, ...) |
| `z4j_core.protocols` | `QueueEngineAdapter`, `FrameworkAdapter`, `SchedulerAdapter` — the three adapter interfaces adapters implement |
| `z4j_core.errors` | Exception hierarchy (`Z4JError`, `ValidationError`, `AuthenticationError`, ...) |
| `z4j_core.redaction` | Secret redaction engine with default patterns and per-field overrides |
| `z4j_core.transport` | Wire protocol — frame shapes, version negotiation, HMAC signing |
| `z4j_core.policy` | Permission engine — `can(user, action, project)` |

## Documentation

- [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) — full system architecture + Protocol signatures
- [`docs/API.md`](../../docs/API.md) — REST + WebSocket agent protocol
- [`docs/SECURITY.md`](../../docs/SECURITY.md) — threat model, redaction, HMAC
- [`docs/patterns.md`](../../docs/patterns.md) — code patterns this package follows

## Development

```bash
# From the repo root:
uv sync
make lint              # ruff + mypy + import-linter
make test-unit         # pytest packages/z4j-core/tests/unit
make check-imports     # import-linter — core purity check
```

## License

Apache 2.0. See [`../../LICENSE-APACHE`](../../LICENSE-APACHE). This
package is deliberately permissively licensed so that proprietary
Django / Flask / FastAPI applications can import it without any
license concerns.
