trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/workflows/interface.py

@@ -0,0 +1,148 @@
+"""Backend-neutral workflow execution interface (ADR-0080 §A).
+
+This module is the contract every workflow backend implements — the default
+outbox-composing backend today, a DBOS backend in 1.0. It is deliberately pure
+Python: it imports no engine module (``celery``, ``dbos``, ``temporalio``) and no
+Django, so it can serve as the stable, neutral surface that both workflow
+consumer code and backend implementations depend on.
+
+The eight primitives are intentionally narrow. Child workflows, continue-as-new,
+and deterministic-replay guarantees are excluded because they leak engine-specific
+(Temporal) semantics into workflow code and would break the abstraction.
+"""
+
+from __future__ import annotations
+
+import enum
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+
+
+class WorkflowStatus(enum.StrEnum):
+    """Backend-neutral workflow lifecycle status.
+
+    Values mirror ``trueppm_api.apps.workflow_engine.models.WorkflowStatus`` (the
+    default backend's persistence enum) and must stay in sync; they are defined
+    here too so consumers can reason about status without importing Django models.
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SLEEPING = "sleeping"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    """Retry behaviour for an activity run via :meth:`WorkflowBackend.run_activity`.
+
+    Backend-neutral: each backend translates these fields into its own retry
+    mechanism (the default backend maps them onto Celery's retry kwargs).
+    """
+
+    max_attempts: int = 3
+    initial_backoff: timedelta = timedelta(seconds=1)
+    backoff_multiplier: float = 2.0
+    max_backoff: timedelta = timedelta(minutes=5)
+
+
+@dataclass(frozen=True, slots=True)
+class HistoryEvent:
+    """One entry in a workflow's ordered, append-only history."""
+
+    seq: int
+    event_type: str
+    payload: dict[str, Any]
+    occurred_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowState:
+    """A point-in-time read model of a workflow instance.
+
+    Returned by :meth:`WorkflowBackend.get_workflow_state`. Intentionally a plain
+    value object, not a Django model, so consumers never bind to the default
+    backend's persistence layer.
+    """
+
+    workflow_id: str
+    name: str
+    status: WorkflowStatus
+    result: dict[str, Any] | None = None
+    error: str = ""
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    completed_at: datetime | None = None
+
+
+class WorkflowBackend(ABC):
+    """The eight-primitive workflow execution contract (ADR-0080 §A).
+
+    Implemented by each backend (default outbox-composing; future DBOS). Workflow
+    consumer code never calls a backend directly — it goes through
+    :mod:`trueppm_api.workflows.services`, which resolves the configured backend.
+    There is deliberately no ``_backend`` parameter on any method: if workflow
+    code ever needed to know which backend it runs on, the abstraction would have
+    already failed (ADR-0080 §E).
+    """
+
+    @abstractmethod
+    def start_workflow(
+        self,
+        name: str,
+        input: dict[str, Any],
+        *,
+        idempotency_key: str | None = None,
+        wait_for_completion: bool = False,
+    ) -> str:
+        """Start a workflow and return its id.
+
+        Fire-and-forget by default (``wait_for_completion=False``); blocking on
+        completion defeats the durability guarantee and is reserved for
+        bounded-short workflows. ``idempotency_key`` defaults to a deterministic
+        hash of ``name`` + ``input`` so a retried start does not duplicate work.
+        """
+
+    @abstractmethod
+    def signal_workflow(self, workflow_id: str, signal: str, payload: dict[str, Any]) -> None:
+        """Deliver a named signal to a workflow.
+
+        Durable: a signal that arrives before the workflow waits for it is queued,
+        not dropped.
+        """
+
+    @abstractmethod
+    def query_workflow(self, workflow_id: str, query: str, args: dict[str, Any]) -> Any:
+        """Run a named read-only query against a workflow's current state."""
+
+    @abstractmethod
+    def get_workflow_state(self, workflow_id: str) -> WorkflowState:
+        """Return a point-in-time read model of the workflow."""
+
+    @abstractmethod
+    def cancel_workflow(self, workflow_id: str, reason: str = "") -> None:
+        """Request cancellation of a workflow, recording an optional reason."""
+
+    @abstractmethod
+    def sleep(self, workflow_id: str, duration: timedelta) -> None:
+        """Durable timer: suspend the workflow until ``duration`` has elapsed."""
+
+    @abstractmethod
+    def run_activity(
+        self, name: str, input: dict[str, Any], retry_policy: RetryPolicy | None = None
+    ) -> Any:
+        """Execute a named activity (the side-effect boundary) with retries.
+
+        Called from within a workflow's execution; the backend resolves the
+        current workflow from execution context. Idempotent at the
+        ``(workflow, activity_name, input)`` level — a replayed activity returns
+        its previously recorded result instead of re-executing the side effect.
+        """
+
+    @abstractmethod
+    def get_history(self, workflow_id: str) -> list[HistoryEvent]:
+        """Return the workflow's ordered, append-only history."""

trueppm_api/workflows/registry.py

@@ -0,0 +1,106 @@
+"""Workflow definition registry (ADR-0080 §A).
+
+Workflow authors register a :class:`WorkflowDefinition` under a unique name; the
+engine resolves it at start time. This module is part of the backend-neutral
+surface — it must never import ``celery``, ``dbos``, or ``temporalio``. A
+definition describes *what* runs (an ordered chain of steps with optional
+compensation, the ``TaskChain`` model from #65); the backend decides *how*.
+
+The declarative step list is what keeps authoring backend-portable: the default
+Celery+outbox backend, the DBOS adapter, and a future Temporal adapter can each
+execute the same definition. See ADR-0080 §A "Authoring model".
+
+Registration mirrors the integration ``ProviderRegistry`` pattern (ADR-0049):
+OSS definitions register in ``WorkflowEngineConfig.ready()``; enterprise definitions
+register from their own ``AppConfig.ready()`` — same hook, no ``if enterprise``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+# An activity is a callable taking a context dict and returning a JSON-able
+# result (or None). The engine wraps every activity execution in once-and-only-once
+# semantics, so an activity must be safe to *record* once even if dispatched twice.
+Activity = Callable[[dict[str, Any]], dict[str, Any] | None]
+
+# A compensation undoes a previously-completed step during saga rollback. It
+# receives the same context the step's activity received. Best-effort: failures
+# are logged, not re-raised, so one failed rollback does not strand the others.
+Compensation = Callable[[dict[str, Any]], None]
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowStep:
+    """One step in a workflow's chain: an activity plus optional compensation.
+
+    ``name`` is unique within a definition and is the activity-name half of the
+    once-and-only-once key ``(workflow, activity_name, input_hash)``.
+    """
+
+    name: str
+    activity: Activity
+    compensate: Compensation | None = None
+
+
+class WorkflowDefinition:
+    """Base class for a registered workflow (ADR-0080 §A).
+
+    Subclasses set ``name`` and implement :meth:`build_steps` to return the
+    ordered chain for a given input. The v1 engine executes the chain
+    sequentially, compensating completed steps in reverse on failure. Override
+    :meth:`on_query` to answer ``query_workflow`` calls.
+    """
+
+    name: str
+
+    def build_steps(self, workflow_input: dict[str, Any]) -> list[WorkflowStep]:
+        """Return the ordered steps for this workflow run.
+
+        Pure and deterministic given ``workflow_input`` — the engine may rebuild
+        the chain on a redelivered step, so the same input must yield the same
+        steps in the same order.
+        """
+        raise NotImplementedError
+
+    def on_query(self, query: str, args: dict[str, Any]) -> Any:
+        """Answer a named read-only query against the workflow (optional)."""
+        raise NotImplementedError(f"workflow {self.name!r} defines no query handler")
+
+
+class WorkflowRegistry:
+    """Name → definition registry, mirroring integrations' ``ProviderRegistry``.
+
+    A duplicate name raises rather than silently overwriting, so two apps cannot
+    both claim a workflow name without a loud failure at registration time.
+    """
+
+    def __init__(self) -> None:
+        self._registry: dict[str, WorkflowDefinition] = {}
+
+    def register(self, definition: WorkflowDefinition) -> WorkflowDefinition:
+        name = definition.name
+        if name in self._registry:
+            raise ValueError(f"workflow {name!r} is already registered")
+        self._registry[name] = definition
+        return definition
+
+    def get(self, name: str) -> WorkflowDefinition:
+        try:
+            return self._registry[name]
+        except KeyError:
+            raise KeyError(f"no workflow registered under {name!r}") from None
+
+    def all(self) -> dict[str, WorkflowDefinition]:
+        """Return a copy of the registered definitions (used by the contract test)."""
+        return dict(self._registry)
+
+    def clear(self) -> None:
+        """Reset the registry — test helper only."""
+        self._registry.clear()
+
+
+# Process-wide singleton. Workflow definitions register against this.
+WORKFLOWS = WorkflowRegistry()

trueppm_api/workflows/services.py

@@ -0,0 +1,90 @@
+"""Public service layer for workflow execution (ADR-0080 §Implementation Notes 4).
+
+All workflow starts, signals, queries, and inspections from view or consumer code
+go through these module-level functions. They resolve the configured backend and
+delegate. Never import or instantiate a backend class directly — the indirection
+here is what keeps consumer code backend-neutral (ADR-0080 §E).
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from functools import lru_cache
+from typing import Any
+
+from django.conf import settings
+from django.utils.module_loading import import_string
+
+from trueppm_api.workflows.interface import (
+    HistoryEvent,
+    RetryPolicy,
+    WorkflowBackend,
+    WorkflowState,
+)
+
+DEFAULT_BACKEND = "trueppm_api.workflows.backends.default.DefaultWorkflowBackend"
+
+
+@lru_cache(maxsize=1)
+def get_backend() -> WorkflowBackend:
+    """Resolve and cache the configured workflow backend.
+
+    Reads ``settings.WORKFLOW_BACKEND`` (a dotted path to a
+    :class:`~trueppm_api.workflows.interface.WorkflowBackend` subclass),
+    defaulting to the outbox-composing default backend. Cached for the process
+    lifetime; tests that swap backends must call ``get_backend.cache_clear()``.
+    """
+    dotted = getattr(settings, "WORKFLOW_BACKEND", DEFAULT_BACKEND)
+    backend_cls: type[WorkflowBackend] = import_string(dotted)
+    return backend_cls()
+
+
+def start_workflow(
+    name: str,
+    input: dict[str, Any],
+    *,
+    idempotency_key: str | None = None,
+    wait_for_completion: bool = False,
+) -> str:
+    """Start a workflow; see :meth:`WorkflowBackend.start_workflow`."""
+    return get_backend().start_workflow(
+        name,
+        input,
+        idempotency_key=idempotency_key,
+        wait_for_completion=wait_for_completion,
+    )
+
+
+def signal_workflow(workflow_id: str, signal: str, payload: dict[str, Any]) -> None:
+    """Deliver a signal; see :meth:`WorkflowBackend.signal_workflow`."""
+    get_backend().signal_workflow(workflow_id, signal, payload)
+
+
+def query_workflow(workflow_id: str, query: str, args: dict[str, Any]) -> Any:
+    """Query a workflow; see :meth:`WorkflowBackend.query_workflow`."""
+    return get_backend().query_workflow(workflow_id, query, args)
+
+
+def get_workflow_state(workflow_id: str) -> WorkflowState:
+    """Fetch workflow state; see :meth:`WorkflowBackend.get_workflow_state`."""
+    return get_backend().get_workflow_state(workflow_id)
+
+
+def cancel_workflow(workflow_id: str, reason: str = "") -> None:
+    """Cancel a workflow; see :meth:`WorkflowBackend.cancel_workflow`."""
+    get_backend().cancel_workflow(workflow_id, reason)
+
+
+def sleep(workflow_id: str, duration: timedelta) -> None:
+    """Durable sleep; see :meth:`WorkflowBackend.sleep`."""
+    get_backend().sleep(workflow_id, duration)
+
+
+def run_activity(name: str, input: dict[str, Any], retry_policy: RetryPolicy | None = None) -> Any:
+    """Run an activity; see :meth:`WorkflowBackend.run_activity`."""
+    return get_backend().run_activity(name, input, retry_policy)
+
+
+def get_history(workflow_id: str) -> list[HistoryEvent]:
+    """Fetch history; see :meth:`WorkflowBackend.get_history`."""
+    return get_backend().get_history(workflow_id)

trueppm_api/wsgi.py

@@ -0,0 +1,11 @@
+"""WSGI application (used by runserver in non-ASGI contexts)."""
+
+from __future__ import annotations
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "trueppm_api.settings.dev")
+
+application = get_wsgi_application()

trueppm_api-0.4.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.5
+Name: trueppm-api
+Version: 0.4.0
+Summary: TruePPM Django REST API — projects, tasks, scheduling, real-time collaboration
+Author: Kelly Hair
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+License-File: NOTICES
+License-File: licenses/GPL-3.0.txt
+License-File: licenses/LGPL-3.0.txt
+License-File: licenses/MPL-2.0.txt
+Requires-Python: >=3.11
+Requires-Dist: boto3<2.0,>=1.35
+Requires-Dist: celery<6.0,>=5.6
+Requires-Dist: channels-redis<5.0,>=4.0
+Requires-Dist: channels<5.0,>=4.0
+Requires-Dist: cryptography<51,>=50.0.0
+Requires-Dist: defusedxml<0.8,>=0.7
+Requires-Dist: django-allauth[socialaccount]<66.0,>=65.18.0
+Requires-Dist: django-environ<1.0,>=0.11
+Requires-Dist: django-simple-history<4.0,>=3.7
+Requires-Dist: django-storages<2.0,>=1.14.6
+Requires-Dist: django<6.0,>=5.2.17
+Requires-Dist: djangorestframework-simplejwt<6.0,>=5.3.1
+Requires-Dist: djangorestframework<3.19,>=3.18.2
+Requires-Dist: dnspython<3.0,>=2.9.0
+Requires-Dist: drf-spectacular[sidecar]==0.30.0
+Requires-Dist: jsonschema<5.0,>=4.21
+Requires-Dist: msgpack<2.0,>=1.2.3
+Requires-Dist: openpyxl<4.0,>=3.1
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.45.1
+Requires-Dist: opentelemetry-instrumentation-asgi<1,>=0.66b1
+Requires-Dist: opentelemetry-instrumentation-celery<1,>=0.66b1
+Requires-Dist: opentelemetry-instrumentation-django<1,>=0.66b1
+Requires-Dist: opentelemetry-instrumentation-psycopg<1,>=0.66b1
+Requires-Dist: opentelemetry-sdk<2,>=1.45.1
+Requires-Dist: packaging>=24.0
+Requires-Dist: psycopg<4.0,>=3.1.8
+Requires-Dist: pyjwt[crypto]<3.0,>=2.14
+Requires-Dist: python-json-logger<3.0,>=2.0
+Requires-Dist: redis<6.5,>=6.4
+Requires-Dist: trueppm-scheduler<0.5,>=0.4.0rc2
+Requires-Dist: uvicorn[standard]<1.0,>=0.29
+Requires-Dist: whitenoise<7.0,>=6.0
+Provides-Extra: binary
+Requires-Dist: psycopg[binary]<4.0,>=3.1.8; extra == 'binary'
+Provides-Extra: c
+Requires-Dist: psycopg[c]<4.0,>=3.1.8; extra == 'c'
+Provides-Extra: dev
+Requires-Dist: diff-cover<10.0,>=9.0; extra == 'dev'
+Requires-Dist: django-stubs[compatible-mypy]==6.1.0; extra == 'dev'
+Requires-Dist: djangorestframework-stubs[compatible-mypy]==3.18.1; extra == 'dev'
+Requires-Dist: mutmut==3.8.0; extra == 'dev'
+Requires-Dist: mypy==1.20.2; extra == 'dev'
+Requires-Dist: psycopg[binary]<4.0,>=3.1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio<2.0,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<8.0,>=4.0; extra == 'dev'
+Requires-Dist: pytest-django<5.0,>=4.8; extra == 'dev'
+Requires-Dist: pytest-socket<1.0,>=0.8; extra == 'dev'
+Requires-Dist: pytest-split<1.0,>=0.9; extra == 'dev'
+Requires-Dist: pytest-timeout<3.0,>=2.4; extra == 'dev'
+Requires-Dist: pytest-xdist<4.0,>=3.6; extra == 'dev'
+Requires-Dist: pytest<10.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.8; extra == 'dev'
+Requires-Dist: testcontainers[postgres]<5.0,>=4.7; extra == 'dev'
+Provides-Extra: fuzz
+Requires-Dist: schemathesis<5.0,>=4.0; extra == 'fuzz'
+Description-Content-Type: text/markdown
+
+# trueppm-api
+
+[![PyPI version](https://img.shields.io/pypi/v/trueppm-api.svg)](https://pypi.org/project/trueppm-api/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/trueppm-api.svg)](https://pypi.org/project/trueppm-api/)
+[![CI](https://gitlab.com/trueppm/trueppm/badges/main/pipeline.svg)](https://gitlab.com/trueppm/trueppm/-/pipelines)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+Django REST + WebSocket backend for [TruePPM](https://trueppm.com) — projects, tasks,
+critical-path scheduling, agile boards and sprints, offline sync, and real-time
+collaboration.
+
+## Is this package for you?
+
+Most people should **not** `pip install` this directly. If you want to run TruePPM,
+start from the [quickstart guide](https://docs.trueppm.com/getting-started/quickstart/)
+(`docker compose up`) or the [Helm chart](https://gitlab.com/trueppm/trueppm/-/tree/main/packages/helm) —
+both wire up PostgreSQL, Valkey, the web frontend, and a Celery worker for you.
+
+This package exists on PyPI for two narrower audiences:
+
+- **Downstream projects that depend on the OSS backend as a library** — most notably
+  [TruePPM Enterprise](https://trueppm.com) (proprietary, separate repo), which pins an
+  exact `trueppm-api` release instead of a git submodule or path dependency. See
+  [Using this as a dependency](#using-this-as-a-dependency).
+- **Operators who want to run the API standalone** — against Postgres/Valkey you
+  already manage, without Docker Compose or the bundled frontend. See
+  [Standalone quickstart](#standalone-quickstart).
+
+If neither of those is you, the linked quickstart is a better starting point.
+
+## Requirements
+
+- **Python 3.11+**
+- **PostgreSQL 16+**, with the `ltree`, `pg_trgm`, and `btree_gist` extensions
+  installable by the connecting role (migrations run `CREATE EXTENSION IF NOT EXISTS`
+  for each — the role needs `CREATEDB`/superuser on a fresh database, or ask your DBA
+  to pre-create the extensions)
+- **Valkey 8+** (or Redis 7+, wire-compatible) — backs the WebSocket channel layer and
+  the Celery broker/result backend
+- **A Celery worker**, if you want anything that runs off the request/response cycle:
+  async schedule recalculation, notifications, MS Project/Jira/CSV import jobs. The
+  API serves reads and writes without one, but background jobs will queue and never run.
+- **S3-compatible object storage**, in production only, for task attachments. Local
+  disk storage is the dev default and is explicitly refused at boot in
+  `trueppm_api.settings.prod` unless you opt in (fine for local/single-node
+  evaluation, not for anything you intend to keep).
+
+## Install
+
+```bash
+# Development — precompiled psycopg wheel, no compiler or system libpq needed
+pip install "trueppm-api[binary]"
+
+# Production — links against the system libpq, so OS security patches reach
+# the driver without a new release of this package
+pip install "trueppm-api[c]"
+```
+
+Extras:
+
+| Extra | Use it for |
+|---|---|
+| `binary` | Local dev / quick-start psycopg (precompiled wheel, bundles its own libpq) |
+| `c` | Production psycopg (compiled against the system libpq) |
+| `dev` | Test tooling (pytest, mypy, ruff, testcontainers) — installed from a source checkout, not by consumers |
+| `fuzz` | Schemathesis, for OpenAPI-schema-driven fuzz testing — installed from a source checkout, not by consumers |
+
+Pick one of `binary`/`c`. The base install already pulls plain `psycopg`, whose
+pure-Python core binds to `libpq` via `ctypes` at runtime — that only works if a
+system `libpq` is already installed and discoverable, so `binary` (bundles its
+own) or `c` (links the one you installed) is the reliable path.
+
+## Standalone quickstart
+
+This runs the API by itself against Postgres/Valkey instances you already have —
+no Docker Compose, no frontend. Five minutes if those two services are already up.
+
+```bash
+pip install "trueppm-api[binary]"
+
+export DJANGO_SETTINGS_MODULE=trueppm_api.settings.dev
+export TRUEPPM_ALLOW_DEV_SETTINGS=1  # dev settings refuse to import without this
+export SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
+export DATABASE_URL="postgres://trueppm:trueppm@localhost:5432/trueppm"
+export REDIS_URL="redis://localhost:6379"
+
+django-admin migrate
+django-admin createsuperuser
+django-admin runserver 0.0.0.0:8000
+```
+
+Then:
+
+- `http://localhost:8000/api/v1/health/` — liveness check, no auth
+- `http://localhost:8000/api/docs/` — interactive Swagger UI (served from `[sidecar]`
+  static assets, so it works offline / behind a strict CSP)
+- `http://localhost:8000/admin/` — Django admin, using the superuser you just created
+
+`trueppm_api.settings.dev` hardcodes `ALLOWED_HOSTS = ["*"]` and open (`AllowAny`)
+API permissions, so it refuses to even import without `TRUEPPM_ALLOW_DEV_SETTINGS=1`
+set (or a test runner active) — that guard is what the env var above satisfies.
+**Do not use it past localhost.** For anything reachable over a network, switch to
+`trueppm_api.settings.prod`, which enforces `ALLOWED_HOSTS`, a real `SECRET_KEY`,
+and durable attachment storage at import time — it refuses to boot rather than
+silently run insecure. `manage.py` (the entry point the full repo uses) is a thin
+wrapper around `django-admin` that defaults `DJANGO_SETTINGS_MODULE` to
+`trueppm_api.settings.dev`; installed via pip you use `django-admin` directly, as
+above, and set the setting explicitly.
+
+For the full experience — the React frontend, a Celery worker, WebSocket
+broadcasts, seeded demo data — use the [Docker Compose
+quickstart](https://docs.trueppm.com/getting-started/quickstart/) instead; it
+runs this same package, wired up for you.
+
+Every environment variable this package reads, including production-only ones
+(object storage, OIDC single sign-on, OpenTelemetry, rate limits) is documented at
+**[docs.trueppm.com/administration/configuration](https://docs.trueppm.com/administration/configuration/)**.
+`SECRET_KEY`, `DATABASE_URL`, and `REDIS_URL` above are the only three with no safe
+default outside of `trueppm_api.settings.dev`.
+
+## Using this as a dependency
+
+Pin an exact release the same way you'd pin any other PyPI package:
+
+```toml
+# pyproject.toml
+[project]
+dependencies = [
+    "trueppm-api==0.4.0",
+]
+```
+
+```bash
+pip install "trueppm-api[c]==0.4.0"
+```
+
+`import trueppm_api; trueppm_api.__version__` reflects the installed distribution
+version (read from package metadata, not a hand-maintained string), so it always
+agrees with `pip show trueppm-api`.
+
+`trueppm_api.settings.base` is written to be extended: a downstream project's own
+settings module can do `from trueppm_api.settings.base import *` and layer
+additional `INSTALLED_APPS`, middleware, or DRF settings on top, the same pattern
+`trueppm_api.settings.prod` itself uses. This is how TruePPM Enterprise adds its
+portfolio-governance apps without forking the OSS backend.
+
+## Versioning and releases
+
+**The version number tracks the whole TruePPM platform release, not this package
+independently.** `0.4.0` on PyPI corresponds to git tag `v0.4.0` in the
+[trueppm-suite](https://gitlab.com/trueppm/trueppm) monorepo — the same release
+that produced the `api`/`web` Docker images and the Helm chart at that version.
+There is no separate changelog or release cadence for `trueppm-api` alone; see the
+[root `CHANGELOG.md`](https://gitlab.com/trueppm/trueppm/-/blob/main/CHANGELOG.md)
+for what changed in any given release.
+
+Every `v*` tag publishes this package to PyPI automatically (CI job
+`api:publish:pypi`), alongside the Docker images and the Helm chart. `@trueppm/web`
+is not published to npm — it is an application bundle, not a library (see the
+[root README's Published artifacts table](https://gitlab.com/trueppm/trueppm#published-artifacts)). As of #3943, this job authenticates via **PyPI Trusted
+Publishing** (GitLab OIDC) and signs [PEP 740](https://peps.python.org/pep-0740/)
+attestations, the same as `trueppm-scheduler` and `trueppm-mcp` — there is no
+static upload token on the publish path. That release job is unproven until
+the next `v*` tag, so versions through `0.4.0-beta.3` predate it and were
+published with a static token, with no attestation. Pre-release versions (`aN`/`bN`/`rcN`) are real
+releases of whatever that tag shipped, not throwaway snapshots — TruePPM is
+pre-1.0 and ships its entire release line as alphas/betas/RCs, per
+[SECURITY.md](https://gitlab.com/trueppm/trueppm/-/blob/main/SECURITY.md).
+
+Before 1.0, breaking changes to this package's Python API (settings shape, model
+fields, management commands) can happen between releases without a deprecation
+window — the published contract that *is* stable pre-1.0 is the HTTP/WebSocket API
+surface, documented at
+[docs.trueppm.com/api/stability](https://docs.trueppm.com/api/stability/). If
+you're pinning this package as a library dependency rather than talking to a
+running instance over HTTP, expect to read the changelog on every bump.
+
+## Documentation
+
+- **Full docs**: [docs.trueppm.com](https://docs.trueppm.com)
+- **API reference**: [docs.trueppm.com/api/reference](https://docs.trueppm.com/api/reference/)
+- **Configuration reference**: [docs.trueppm.com/administration/configuration](https://docs.trueppm.com/administration/configuration/)
+- **Source / issues**: [gitlab.com/trueppm/trueppm](https://gitlab.com/trueppm/trueppm)
+
+## Tests
+
+From a source checkout:
+
+```bash
+cd packages/api
+pip install -e ".[binary,dev]"
+pytest
+```
+
+Most tests need a real PostgreSQL (for `ltree`/`pg_trgm` queries) — the repo's
+`docker compose up` provides one; `testcontainers[postgres]` (a `dev` extra) can
+also spin one up ephemerally.
+
+## License
+
+Apache 2.0 — see [LICENSE](https://gitlab.com/trueppm/trueppm/-/blob/main/LICENSE).
+Copyright MacroDream, LLC and contributors — see
+[NOTICE](https://gitlab.com/trueppm/trueppm/-/blob/main/NOTICE).