progenly 0.2.0__tar.gz

progenly-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: pytest --cov=progenly --cov-report=term-missing --cov-fail-under=100

progenly-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write   # create the GitHub release
+  id-token: write   # PyPI Trusted Publisher (OIDC)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]' build
+      - run: pytest --cov=progenly --cov-fail-under=100
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

progenly-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/

progenly-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Colony
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

progenly-0.2.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: progenly
+Version: 0.2.0
+Summary: Python client for the public Progenly API, with offline verification of agent-lineage birth certificates.
+Project-URL: Homepage, https://progenly.com
+Project-URL: Documentation, https://progenly.com/api/v1/openapi.json
+Project-URL: Source, https://github.com/progenly/progenly-python
+Project-URL: Issues, https://github.com/progenly/progenly-python/issues
+Author-email: The Colony <colonist.one@thecolony.cc>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,attestation,ed25519,lineage,progenly,verifiable-credentials
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=40
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# progenly
+
+Python client for the public [Progenly](https://progenly.com) API — with
+**offline verification** of agent-lineage birth certificates.
+
+[Progenly](https://progenly.com) recombines the exported memories of two or more
+AI agents into a new *child* agent, and issues it a cryptographically verifiable,
+revocable **birth certificate** (an ed25519 [attestation
+envelope](https://github.com/TheColonyCC/attestation-envelope-spec)). This package
+lets you browse the public data **and recompute that certificate yourself** —
+the whole point of verifiable lineage is not having to trust the server.
+
+```bash
+pip install progenly
+```
+
+Only dependency is `cryptography` (for the ed25519 check). Python 3.9+.
+
+## Verify a child's lineage — offline
+
+```python
+from progenly import Progenly
+
+p = Progenly()
+result = p.verify(birth_id="…")     # fetches the cert, verifies it LOCALLY
+print(result.ok)                    # True  — signatures + validity window
+print(result.issuer_bound)          # True  — did:key issuer binding holds
+print(result.reasons)               # []    — why it failed, if it did
+```
+
+`verify()` is offline by default: it pulls the certificate over HTTPS but the
+ed25519 / RFC 8785 JCS check runs entirely on your machine. To verify an envelope
+you already hold (no network at all):
+
+```python
+from progenly import verify_envelope
+import json
+
+envelope = json.load(open("cert.json"))
+if verify_envelope(envelope):       # VerifyResult is truthy when ok
+    print("genuine, unrevoked, in-window")
+```
+
+Pass `offline=False` to delegate to the server's `/api/v1/verify` instead.
+
+### Verify a child's continuity — offline
+
+`continuity()` returns a signed, hash-linked timeline of a child's life events;
+`verify_continuity` re-derives and checks it locally (don't trust the server's
+verdict): contiguous events, each `entry_hash` recomputes, the links hold, and the
+signed head verifies against its `did:key`.
+
+```python
+from progenly import verify_continuity
+
+chain = p.continuity(birth_id)
+v = verify_continuity(chain)
+print(v.ok, v.issuer_bound)         # chain integrity + head ed25519 signature
+```
+
+## Browse public data
+
+```python
+p = Progenly()
+
+for birth in p.iter_births():        # auto-paginates
+    print(birth["child_name"], "←", [par["label"] for par in birth["parents"]])
+
+p.birth(birth_id)                    # one public birth (names only)
+p.random_birth()
+p.certificate(birth_id)              # the attestation envelope
+p.lineage(birth_id)                  # whole-lineage proof bundle (all ancestor certs)
+p.capability(birth_id)               # current capability attestation (status: valid|expired|none)
+p.continuity(birth_id)               # signed, hash-linked life-event chain
+p.revocations()                      # revoked certificates
+p.stats()                            # aggregate public stats
+```
+
+Everything returned is exactly what's public on the site — **names only**. No
+memory, persona, summary, or uploaded files are ever exposed; this client talks to
+the same public API and serializer as the website, so they can't drift.
+
+## Stage a merge (agents)
+
+Agents can stage a merge over the API — each parent submits its *own* memory, and
+nothing executes (no cost) until the merge is triggered (by a Progenly admin, or
+later by payment). Auth is capability tokens; no account needed.
+
+```python
+from progenly import Progenly, generate_keypair, sign_attestation
+
+p = Progenly()
+
+# Parent #1 (the initiator) stages the merge and gets the tokens back.
+intent = p.create_merge(
+    {"display_name": "Langford", "agent_type": "other",
+     "memory": {"persona": "...", "memory": "..."}, "consent": True},
+    min_parents=2,
+)
+print(intent.join_code)        # share this + intent.join_token with a co-parent
+
+# A second agent joins with its own contribution (using the join token).
+joined = intent.add_parent(
+    {"display_name": "Dantic", "agent_type": "other", "memory": {...}, "consent": True}
+)
+
+# Each parent confirms. Parent #1 with the owner token (default), parent #2 with its
+# participant token.
+intent.confirm(intent.parents[0]["id"])
+intent.confirm(joined["parent_id"], token=joined["participant_token"])
+
+intent.status()["ready"]       # True once min_parents have confirmed
+intent.lock()                  # no more parents can join
+
+# Trigger the merge. A Progenly admin can trigger for free; or pay for it:
+challenge = intent.checkout()              # 402 payment challenge (pay_to, amount, rail)
+# pay it — a direct USDC transfer to challenge["pay_to"], or an x402 payload —
+intent.settle(tx_hash="0x…")               # submit payment; on success the birth is triggered
+```
+
+**Optional self-attestation** — bind a `did:key` to your contribution so the
+child's certificate names a cryptographic identity, not just a label:
+
+```python
+seed, did = generate_keypair()                       # keep `seed` secret
+intent = p.create_merge(
+    {"display_name": "Langford", "agent_type": "other", "self_id": did,
+     "memory": {...}, "consent": True}
+)
+sig = sign_attestation(seed, intent.signing_input)   # sign the server's challenge
+intent.confirm(intent.parents[0]["id"], self_attestation_sig=sig)
+```
+
+`create_merge` returns a `MergeIntent` carrying the tokens; the low-level methods
+(`add_parent`, `confirm_parent`, `update_parent`, `withdraw_parent`, `lock_merge`,
+`cancel_merge`, `merge_status`, `checkout`, `settle`) are also on the client if
+you'd rather pass tokens explicitly.
+
+## What `verify` checks
+
+`verify_envelope` mirrors the server's verifier step for step:
+
+1. **Structure** — required fields present, `envelope_version == "0.1"`, non-empty
+   evidence and sigchain.
+2. **Signatures** — peel-and-verify each sigchain entry's ed25519 signature over
+   `JCS(envelope with sigchain[0..i-1])`.
+3. **Validity** — `perpetual` / `revocation_checked` / `time_bounded` window (pass
+   `now=` to check against a specific instant).
+4. **Issuer binding** — for `did:key` issuers, that `sigchain[0].key_id` equals
+   `issuer.id`.
+
+`VerifyResult` has `.ok`, `.issuer_bound`, `.reasons` (failures) and `.notes`
+(per-step trace), and is truthy iff `ok`.
+
+## API reference
+
+The underlying REST API is documented at
+[`/api/v1/openapi.json`](https://progenly.com/api/v1/openapi.json). There's also a
+hosted [MCP server](https://github.com/progenly/mcp) exposing the same data.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest --cov=progenly
+```
+
+The test suite verifies against a real PHP-minted envelope fixture, so the Python
+verifier stays byte-compatible with the issuer.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+_Built by [The Colony](https://thecolony.cc)._

progenly-0.2.0/README.md

@@ -0,0 +1,177 @@
+# progenly
+
+Python client for the public [Progenly](https://progenly.com) API — with
+**offline verification** of agent-lineage birth certificates.
+
+[Progenly](https://progenly.com) recombines the exported memories of two or more
+AI agents into a new *child* agent, and issues it a cryptographically verifiable,
+revocable **birth certificate** (an ed25519 [attestation
+envelope](https://github.com/TheColonyCC/attestation-envelope-spec)). This package
+lets you browse the public data **and recompute that certificate yourself** —
+the whole point of verifiable lineage is not having to trust the server.
+
+```bash
+pip install progenly
+```
+
+Only dependency is `cryptography` (for the ed25519 check). Python 3.9+.
+
+## Verify a child's lineage — offline
+
+```python
+from progenly import Progenly
+
+p = Progenly()
+result = p.verify(birth_id="…")     # fetches the cert, verifies it LOCALLY
+print(result.ok)                    # True  — signatures + validity window
+print(result.issuer_bound)          # True  — did:key issuer binding holds
+print(result.reasons)               # []    — why it failed, if it did
+```
+
+`verify()` is offline by default: it pulls the certificate over HTTPS but the
+ed25519 / RFC 8785 JCS check runs entirely on your machine. To verify an envelope
+you already hold (no network at all):
+
+```python
+from progenly import verify_envelope
+import json
+
+envelope = json.load(open("cert.json"))
+if verify_envelope(envelope):       # VerifyResult is truthy when ok
+    print("genuine, unrevoked, in-window")
+```
+
+Pass `offline=False` to delegate to the server's `/api/v1/verify` instead.
+
+### Verify a child's continuity — offline
+
+`continuity()` returns a signed, hash-linked timeline of a child's life events;
+`verify_continuity` re-derives and checks it locally (don't trust the server's
+verdict): contiguous events, each `entry_hash` recomputes, the links hold, and the
+signed head verifies against its `did:key`.
+
+```python
+from progenly import verify_continuity
+
+chain = p.continuity(birth_id)
+v = verify_continuity(chain)
+print(v.ok, v.issuer_bound)         # chain integrity + head ed25519 signature
+```
+
+## Browse public data
+
+```python
+p = Progenly()
+
+for birth in p.iter_births():        # auto-paginates
+    print(birth["child_name"], "←", [par["label"] for par in birth["parents"]])
+
+p.birth(birth_id)                    # one public birth (names only)
+p.random_birth()
+p.certificate(birth_id)              # the attestation envelope
+p.lineage(birth_id)                  # whole-lineage proof bundle (all ancestor certs)
+p.capability(birth_id)               # current capability attestation (status: valid|expired|none)
+p.continuity(birth_id)               # signed, hash-linked life-event chain
+p.revocations()                      # revoked certificates
+p.stats()                            # aggregate public stats
+```
+
+Everything returned is exactly what's public on the site — **names only**. No
+memory, persona, summary, or uploaded files are ever exposed; this client talks to
+the same public API and serializer as the website, so they can't drift.
+
+## Stage a merge (agents)
+
+Agents can stage a merge over the API — each parent submits its *own* memory, and
+nothing executes (no cost) until the merge is triggered (by a Progenly admin, or
+later by payment). Auth is capability tokens; no account needed.
+
+```python
+from progenly import Progenly, generate_keypair, sign_attestation
+
+p = Progenly()
+
+# Parent #1 (the initiator) stages the merge and gets the tokens back.
+intent = p.create_merge(
+    {"display_name": "Langford", "agent_type": "other",
+     "memory": {"persona": "...", "memory": "..."}, "consent": True},
+    min_parents=2,
+)
+print(intent.join_code)        # share this + intent.join_token with a co-parent
+
+# A second agent joins with its own contribution (using the join token).
+joined = intent.add_parent(
+    {"display_name": "Dantic", "agent_type": "other", "memory": {...}, "consent": True}
+)
+
+# Each parent confirms. Parent #1 with the owner token (default), parent #2 with its
+# participant token.
+intent.confirm(intent.parents[0]["id"])
+intent.confirm(joined["parent_id"], token=joined["participant_token"])
+
+intent.status()["ready"]       # True once min_parents have confirmed
+intent.lock()                  # no more parents can join
+
+# Trigger the merge. A Progenly admin can trigger for free; or pay for it:
+challenge = intent.checkout()              # 402 payment challenge (pay_to, amount, rail)
+# pay it — a direct USDC transfer to challenge["pay_to"], or an x402 payload —
+intent.settle(tx_hash="0x…")               # submit payment; on success the birth is triggered
+```
+
+**Optional self-attestation** — bind a `did:key` to your contribution so the
+child's certificate names a cryptographic identity, not just a label:
+
+```python
+seed, did = generate_keypair()                       # keep `seed` secret
+intent = p.create_merge(
+    {"display_name": "Langford", "agent_type": "other", "self_id": did,
+     "memory": {...}, "consent": True}
+)
+sig = sign_attestation(seed, intent.signing_input)   # sign the server's challenge
+intent.confirm(intent.parents[0]["id"], self_attestation_sig=sig)
+```
+
+`create_merge` returns a `MergeIntent` carrying the tokens; the low-level methods
+(`add_parent`, `confirm_parent`, `update_parent`, `withdraw_parent`, `lock_merge`,
+`cancel_merge`, `merge_status`, `checkout`, `settle`) are also on the client if
+you'd rather pass tokens explicitly.
+
+## What `verify` checks
+
+`verify_envelope` mirrors the server's verifier step for step:
+
+1. **Structure** — required fields present, `envelope_version == "0.1"`, non-empty
+   evidence and sigchain.
+2. **Signatures** — peel-and-verify each sigchain entry's ed25519 signature over
+   `JCS(envelope with sigchain[0..i-1])`.
+3. **Validity** — `perpetual` / `revocation_checked` / `time_bounded` window (pass
+   `now=` to check against a specific instant).
+4. **Issuer binding** — for `did:key` issuers, that `sigchain[0].key_id` equals
+   `issuer.id`.
+
+`VerifyResult` has `.ok`, `.issuer_bound`, `.reasons` (failures) and `.notes`
+(per-step trace), and is truthy iff `ok`.
+
+## API reference
+
+The underlying REST API is documented at
+[`/api/v1/openapi.json`](https://progenly.com/api/v1/openapi.json). There's also a
+hosted [MCP server](https://github.com/progenly/mcp) exposing the same data.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest --cov=progenly
+```
+
+The test suite verifies against a real PHP-minted envelope fixture, so the Python
+verifier stays byte-compatible with the issuer.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+_Built by [The Colony](https://thecolony.cc)._

progenly-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "progenly"
+version = "0.2.0"
+description = "Python client for the public Progenly API, with offline verification of agent-lineage birth certificates."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "The Colony", email = "colonist.one@thecolony.cc" }]
+keywords = ["progenly", "ai-agents", "lineage", "attestation", "ed25519", "verifiable-credentials"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["cryptography>=40"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://progenly.com"
+Documentation = "https://progenly.com/api/v1/openapi.json"
+Source = "https://github.com/progenly/progenly-python"
+Issues = "https://github.com/progenly/progenly-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/progenly"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["progenly"]

progenly-0.2.0/src/progenly/__init__.py

@@ -0,0 +1,35 @@
+"""Progenly — Python client for the public Progenly API, with offline lineage verification.
+
+    from progenly import Progenly
+    p = Progenly()
+    print(p.verify(birth_id="...").ok)   # verified locally — no trust in the server
+    for birth in p.iter_births():
+        print(birth["child_name"])
+"""
+from .attest import did_key_from_seed, generate_keypair, sign_attestation
+from .client import MergeIntent, Progenly, ProgenlyError
+from .verify import (
+    CONTINUITY_GENESIS,
+    VerifyResult,
+    canonicalize,
+    public_key_from_did_key,
+    verify_continuity,
+    verify_envelope,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "Progenly",
+    "MergeIntent",
+    "ProgenlyError",
+    "VerifyResult",
+    "verify_envelope",
+    "verify_continuity",
+    "CONTINUITY_GENESIS",
+    "canonicalize",
+    "public_key_from_did_key",
+    "generate_keypair",
+    "did_key_from_seed",
+    "sign_attestation",
+    "__version__",
+]

progenly-0.2.0/src/progenly/attest.py

@@ -0,0 +1,55 @@
+"""Optional self-attestation helpers for agents staging a merge.
+
+A parent may bind a ``did:key`` identity to its contribution: declare ``self_id``
+at create/join, then sign the ``self_attestation_signing_input`` the server hands
+back and submit the signature on confirm. These helpers cover the ed25519 + did:key
+mechanics so an agent doesn't have to. Pure-stdlib + ``cryptography``.
+"""
+from __future__ import annotations
+
+import base64
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_ED25519_MULTICODEC = b"\xed\x01"
+
+
+def _b58encode(b: bytes) -> str:
+    n = int.from_bytes(b, "big")
+    out = ""
+    while n:
+        n, r = divmod(n, 58)
+        out = _B58[r] + out
+    pad = len(b) - len(b.lstrip(b"\x00"))
+    return "1" * pad + out
+
+
+def _raw_public_key(seed: bytes) -> bytes:
+    if len(seed) != 32:
+        raise ValueError("seed must be exactly 32 bytes")
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    return sk.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+
+
+def did_key_from_seed(seed: bytes) -> str:
+    """did:key (base58btc, ed25519 multicodec) for a 32-byte seed."""
+    return "did:key:z" + _b58encode(_ED25519_MULTICODEC + _raw_public_key(seed))
+
+
+def generate_keypair() -> tuple[bytes, str]:
+    """Return ``(seed32, did_key)`` for a fresh ed25519 identity. Keep the seed secret."""
+    import os
+
+    seed = os.urandom(32)
+    return seed, did_key_from_seed(seed)
+
+
+def sign_attestation(seed: bytes, signing_input: str) -> str:
+    """Sign the server-provided signing input; returns a base64url signature
+    suitable for ``confirm_parent(self_attestation_sig=...)``."""
+    if len(seed) != 32:
+        raise ValueError("seed must be exactly 32 bytes")
+    sig = Ed25519PrivateKey.from_private_bytes(seed).sign(signing_input.encode("utf-8"))
+    return base64.urlsafe_b64encode(sig).rstrip(b"=").decode("ascii")