mycelium-sdk 0.1.0__tar.gz

mycelium_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: mycelium-sdk
+Version: 0.1.0
+Summary: Mycelium on-chain agent SDK (signing, contract calls, hive discovery, x402)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: stellar-sdk<15,>=14
+Requires-Dist: cryptography>=42
+Requires-Dist: requests>=2.31
+Provides-Extra: langgraph
+Requires-Dist: langgraph; extra == "langgraph"
+Requires-Dist: langchain-core; extra == "langgraph"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai; extra == "gemini"
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+
+# Mycelium SDK
+
+The Mycelium SDK provides a clean, Python-first interface for orchestrating autonomous agents, verifying cryptographically signed payloads, querying the Swarm Hive Registry, and settling M2M payments via the x402 Commerce Protocol on the Stellar/Soroban network.
+
+## Installation
+
+The SDK can be installed directly from PyPI (or via the wrapper `mycelium-stellar` package):
+```bash
+pip install mycelium-sdk
+```
+
+---
+
+## Core Architecture
+
+The SDK handles all off-chain agent logic, cryptography, AI orchestration, and RPC interactions with Soroban.
+
+```
+                  ┌──────────────────────────────┐
+                  │          AI Framework        │
+                  │   (LangGraph/Gemini/etc.)    │
+                  └──────────────┬───────────────┘
+                                 │
+                                 ▼
+                  ┌──────────────────────────────┐
+                  │         Mycelium SDK         │
+                  │ (AgentContext & HiveClient)  │
+                  └──────────────┬───────────────┘
+                                 │
+                                 ▼
+                  ┌──────────────────────────────┐
+                  │    Stellar Soroban Network   │
+                  │    (RPC, Ledger Queries)     │
+                  └──────────────────────────────┘
+```
+
+---
+
+## Primary APIs
+
+### 1. `AgentContext`
+Manages on-chain identity, cryptographic keypairs, and transaction orchestration.
+* `AgentContext(keypair_path: str, network_type: str = "testnet")`
+  - Loads an encrypted wallet keypair from local storage.
+* `AgentContext.read_only(network_type: str = "testnet")`
+  - Initializes a read-only context (does not require a keypair; ideal for registry scans).
+* `AgentContext.from_keypair(keypair: Keypair, network_type: str = "testnet")`
+  - Initializes a context from an in-memory `stellar_sdk.Keypair` object.
+* `call_contract(contract_id: str, function_name: str, args: list, send: bool = False)`
+  - Invokes an on-chain smart contract function.
+* `acall_contract(contract_id: str, function_name: str, args: list)`
+  - Asynchronous contract invocation wrapper.
+
+### 2. `HiveClient`
+Interfaces with the on-chain Hive Registry to register, discover, and resolve agents.
+* `register_agent(name: str, capability_hash: str, endpoint: str)`
+  - Registers the agent's unique name, capabilities, and HTTPS service endpoint.
+* `resolve_agent(name: str) -> dict`
+  - Resolves an agent name to its public address, capabilities, endpoint, and reputation.
+* `lookup_partner_agent(capability: str) -> list[dict]`
+  - Scans the ledger to discover agents matching a specific service capability.
+
+### 3. `EscrowPaymentRouter` (x402 Commerce)
+Manages multi-agent escrow settlements and trustless commerce routing.
+* `create_locked_escrow(recipient: str, amount: str, token: str = None) -> str`
+  - Locks funds on-chain under an escrow contract router.
+* `release_escrow(escrow_id: str, signature: str)`
+  - Releases locked funds to the recipient agent after cryptographic validation.
+* `refund_escrow(escrow_id: str)`
+  - Reclaims locked funds after a predetermined expiry period.
+* **Note**: `EscrowPaymentManager` is maintained as a backward-compatible alias.
+
+### 4. `run_agent_loop`
+Executes autonomous agent orchestration loops wired to cloud LLM APIs (Anthropic, Gemini, etc.) and exposes on-chain interactions as executable LLM tools.
+
+---
+
+## Code Example: Autonomous Payment Agent
+
+```python
+import os
+from mycelium import AgentContext, HiveClient, run_agent_loop, ContractTool
+
+# Load sovereign on-chain identity
+context = AgentContext(keypair_path=".mycelium/wallet.json", network_type="testnet")
+hive = HiveClient(context)
+
+# On-chain contract ID
+CONTRACT_ID = os.environ.get("MYCELIUM_CONTRACT_ID")
+
+def main():
+    print(f"Agent online as: {context.keypair.public_key}")
+    
+    # Run the autonomous execution loop
+    response = run_agent_loop(
+        "Scan the registry for an agent offering translation capabilities, "
+        "negotiate a settlement, and execute the payment.",
+        context=context,
+        provider="gemini",
+        model="gemini-1.5-pro",
+        api_key=os.environ.get("GEMINI_API_KEY"),
+        contract_id=CONTRACT_ID,
+        tools=[
+            ContractTool("increment"),
+            ContractTool("get_count", read_only=True),
+        ],
+        hive=hive
+    )
+    print(f"Loop Response:\n{response}")
+
+if __name__ == "__main__":
+    main()
+```

mycelium_sdk-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Mycelium SDK
+
+The Mycelium SDK provides a clean, Python-first interface for orchestrating autonomous agents, verifying cryptographically signed payloads, querying the Swarm Hive Registry, and settling M2M payments via the x402 Commerce Protocol on the Stellar/Soroban network.
+
+## Installation
+
+The SDK can be installed directly from PyPI (or via the wrapper `mycelium-stellar` package):
+```bash
+pip install mycelium-sdk
+```
+
+---
+
+## Core Architecture
+
+The SDK handles all off-chain agent logic, cryptography, AI orchestration, and RPC interactions with Soroban.
+
+```
+                  ┌──────────────────────────────┐
+                  │          AI Framework        │
+                  │   (LangGraph/Gemini/etc.)    │
+                  └──────────────┬───────────────┘
+                                 │
+                                 ▼
+                  ┌──────────────────────────────┐
+                  │         Mycelium SDK         │
+                  │ (AgentContext & HiveClient)  │
+                  └──────────────┬───────────────┘
+                                 │
+                                 ▼
+                  ┌──────────────────────────────┐
+                  │    Stellar Soroban Network   │
+                  │    (RPC, Ledger Queries)     │
+                  └──────────────────────────────┘
+```
+
+---
+
+## Primary APIs
+
+### 1. `AgentContext`
+Manages on-chain identity, cryptographic keypairs, and transaction orchestration.
+* `AgentContext(keypair_path: str, network_type: str = "testnet")`
+  - Loads an encrypted wallet keypair from local storage.
+* `AgentContext.read_only(network_type: str = "testnet")`
+  - Initializes a read-only context (does not require a keypair; ideal for registry scans).
+* `AgentContext.from_keypair(keypair: Keypair, network_type: str = "testnet")`
+  - Initializes a context from an in-memory `stellar_sdk.Keypair` object.
+* `call_contract(contract_id: str, function_name: str, args: list, send: bool = False)`
+  - Invokes an on-chain smart contract function.
+* `acall_contract(contract_id: str, function_name: str, args: list)`
+  - Asynchronous contract invocation wrapper.
+
+### 2. `HiveClient`
+Interfaces with the on-chain Hive Registry to register, discover, and resolve agents.
+* `register_agent(name: str, capability_hash: str, endpoint: str)`
+  - Registers the agent's unique name, capabilities, and HTTPS service endpoint.
+* `resolve_agent(name: str) -> dict`
+  - Resolves an agent name to its public address, capabilities, endpoint, and reputation.
+* `lookup_partner_agent(capability: str) -> list[dict]`
+  - Scans the ledger to discover agents matching a specific service capability.
+
+### 3. `EscrowPaymentRouter` (x402 Commerce)
+Manages multi-agent escrow settlements and trustless commerce routing.
+* `create_locked_escrow(recipient: str, amount: str, token: str = None) -> str`
+  - Locks funds on-chain under an escrow contract router.
+* `release_escrow(escrow_id: str, signature: str)`
+  - Releases locked funds to the recipient agent after cryptographic validation.
+* `refund_escrow(escrow_id: str)`
+  - Reclaims locked funds after a predetermined expiry period.
+* **Note**: `EscrowPaymentManager` is maintained as a backward-compatible alias.
+
+### 4. `run_agent_loop`
+Executes autonomous agent orchestration loops wired to cloud LLM APIs (Anthropic, Gemini, etc.) and exposes on-chain interactions as executable LLM tools.
+
+---
+
+## Code Example: Autonomous Payment Agent
+
+```python
+import os
+from mycelium import AgentContext, HiveClient, run_agent_loop, ContractTool
+
+# Load sovereign on-chain identity
+context = AgentContext(keypair_path=".mycelium/wallet.json", network_type="testnet")
+hive = HiveClient(context)
+
+# On-chain contract ID
+CONTRACT_ID = os.environ.get("MYCELIUM_CONTRACT_ID")
+
+def main():
+    print(f"Agent online as: {context.keypair.public_key}")
+    
+    # Run the autonomous execution loop
+    response = run_agent_loop(
+        "Scan the registry for an agent offering translation capabilities, "
+        "negotiate a settlement, and execute the payment.",
+        context=context,
+        provider="gemini",
+        model="gemini-1.5-pro",
+        api_key=os.environ.get("GEMINI_API_KEY"),
+        contract_id=CONTRACT_ID,
+        tools=[
+            ContractTool("increment"),
+            ContractTool("get_count", read_only=True),
+        ],
+        hive=hive
+    )
+    print(f"Loop Response:\n{response}")
+
+if __name__ == "__main__":
+    main()
+```

mycelium_sdk-0.1.0/mycelium_sdk/__init__.py

@@ -0,0 +1,35 @@
+from mycelium_sdk.context import AgentContext, StellarNetwork, TxResult
+from mycelium_sdk.hive import HiveClient
+from mycelium_sdk.x402.settlement import EscrowPaymentRouter, EscrowPaymentManager
+from mycelium_sdk.constants import HIVEMIND_REGISTRY_ADDRESS
+from mycelium_sdk.banner import print_banner, show_startup_banner
+from mycelium_sdk.agent_loop import run_agent_loop, ContractTool
+from mycelium_sdk.contract_client import ContractClient
+from mycelium_sdk import logging
+from mycelium_sdk import scval
+from mycelium_sdk.scval import (
+    u32, u64, u128, i32, i64, i128, address, symbol, string, bytes_val, boolean,
+)
+
+__all__ = [
+    "AgentContext",
+    "StellarNetwork",
+    "TxResult",
+    "HiveClient",
+    "EscrowPaymentRouter",
+    "EscrowPaymentManager",
+    "HIVEMIND_REGISTRY_ADDRESS",
+    "print_banner",
+    "show_startup_banner",
+    # one-call agent loop helper (collapses agent.py boilerplate)
+    "run_agent_loop",
+    "ContractTool",
+    # typed contract client: ctx.contract(cid).add(40)
+    "ContractClient",
+    # structured logging (configure(quiet=True) for production agents)
+    "logging",
+    # width-correct Soroban value helpers (no stellar_sdk import needed)
+    "scval",
+    "u32", "u64", "u128", "i32", "i64", "i128",
+    "address", "symbol", "string", "bytes_val", "boolean",
+]

mycelium_sdk-0.1.0/mycelium_sdk/adapters/__init__.py

@@ -0,0 +1,23 @@
+"""
+AI orchestrator adapters (sdk.md §4).
+
+These bridge the on-chain SDK (`AgentContext` / `HiveClient`) to popular LLM
+frameworks by exposing contract calls as framework-native "tools". Each adapter
+lives in its own module and imports its framework lazily, so the heavy optional
+dependency is only required if you actually use that adapter:
+
+    pip install "mycelium[langgraph]"   # or [gemini] / [anthropic]
+
+Example:
+
+    from mycelium_sdk import AgentContext
+    from mycelium_sdk.adapters.langgraph import make_contract_tool
+
+    ctx = AgentContext(".mycelium/wallet.json")
+    trade = make_contract_tool(ctx, "execute_trade",
+                               description="Execute an on-chain trade.")
+"""
+
+from mycelium_sdk.adapters import langgraph, gemini, anthropic
+
+__all__ = ["langgraph", "gemini", "anthropic"]

mycelium_sdk-0.1.0/mycelium_sdk/adapters/anthropic.py

@@ -0,0 +1,81 @@
+"""
+Anthropic (Claude) adapter.
+
+Anthropic tool use is schema-driven: you pass JSON tool definitions to the
+Messages API, then dispatch the model's `tool_use` blocks back to your code.
+This adapter generates the tool schema for an on-chain contract call and a
+dispatcher that executes the call. The `anthropic` SDK is only needed to run the
+conversation loop, not to build the schema; install it with `mycelium[anthropic]`.
+"""
+
+from typing import Any, Callable, Dict, List, Optional
+
+
+def require_anthropic():
+    """Import the anthropic client, with a clear error if the extra is missing."""
+    try:
+        import anthropic
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError(
+            "The Anthropic adapter needs the anthropic SDK. Install it with:\n"
+            "    pip install 'mycelium[anthropic]'"
+        ) from exc
+    return anthropic
+
+
+def contract_tool_schema(
+    name: str,
+    description: str,
+    contract_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Build an Anthropic tool definition for an on-chain contract call. The tool
+    takes an `args` array; if `contract_id` is not fixed here, a `contract_id`
+    string field is added to the schema.
+    """
+    properties: Dict[str, Any] = {
+        "args": {
+            "type": "array",
+            "description": "Positional arguments for the contract function.",
+            "items": {},
+        }
+    }
+    required = ["args"]
+    if contract_id is None:
+        properties["contract_id"] = {
+            "type": "string",
+            "description": "The target Soroban contract id.",
+        }
+        required.append("contract_id")
+
+    return {
+        "name": name,
+        "description": description,
+        "input_schema": {"type": "object", "properties": properties, "required": required},
+    }
+
+
+def make_tool_dispatcher(
+    context,
+    function_name: str,
+    contract_id: Optional[str] = None,
+    read_only: bool = False,
+) -> Callable[[Dict[str, Any]], str]:
+    """
+    Build a dispatcher that executes a Claude `tool_use` block's `input` dict by
+    invoking `function_name` on the contract, returning a string for the
+    tool_result.
+    """
+    def dispatch(tool_input: Dict[str, Any]) -> str:
+        target = contract_id or tool_input.get("contract_id")
+        if not target:
+            return "Error: no contract_id provided."
+        try:
+            result = context.call_contract(
+                target, function_name, list(tool_input.get("args", [])), read_only=read_only
+            )
+            return f"On-chain result: {getattr(result, 'return_value', result)}"
+        except Exception as e:
+            return f"Contract call failed: {e}"
+
+    return dispatch

mycelium_sdk-0.1.0/mycelium_sdk/adapters/gemini.py

@@ -0,0 +1,59 @@
+"""
+Google Gemini adapter (sdk.md §4.2).
+
+Produces plain Python callables that Gemini's automatic function-calling can
+invoke directly (Gemini reads the function signature + docstring), each backed
+by a live on-chain call. Requires `google-generativeai` (install
+`mycelium[gemini]`) only if you build a `GenerativeModel` from them — the helpers
+themselves return ordinary functions.
+"""
+
+from typing import Any, Callable, List, Optional
+
+
+def require_genai():
+    """Import google.generativeai, with a clear error if the extra is missing."""
+    try:
+        import google.generativeai as genai
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError(
+            "The Gemini adapter needs google-generativeai. Install it with:\n"
+            "    pip install 'mycelium[gemini]'"
+        ) from exc
+    return genai
+
+
+def make_contract_function(
+    context,
+    function_name: str,
+    contract_id: str,
+    read_only: bool = False,
+) -> Callable[..., str]:
+    """
+    Build a Gemini-callable function that invokes `function_name` on
+    `contract_id`. The returned function takes a single `args` list and returns
+    a human-readable result string for the model.
+    """
+    def contract_call(args: List[Any]) -> str:
+        """Invoke an on-chain Soroban contract function and return the result."""
+        try:
+            result = context.call_contract(contract_id, function_name, list(args), read_only=read_only)
+            return f"On-chain result: {getattr(result, 'return_value', result)}"
+        except Exception as e:
+            return f"Contract call failed: {e}"
+
+    contract_call.__name__ = function_name
+    return contract_call
+
+
+def make_resolve_agent_function(hive_client) -> Callable[[str], str]:
+    """A Gemini-callable function that resolves an agent via the Hive Registry."""
+    def lookup_partner_agent(name_tag: str) -> str:
+        """Query the Hive Registry to find a registered service agent by name."""
+        try:
+            meta = hive_client.resolve_agent(name_tag)
+            return f"Agent found. Public Key: {meta['public_key']}, Endpoint: {meta['endpoint']}"
+        except Exception:
+            return "Agent name not registered in the Hive Registry."
+
+    return lookup_partner_agent

mycelium_sdk-0.1.0/mycelium_sdk/adapters/langgraph.py

@@ -0,0 +1,76 @@
+"""
+LangGraph / LangChain adapter (sdk.md §4.1).
+
+Turns an on-chain contract function into a LangChain `@tool` that a LangGraph
+node can invoke. Requires `langchain-core` (install `mycelium[langgraph]`).
+"""
+
+from typing import Any, Callable, List, Optional
+
+
+def _require_langchain():
+    try:
+        from langchain_core.tools import tool  # noqa: F401
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError(
+            "The LangGraph adapter needs langchain-core. Install it with:\n"
+            "    pip install 'mycelium[langgraph]'"
+        ) from exc
+    return tool
+
+
+def make_contract_tool(
+    context,
+    function_name: str,
+    contract_id: Optional[str] = None,
+    description: Optional[str] = None,
+    name: Optional[str] = None,
+    read_only: bool = False,
+) -> Callable:
+    """
+    Build a LangChain tool that invokes `function_name` on a Soroban contract.
+
+    The returned tool accepts a single `args` list (the contract call arguments).
+    If `contract_id` is omitted, the tool's first argument is treated as the
+    target contract id.
+    """
+    tool = _require_langchain()
+    tool_name = name or function_name
+    tool_doc = description or f"Invoke '{function_name}' on a Soroban contract."
+
+    @tool(tool_name)
+    def _contract_tool(args: List[Any]) -> str:
+        target = contract_id
+        call_args = list(args)
+        if target is None:
+            if not call_args:
+                return "Error: no contract_id provided and none configured."
+            target, call_args = call_args[0], call_args[1:]
+        try:
+            result = context.call_contract(target, function_name, call_args, read_only=read_only)
+            tx_hash = getattr(result, "hash", None)
+            return (
+                f"Settled on-chain. Tx: {tx_hash}, return: {getattr(result, 'return_value', result)}"
+                if tx_hash else f"Result: {result}"
+            )
+        except Exception as e:  # surface failures to the agent loop
+            return f"Contract call failed: {e}"
+
+    _contract_tool.__doc__ = tool_doc
+    return _contract_tool
+
+
+def make_resolve_agent_tool(hive_client, name: str = "lookup_partner_agent") -> Callable:
+    """A LangChain tool that resolves an agent name via the Hive Registry."""
+    tool = _require_langchain()
+
+    @tool(name)
+    def _resolve(name_tag: str) -> str:
+        """Look up a registered agent by its unique name in the Hive Registry."""
+        try:
+            meta = hive_client.resolve_agent(name_tag)
+            return f"Agent found. Public Key: {meta['public_key']}, Endpoint: {meta['endpoint']}"
+        except Exception:
+            return "Agent name not registered in the Hive Registry."
+
+    return _resolve