platform-common-libraries

Shared infrastructure plumbing for platform agents. One package, one version, imported by every agent under cjot-backstage-az/agents/.

Current version: 0.1.0 (see CHANGELOG.md) Pairs with: agent-harness-spec — the spec mandates externalised state; this library provides the implementation.

Scope

This package contains only infrastructure plumbing that recurs across agents:

Module	What it does	Status
`platform_common.jobs`	`JobStore` — TTL-bounded, replica-safe key/value store for job, session, and conversation state.	v0.1.0 — interface + in-memory backend
`platform_common.checkpoint`	`make_checkpointer()` — LangGraph checkpointer factory (Redis or Postgres).	Planned — v0.2
`platform_common.blob`	`BlobStore` — Azure Blob wrapper for large artefacts.	Planned — v0.3
`platform_common.lease`	`LeaderLease` — Kubernetes Lease-based singleton coordination.	Planned — v0.4
`platform_common.testing`	Fakes for unit tests in downstream agents.	Tracks each module

Explicit non-goals

This package does not contain:

Business logic (catalog models, prompts, LangGraph workflows, domain APIs)
HTTP framework code (routes, middleware, manifest serialisation — that's agent-harness-spec/template/)
One-off helpers used by a single agent

If a module would only ever be imported by one agent, it does not belong here.

Install

From the Gitea PyPI registry (recommended)

pip install --extra-index-url https://gitea.kyndemo.live/api/packages/platform/pypi/simple/ \
            platform-common[redis]

In an agent's requirements.txt:

--extra-index-url https://gitea.kyndemo.live/api/packages/platform/pypi/simple/
platform-common[redis]==0.1.0

From git (no registry needed)

platform-common[redis] @ git+https://gitea.kyndemo.live/platform/platform-common-libraries.git@v0.1.0

Extras

Each module's third-party dependencies are gated behind an extra so agents only install what they need:

Extra	Pulls in
`[redis]`	`redis` (sync + asyncio client)
`[azure-blob]`	`azure-storage-blob`, `azure-identity`
`[langgraph]`	`langgraph` + Redis/Postgres checkpointers
`[k8s]`	`kubernetes` (for `LeaderLease`)
`[testing]`	`pytest`, `pytest-asyncio`, `fakeredis`
`[dev]`	All of the above + `ruff`, `mypy`, `build`, `twine`

Versioning policy

Strict semver:

MAJOR — breaking change to any public symbol (signature, return type, env var name).
MINOR — additive: new module, new optional parameter, new backend.
PATCH — bug fixes, performance, internal refactors.

Public surface = anything not prefixed with _. Deprecations get one minor release with a DeprecationWarning before removal.

The Python floor tracks agent-harness-spec — currently >=3.12.

Development

git clone https://gitea.kyndemo.live/platform/platform-common-libraries.git
cd platform-common-libraries
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check .
mypy
pytest

Releasing

Bump version in pyproject.toml.
Move the [Unreleased] notes in CHANGELOG.md under a new ## [X.Y.Z] — YYYY-MM-DD heading.
Commit, then git tag vX.Y.Z && git push --tags.
The Gitea Actions release workflow builds the wheel + sdist and publishes to the platform PyPI registry.

Repository layout

platform-common-libraries/
├── pyproject.toml
├── README.md
├── CHANGELOG.md
├── LICENSE
├── .gitea/workflows/ci.yml       # lint, type-check, test, publish on tag
├── src/
│   └── platform_common/
│       ├── __init__.py
│       ├── py.typed              # PEP 561 marker — agents get type hints
│       └── jobs.py               # JobStore (v0.1.0)
├── tests/
│   └── test_jobs.py
└── docs/
    └── jobstore-design.md        # contract & rationale for JobStore

4.1 KiB Raw Permalink Blame History