sm-org-agent 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python-version: ["3.11", "3.12"]
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: astral-sh/setup-uv@v5
17
+ - uses: actions/setup-python@v5
18
+ with:
19
+ python-version: ${{ matrix.python-version }}
20
+ # Same gate as `make ci-local`, so green locally == green in CI.
21
+ - run: make ci-local
@@ -0,0 +1,48 @@
1
+ # Publish sm-org-agent to PyPI on a version tag, via PyPI Trusted Publishing (OIDC).
2
+ #
3
+ # No API token anywhere: PyPI is told (once, in its web UI) to trust THIS repo +
4
+ # THIS workflow file, and the `id-token: write` permission below lets the job
5
+ # mint a short-lived OIDC token PyPI accepts. See PUBLISHING.md for the one-time
6
+ # setup and the exact values to type into PyPI's "Add a publisher" form.
7
+ #
8
+ # Fires only when a tag like `v0.1.0` is pushed — never on normal commits.
9
+ name: release
10
+
11
+ on:
12
+ push:
13
+ tags:
14
+ - "v*"
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ jobs:
20
+ publish:
21
+ name: Build + publish to PyPI
22
+ runs-on: ubuntu-latest
23
+ permissions:
24
+ # A job-level permissions block REPLACES the workflow-level one (it does not
25
+ # merge), so contents:read must be restated here or actions/checkout 404s on
26
+ # its own repo. Both lines are required.
27
+ contents: read # for actions/checkout
28
+ id-token: write # REQUIRED for Trusted Publishing — this is what replaces the token.
29
+ steps:
30
+ - uses: actions/checkout@v4
31
+
32
+ - uses: actions/setup-python@v5
33
+ with:
34
+ python-version: "3.12"
35
+
36
+ - name: Build sdist + wheel
37
+ run: |
38
+ python -m pip install --upgrade build
39
+ python -m build
40
+
41
+ - name: Check the built distributions
42
+ run: |
43
+ python -m pip install --upgrade twine
44
+ python -m twine check dist/*
45
+
46
+ - name: Publish to PyPI
47
+ # No `with: password:` — the action uses the OIDC token automatically.
48
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,20 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ venv/
9
+
10
+ # Tooling caches
11
+ .pytest_cache/
12
+ .mypy_cache/
13
+ .ruff_cache/
14
+ .coverage
15
+ htmlcov/
16
+ coverage/
17
+
18
+ # Agent tooling (never commit dev artifacts)
19
+ .claude/
20
+ .DS_Store
@@ -0,0 +1,24 @@
1
+ {
2
+ "payload": {
3
+ "schema_version": 1,
4
+ "runtime": "sm-member-sdk",
5
+ "protocol_versions": [
6
+ "0.1"
7
+ ],
8
+ "suite_digest": "sha256:d3610cf5bf09bef6dc49db731a8d93aaf3f553b0df8acf80790d152c8e9dc513",
9
+ "completed_at": "2026-06-05T02:26:45+00:00",
10
+ "exit_status": 0,
11
+ "passed": 22,
12
+ "failed": 0,
13
+ "skipped": 0,
14
+ "xfailed": 0,
15
+ "xpassed": 0,
16
+ "total_vectors": 22,
17
+ "extensions": {
18
+ "arp.conformance.profile": "receipts-0.1"
19
+ }
20
+ },
21
+ "signed_by": "did:key:z6MkgJAvpeMpW1GPaMBBQMifd5zphYvMZtBtU6ZJGJHw8M9F",
22
+ "signed_at": "2026-06-05T02:26:45+00:00",
23
+ "signature": "at8L8Z7S5xdi52d0LX1ui4+YJJUYF+tI3lxtYKAoebyxufdrje31zhT8g9NPeu1W7Mk3karkepUjTr4AgNzvDg=="
24
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "payload": {
3
+ "schema_version": 1,
4
+ "runtime": "sm-member-sdk",
5
+ "protocol_versions": [
6
+ "0.3"
7
+ ],
8
+ "suite_digest": "sha256:dc16b6a2add91e96b86f569d979ca3b616e94bb17f27d5b35c4337a67587d669",
9
+ "completed_at": "2026-06-01T22:59:23.088768+00:00",
10
+ "exit_status": 0,
11
+ "passed": 46,
12
+ "failed": 0,
13
+ "skipped": 1,
14
+ "xfailed": 0,
15
+ "xpassed": 0,
16
+ "total_vectors": 47
17
+ },
18
+ "signed_by": "did:key:z6MkgJAvpeMpW1GPaMBBQMifd5zphYvMZtBtU6ZJGJHw8M9F",
19
+ "signed_at": "2026-06-01T22:59:23.088768+00:00",
20
+ "signature": "HvSvd/Zms2AwckZpfAlAPjVA0I1VyFTrIPg7Jqd8dZ3LitsYpl3zBvGkBEh87g/ZfrWAOaWMQKMCdnZzX1R1Dg=="
21
+ }
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ### Changed
10
+ - **Server rename (Tier 4, brand only — wire frozen).** Prose and docstrings now use *server* vocabulary for the host the client talks to (was "chapter"). No code symbols, env vars, or wire formats changed: the canonical-string formats, header set, did:key derivation, and the `chapter_id` field remain frozen by the protocol. "member" is unchanged — it stays the role word. Conformance stays green.
11
+
12
+ ### Added
13
+ - **ARP receipts.** The SDK is now ARP-native via the `sm_arp` consumable library:
14
+ - `MemberAgent(identity, AgencyLog(...))` — `.record(category, human_summary, ...)` issues a signed receipt, hash-chains it to the agent's previous one (§6.4), appends to the Agency Log (§10.1), and returns it. Emission is the default, not an add-on; the chain resumes from an existing log across restarts.
15
+ - `issue(identity, action=...)` — one-shot signed receipt bound to an identity; `principal_did` defaults to the member's own DID, overridable for delegated action.
16
+ - `verify_receipt` — the consumer surface: verify a counterparty's receipt before trusting it.
17
+ - **Signed ARP conformance badge** at `.nanda/arp-conformance.json`, generated mechanically by `scripts/gen_arp_badge.py` (the canonical receipt vectors run through the SDK's `verify_receipt`).
18
+
19
+ `did:key` derivation is byte-identical to `sm_arp`, so receipts are attributed to the member's DID.
20
+
21
+ ## [0.1.0] — 2026-06-01
22
+
23
+ Initial public release.
24
+
25
+ ### Added
26
+ - `Identity` — Ed25519 keypair plus its derived did:key; `generate` and `from_seed`.
27
+ - `crypto` — did:key derivation/parsing, keypair generation, Ed25519 sign/verify.
28
+ - `signing` — v0.2 and v0.3 canonical strings, header sets, and the `sign_request` one-call signer.
29
+ - `ConformanceAdapter` — plugs the SDK into the server-protocol client conformance suite.
30
+ - Signed conformance badge at `.nanda/conformance.json`.
@@ -0,0 +1,23 @@
1
+ # Governance
2
+
3
+ ## Scope
4
+
5
+ `sm-org-agent` is the client signing surface of the server protocol: identity (did:key), canonical-string construction, Ed25519 signing, and the header set, for v0.2 and v0.3. It is deliberately *not* a transport, an agent runtime, or a product. HTTP, retries, and agent behaviour live above this line, in your code.
6
+
7
+ ## Versioning
8
+
9
+ - The package follows semantic versioning, independent of any protocol version.
10
+ - The **wire it produces** — canonical-string formats, header names and casing, did:key derivation, signature scheme labels — does not change within a major. A change to any of these is a major bump with a CHANGELOG entry and a regenerated conformance badge.
11
+ - Additive or configuration-only changes are minor or patch.
12
+
13
+ ## Conformance
14
+
15
+ A build is conformant *iff* the client conformance suite passes against its adapter and the repository carries a green, signed `.nanda/conformance.json` pinned to that suite's vector digest. A passing badge is a precondition for any release tag. The signing key is a runtime key held outside CI; it is never committed.
16
+
17
+ ## Contributions
18
+
19
+ Issues and pull requests are welcome. A change that touches the produced wire must keep conformance green and update the badge. All code keeps the gate green: `ruff`, `ruff format`, `mypy --strict`, and `pytest` at or above the coverage floor. Run the whole gate with one command before every push — `make ci-local` (uv-orchestrated; the same steps CI runs).
20
+
21
+ ## Attribution
22
+
23
+ Personal research contributions aligned with [Project NANDA](https://projectnanda.org) standards. Maintained by [stellarminds.ai](https://stellarminds.ai).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 stellarminds.ai
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,20 @@
1
+ .PHONY: ci-local sync lint format typecheck test
2
+
3
+ # One command, run before every push. Mirrors CI exactly and hard-fails on the
4
+ # first red step. Same checks the GOVERNANCE gate names: ruff, mypy --strict, pytest.
5
+ ci-local: sync lint format typecheck test
6
+
7
+ sync:
8
+ uv sync --extra dev
9
+
10
+ lint:
11
+ uv run ruff check .
12
+
13
+ format:
14
+ uv run ruff format --check .
15
+
16
+ typecheck:
17
+ uv run mypy sm_agent
18
+
19
+ test:
20
+ uv run pytest -v
@@ -0,0 +1,110 @@
1
+ Metadata-Version: 2.4
2
+ Name: sm-org-agent
3
+ Version: 0.1.0
4
+ Summary: Client signing surface for federated AI-agent chapters — identity, canonical strings, Ed25519 signatures, headers.
5
+ Project-URL: Homepage, https://github.com/Sharathvc23/sm-org-agent
6
+ Project-URL: Repository, https://github.com/Sharathvc23/sm-org-agent
7
+ Project-URL: Changelog, https://github.com/Sharathvc23/sm-org-agent/blob/main/CHANGELOG.md
8
+ Author: stellarminds.ai
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agent,agents,conformance,did,ed25519,signing
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Security :: Cryptography
18
+ Requires-Python: >=3.11
19
+ Requires-Dist: base58>=2.1
20
+ Requires-Dist: cryptography>=42
21
+ Requires-Dist: jcs>=0.2
22
+ Requires-Dist: sm-arp>=0.2.1
23
+ Provides-Extra: dev
24
+ Requires-Dist: mypy>=1.11; extra == 'dev'
25
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
26
+ Requires-Dist: pytest>=8.0; extra == 'dev'
27
+ Requires-Dist: ruff>=0.6; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # sm-org-agent
31
+
32
+ **The client surface for federated AI-agent servers — identity, signed requests, and signed ARP receipts. No transport, no framework.**
33
+
34
+ A *member* is an AI agent with a cryptographic identity. It signs its **requests** so a server can authenticate them, and signs a **receipt** for each action it takes so anyone can later verify what it did. `sm-org-agent` is exactly those surfaces: a did:key identity, the canonical string the server re-derives, Ed25519 signatures, the header set — and an ARP receipt-emitting agent with its Agency Log. No HTTP client, no framework, no transport opinion — just the bytes a server will verify.
35
+
36
+ ```python
37
+ from sm_agent import Identity, sign_request
38
+
39
+ alice = Identity.generate("alice") # keypair + did:key
40
+ headers = sign_request(alice, body='{"kind":"hello"}', timestamp="1700000000")
41
+ # → attach `headers` to your POST; the server verifies the signature
42
+ ```
43
+
44
+ ## Why a separate, tiny SDK
45
+
46
+ A server authenticates a request by re-deriving a **canonical string** from its fields and checking the Ed25519 signature over it. Get one byte wrong — a header name, the field order, the multicodec prefix on a did:key — and every request is rejected. That correctness surface is small, fixed by the spec, and identical across every client. So it deserves to be a single audited library, not re-implemented (and re-broken) in each agent.
47
+
48
+ `sm-org-agent` is that library. It carries no transport because transport is yours: attach the headers to `httpx`, `requests`, an MCP call, anything.
49
+
50
+ ## What it does
51
+
52
+ | Operation | What it gives you |
53
+ |---|---|
54
+ | `Identity.generate(agent_id)` | A fresh Ed25519 identity with its did:key |
55
+ | `Identity.from_seed(agent_id, seed)` | Reconstruct an identity from a stored 32-byte seed |
56
+ | `sign_request(identity, body, timestamp)` | v0.2 signed-request headers |
57
+ | `sign_request(..., method=, url_path=, nonce=)` | v0.3 signed-request headers (replay-resistant) |
58
+ | `MemberAgent(identity, AgencyLog(...))` | A receipt-emitting agent + its Agency Log |
59
+ | `agent.record(category=, human_summary=, ...)` | Issue + hash-chain + log a signed ARP receipt |
60
+ | `issue(identity, action=, ...)` | One-shot signed receipt bound to an identity |
61
+ | `verify_receipt(receipt)` | Verify a counterparty's receipt before trusting it |
62
+ | `crypto.derive_did_key` / `parse_did_key` | did:key ↔ public key |
63
+
64
+ ### Two signing schemes
65
+
66
+ - **v0.2** — canonical `body:agent_id:timestamp`, scheme `ed25519`.
67
+ - **v0.3** — canonical `METHOD:url_path:body:agent_id:timestamp:nonce`, scheme `ed25519+nonce`, with a per-request nonce the server tracks to reject replays.
68
+
69
+ `sign_request` selects v0.3 when you pass `method`, `url_path`, and `nonce`; otherwise v0.2.
70
+
71
+ ## Receipts (ARP)
72
+
73
+ Signing requests proves a member *spoke*; signing **receipts** proves what it *did*. A member emits an [Agency Receipt Protocol](https://github.com/Sharathvc23/sm-arp) receipt for each action — Ed25519-signed, JCS-canonical, hash-chained — and keeps them in its **Agency Log** (ARP §10.1). Emission is the default, not an add-on.
74
+
75
+ ![ARP receipt flow](docs/figures/arp-receipt-flow.svg)
76
+
77
+ ```python
78
+ from sm_agent import Identity, MemberAgent, AgencyLog
79
+
80
+ agent = MemberAgent(Identity.generate("alice"), AgencyLog("alice.sqlite"))
81
+ receipt = agent.record(category="data_shared", human_summary="shared my calendar")
82
+ # signed, hash-chained, logged — ready to POST to a server's /api/receipts
83
+ ```
84
+
85
+ The same identity signs both requests and receipts; `did:key` derivation is byte-identical to the canonical [`sm_arp`](https://github.com/Sharathvc23/sm-arp) library, so a receipt is attributed to the member's DID. A member is also a *consumer* — `verify_receipt` checks the receipts its counterparties present before trusting them.
86
+
87
+ ## Conformance
88
+
89
+ The SDK ships **two** signed badges:
90
+
91
+ - `.nanda/conformance.json` — the server-protocol **client** suite, via a `ConformanceAdapter`:
92
+ ```
93
+ pytest conformance/client --adapter=sm_agent.conformance:ConformanceAdapter
94
+ ```
95
+ - `.nanda/arp-conformance.json` — the **ARP receipt** suite (a distinct corpus → a distinct badge), generated mechanically by `scripts/gen_arp_badge.py`, which runs the canonical receipt vectors through the SDK's `verify_receipt` surface and counts what it accepts/rejects.
96
+
97
+ See the [conformance toolkit](https://github.com/Sharathvc23/sm-conformance) for how badges are produced and verified.
98
+
99
+ ## Development
100
+
101
+ ```
102
+ pip install -e '.[dev]'
103
+ ruff check sm_agent tests
104
+ mypy sm_agent
105
+ pytest # ≥80% coverage gate
106
+ ```
107
+
108
+ ## License
109
+
110
+ MIT © stellarminds.ai. See [LICENSE](LICENSE).
@@ -0,0 +1,48 @@
1
+ # Publishing sm-org-agent to PyPI
2
+
3
+ `sm-org-agent` publishes via **PyPI Trusted Publishing** — no API tokens. You tell PyPI
4
+ once that this repo's `release.yml` workflow may publish; after that, pushing a
5
+ version tag builds and uploads automatically.
6
+
7
+ > Do this only when `sm-org-agent` is meant to be **public**.
8
+
9
+ ## One-time setup (≈5 minutes — this is the part only you can do)
10
+
11
+ 1. Create / sign in to a PyPI account → https://pypi.org/account/register/ (enable 2FA).
12
+ 2. Go to **https://pypi.org/manage/account/publishing/** → "Add a pending
13
+ publisher" (use *pending*, because the `sm-org-agent` project doesn't exist on PyPI
14
+ yet — the first publish creates it).
15
+ 3. Fill the form with **exactly** these values:
16
+
17
+ | Field | Value |
18
+ |-------|-------|
19
+ | PyPI Project Name | `sm-org-agent` |
20
+ | Owner | `Sharathvc23` |
21
+ | Repository name | `sm-org-agent` |
22
+ | **Workflow name** | `release.yml` ← just the filename |
23
+ | Environment name | *(leave blank)* |
24
+
25
+ That's it. No secret is created or stored anywhere.
26
+
27
+ ## Releasing (every time, after setup)
28
+
29
+ ```bash
30
+ # bump version in pyproject.toml, commit, then:
31
+ git tag v0.1.0
32
+ git push origin v0.1.0
33
+ ```
34
+
35
+ The `release` workflow builds the sdist + wheel, runs `twine check`, and uploads
36
+ to PyPI over OIDC. Watch it under the repo's **Actions** tab. Within a minute,
37
+ `pip install sm-org-agent` works for everyone.
38
+
39
+ ## Notes
40
+
41
+ - The tag (`v0.1.0`) and `version` in `pyproject.toml` must match.
42
+ - Dry run anytime, no upload: `python -m build && python -m twine check dist/*`.
43
+ - To test against TestPyPI first, add a pending publisher on
44
+ https://test.pypi.org and point the publish step at it with
45
+ `with: { repository-url: https://test.pypi.org/legacy/ }`.
46
+ - Hardening (optional): set `environment: pypi` on the job + a matching
47
+ Environment name in the PyPI publisher, then require reviewers on that GitHub
48
+ environment so a human approves each release.
@@ -0,0 +1,81 @@
1
+ # sm-org-agent
2
+
3
+ **The client surface for federated AI-agent servers — identity, signed requests, and signed ARP receipts. No transport, no framework.**
4
+
5
+ A *member* is an AI agent with a cryptographic identity. It signs its **requests** so a server can authenticate them, and signs a **receipt** for each action it takes so anyone can later verify what it did. `sm-org-agent` is exactly those surfaces: a did:key identity, the canonical string the server re-derives, Ed25519 signatures, the header set — and an ARP receipt-emitting agent with its Agency Log. No HTTP client, no framework, no transport opinion — just the bytes a server will verify.
6
+
7
+ ```python
8
+ from sm_agent import Identity, sign_request
9
+
10
+ alice = Identity.generate("alice") # keypair + did:key
11
+ headers = sign_request(alice, body='{"kind":"hello"}', timestamp="1700000000")
12
+ # → attach `headers` to your POST; the server verifies the signature
13
+ ```
14
+
15
+ ## Why a separate, tiny SDK
16
+
17
+ A server authenticates a request by re-deriving a **canonical string** from its fields and checking the Ed25519 signature over it. Get one byte wrong — a header name, the field order, the multicodec prefix on a did:key — and every request is rejected. That correctness surface is small, fixed by the spec, and identical across every client. So it deserves to be a single audited library, not re-implemented (and re-broken) in each agent.
18
+
19
+ `sm-org-agent` is that library. It carries no transport because transport is yours: attach the headers to `httpx`, `requests`, an MCP call, anything.
20
+
21
+ ## What it does
22
+
23
+ | Operation | What it gives you |
24
+ |---|---|
25
+ | `Identity.generate(agent_id)` | A fresh Ed25519 identity with its did:key |
26
+ | `Identity.from_seed(agent_id, seed)` | Reconstruct an identity from a stored 32-byte seed |
27
+ | `sign_request(identity, body, timestamp)` | v0.2 signed-request headers |
28
+ | `sign_request(..., method=, url_path=, nonce=)` | v0.3 signed-request headers (replay-resistant) |
29
+ | `MemberAgent(identity, AgencyLog(...))` | A receipt-emitting agent + its Agency Log |
30
+ | `agent.record(category=, human_summary=, ...)` | Issue + hash-chain + log a signed ARP receipt |
31
+ | `issue(identity, action=, ...)` | One-shot signed receipt bound to an identity |
32
+ | `verify_receipt(receipt)` | Verify a counterparty's receipt before trusting it |
33
+ | `crypto.derive_did_key` / `parse_did_key` | did:key ↔ public key |
34
+
35
+ ### Two signing schemes
36
+
37
+ - **v0.2** — canonical `body:agent_id:timestamp`, scheme `ed25519`.
38
+ - **v0.3** — canonical `METHOD:url_path:body:agent_id:timestamp:nonce`, scheme `ed25519+nonce`, with a per-request nonce the server tracks to reject replays.
39
+
40
+ `sign_request` selects v0.3 when you pass `method`, `url_path`, and `nonce`; otherwise v0.2.
41
+
42
+ ## Receipts (ARP)
43
+
44
+ Signing requests proves a member *spoke*; signing **receipts** proves what it *did*. A member emits an [Agency Receipt Protocol](https://github.com/Sharathvc23/sm-arp) receipt for each action — Ed25519-signed, JCS-canonical, hash-chained — and keeps them in its **Agency Log** (ARP §10.1). Emission is the default, not an add-on.
45
+
46
+ ![ARP receipt flow](docs/figures/arp-receipt-flow.svg)
47
+
48
+ ```python
49
+ from sm_agent import Identity, MemberAgent, AgencyLog
50
+
51
+ agent = MemberAgent(Identity.generate("alice"), AgencyLog("alice.sqlite"))
52
+ receipt = agent.record(category="data_shared", human_summary="shared my calendar")
53
+ # signed, hash-chained, logged — ready to POST to a server's /api/receipts
54
+ ```
55
+
56
+ The same identity signs both requests and receipts; `did:key` derivation is byte-identical to the canonical [`sm_arp`](https://github.com/Sharathvc23/sm-arp) library, so a receipt is attributed to the member's DID. A member is also a *consumer* — `verify_receipt` checks the receipts its counterparties present before trusting them.
57
+
58
+ ## Conformance
59
+
60
+ The SDK ships **two** signed badges:
61
+
62
+ - `.nanda/conformance.json` — the server-protocol **client** suite, via a `ConformanceAdapter`:
63
+ ```
64
+ pytest conformance/client --adapter=sm_agent.conformance:ConformanceAdapter
65
+ ```
66
+ - `.nanda/arp-conformance.json` — the **ARP receipt** suite (a distinct corpus → a distinct badge), generated mechanically by `scripts/gen_arp_badge.py`, which runs the canonical receipt vectors through the SDK's `verify_receipt` surface and counts what it accepts/rejects.
67
+
68
+ See the [conformance toolkit](https://github.com/Sharathvc23/sm-conformance) for how badges are produced and verified.
69
+
70
+ ## Development
71
+
72
+ ```
73
+ pip install -e '.[dev]'
74
+ ruff check sm_agent tests
75
+ mypy sm_agent
76
+ pytest # ≥80% coverage gate
77
+ ```
78
+
79
+ ## License
80
+
81
+ MIT © stellarminds.ai. See [LICENSE](LICENSE).
@@ -0,0 +1,77 @@
1
+ # sm-org-agent: The Client Signing Surface for Federated AI Agents
2
+
3
+ ## Abstract
4
+
5
+ For an AI agent to participate in a federated community, every request it sends must be provably from *it*. The mechanism is unglamorous and unforgiving: a cryptographic identity, a canonical string re-derived identically on both ends, and an Ed25519 signature over it. The surface is small and fixed by the protocol — and precisely because it is small and fixed, re-implementing it in each agent is how interoperability quietly breaks. `sm-org-agent` is that surface extracted once, correctly: did:key identity, canonical-string construction, signing, and the header set, with no transport and no framework attached.
6
+
7
+ ## 1. Problem
8
+
9
+ A server authenticates an incoming request by reconstructing the exact string the client claims to have signed and verifying the signature against the presented public key. Every field matters: the order of `body:agent_id:timestamp`, the casing of `X-Agent-Sig-Scheme`, the `0xed01` multicodec prefix that turns a raw public key into a did:key. A single deviation is not a degraded experience — it is a `401`. The whole request is rejected.
10
+
11
+ When this logic is copy-pasted into every agent, three failures follow. Clients drift from the spec in small ways and only discover it against a live server. A client that *thinks* it is compatible cannot prove it. And a protocol upgrade (v0.2 → v0.3) has to be chased through every copy. The surface that makes federation possible becomes the surface that makes it fragile.
12
+
13
+ ## 2. The Client Primitive
14
+
15
+ `sm-org-agent` is the client half of the wire, isolated from everything around it:
16
+
17
+ ```
18
+ your agent · transport · product ← you write this
19
+ ┌──────────────────────────────────────┐
20
+ │ sm-org-agent │ ← the client signing surface
21
+ │ Identity · canonical · sign · headers│
22
+ └──────────────────────────────────────┘
23
+ Ed25519 · did:key ← the cryptographic floor
24
+ ```
25
+
26
+ It depends only on `cryptography` and `base58`. It returns headers, not requests — you attach them to whatever transport you already use. The library has one job and is auditable in an afternoon.
27
+
28
+ ## 3. Design Axioms
29
+
30
+ ### 3.1 Build the bytes the server will verify, exactly
31
+
32
+ The canonical string and header set are not conveniences; they are the contract. The SDK produces them to the letter of the spec.
33
+
34
+ **Consequence:** the SDK is byte-for-byte equivalent to the reference implementation. The conformance suite asserts this against shared vectors — a deviation fails before any server is involved.
35
+
36
+ ### 3.2 Transport is not our concern
37
+
38
+ Signing is pure: identity and request fields in, headers out. No sockets, no retries, no HTTP library.
39
+
40
+ **Consequence:** the SDK composes with any transport (`httpx`, `requests`, MCP, A2A) and stays tiny. The agent owns the network; the SDK owns the signature.
41
+
42
+ ### 3.3 Two schemes, one call
43
+
44
+ v0.2 (`ed25519`) and v0.3 (`ed25519+nonce`, replay-resistant) share an identity and a did:key. `sign_request` selects the scheme from its arguments.
45
+
46
+ **Consequence:** upgrading a client from v0.2 to v0.3 is passing three more arguments, not rewriting its auth.
47
+
48
+ ### 3.4 Conformance is mechanical
49
+
50
+ The SDK exposes its operations to a conformance adapter and ships a signed badge attesting it passes the client suite.
51
+
52
+ **Consequence:** "this client speaks the protocol" becomes a verifiable artifact, not a claim — exactly what a server or registry can demand before trusting a signature.
53
+
54
+ ### 3.5 A member's actions leave receipts
55
+
56
+ Signing a request proves a member *spoke*. It does not record what it *did*. So a member also issues an [ARP](https://github.com/Sharathvc23/sm-arp) receipt for each action — the same Ed25519 identity, now signing a JCS-canonical, hash-chained envelope — and keeps them in an **Agency Log**. The receipt envelope is the one canonical `sm_arp` library, shared with the server, so `did:key` derivation and canonical bytes are byte-identical on both ends. A member verifies its counterparties' receipts through the same library before trusting them.
57
+
58
+ **Consequence:** the member is a first-class participant in a verifiable history, not just an authenticated caller. Its actions are attributable to its DID without a trusted intermediary, and it ships a second signed badge attesting it passes the ARP receipt suite — run mechanically through its own `verify_receipt` surface.
59
+
60
+ ## 4. Where This Fits
61
+
62
+ `sm-org-agent` is the client end of a protocol whose server end is a server. A member mints an identity here, signs its requests *and its receipts* here, and sends them to a server that verifies both. The two were built and conformance-tested independently, against the same shared vectors and the same `sm_arp` receipt library — which is the point: neither has to trust the other's implementation, only the shared spec.
63
+
64
+ ## 5. NANDA Alignment
65
+
66
+ [Project NANDA](https://projectnanda.org) frames the open Internet of Agents around four pillars, of which **CA** (decentralized identity) is the one a member embodies: a self-custodied did:key that signs its own requests. `sm-org-agent` is the conformant client expression of that pillar — the smallest correct way for an agent to *be* an identity on the wire.
67
+
68
+ ## 6. Related Packages
69
+
70
+ | Package | Role |
71
+ |---|---|
72
+ | [`sm-conformance`](https://github.com/Sharathvc23/sm-conformance) | The conformance-badge toolkit — produces and verifies the signed badge this SDK ships |
73
+ | [`sm-arp`](https://github.com/Sharathvc23/sm-arp) | Agency Receipt Protocol — per-action signed receipts an agent emits above this signing layer |
74
+
75
+ ---
76
+
77
+ *Personal research contributions aligned with [Project NANDA](https://projectnanda.org) standards. [Stellarminds.ai](https://stellarminds.ai)*
@@ -0,0 +1,58 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="920" height="440" viewBox="0 0 920 440" font-family="-apple-system, Segoe UI, Roboto, sans-serif">
2
+ <defs>
3
+ <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
4
+ <path d="M0,0 L8,3 L0,6 Z" fill="#475569"/>
5
+ </marker>
6
+ <style>
7
+ .box{fill:#fff;stroke:#cbd5e1;stroke-width:1.5;rx:10}
8
+ .title{font-size:15px;font-weight:700;fill:#0f172a}
9
+ .sub{font-size:11.5px;fill:#475569}
10
+ .lbl{font-size:11.5px;fill:#334155;font-weight:600}
11
+ .edge{stroke:#475569;stroke-width:1.6;fill:none}
12
+ .lib{fill:#eef2ff;stroke:#a5b4fc;stroke-width:1.5}
13
+ .badge{fill:#ecfdf5;stroke:#6ee7b7;stroke-width:1.5}
14
+ .mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11px;fill:#3730a3}
15
+ </style>
16
+ </defs>
17
+
18
+ <text x="30" y="34" class="title" font-size="18">ARP receipts: one signed envelope, every runtime</text>
19
+
20
+ <!-- Member SDK -->
21
+ <rect class="box" x="30" y="70" width="250" height="150" rx="10"/>
22
+ <text x="46" y="98" class="title">sm-org-agent</text>
23
+ <text x="46" y="120" class="sub">MemberAgent.record(action)</text>
24
+ <text x="46" y="140" class="sub">→ signs an ARP receipt</text>
25
+ <text x="46" y="160" class="sub">→ hash-chains it (§6.4)</text>
26
+ <text x="46" y="180" class="sub">→ appends to its Agency Log (§10.1)</text>
27
+ <text x="46" y="203" class="lbl">verify_receipt — checks counterparties</text>
28
+
29
+ <!-- Chapter -->
30
+ <rect class="box" x="640" y="70" width="250" height="150" rx="10"/>
31
+ <text x="656" y="98" class="title">sm-org-server</text>
32
+ <text x="656" y="120" class="sub">POST /api/receipts</text>
33
+ <text x="656" y="140" class="sub">verify → resolve prior → persist</text>
34
+ <text x="656" y="160" class="sub">Issuer Log (§10.2), via ChapterStore</text>
35
+ <text x="656" y="183" class="lbl">also emits: attestation_issued</text>
36
+ <text x="656" y="203" class="sub">issuer=chapter → counterparty=member</text>
37
+
38
+ <!-- arrow member -> chapter -->
39
+ <path class="edge" d="M280,135 L636,135" marker-end="url(#arrow)"/>
40
+ <text x="460" y="125" class="lbl" text-anchor="middle">signed receipt (self-authenticating)</text>
41
+ <text x="460" y="152" class="mono" text-anchor="middle">{"accepted": true, "chain_link": "sha256:…"}</text>
42
+
43
+ <!-- sm_arp library spanning under both -->
44
+ <rect class="lib" x="30" y="250" width="860" height="64" rx="10"/>
45
+ <text x="46" y="278" class="title">sm_arp — the one canonical receipt library</text>
46
+ <text x="46" y="300" class="sub">build · sign · verify · canonical-bytes (JCS / RFC 8785) · chain-link · Issuer/Agency Log — imported by both, so the envelope cannot drift</text>
47
+
48
+ <!-- reputation -->
49
+ <rect class="box" x="640" y="344" width="250" height="66" rx="10"/>
50
+ <text x="656" y="370" class="title">reputation</text>
51
+ <text x="656" y="392" class="sub">reads edges (issuer → counterparty)</text>
52
+ <path class="edge" d="M765,220 L765,344" marker-end="url(#arrow)"/>
53
+
54
+ <!-- badges -->
55
+ <rect class="badge" x="30" y="344" width="560" height="66" rx="10"/>
56
+ <text x="46" y="370" class="title">signed ARP conformance badges</text>
57
+ <text x="46" y="392" class="sub">each runtime: 22/22 vectors, run mechanically against its own surface · profile receipts-0.1 · rung-1 self-signed</text>
58
+ </svg>