z3rno-server 0.1.0__tar.gz

z3rno_server-0.1.0/.env.example

@@ -0,0 +1,46 @@
+# z3rno-server local dev environment
+#
+# Copy this file to `.env` and adjust values as needed:
+#   cp .env.example .env
+#
+# Docker Compose automatically picks up .env when running `docker compose up`.
+# Do NOT commit your real .env — it's already in .gitignore.
+
+# -----------------------------------------------------------------------------
+# PostgreSQL (z3rno-postgres:17 with all extensions pre-installed)
+# -----------------------------------------------------------------------------
+POSTGRES_DB=z3rno
+POSTGRES_USER=z3rno
+POSTGRES_PASSWORD=z3rno_dev_password
+POSTGRES_HOST_PORT=5432
+
+# -----------------------------------------------------------------------------
+# Valkey (used for cache, session state, rate-limit counters, Celery broker)
+# -----------------------------------------------------------------------------
+VALKEY_HOST_PORT=6379
+
+# -----------------------------------------------------------------------------
+# z3rno-server (FastAPI)
+# -----------------------------------------------------------------------------
+SERVER_HOST_PORT=8000
+LOG_LEVEL=INFO
+CORS_ORIGINS=http://localhost:3000,http://localhost:8000
+
+# API key for local dev. The real z3rno-server will look up org_id via this.
+# In production, API keys are stored hashed in the api_keys table. For local
+# dev, any non-empty string works and maps to a bootstrap dev tenant.
+Z3RNO_API_KEY=z3rno_sk_test_localdev
+
+# -----------------------------------------------------------------------------
+# Embedding provider (LiteLLM)
+# -----------------------------------------------------------------------------
+# MVP default is OpenAI text-embedding-3-small (1536 dims).
+# Leave OPENAI_API_KEY empty for schema work that doesn't need real embeddings;
+# the server will use a random-vector stub for development.
+EMBEDDING_MODEL=text-embedding-3-small
+OPENAI_API_KEY=
+
+# -----------------------------------------------------------------------------
+# Celery worker
+# -----------------------------------------------------------------------------
+CELERY_WORKER_CONCURRENCY=4

z3rno_server-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12']
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: z3rno
+          POSTGRES_PASSWORD: z3rno_dev_password
+          POSTGRES_DB: z3rno
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U z3rno -d z3rno"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      valkey:
+        image: valkey/valkey:8
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "valkey-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      DATABASE_URL: postgresql+asyncpg://z3rno:z3rno_dev_password@localhost:5432/z3rno
+      REDIS_URL: redis://localhost:6379/0
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Ruff — lint
+        run: uv run ruff check .
+
+      - name: Ruff — format check
+        run: uv run ruff format --check .
+
+      - name: mypy — type check
+        run: uv run mypy .
+
+      - name: pytest — unit tests
+        run: uv run pytest -v --cov --cov-report=term-missing --cov-report=xml

z3rno_server-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

z3rno_server-0.1.0/.gitignore

@@ -0,0 +1,74 @@
+# macOS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pyre/
+.pytype/
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Local state
+*.log
+*.sqlite
+*.db
+.env.local
+.env.*.local
+
+# Secrets — never commit
+secrets/
+*.key
+*.pem

z3rno_server-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,100 @@
+# Pre-commit hooks for Python repos (z3rno-core, z3rno-server, z3rno-sdk-python)
+#
+# Install:
+#   pip install pre-commit  # or: brew install pre-commit
+#   pre-commit install      # wires into .git/hooks/pre-commit
+#
+# Run manually:
+#   pre-commit run --all-files
+#
+# Skip a hook for one commit:
+#   SKIP=ruff git commit -m "..."
+#
+# Update pinned versions:
+#   pre-commit autoupdate
+
+default_language_version:
+  python: python3.12
+
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+repos:
+  # ---------------------------------------------------------------------------
+  # Generic hygiene — applies to every repo
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: check-symlinks
+      - id: destroyed-symlinks
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: detect-private-key
+
+  # ---------------------------------------------------------------------------
+  # Ruff — linter + formatter (replaces black, isort, flake8, pyupgrade)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  # ---------------------------------------------------------------------------
+  # mypy — strict static type checking (skeleton-mode tolerant)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        # Skip cleanly if no pyproject.toml exists yet (skeleton mode).
+        entry: bash -c 'if [ -f pyproject.toml ]; then mypy "$@"; else echo "skeleton mode: no pyproject.toml — skipping mypy"; fi' --
+        additional_dependencies:
+          - pydantic>=2.10
+          - sqlalchemy[mypy]>=2.0.36
+          - types-redis
+          - types-requests
+
+  # ---------------------------------------------------------------------------
+  # sqlfluff — SQL linter + formatter (PostgreSQL dialect)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/sqlfluff/sqlfluff
+    rev: 3.3.0
+    hooks:
+      - id: sqlfluff-lint
+        args: [--dialect=postgres]
+      - id: sqlfluff-fix
+        args: [--dialect=postgres]
+
+  # ---------------------------------------------------------------------------
+  # commit message format (conventional commits, soft enforcement)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.6.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: [feat, fix, build, chore, ci, docs, perf, refactor, revert, style, test]
+
+ci:
+  # If you ever flip the repo to use pre-commit.ci (a free SaaS that runs
+  # pre-commit on every PR and auto-fixes), this controls its behaviour.
+  # Until then it's harmless metadata.
+  autofix_prs: true
+  autoupdate_schedule: monthly
+  skip: []
+  submodules: false

z3rno_server-0.1.0/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+## Project
+
+z3rno-server is the FastAPI REST API server for Z3rno. It wraps z3rno-core engine functions as HTTP endpoints, handles authentication, rate limiting, and manages Celery workers for background tasks. SDKs and external clients only talk to this server.
+
+## Quick Reference
+
+```bash
+uv sync --dev                    # Install dependencies
+uv run ruff check .              # Lint
+uv run ruff format .             # Format
+uv run mypy .                    # Type check
+uv run pytest                    # Run tests
+make dev-up                      # Start docker compose stack
+make dev-down                    # Stop stack
+make dev-psql                    # Connect to postgres shell
+```
+
+## Architecture
+
+- `src/z3rno_server/main.py` — FastAPI app factory, middleware registration, router includes
+- `src/z3rno_server/api/` — Route handlers: memories.py (store/recall/forget), audit.py, sessions.py, health.py, worker.py
+- `src/z3rno_server/middleware/` — auth.py, rate_limit.py, logging.py, request_id.py, org_context.py
+- `src/z3rno_server/schemas/` — Pydantic request/response models (the API contract for SDKs)
+- `src/z3rno_server/workers/` — Celery tasks: lifecycle.py, embeddings.py, healthcheck.py, celery_app.py
+- `src/z3rno_server/config.py` — pydantic-settings (DATABASE_URL, REDIS_URL, etc.)
+- `src/z3rno_server/dependencies.py` — FastAPI DI: database session with RLS context
+
+## API Endpoints
+
+- `POST /v1/memories` — Store memory (calls z3rno_core.engine.store)
+- `POST /v1/memories/recall` — Recall by query (calls z3rno_core.engine.recall)
+- `POST /v1/memories/forget` — Forget/delete (calls z3rno_core.engine.forget)
+- `GET /v1/audit` — Query audit log (calls z3rno_core.engine.audit)
+- `POST /v1/sessions` — Start session (Redis-only)
+- `POST /v1/sessions/{id}/end` — End session
+- `GET /v1/health` — Liveness probe
+- `GET /v1/ready` — Readiness probe
+- `GET /v1/worker/health` — Celery worker healthcheck (public, no auth)
+- `GET /metrics` — Prometheus metrics (public, no auth)
+
+## Middleware Chain (order matters)
+
+RequestId -> Logging -> Auth -> RateLimit -> Route Handler
+
+## Key Conventions
+
+- Python 3.11+, src/ layout, hatchling build
+- z3rno-core is a git dependency (switches to PyPI version when published)
+- Ruff + mypy for code quality
+- API key auth via Authorization: Bearer or X-API-Key header
+- Public paths skip auth: /v1/health, /v1/ready, /docs, /redoc, /openapi.json, /metrics, /v1/worker/health
+- Sessions are Redis-only (no relational sessions table)
+- Celery workers use Valkey as broker and result backend
+- Conventional commits
+
+## Environment Variables
+
+- `DATABASE_URL` — PostgreSQL connection (asyncpg driver)
+- `REDIS_URL` — Valkey connection
+- `EMBEDDING_MODEL` — LiteLLM model name (default: text-embedding-3-small)
+- `OPENAI_API_KEY` — For embedding generation
+- `CORS_ORIGINS` — Comma-separated allowed origins
+- `LOG_LEVEL` — Structlog level (default: INFO)
+
+## Docker Compose
+
+`docker-compose.dev.yml` runs 4 services: postgres (z3rno-postgres:17), valkey, server, worker. All on the `z3rno` network. Postgres uses platform: linux/amd64 for Apple Silicon compatibility.
+
+`docker-compose.prod.yml` runs the same services plus Traefik for TLS termination. Uses required env vars, resource limits, health checks, password-protected Valkey, and real Celery worker command.

z3rno_server-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to z3rno-server
+
+Thank you for your interest in contributing to Z3rno. This guide covers the development workflow for `z3rno-server`.
+
+## Getting Started
+
+1. Fork and clone the repository.
+2. Install Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+3. Install dependencies:
+
+```bash
+uv sync --dev
+```
+
+4. Start the local development stack:
+
+```bash
+docker compose -f docker-compose.dev.yml up
+```
+
+This brings up PostgreSQL (with pgvector, Apache AGE), Valkey, the server, and a Celery worker.
+
+5. Run the checks:
+
+```bash
+uv run ruff check .
+uv run mypy .
+uv run pytest
+```
+
+## Development Workflow
+
+1. Create a feature branch from `main`:
+   ```bash
+   git checkout -b feat/your-feature
+   ```
+2. Write your code with tests.
+3. Run linting, type checking, and tests (see above).
+4. Commit using conventional commit messages.
+5. Open a pull request against `main`.
+
+## Code Style
+
+This project uses **ruff** for linting and formatting. Configuration lives in `pyproject.toml`.
+
+```bash
+# Lint
+uv run ruff check .
+
+# Format
+uv run ruff format .
+
+# Type check
+uv run mypy .
+```
+
+## Testing
+
+Tests use `pytest` with `pytest-asyncio` and `httpx` for endpoint testing. Integration tests require running services and are marked with `@pytest.mark.integration`.
+
+```bash
+# All tests
+uv run pytest
+
+# Unit tests only
+uv run pytest -m "not integration"
+
+# With coverage
+uv run pytest --cov=src/z3rno_server
+```
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` new feature
+- `fix:` bug fix
+- `docs:` documentation only
+- `test:` adding or updating tests
+- `refactor:` code change that neither fixes a bug nor adds a feature
+- `chore:` maintenance (deps, CI, tooling)
+
+Examples:
+- `feat: add session timeout endpoint`
+- `fix: rate limiter not respecting Retry-After header`
+
+## Pull Request Process
+
+1. Ensure all checks pass (`ruff check`, `mypy`, `pytest`).
+2. Keep PRs focused -- one logical change per PR.
+3. Update or add tests for any changed behavior.
+4. Fill out the PR template description.
+5. A maintainer will review and merge.
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/the-ai-project-co/z3rno-server/discussions) or reach out at engineering@z3rno.dev.

z3rno_server-0.1.0/Dockerfile

@@ -0,0 +1,62 @@
+# syntax=docker/dockerfile:1.7
+#
+# z3rno-server — FastAPI REST server for Z3rno
+# Multi-stage build: builder installs deps, runtime copies only what's needed.
+
+# ---------------------------------------------------------------------------
+# Stage 1: builder — install dependencies with uv
+# ---------------------------------------------------------------------------
+FROM python:3.12-slim-bookworm AS builder
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast dependency resolution
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml ./
+COPY src/ src/
+
+# Install dependencies into the system site-packages
+RUN uv pip install --system -e ".[worker]"
+
+# ---------------------------------------------------------------------------
+# Stage 2: runtime — lean image with only installed packages and source
+# ---------------------------------------------------------------------------
+FROM python:3.12-slim-bookworm AS runtime
+
+LABEL org.opencontainers.image.title="z3rno-server" \
+      org.opencontainers.image.source="https://github.com/the-ai-project-co/z3rno-server" \
+      org.opencontainers.image.licenses="Apache-2.0"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN groupadd --system z3rno && useradd --system --gid z3rno --create-home z3rno
+
+WORKDIR /app
+
+# Copy installed Python packages from builder
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy application source
+COPY --chown=z3rno:z3rno src/ src/
+
+USER z3rno
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/v1/health')"]
+
+CMD ["uvicorn", "z3rno_server.main:app", "--host", "0.0.0.0", "--port", "8000"]