feat: initial scaffold + JobStore (v0.1.0)

README.md

@@ -0,0 +1,125 @@
+# 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](CHANGELOG.md))
+> **Pairs with:** [`agent-harness-spec`](https://github.com/kyndryl/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)
+
+```bash
+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](https://semver.org/):
+
+- **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
+
+```bash
+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
+
+1. Bump `version` in `pyproject.toml`.
+2. Move the `[Unreleased]` notes in `CHANGELOG.md` under a new `## [X.Y.Z] — YYYY-MM-DD` heading.
+3. Commit, then `git tag vX.Y.Z && git push --tags`.
+4. 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
+```