agentos-ledger-client 0.1.0__tar.gz

agentos_ledger_client-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: agentos-ledger-client
+Version: 0.1.0
+Summary: Canonical AgentOS State Ledger client and content-addressed blob storage
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: asyncpg>=0.29.0
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.0.0; extra == "gcs"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: pgserver>=0.1.4; extra == "test"
+
+# agentos-ledger-client
+
+Canonical AgentOS State Ledger client, hash-chain verification, and content-addressed blob storage.
+
+## Features
+
+- **Advisory-Locked Journal Appends**: Uses canonical `GLOBAL_CHAIN_LOCK_ID = 0x4C454447` to serialize concurrent writers and eliminate silent chain forks.
+- **SHA-256 Hash Chaining**: Verifiable hash chain where `integrity_hash = sha256(previous_hash + payload_json)`.
+- **Envelope Digest**: Secondary actor-bound digest `sha256(event_type + actor_id + actor_type + on_behalf_of + payload_json)` ensuring tamper-evident provenance.
+- **Content-Addressed Blob Storage**: Tiered binary blob storage with deduplication:
+  - Payloads $\le$ 1MB stored inline (`BYTEA`).
+  - Payloads $>$ 1MB stored in Google Cloud Storage (`gs://...`).
+- **Complete Schema Definitions**: Canonical event namespace constants for tasks, goals, iam, approval, and rlagt events.
+- **Lightweight Dependencies**: Standard library + `asyncpg`. Optional GCS client support.
+
+## Installation
+
+```bash
+pip install agentos-ledger-client
+```
+
+That is the whole thing. It is on PyPI, so there is no index to
+configure, no credential to obtain, and nothing to do differently on a
+laptop, in CI, or inside an AgentOS execution sandbox — PyPI is already
+reachable from all three.
+
+Blobs over 1MB need Google Cloud Storage; at or under 1MB they are
+stored inline as BYTEA and nothing external is required:
+
+```bash
+pip install "agentos-ledger-client[gcs]"
+```
+
+**As a dependency**, declare it the ordinary way and pin the series:
+
+```toml
+dependencies = [ "agentos-ledger-client>=0.1,<0.2" ]
+```
+
+### Versions
+
+Releases are cut automatically and only when the code changes. The
+build asks PyPI for the highest `0.1.x`, compares that release's
+contents with the tree, and publishes `0.1.<n+1>` only if they differ —
+so a version number always means the same bytes, and a run of builds
+that did not touch this package produces no releases at all.
+
+`>=0.1,<0.2` therefore resolves to the newest build of the current
+series. The series moves to `0.2` only for a breaking change, which is
+the one judgement nobody automates.
+
+Published from `agent_os_refactor_dev` alone. Other branches never
+publish, so a version cannot mean two different things depending on
+where it was built.
+
+**If you are changing this package** — person or agent — change the
+code and stop there. Do not set `__version__`: `scripts/ci/publish_ledger_client.py`
+writes it, after reading what PyPI already has, and a hand-set number
+either collides with one that is taken or is overwritten. A PyPI
+version is burned forever, so a collision is not recoverable.
+
+Raise it explicitly if you break the public API, since moving the
+series is the one decision here that is not automatic. The full rules
+are in `CONTRIBUTING.md` under *Releasing agentos-ledger-client*.
+
+
+## Quick Start
+
+```python
+import asyncpg
+from agentos_ledger_client import (
+    chain_hash,
+    GLOBAL_CHAIN_LOCK_ID,
+    append_event,
+    store_blob,
+    read_blob,
+)
+
+
+async def example(conn: asyncpg.Connection):
+    # Store blob
+    ref = await store_blob(conn, b"example payload", content_type="text/plain")
+    print(ref.sha256, ref.storage_backend)
+
+    # Append ledger event
+    res = await append_event(
+        conn,
+        event_type="task.created",
+        payload={"title": "Test task", "blob_sha256": ref.sha256},
+        actor_id=my_actor_id,
+        actor_type="independent_agent",   # one of:
+        # human | shca | independent_agent | system  (CHECK constraint)
+    )
+    print(res["event_id"], res["integrity_hash"])
+```
+
+`actor_id` is `UUID NOT NULL` and `actor_type` is constrained to the four
+values above — a consumer whose actors are strings (`"ecommerce-sim"`)
+needs a stable UUID per actor and must pick one of the four types.
+
+## Creating the tables
+
+```python
+from agentos_ledger_client import init_schema
+
+await init_schema(conn)   # idempotent; safe in a test fixture
+
+```
+
+## Checking it against your own database
+
+The suite that verifies this client ships *inside* it, so you can run it
+where it matters — against the Postgres you intend to use, on your
+Python, without cloning `pwt_agent_os`.
+
+```bash
+pip install "agentos-ledger-client[test]"
+pytest --pyargs agentos_ledger_client
+```
+
+**No database setup is required.** The `[test]` extra brings `pgserver`,
+a real PostgreSQL shipped as a wheel, and the fixtures start one and
+tear it down. To point the suite at a server you already have, set
+`DATABASE_URL` instead — it is used when reachable and ignored when not,
+so a stale value degrades to a skip rather than a confusing error.
+
+**Why bother.** What you share with AgentOS is a *hash-chained* table. A
+schema disagreement does not announce itself as "the schema differs" —
+it surfaces later as a chain that will not verify, by which point the
+rows exist. This suite builds the schema from the shipped `schema.sql`
+on an empty database, appends a chained event, and verifies it.
+
+It is not a hypothetical check. `schema.sql` shipped a `CHECK` on
+`actor_type` that refused `goal_orchestrator`, `executor` and
+`verifier` — 29% of the events on a live deployment — because it was
+copied from the first migration and two later ones widened it. AgentOS
+never noticed: its own tables come from `migrations/`, not from this
+file. The first person to execute it would have been a consumer.
+
+Requires Python 3.12: `pgserver` publishes cp312 wheels and no sdist.
+The library itself has no such constraint at runtime, but the project
+declares 3.12 because that is the only version it is tested on.

agentos_ledger_client-0.1.0/README.md

@@ -0,0 +1,142 @@
+# agentos-ledger-client
+
+Canonical AgentOS State Ledger client, hash-chain verification, and content-addressed blob storage.
+
+## Features
+
+- **Advisory-Locked Journal Appends**: Uses canonical `GLOBAL_CHAIN_LOCK_ID = 0x4C454447` to serialize concurrent writers and eliminate silent chain forks.
+- **SHA-256 Hash Chaining**: Verifiable hash chain where `integrity_hash = sha256(previous_hash + payload_json)`.
+- **Envelope Digest**: Secondary actor-bound digest `sha256(event_type + actor_id + actor_type + on_behalf_of + payload_json)` ensuring tamper-evident provenance.
+- **Content-Addressed Blob Storage**: Tiered binary blob storage with deduplication:
+  - Payloads $\le$ 1MB stored inline (`BYTEA`).
+  - Payloads $>$ 1MB stored in Google Cloud Storage (`gs://...`).
+- **Complete Schema Definitions**: Canonical event namespace constants for tasks, goals, iam, approval, and rlagt events.
+- **Lightweight Dependencies**: Standard library + `asyncpg`. Optional GCS client support.
+
+## Installation
+
+```bash
+pip install agentos-ledger-client
+```
+
+That is the whole thing. It is on PyPI, so there is no index to
+configure, no credential to obtain, and nothing to do differently on a
+laptop, in CI, or inside an AgentOS execution sandbox — PyPI is already
+reachable from all three.
+
+Blobs over 1MB need Google Cloud Storage; at or under 1MB they are
+stored inline as BYTEA and nothing external is required:
+
+```bash
+pip install "agentos-ledger-client[gcs]"
+```
+
+**As a dependency**, declare it the ordinary way and pin the series:
+
+```toml
+dependencies = [ "agentos-ledger-client>=0.1,<0.2" ]
+```
+
+### Versions
+
+Releases are cut automatically and only when the code changes. The
+build asks PyPI for the highest `0.1.x`, compares that release's
+contents with the tree, and publishes `0.1.<n+1>` only if they differ —
+so a version number always means the same bytes, and a run of builds
+that did not touch this package produces no releases at all.
+
+`>=0.1,<0.2` therefore resolves to the newest build of the current
+series. The series moves to `0.2` only for a breaking change, which is
+the one judgement nobody automates.
+
+Published from `agent_os_refactor_dev` alone. Other branches never
+publish, so a version cannot mean two different things depending on
+where it was built.
+
+**If you are changing this package** — person or agent — change the
+code and stop there. Do not set `__version__`: `scripts/ci/publish_ledger_client.py`
+writes it, after reading what PyPI already has, and a hand-set number
+either collides with one that is taken or is overwritten. A PyPI
+version is burned forever, so a collision is not recoverable.
+
+Raise it explicitly if you break the public API, since moving the
+series is the one decision here that is not automatic. The full rules
+are in `CONTRIBUTING.md` under *Releasing agentos-ledger-client*.
+
+
+## Quick Start
+
+```python
+import asyncpg
+from agentos_ledger_client import (
+    chain_hash,
+    GLOBAL_CHAIN_LOCK_ID,
+    append_event,
+    store_blob,
+    read_blob,
+)
+
+
+async def example(conn: asyncpg.Connection):
+    # Store blob
+    ref = await store_blob(conn, b"example payload", content_type="text/plain")
+    print(ref.sha256, ref.storage_backend)
+
+    # Append ledger event
+    res = await append_event(
+        conn,
+        event_type="task.created",
+        payload={"title": "Test task", "blob_sha256": ref.sha256},
+        actor_id=my_actor_id,
+        actor_type="independent_agent",   # one of:
+        # human | shca | independent_agent | system  (CHECK constraint)
+    )
+    print(res["event_id"], res["integrity_hash"])
+```
+
+`actor_id` is `UUID NOT NULL` and `actor_type` is constrained to the four
+values above — a consumer whose actors are strings (`"ecommerce-sim"`)
+needs a stable UUID per actor and must pick one of the four types.
+
+## Creating the tables
+
+```python
+from agentos_ledger_client import init_schema
+
+await init_schema(conn)   # idempotent; safe in a test fixture
+
+```
+
+## Checking it against your own database
+
+The suite that verifies this client ships *inside* it, so you can run it
+where it matters — against the Postgres you intend to use, on your
+Python, without cloning `pwt_agent_os`.
+
+```bash
+pip install "agentos-ledger-client[test]"
+pytest --pyargs agentos_ledger_client
+```
+
+**No database setup is required.** The `[test]` extra brings `pgserver`,
+a real PostgreSQL shipped as a wheel, and the fixtures start one and
+tear it down. To point the suite at a server you already have, set
+`DATABASE_URL` instead — it is used when reachable and ignored when not,
+so a stale value degrades to a skip rather than a confusing error.
+
+**Why bother.** What you share with AgentOS is a *hash-chained* table. A
+schema disagreement does not announce itself as "the schema differs" —
+it surfaces later as a chain that will not verify, by which point the
+rows exist. This suite builds the schema from the shipped `schema.sql`
+on an empty database, appends a chained event, and verifies it.
+
+It is not a hypothetical check. `schema.sql` shipped a `CHECK` on
+`actor_type` that refused `goal_orchestrator`, `executor` and
+`verifier` — 29% of the events on a live deployment — because it was
+copied from the first migration and two later ones widened it. AgentOS
+never noticed: its own tables come from `migrations/`, not from this
+file. The first person to execute it would have been a consumer.
+
+Requires Python 3.12: `pgserver` publishes cp312 wheels and no sdist.
+The library itself has no such constraint at runtime, but the project
+declares 3.12 because that is the only version it is tested on.

agentos_ledger_client-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentos-ledger-client"
+# THE VERSION LIVES IN `__init__.py`, and is read from there.
+#
+# It was declared in both places. Two declarations of one fact drift,
+# and the one that drifts here is invisible: a wheel built from a
+# pyproject saying 0.1.0 while the module says 0.1.7 installs as
+# 0.1.0 and reports 0.1.7 when asked. Nothing errors.
+#
+# CI rewrites the single line in `__init__.py` before building --
+# `0.1.<commits touching this package>` -- so the published version,
+# the installed version and `agentos_ledger_client.__version__` are
+# necessarily the same string.
+dynamic = ["version"]
+description = "Canonical AgentOS State Ledger client and content-addressed blob storage"
+readme = "README.md"
+# 3.12, NOT ">=3.10", WHICH WE NEVER TESTED. Nothing that uses this
+# package runs below 3.12: the app image, the sandbox image and
+# multi-agent-RL are all 3.12, and the only 3.11 image in the
+# repository (the task runner) does not import it. The old floor was
+# an untested compatibility claim on a package whose whole purpose is
+# being depended on -- the wrong place for optimism, as the Linux
+# bootstrap and the actor_type CHECK both demonstrated.
+#
+# It also makes the test extra below honest: `pgserver` publishes
+# cp312 wheels and no sdist, so on 3.10 or 3.11 the embedded database
+# is simply unavailable and the conformance suite could not run.
+requires-python = ">=3.12"
+dependencies = [
+    "asyncpg>=0.29.0",
+]
+
+[project.optional-dependencies]
+gcs = [
+    "google-cloud-storage>=2.0.0",
+]
+# `pip install "agentos-ledger-client[test]"` must yield a RUNNABLE
+# suite. It used to give pytest and no database, so every test that
+# matters -- the ones that put the schema on a real Postgres and append
+# a chained event -- skipped, and the install looked fine.
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    # An actual PostgreSQL, shipped as a wheel: no Docker, no system
+    # install, no port to remember. This is what makes
+    # `pytest --pyargs agentos_ledger_client` work on a consumer's
+    # machine with nothing set up.
+    "pgserver>=0.1.4",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "agentos_ledger_client.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agentos_ledger_client = ["py.typed", "schema.sql"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+testpaths = ["src/agentos_ledger_client/tests", "tests"]

agentos_ledger_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentos_ledger_client-0.1.0/src/agentos_ledger_client/__init__.py

@@ -0,0 +1,69 @@
+"""AgentOS State Ledger Client Package.
+
+Lightweight client and content-addressed blob storage for the AgentOS State Ledger.
+"""
+from __future__ import annotations
+
+from agentos_ledger_client.blobs import (
+    INLINE_THRESHOLD_BYTES,
+    STORAGE_GCS,
+    STORAGE_INLINE,
+    BlobRef,
+    get_blob_ref,
+    get_blob_ref_by_sha256,
+    read_blob,
+    read_blob_by_sha256,
+    store_blob,
+)
+from agentos_ledger_client.bootstrap import init_schema, schema_sql
+from agentos_ledger_client.chain import (
+    GENESIS,
+    GLOBAL_CHAIN_LOCK_ID,
+    chain_hash,
+    envelope_digest,
+    new_event_id,
+    payload_json,
+)
+from agentos_ledger_client.client import LedgerClient
+from agentos_ledger_client.journal import (
+    append_event,
+    generate_event_id,
+    register_post_append_hook,
+    register_pre_append_hook,
+)
+from agentos_ledger_client.types import AppendResult, ChainHead, LedgerEvent
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "init_schema",
+    "schema_sql",
+    # Chain & Lock
+    "GENESIS",
+    "GLOBAL_CHAIN_LOCK_ID",
+    "chain_hash",
+    "envelope_digest",
+    "new_event_id",
+    "payload_json",
+    # Journal
+    "append_event",
+    "generate_event_id",
+    "register_pre_append_hook",
+    "register_post_append_hook",
+    # Blobs
+    "BlobRef",
+    "store_blob",
+    "read_blob",
+    "get_blob_ref",
+    "get_blob_ref_by_sha256",
+    "read_blob_by_sha256",
+    "INLINE_THRESHOLD_BYTES",
+    "STORAGE_INLINE",
+    "STORAGE_GCS",
+    # Client
+    "LedgerClient",
+    # Types
+    "AppendResult",
+    "ChainHead",
+    "LedgerEvent",
+]