z4j 1.0.1__tar.gz

z4j-1.0.1/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# All changes default to the project maintainer.
+*    @z4jdev

z4j-1.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Report a problem with z4j
+title: "[bug] "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug in `z4j`.
+
+        **Security bugs do NOT belong here.** If you believe you've
+        found a security issue, please email `security@z4j.com` -
+        see [SECURITY.md](../blob/main/SECURITY.md).
+
+  - type: input
+    id: package-version
+    attributes:
+      label: z4j version
+      description: Output of `pip show z4j | grep -E 'Name|Version'`
+      placeholder: z4j 1.0.0
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: 3.14.4
+    validations:
+      required: true
+
+  - type: dropdown
+    id: module
+    attributes:
+      label: Affected module
+      description: (Customize this dropdown's options per package.)
+      options:
+        - Unsure / multiple
+    validations:
+      required: false
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A standalone script is ideal.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the full traceback if applicable. Please redact secrets.
+      render: shell
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirmation
+      options:
+        - label: I searched existing issues and this is not a duplicate
+          required: true
+        - label: This is NOT a security issue (those go to security@z4j.com)
+          required: true

z4j-1.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: mailto:security@z4j.com
+    about: Report a security issue privately
+  - name: Question or discussion
+    url: https://github.com/z4jdev/z4j/discussions
+    about: General questions about z4j go to the project-wide Discussions

z4j-1.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature request
+description: Suggest a capability for z4j
+title: "[feature] "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature for `z4j`. Please describe
+        the problem you're trying to solve, not just the solution you
+        have in mind.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that z4j does not currently support?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed
+    attributes:
+      label: Proposed solution
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

z4j-1.0.1/.github/dependabot.yml

@@ -0,0 +1,35 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "04:00"
+      timezone: UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - python
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "04:00"
+      timezone: UTC
+    open-pull-requests-limit: 3
+    labels:
+      - dependencies
+      - ci
+    commit-message:
+      prefix: ci

z4j-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  UV_VERSION: "0.5.11"
+  FORCE_COLOR: "1"
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+jobs:
+  lint:
+    name: Lint and format
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Mypy
+        run: uv run mypy src
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-24.04
+    needs: [lint]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest -xvs tests/
+
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-24.04
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Build
+        run: uv build
+
+      - name: Validate metadata
+        run: |
+          uv tool install twine
+          uv tool run twine check dist/*
+
+      - name: Upload artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

z4j-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+# Manual-publish phase: this workflow builds the package and attaches
+# the wheel + sdist to a GitHub Release. It does NOT upload to PyPI.
+# PyPI uploads are hand-picked from a local staging folder via twine,
+# under the maintainer's direct control. See docs/RELEASE.md.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: read
+
+env:
+  UV_VERSION: "0.5.11"
+
+jobs:
+  build-and-release:
+    name: Build and attach to GitHub Release
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag matches pyproject version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/version = "(.*)"/\1/')
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest -xvs tests/
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Validate metadata
+        run: |
+          uv tool install twine
+          uv tool run twine check dist/*
+
+      - name: Create GitHub Release with artefacts
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          fail_on_unmatched_files: true

z4j-1.0.1/.gitignore

@@ -0,0 +1,100 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg
+*.egg-info/
+.eggs/
+dist/
+build/
+wheels/
+*.egg-info/
+.installed.cfg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+.pytest_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+.python-version-local
+
+# uv
+.uv/
+
+# Node / pnpm
+node_modules/
+.pnpm-store/
+pnpm-debug.log*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# TanStack Router auto-generated routes
+routeTree.gen.ts
+routeTree.gen.ts.timestamp-*
+
+# Next.js / Vite build outputs (defensive — future proofing)
+.next/
+.vite/
+dist/
+out/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Claude Code workspace state — local-machine permissions cache,
+# scheduled-task locks, and an allowlist that often embeds dev
+# tokens. Each developer regenerates their own.
+.claude/
+
+# OS
+.AppleDouble
+.LSOverride
+
+# Env files — never commit secrets. Match every .env* by default,
+# then explicitly allow-list the templates / examples that are
+# safe to share publicly.
+.env
+.env.*
+!.env.example
+!.env.template
+!.env.sample
+
+# z4j local data
+/var/
+*.sqlite
+*.sqlite-journal
+z4j-*.dump
+
+# Docker
+docker-compose.override.yml
+
+# Logs
+*.log
+logs/
+
+# Misc build artifacts
+*.bak
+*.orig
+*.rej

z4j-1.0.1/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `z4j` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-04-22
+
+First public release of the z4j umbrella package. Synchronized with z4j-brain 1.0.1.
+
+### Features
+
+- **Meta-install for the z4j control plane.** `pip install z4j` resolves to `z4j-brain>=1.0.1` + `z4j-core>=1.0.1`, giving a fully working brain server (dashboard, REST API, WebSocket gateway, SQLite DB, Alembic migrations, CLI) in one command. Mirrors the `docker run z4jdev/z4j` experience for Python-first operators.
+- **Clean extras surface for adapter selection**: `[celery]`, `[django]`, `[flask]`, `[fastapi]`, `[rq]`, `[dramatiq]`, `[huey]`, `[arq]`, `[taskiq]`, `[apscheduler]`, `[bare]`. Each extra pulls the engine adapter plus its companion scheduler (where applicable) in one shot, covering the 95% case.
+- **Infra pass-through extra** `[postgres]` defers to `z4j-brain[postgres]`, so asyncpg's version floor stays owned by the brain package rather than being duplicated here.
+- **Convenience bundles**: `[agents]` (every engine adapter at once) and `[all]` (= `[agents,postgres]`, the kitchen sink for CI / dev rigs).
+- **Agent-only install recipe documented** for organizations whose policy forbids AGPL code: `pip install z4j-core z4j-<adapter>` keeps Apache-2.0 purity without touching the brain.
+
+### Notes
+
+- **OpenTelemetry is not shipped.** The umbrella intentionally does not expose an `[otel]` extra. z4j-brain 1.0.1 simultaneously drops its own `[otel]` extra because the packages were installed but the integration code was never wired (no `TracerProvider` init, no FastAPI instrumentation, no OTLP export path). OpenTelemetry support will return as a real working feature in a future release, at which point both packages will reintroduce the extra. Until then, the working observability story is Prometheus `/metrics` + structlog JSON logs, both wired in z4j-brain since 1.0.0.
+
+### Compatibility
+
+- Python 3.11, 3.12, 3.13, 3.14.
+- Operating-system independent (Linux, macOS, Windows).
+- Depends on `z4j-brain>=1.0.1` (AGPL v3) and `z4j-core>=1.0.1` (Apache 2.0).
+
+## Links
+
+- Repository: <https://github.com/z4jdev/z4j>
+- Issues: <https://github.com/z4jdev/z4j/issues>
+- PyPI: <https://pypi.org/project/z4j/>
+
+[Unreleased]: https://github.com/z4jdev/z4j/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/z4jdev/z4j/releases/tag/v1.0.0