grains-sdk 0.1.0__tar.gz

grains_sdk-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

grains_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: grains-sdk
+Version: 0.1.0
+Summary: The Python framework for building Grains agents (hosted AI agents with a signed identity that can charge per call).
+Author: Grains
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://grains.run
+Project-URL: Documentation, https://grains.run/docs.html
+Project-URL: Repository, https://github.com/0000F8/grains
+Keywords: ai,agents,llm,claude,mcp,x402,hosting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: crypto
+Requires-Dist: ecdsa>=0.18; extra == "crypto"
+Requires-Dist: pycryptodome>=3.19; extra == "crypto"
+Dynamic: license-file
+
+# grains-sdk
+
+The Python framework for building [Grains](https://grains.run) agents — deploy
+AI agents that run hosted, get a signed cryptographic identity, and can charge
+per call.
+
+Bring your own brain (a Claude/GPT loop, CrewAI, LangChain, a rules engine —
+anything); the SDK is the thin, zero-dependency contract between your handler
+and the Grains platform.
+
+```python
+from grains import agent
+
+@agent.handler
+def handle(task):
+    return task.reply("echo: " + task.text)
+```
+
+Deploy it with the [`grains` CLI](https://pypi.org/project/grains-cli/) or from
+inside Claude with [`grains-mcp`](https://pypi.org/project/grains-mcp/).
+
+## Install
+
+```bash
+pip install grains-sdk            # core (no runtime deps)
+pip install "grains-sdk[crypto]"  # + offline receipt/identity verification
+```
+
+## API
+
+- `@agent.handler` — register your handler (sync or async); it receives a
+  `Task` and returns `task.reply(...)`.
+- `Task` — `.text`, `.payload`, `.reply(text, **data)`, `.charge(value,
+  currency="USDC")` (amounts are decimal strings, never floats).
+- `agent.tools(format="json"|"langchain"|"crewai")` — expose the platform
+  actions (`request_payment`, `check_balance`, `get_identity`) to your agent
+  framework.
+- `grains.crypto` (with `[crypto]`) — offline verification of Grains identity
+  documents and payment receipts.
+
+Docs: https://grains.run/docs.html · License: Apache-2.0

grains_sdk-0.1.0/README.md

@@ -0,0 +1,41 @@
+# grains-sdk
+
+The Python framework for building [Grains](https://grains.run) agents — deploy
+AI agents that run hosted, get a signed cryptographic identity, and can charge
+per call.
+
+Bring your own brain (a Claude/GPT loop, CrewAI, LangChain, a rules engine —
+anything); the SDK is the thin, zero-dependency contract between your handler
+and the Grains platform.
+
+```python
+from grains import agent
+
+@agent.handler
+def handle(task):
+    return task.reply("echo: " + task.text)
+```
+
+Deploy it with the [`grains` CLI](https://pypi.org/project/grains-cli/) or from
+inside Claude with [`grains-mcp`](https://pypi.org/project/grains-mcp/).
+
+## Install
+
+```bash
+pip install grains-sdk            # core (no runtime deps)
+pip install "grains-sdk[crypto]"  # + offline receipt/identity verification
+```
+
+## API
+
+- `@agent.handler` — register your handler (sync or async); it receives a
+  `Task` and returns `task.reply(...)`.
+- `Task` — `.text`, `.payload`, `.reply(text, **data)`, `.charge(value,
+  currency="USDC")` (amounts are decimal strings, never floats).
+- `agent.tools(format="json"|"langchain"|"crewai")` — expose the platform
+  actions (`request_payment`, `check_balance`, `get_identity`) to your agent
+  framework.
+- `grains.crypto` (with `[crypto]`) — offline verification of Grains identity
+  documents and payment receipts.
+
+Docs: https://grains.run/docs.html · License: Apache-2.0

grains_sdk-0.1.0/grains/__init__.py

@@ -0,0 +1,56 @@
+"""grains-sdk: `@agent.handler`, `Task`, and tool adapters. Stdlib only."""
+from __future__ import annotations
+
+import inspect
+from typing import Callable
+
+from .task import Charge, Reply, Task
+from .tools import get_tools
+
+__all__ = ["agent", "Task", "Reply", "Charge"]
+
+
+class _Agent:
+    """Process-wide handler registry — exactly one handler per process.
+
+    Re-registering (calling @agent.handler again) replaces the previous
+    handler, matching a single Lambda/worker process running one agent.
+    """
+
+    def __init__(self):
+        self._handler: Callable | None = None
+
+    def handler(self, func: Callable) -> Callable:
+        self._handler = func
+        return func
+
+    def get_handler(self) -> Callable | None:
+        return self._handler
+
+    def tools(self, format: str = "json") -> list:
+        return get_tools(format)
+
+    async def invoke(self, task: Task) -> Reply:
+        """Run the registered handler (sync or async) and normalize its result."""
+        handler = self._handler
+        if handler is None:
+            raise RuntimeError("no handler registered; use @agent.handler")
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(task)
+        else:
+            result = handler(task)
+        if isinstance(result, Reply):
+            return result
+        if isinstance(result, str):
+            return task.reply(result)
+        if result is None:
+            if task.replies:
+                return task.replies[-1]
+            raise TypeError(
+                "handler returned None and recorded no reply - did you forget "
+                "`return task.reply(...)`?"
+            )
+        raise TypeError(f"handler must return a Reply or str, got {type(result).__name__}")
+
+
+agent = _Agent()

grains_sdk-0.1.0/grains/crypto.py

@@ -0,0 +1,181 @@
+"""grains-sdk crypto: identity (secp256k1 did:key) and receipt primitives.
+
+Implements spec/identity.md and spec/receipts.md, matching
+spec/tools/generate_vectors.py exactly. Requires the `crypto` extra
+(`ecdsa`, `pycryptodome`); imports of those libraries are deferred into the
+functions that need them so importing this module never requires them.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from datetime import datetime
+from typing import Callable
+
+_B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_DID_PREFIX = "did:key:z"
+_MULTICODEC_SECP256K1 = b"\xe7\x01"
+
+
+def canonical(doc: dict) -> bytes:
+    """Canonical signing bytes per spec/identity.md §4 (`sig` field removed)."""
+    doc = {k: v for k, v in doc.items() if k != "sig"}
+    return json.dumps(doc, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+def _b58encode(data: bytes) -> str:
+    n = int.from_bytes(data, "big")
+    out = ""
+    while n:
+        n, r = divmod(n, 58)
+        out = _B58_ALPHABET[r] + out
+    pad = 0
+    for b in data:
+        if b == 0:
+            pad += 1
+        else:
+            break
+    return "1" * pad + out
+
+
+def _b58decode(s: str) -> bytes:
+    n = 0
+    for ch in s:
+        n = n * 58 + _B58_ALPHABET.index(ch)
+    raw = n.to_bytes((n.bit_length() + 7) // 8, "big")
+    pad = len(s) - len(s.lstrip("1"))
+    return b"\x00" * pad + raw
+
+
+def pubkey_to_did(compressed: bytes) -> str:
+    """secp256k1 compressed pubkey (33 bytes) -> did:key (spec/identity.md §2)."""
+    return _DID_PREFIX + _b58encode(_MULTICODEC_SECP256K1 + compressed)
+
+
+def did_to_pubkey(did: str) -> bytes:
+    """did:key -> secp256k1 compressed pubkey (reverse of spec/identity.md §2)."""
+    if not did.startswith(_DID_PREFIX):
+        raise ValueError(f"not a did:key: {did!r}")
+    decoded = _b58decode(did[len(_DID_PREFIX):])
+    if decoded[:2] != _MULTICODEC_SECP256K1:
+        raise ValueError("not a secp256k1-pub did:key")
+    return decoded[2:]
+
+
+def pubkey_to_evm_address(uncompressed: bytes) -> str:
+    """secp256k1 uncompressed pubkey (65 bytes) -> EVM address (spec/identity.md §3)."""
+    from Crypto.Hash import keccak
+
+    k = keccak.new(digest_bits=256)
+    k.update(uncompressed[1:])
+    return "0x" + k.digest()[-20:].hex()
+
+
+def sign_doc(doc: dict, signer: Callable[[bytes], bytes], did: str) -> dict:
+    """Sign `doc` and return its `sig` object per spec/identity.md §5.
+
+    `signer` receives the SHA-256 digest of the canonical bytes and must
+    return a 64-byte r||s signature -- this is the shared call shape for
+    both local (ecdsa) and KMS signing.
+    """
+    digest = hashlib.sha256(canonical(doc)).digest()
+    raw = signer(digest)
+    value = base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+    return {"alg": "ES256K", "kid": did, "value": value}
+
+
+def _verify_sig(doc: dict) -> "object | None":
+    """Verify a document's `sig` against the key named by `sig.kid`.
+
+    Returns the VerifyingKey on success, else None. Enforces strict low-s
+    (§5, no signature malleability) and fails closed on any malformed input.
+    Does NOT check who kid belongs to -- that binding is the caller's, and
+    differs for identity docs (kid == did) vs receipts (kid == payee).
+    """
+    from ecdsa import BadSignatureError, SECP256k1, VerifyingKey
+    from ecdsa.errors import MalformedPointError
+
+    sig = doc.get("sig")
+    if not isinstance(sig, dict) or sig.get("alg") != "ES256K":
+        return None
+    try:
+        vk = VerifyingKey.from_string(did_to_pubkey(sig["kid"]), curve=SECP256k1)
+        raw = base64.urlsafe_b64decode(sig["value"] + "=" * (-len(sig["value"]) % 4))
+        if len(raw) != 64:
+            return None
+        if int.from_bytes(raw[32:], "big") > SECP256k1.order // 2:
+            return None
+        if not vk.verify(raw, canonical(doc), hashfunc=hashlib.sha256):
+            return None
+        return vk
+    except (BadSignatureError, MalformedPointError, ValueError, KeyError, TypeError):
+        return None
+
+
+def verify_doc(doc: dict) -> bool:
+    """Self-contained identity-document verification per spec/identity.md §7.
+
+    Enforces: valid signature (§5, low-s); sig.kid == doc.did (step 2); and,
+    for every rail binding claiming the root key, that the bound address
+    re-derives from the signing key (step 3). Fails closed.
+    """
+    from ecdsa.errors import MalformedPointError
+
+    # §7 step 2: the signer's key MUST be the document's own DID.
+    if not isinstance(doc.get("sig"), dict) or doc["sig"].get("kid") != doc.get("did"):
+        return False
+    vk = _verify_sig(doc)
+    if vk is None:
+        return False
+
+    # §7 step 3: a rail binding sharing the root key must match a re-derived
+    # address, or a valid signature could still direct funds anywhere.
+    try:
+        expected = pubkey_to_evm_address(b"\x04" + vk.to_string("uncompressed")[-64:])
+    except (MalformedPointError, ValueError):
+        return False
+    for binding in doc.get("bindings", []):
+        if isinstance(binding, dict) and binding.get("type") == "rail":
+            addr = binding.get("address")
+            if isinstance(addr, str) and addr.lower() != expected.lower():
+                return False
+    return True
+
+
+def verify_receipt(receipt: dict) -> tuple[bool, str]:
+    """Offline verification per spec/receipts.md §2 steps 1-4."""
+    payee_identity = receipt.get("payee_identity")
+    if not isinstance(payee_identity, dict):
+        return False, "missing payee_identity"
+    if not verify_doc(payee_identity):
+        return False, "payee_identity signature invalid"
+
+    did = payee_identity.get("did")
+    sig = receipt.get("sig") or {}
+    if not (receipt.get("payee") == did == sig.get("kid")):
+        return False, "payee / payee_identity.did / sig.kid mismatch"
+
+    if _verify_sig(receipt) is None:
+        return False, "receipt signature invalid"
+
+    amount = receipt.get("amount") or {}
+    value = amount.get("value")
+    decimals = amount.get("decimals")
+    if not isinstance(value, str) or not isinstance(decimals, int):
+        return False, "amount malformed"
+    whole, sep, frac = value.partition(".")
+    if not sep or len(frac) != decimals or not frac.isdigit() or not whole.lstrip("-").isdigit():
+        return False, "amount.value malformed for decimals"
+
+    try:
+        datetime.fromisoformat(str(receipt.get("issued_at", "")).replace("Z", "+00:00"))
+    except ValueError:
+        return False, "issued_at malformed"
+
+    if receipt.get("type") != "payment":
+        return False, "unknown receipt type"
+
+    return True, "VERIFIED (offline)"

grains_sdk-0.1.0/grains/task.py

@@ -0,0 +1,43 @@
+"""Task, Reply, and Charge — the SDK's core data shapes."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Reply:
+    text: str
+    data: dict
+
+
+@dataclass
+class Charge:
+    # value is a decimal string (e.g. "1.50"), never a float — see spec/identity.md.
+    value: str
+    currency: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.value, str):
+            raise TypeError(
+                f"charge value must be a decimal string, not {type(self.value).__name__} "
+                "(amounts are never floats)"
+            )
+
+
+class Task:
+    def __init__(self, id: str, text: str, payload: dict | None = None):
+        self.id = id
+        self.text = text
+        self.payload = payload if payload is not None else {}
+        self.replies: list[Reply] = []
+        self.charges: list[Charge] = []
+
+    def reply(self, text: str, **data) -> Reply:
+        r = Reply(text=text, data=data)
+        self.replies.append(r)
+        return r
+
+    def charge(self, value: str, currency: str = "USDC") -> Charge:
+        c = Charge(value=value, currency=currency)
+        self.charges.append(c)
+        return c

grains_sdk-0.1.0/grains/tools.py

@@ -0,0 +1,104 @@
+"""Agent tool definitions and framework adapters.
+
+M1: tool executors are stubs — real payment/identity wiring lands with the
+control plane (M2+). Definitions themselves are stable JSON Schema so agent
+authors can start writing tool-using prompts today.
+"""
+from __future__ import annotations
+
+TOOL_DEFS = [
+    {
+        "name": "request_payment",
+        "description": "Request a payment from the caller for work this agent performed.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "type": "string",
+                    "description": "Decimal amount as a string, e.g. \"1.50\" (never a float).",
+                },
+                "currency": {
+                    "type": "string",
+                    "description": "Currency code.",
+                    "default": "USDC",
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "Human-readable reason for the charge.",
+                },
+            },
+            "required": ["amount"],
+        },
+    },
+    {
+        "name": "check_balance",
+        "description": "Check this agent's current wallet balance.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "currency": {
+                    "type": "string",
+                    "description": "Currency code to check.",
+                    "default": "USDC",
+                },
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "get_identity",
+        "description": "Get this agent's signed identity document (did:key, wallet address).",
+        "input_schema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+]
+
+
+def _stub_executor(**_kwargs) -> dict:
+    return {"status": "unavailable_in_local_dev"}
+
+
+def get_tools(format: str = "json") -> list:
+    if format == "json":
+        return [dict(t) for t in TOOL_DEFS]
+    if format == "langchain":
+        return _wrap_langchain()
+    if format == "crewai":
+        return _wrap_crewai()
+    raise ValueError(f"unknown tools format: {format!r}")
+
+
+def _wrap_langchain() -> list:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as e:
+        raise ImportError(
+            "the 'langchain' tools format requires the 'langchain-core' package "
+            "(pip install langchain-core)"
+        ) from e
+    return [
+        StructuredTool.from_function(
+            func=_stub_executor,
+            name=t["name"],
+            description=t["description"],
+        )
+        for t in TOOL_DEFS
+    ]
+
+
+def _wrap_crewai() -> list:
+    try:
+        from crewai.tools import BaseTool
+    except ImportError as e:
+        raise ImportError(
+            "the 'crewai' tools format requires the 'crewai' package (pip install crewai)"
+        ) from e
+
+    class _StubTool(BaseTool):
+        def _run(self, **kwargs) -> dict:
+            return _stub_executor(**kwargs)
+
+    return [_StubTool(name=t["name"], description=t["description"]) for t in TOOL_DEFS]

grains_sdk-0.1.0/grains_sdk.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: grains-sdk
+Version: 0.1.0
+Summary: The Python framework for building Grains agents (hosted AI agents with a signed identity that can charge per call).
+Author: Grains
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://grains.run
+Project-URL: Documentation, https://grains.run/docs.html
+Project-URL: Repository, https://github.com/0000F8/grains
+Keywords: ai,agents,llm,claude,mcp,x402,hosting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: crypto
+Requires-Dist: ecdsa>=0.18; extra == "crypto"
+Requires-Dist: pycryptodome>=3.19; extra == "crypto"
+Dynamic: license-file
+
+# grains-sdk
+
+The Python framework for building [Grains](https://grains.run) agents — deploy
+AI agents that run hosted, get a signed cryptographic identity, and can charge
+per call.
+
+Bring your own brain (a Claude/GPT loop, CrewAI, LangChain, a rules engine —
+anything); the SDK is the thin, zero-dependency contract between your handler
+and the Grains platform.
+
+```python
+from grains import agent
+
+@agent.handler
+def handle(task):
+    return task.reply("echo: " + task.text)
+```
+
+Deploy it with the [`grains` CLI](https://pypi.org/project/grains-cli/) or from
+inside Claude with [`grains-mcp`](https://pypi.org/project/grains-mcp/).
+
+## Install
+
+```bash
+pip install grains-sdk            # core (no runtime deps)
+pip install "grains-sdk[crypto]"  # + offline receipt/identity verification
+```
+
+## API
+
+- `@agent.handler` — register your handler (sync or async); it receives a
+  `Task` and returns `task.reply(...)`.
+- `Task` — `.text`, `.payload`, `.reply(text, **data)`, `.charge(value,
+  currency="USDC")` (amounts are decimal strings, never floats).
+- `agent.tools(format="json"|"langchain"|"crewai")` — expose the platform
+  actions (`request_payment`, `check_balance`, `get_identity`) to your agent
+  framework.
+- `grains.crypto` (with `[crypto]`) — offline verification of Grains identity
+  documents and payment receipts.
+
+Docs: https://grains.run/docs.html · License: Apache-2.0

grains_sdk-0.1.0/grains_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+grains/__init__.py
+grains/crypto.py
+grains/task.py
+grains/tools.py
+grains_sdk.egg-info/PKG-INFO
+grains_sdk.egg-info/SOURCES.txt
+grains_sdk.egg-info/dependency_links.txt
+grains_sdk.egg-info/requires.txt
+grains_sdk.egg-info/top_level.txt
+tests/test_crypto.py
+tests/test_handler.py
+tests/test_task.py
+tests/test_tools.py

grains_sdk-0.1.0/grains_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

grains_sdk-0.1.0/grains_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[crypto]
+ecdsa>=0.18
+pycryptodome>=3.19

grains_sdk-0.1.0/grains_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+grains

grains_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grains-sdk"
+version = "0.1.0"
+description = "The Python framework for building Grains agents (hosted AI agents with a signed identity that can charge per call)."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Grains" }]
+keywords = ["ai", "agents", "llm", "claude", "mcp", "x402", "hosting"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+crypto = ["ecdsa>=0.18", "pycryptodome>=3.19"]
+
+[project.urls]
+Homepage = "https://grains.run"
+Documentation = "https://grains.run/docs.html"
+Repository = "https://github.com/0000F8/grains"
+
+[tool.setuptools.packages.find]
+include = ["grains*"]

grains_sdk-0.1.0/setup.cfg

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

grains_sdk-0.1.0/tests/test_crypto.py

@@ -0,0 +1,155 @@
+"""crypto.py round-trips against spec/vectors/*.json -- see spec/tools/generate_vectors.py."""
+import base64
+import copy
+import hashlib
+import json
+from pathlib import Path
+
+import pytest
+from grains import crypto
+from grains.crypto import verify_doc
+
+VECTORS = Path(__file__).resolve().parents[2] / "spec" / "vectors"
+
+
+def load(name):
+    return json.loads((VECTORS / name).read_text())
+
+
+def _local_signer(priv: bytes):
+    from ecdsa import SECP256k1, SigningKey
+    from ecdsa.util import sigencode_string_canonize
+
+    sk = SigningKey.from_string(priv, curve=SECP256k1)
+
+    def signer(digest: bytes) -> bytes:
+        return sk.sign_digest_deterministic(
+            digest, hashfunc=hashlib.sha256, sigencode=sigencode_string_canonize
+        )
+
+    return signer
+
+
+def test_key_derivations_match_vector():
+    keys = load("keys.json")
+    compressed = bytes.fromhex(keys["public_key_compressed_hex"])
+    uncompressed = bytes.fromhex(keys["public_key_uncompressed_hex"])
+    assert crypto.pubkey_to_did(compressed) == keys["did"]
+    assert crypto.did_to_pubkey(keys["did"]) == compressed
+    assert crypto.pubkey_to_evm_address(uncompressed) == keys["evm_address"]
+
+
+def test_sign_doc_matches_vector_exactly():
+    keys = load("keys.json")
+    priv = bytes.fromhex(keys["private_key_hex"])
+    identity = load("identity_doc.json")
+    unsigned = {k: v for k, v in identity.items() if k != "sig"}
+    signed = crypto.sign_doc(unsigned, _local_signer(priv), keys["did"])
+    assert signed == identity["sig"]
+
+
+def test_identity_doc_verifies():
+    identity = load("identity_doc.json")
+    assert crypto.verify_doc(identity)
+    assert identity["sig"]["kid"] == identity["did"]
+
+
+def test_receipt_verifies_offline():
+    receipt = load("payment_receipt.json")
+    ok, reason = crypto.verify_receipt(receipt)
+    assert ok, reason
+    assert reason == "VERIFIED (offline)"
+
+
+@pytest.mark.parametrize(
+    "mutate",
+    [
+        lambda d: d.__setitem__("did", d["did"][:-2] + "aa"),
+        lambda d: d["sig"].__setitem__("value", d["sig"]["value"][:-2] + "AA"),
+        lambda d: d["bindings"][0].__setitem__("address", "0x" + "0" * 40),
+    ],
+)
+def test_identity_tamper_fails(mutate):
+    identity = copy.deepcopy(load("identity_doc.json"))
+    mutate(identity)
+    assert not crypto.verify_doc(identity)
+
+
+@pytest.mark.parametrize(
+    "mutate",
+    [
+        lambda r: r["amount"].__setitem__("value", "9.999999"),
+        lambda r: r["tx"].__setitem__("hash", "0x" + "cd" * 32),
+        lambda r: r.__setitem__("payee", r["payee"][:-2] + "aa"),
+        lambda r: r["sig"].__setitem__("value", r["sig"]["value"][:-2] + "AA"),
+        lambda r: r["payee_identity"]["sig"].__setitem__(
+            "value", r["payee_identity"]["sig"]["value"][:-2] + "AA"
+        ),
+    ],
+)
+def test_receipt_tamper_fails(mutate):
+    receipt = copy.deepcopy(load("payment_receipt.json"))
+    mutate(receipt)
+    ok, _reason = crypto.verify_receipt(receipt)
+    assert not ok
+
+
+def test_verify_doc_rejects_missing_sig():
+    assert not crypto.verify_doc({"spec": "grains-identity/0.1"})
+
+
+# --- security regression tests (review findings 2, 6, 7, 8) ---
+
+
+def test_verify_doc_rejects_kid_did_mismatch():
+    # finding 2: sig.kid must equal doc.did
+    doc = copy.deepcopy(load("identity_doc.json"))
+    doc["sig"]["kid"] = doc["did"][:-4] + "aaaa"
+    assert verify_doc(doc) is False
+
+
+def test_verify_doc_rejects_high_s():
+    # finding 6: malleated high-s signature must fail
+    from ecdsa import SECP256k1
+    doc = copy.deepcopy(load("identity_doc.json"))
+    raw = base64.urlsafe_b64decode(doc["sig"]["value"] + "==")
+    r = int.from_bytes(raw[:32], "big")
+    s = int.from_bytes(raw[32:], "big")
+    mall = r.to_bytes(32, "big") + (SECP256k1.order - s).to_bytes(32, "big")
+    doc["sig"]["value"] = base64.urlsafe_b64encode(mall).rstrip(b"=").decode()
+    assert verify_doc(doc) is False
+
+
+def test_verify_doc_fails_closed_on_malformed_did():
+    # finding 7: MalformedPointError must be caught -> False, not raise
+    doc = copy.deepcopy(load("identity_doc.json"))
+    doc["did"] = "did:key:zQ3sNOTAVALIDPOINT"
+    doc["sig"]["kid"] = doc["did"]
+    assert verify_doc(doc) is False
+
+
+def test_verify_doc_rejects_bogus_rail_address():
+    # finding 8: rail binding address must re-derive from the signing key
+    from ecdsa import SECP256k1, SigningKey
+    from ecdsa.util import sigencode_string_canonize
+    from grains.crypto import sign_doc
+
+    keys = load("keys.json")
+    sk = SigningKey.from_string(bytes.fromhex(keys["private_key_hex"]), curve=SECP256k1)
+    doc = copy.deepcopy(load("identity_doc.json"))
+    for b in doc["bindings"]:
+        if b["type"] == "rail":
+            b["address"] = "0x000000000000000000000000000000000000dead"
+    doc.pop("sig", None)
+
+    def signer(digest):
+        return sk.sign_digest_deterministic(
+            digest, hashfunc=hashlib.sha256, sigencode=sigencode_string_canonize
+        )
+
+    doc["sig"] = sign_doc(doc, signer, keys["did"])
+    assert verify_doc(doc) is False
+
+
+def test_verify_doc_still_accepts_genuine():
+    assert verify_doc(load("identity_doc.json")) is True

grains_sdk-0.1.0/tests/test_handler.py

@@ -0,0 +1,100 @@
+import asyncio
+
+import pytest
+from grains import Reply, Task, agent
+
+
+def test_sync_handler_registration_and_reply():
+    @agent.handler
+    def handle(task: Task):
+        return task.reply("sync: " + task.text)
+
+    assert agent.get_handler() is handle
+    task = Task(id="1", text="hi")
+    reply = asyncio.run(agent.invoke(task))
+    assert reply.text == "sync: hi"
+
+
+def test_async_handler_registration_and_reply():
+    @agent.handler
+    async def handle(task: Task):
+        return task.reply("async: " + task.text)
+
+    assert agent.get_handler() is handle
+    task = Task(id="2", text="hi")
+    reply = asyncio.run(agent.invoke(task))
+    assert reply.text == "async: hi"
+
+
+def test_str_return_is_wrapped_as_reply():
+    @agent.handler
+    def handle(task: Task):
+        return "plain string"
+
+    task = Task(id="3", text="hi")
+    reply = asyncio.run(agent.invoke(task))
+    assert isinstance(reply, Reply)
+    assert reply.text == "plain string"
+    assert task.replies == [reply]
+
+
+def test_reregistering_replaces_handler():
+    @agent.handler
+    def first(task: Task):
+        return "first"
+
+    @agent.handler
+    def second(task: Task):
+        return "second"
+
+    assert agent.get_handler() is second
+    task = Task(id="4", text="hi")
+    reply = asyncio.run(agent.invoke(task))
+    assert reply.text == "second"
+
+
+def test_invoke_without_handler_raises():
+    agent._handler = None
+    task = Task(id="5", text="hi")
+    with pytest.raises(RuntimeError):
+        asyncio.run(agent.invoke(task))
+
+
+def test_none_return_with_recorded_reply_uses_it():
+    from grains import Task, agent
+
+    @agent.handler
+    def h(task):
+        task.reply("recorded")
+
+    import asyncio
+    reply = asyncio.run(agent.invoke(Task(id="t", text="x")))
+    assert reply.text == "recorded"
+
+
+def test_none_return_without_reply_raises():
+    import asyncio
+
+    import pytest
+    from grains import Task, agent
+
+    @agent.handler
+    def h(task):
+        return None
+
+    with pytest.raises(TypeError, match="forget"):
+        asyncio.run(agent.invoke(Task(id="t", text="x")))
+
+
+def test_non_reply_return_raises():
+    import asyncio
+
+    import pytest
+    from grains import Task, agent
+
+    @agent.handler
+    def h(task):
+        return {"oops": True}
+
+    with pytest.raises(TypeError, match="dict"):
+        asyncio.run(agent.invoke(Task(id="t", text="x")))

grains_sdk-0.1.0/tests/test_task.py

@@ -0,0 +1,45 @@
+import pytest
+from grains import Task
+
+
+def test_reply_records_and_returns():
+    task = Task(id="t1", text="hello")
+    reply = task.reply("hi there", foo="bar")
+    assert reply.text == "hi there"
+    assert reply.data == {"foo": "bar"}
+    assert task.replies == [reply]
+
+
+def test_charge_records_intent():
+    task = Task(id="t1", text="hello")
+    charge = task.charge("1.50", currency="USDC")
+    assert charge.value == "1.50"
+    assert charge.currency == "USDC"
+    assert task.charges == [charge]
+
+
+def test_charge_default_currency():
+    task = Task(id="t1", text="hello")
+    charge = task.charge("2.00")
+    assert charge.currency == "USDC"
+
+
+def test_charge_rejects_float():
+    task = Task(id="t1", text="hello")
+    with pytest.raises(TypeError):
+        task.charge(1.50)
+
+
+def test_task_payload_defaults_to_empty_dict():
+    task = Task(id="t1", text="hello")
+    assert task.payload == {}
+    task2 = Task(id="t2", text="hello", payload={"a": 1})
+    assert task2.payload == {"a": 1}
+
+
+def test_charge_dataclass_rejects_float_directly():
+    import pytest
+    from grains.task import Charge
+
+    with pytest.raises(TypeError, match="decimal string"):
+        Charge(value=1.5, currency="USDC")

grains_sdk-0.1.0/tests/test_tools.py

@@ -0,0 +1,40 @@
+import pytest
+from grains import agent
+
+EXPECTED_NAMES = {"request_payment", "check_balance", "get_identity"}
+
+
+def test_json_format_returns_three_tools():
+    tools = agent.tools(format="json")
+    assert len(tools) == 3
+    assert {t["name"] for t in tools} == EXPECTED_NAMES
+
+
+def test_json_format_default():
+    assert agent.tools() == agent.tools(format="json")
+
+
+def test_json_tools_have_valid_schema_keys():
+    for tool in agent.tools(format="json"):
+        assert set(tool.keys()) == {"name", "description", "input_schema"}
+        assert isinstance(tool["name"], str)
+        assert isinstance(tool["description"], str)
+        schema = tool["input_schema"]
+        assert schema["type"] == "object"
+        assert "properties" in schema
+        assert "required" in schema
+
+
+def test_langchain_format_raises_import_error_when_missing():
+    with pytest.raises(ImportError, match="langchain-core"):
+        agent.tools(format="langchain")
+
+
+def test_crewai_format_raises_import_error_when_missing():
+    with pytest.raises(ImportError, match="crewai"):
+        agent.tools(format="crewai")
+
+
+def test_unknown_format_raises_value_error():
+    with pytest.raises(ValueError):
+        agent.tools(format="bogus")