126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
# 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
|
|
```
|