# 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
```