ergo-agent-sdk 0.2.0__tar.gz

ergo_agent_sdk-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a bug in the ergo-agent SDK
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+## Describe the Bug
+
+A clear description of what the bug is.
+
+## To Reproduce
+
+```python
+# Minimal code to reproduce:
+from ergo_agent import ErgoNode
+
+node = ErgoNode()
+# ...
+```
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the full error traceback if applicable.
+
+## Environment
+
+- OS: [e.g. Windows 11, Ubuntu 22.04]
+- Python version: [e.g. 3.12]
+- ergo-agent version: [e.g. 0.1.0]

ergo_agent_sdk-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest a new feature for the ergo-agent SDK
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+How should this feature work?
+
+## Alternatives Considered
+
+Any alternative approaches you've thought about.
+
+## Additional Context
+
+Links to relevant Ergo docs, protocols, or examples.

ergo_agent_sdk-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Description
+
+Brief description of what this PR does.
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] `pytest tests/ -v` passes
+- [ ] `ruff check src/` passes
+- [ ] Documentation updated (if public API changed)
+- [ ] No sensitive data (keys, mnemonics) in the diff

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

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run unit tests (no network)
+        run: pytest tests/unit/ -v --tb=short
+
+  integration:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Run integration tests (live testnet API)
+        run: pytest tests/integration/ -v --tb=short
+        env:
+          ERGO_API_URL: https://api.ergoplatform.com
+          ERGO_TEST_ADDRESS: ${{ secrets.ERGO_TEST_ADDRESS }}

ergo_agent_sdk-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to ergo-agent SDK
+
+Thanks for your interest in contributing! This guide covers setup, testing, and PR workflow.
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/ergoplatform/ergo-agent-sdk.git
+cd ergo-agent-sdk
+
+# Create a virtual environment
+python -m venv .venv
+.venv\Scripts\activate       # Windows
+# source .venv/bin/activate  # macOS/Linux
+
+# Install in editable mode with all dev dependencies
+pip install -e ".[all,dev]"
+```
+
+## Running Tests
+
+```bash
+# Unit tests only (fast, no network)
+pytest tests/unit/ -v
+
+# Integration tests (requires internet — hits live APIs)
+pytest tests/integration/ -v
+
+# All tests
+pytest tests/ -v
+```
+
+## Code Style
+
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Documentation
+
+```bash
+pip install mkdocs-material mkdocstrings[python]
+mkdocs serve  # preview at http://localhost:8000
+```
+
+## Pull Request Process
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Add tests for new functionality
+4. Run `pytest tests/ -v` and `ruff check src/`
+5. Update docs if you changed public APIs
+6. Submit a PR with a clear description
+
+## Architecture
+
+See the [Architecture docs](https://ergo-agent.readthedocs.io/architecture/) for how the codebase is structured. Key rule: each layer only depends on the one below it (tools → defi → core).

ergo_agent_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: ergo-agent-sdk
+Version: 0.2.0
+Summary: Open-source Python SDK for AI agents to interact with the Ergo blockchain
+Project-URL: Homepage, https://github.com/ergoplatform/ergo-agent-sdk
+Project-URL: Documentation, https://ergo-agent.readthedocs.io
+Project-URL: Repository, https://github.com/ergoplatform/ergo-agent-sdk
+Project-URL: Issues, https://github.com/ergoplatform/ergo-agent-sdk/issues
+License: MIT
+Keywords: agent,ai,blockchain,defi,ergo,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.8.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.30.0; extra == 'all'
+Requires-Dist: langchain-core>=0.2.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# ergo-agent 🤖⛓️
+
+> **Open-source Python SDK for AI agents on the Ergo blockchain.**
+
+Give any LLM agent (Claude, GPT-4, LangChain, CrewAI...) the ability to read wallet balances, fetch live prices, swap tokens on Spectrum DEX — all autonomously, with built-in safety guardrails.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## Why?
+
+Existing Ergo SDKs (ergpy, fleet-sdk, AppKit) are built for **human developers**. This SDK is built for **AI agents** — it speaks the language of function calling, returns structured JSON, and has a safety layer so the agent can't accidentally drain a wallet.
+
+---
+
+## Quickstart
+
+```bash
+pip install ergo-agent
+```
+
+### Read-only (no wallet needed)
+
+```python
+from ergo_agent import ErgoNode, Wallet
+from ergo_agent.tools import ErgoToolkit, SafetyConfig
+
+node = ErgoNode()
+wallet = Wallet.read_only("9f...")  # any address to monitor
+toolkit = ErgoToolkit(node=node, wallet=wallet)
+
+# Check address balance
+result = toolkit.get_wallet_balance()
+
+# Get live ERG/USD price from Oracle Pool v2
+price = toolkit.get_erg_price()
+
+# Get a swap quote from Spectrum DEX
+quote = toolkit.get_swap_quote(token_in="ERG", token_out="SigUSD", amount_erg=1.0)
+```
+
+### With a wallet (transactions enabled)
+
+```python
+from ergo_agent import ErgoNode, Wallet
+from ergo_agent.tools import ErgoToolkit, SafetyConfig
+
+node = ErgoNode(node_url="http://your-node:9053", api_key="your-key")
+wallet = Wallet.from_node_wallet("9f...")
+
+toolkit = ErgoToolkit(
+    node=node,
+    wallet=wallet,
+    safety=SafetyConfig(
+        max_erg_per_tx=5.0,
+        max_erg_per_day=50.0,
+        allowed_contracts=["spectrum"],
+        rate_limit_per_hour=20,
+    )
+)
+
+# Send ERG
+toolkit.send_erg(to="9f...", amount_erg=1.5)
+
+# Swap ERG for a token on Spectrum DEX
+toolkit.swap_erg_for_token(token_out="SigUSD", amount_erg=1.0)
+```
+
+### Use with LLM frameworks
+
+```python
+# OpenAI function calling
+tools = toolkit.to_openai_tools()
+
+# Anthropic tool use
+tools = toolkit.to_anthropic_tools()
+
+# LangChain
+lc_tools = toolkit.to_langchain_tools()
+```
+
+---
+
+## Available Tools
+
+| Tool | Description | Requires Wallet |
+|---|---|---|
+| `get_wallet_balance` | ERG + token balances | No |
+| `get_erg_price` | Live ERG/USD from Oracle Pool v2 | No |
+| `get_swap_quote` | Spectrum DEX swap quote | No |
+| `get_mempool_status` | Pending transactions | No |
+| `get_safety_status` | Current spending limits & usage | No |
+| `send_erg` | Send ERG to an address | Yes |
+| `swap_erg_for_token` | Execute a swap on Spectrum DEX | Yes |
+
+---
+
+## Architecture
+
+```
+ergo_agent/
+├── core/        # ErgoNode client, Wallet, TransactionBuilder, Address utilities
+├── defi/        # Oracle Pool v2, Spectrum DEX adapters
+└── tools/       # LLM tool schemas (OpenAI / Anthropic / LangChain) + safety layer
+```
+
+---
+
+## Safety Layer
+
+Every state-changing action passes through `SafetyConfig` before execution:
+
+```python
+SafetyConfig(
+    max_erg_per_tx=10.0,                  # hard cap per transaction
+    max_erg_per_day=50.0,                 # daily rolling limit
+    allowed_contracts=["spectrum"],        # contract whitelist
+    rate_limit_per_hour=20,               # max 20 actions/hour
+    dry_run=False,                        # set True for dry-run mode
+)
+```
+
+---
+
+## Network
+
+By default the SDK connects to the **Ergo public API** (`https://api.ergoplatform.com`). For production use or transaction signing, point it at your own node:
+
+```python
+node = ErgoNode(node_url="http://your-node:9053", api_key="your-key")
+```
+
+---
+
+## Contributing
+
+This is an open-source project for the Ergo ecosystem. PRs welcome.
+
+**Roadmap:**
+- v0.1.0 — Core + Oracle + Spectrum + Tool schemas + Safety layer *(current)*
+- v0.2.0 — SigmaUSD + Rosen Bridge adapters
+- v0.3.0 — Treasury contract (ErgoScript on-chain spending limits)
+
+---
+
+## License
+
+MIT

ergo_agent_sdk-0.2.0/README.md

@@ -0,0 +1,150 @@
+# ergo-agent 🤖⛓️
+
+> **Open-source Python SDK for AI agents on the Ergo blockchain.**
+
+Give any LLM agent (Claude, GPT-4, LangChain, CrewAI...) the ability to read wallet balances, fetch live prices, swap tokens on Spectrum DEX — all autonomously, with built-in safety guardrails.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## Why?
+
+Existing Ergo SDKs (ergpy, fleet-sdk, AppKit) are built for **human developers**. This SDK is built for **AI agents** — it speaks the language of function calling, returns structured JSON, and has a safety layer so the agent can't accidentally drain a wallet.
+
+---
+
+## Quickstart
+
+```bash
+pip install ergo-agent
+```
+
+### Read-only (no wallet needed)
+
+```python
+from ergo_agent import ErgoNode, Wallet
+from ergo_agent.tools import ErgoToolkit, SafetyConfig
+
+node = ErgoNode()
+wallet = Wallet.read_only("9f...")  # any address to monitor
+toolkit = ErgoToolkit(node=node, wallet=wallet)
+
+# Check address balance
+result = toolkit.get_wallet_balance()
+
+# Get live ERG/USD price from Oracle Pool v2
+price = toolkit.get_erg_price()
+
+# Get a swap quote from Spectrum DEX
+quote = toolkit.get_swap_quote(token_in="ERG", token_out="SigUSD", amount_erg=1.0)
+```
+
+### With a wallet (transactions enabled)
+
+```python
+from ergo_agent import ErgoNode, Wallet
+from ergo_agent.tools import ErgoToolkit, SafetyConfig
+
+node = ErgoNode(node_url="http://your-node:9053", api_key="your-key")
+wallet = Wallet.from_node_wallet("9f...")
+
+toolkit = ErgoToolkit(
+    node=node,
+    wallet=wallet,
+    safety=SafetyConfig(
+        max_erg_per_tx=5.0,
+        max_erg_per_day=50.0,
+        allowed_contracts=["spectrum"],
+        rate_limit_per_hour=20,
+    )
+)
+
+# Send ERG
+toolkit.send_erg(to="9f...", amount_erg=1.5)
+
+# Swap ERG for a token on Spectrum DEX
+toolkit.swap_erg_for_token(token_out="SigUSD", amount_erg=1.0)
+```
+
+### Use with LLM frameworks
+
+```python
+# OpenAI function calling
+tools = toolkit.to_openai_tools()
+
+# Anthropic tool use
+tools = toolkit.to_anthropic_tools()
+
+# LangChain
+lc_tools = toolkit.to_langchain_tools()
+```
+
+---
+
+## Available Tools
+
+| Tool | Description | Requires Wallet |
+|---|---|---|
+| `get_wallet_balance` | ERG + token balances | No |
+| `get_erg_price` | Live ERG/USD from Oracle Pool v2 | No |
+| `get_swap_quote` | Spectrum DEX swap quote | No |
+| `get_mempool_status` | Pending transactions | No |
+| `get_safety_status` | Current spending limits & usage | No |
+| `send_erg` | Send ERG to an address | Yes |
+| `swap_erg_for_token` | Execute a swap on Spectrum DEX | Yes |
+
+---
+
+## Architecture
+
+```
+ergo_agent/
+├── core/        # ErgoNode client, Wallet, TransactionBuilder, Address utilities
+├── defi/        # Oracle Pool v2, Spectrum DEX adapters
+└── tools/       # LLM tool schemas (OpenAI / Anthropic / LangChain) + safety layer
+```
+
+---
+
+## Safety Layer
+
+Every state-changing action passes through `SafetyConfig` before execution:
+
+```python
+SafetyConfig(
+    max_erg_per_tx=10.0,                  # hard cap per transaction
+    max_erg_per_day=50.0,                 # daily rolling limit
+    allowed_contracts=["spectrum"],        # contract whitelist
+    rate_limit_per_hour=20,               # max 20 actions/hour
+    dry_run=False,                        # set True for dry-run mode
+)
+```
+
+---
+
+## Network
+
+By default the SDK connects to the **Ergo public API** (`https://api.ergoplatform.com`). For production use or transaction signing, point it at your own node:
+
+```python
+node = ErgoNode(node_url="http://your-node:9053", api_key="your-key")
+```
+
+---
+
+## Contributing
+
+This is an open-source project for the Ergo ecosystem. PRs welcome.
+
+**Roadmap:**
+- v0.1.0 — Core + Oracle + Spectrum + Tool schemas + Safety layer *(current)*
+- v0.2.0 — SigmaUSD + Rosen Bridge adapters
+- v0.3.0 — Treasury contract (ErgoScript on-chain spending limits)
+
+---
+
+## License
+
+MIT

ergo_agent_sdk-0.2.0/docs/api-reference.md

@@ -0,0 +1,132 @@
+# API Reference
+
+Complete reference for all public classes and methods.
+
+---
+
+## Core
+
+### ErgoNode
+
+::: ergo_agent.core.node.ErgoNode
+    options:
+      members:
+        - __init__
+        - get_height
+        - get_network_info
+        - get_balance
+        - get_unspent_boxes
+        - get_transaction_history
+        - get_mempool_transactions
+        - get_oracle_pool_box
+        - submit_transaction
+        - close
+
+### Wallet
+
+::: ergo_agent.core.wallet.Wallet
+    options:
+      members:
+        - read_only
+        - from_node_wallet
+        - from_mnemonic
+        - address
+        - sign_transaction
+
+### TransactionBuilder
+
+::: ergo_agent.core.builder.TransactionBuilder
+    options:
+      members:
+        - __init__
+        - send
+        - send_token
+        - add_output_raw
+        - with_input
+        - build
+
+### Address Utilities
+
+::: ergo_agent.core.address
+    options:
+      members:
+        - is_valid_address
+        - validate_address
+        - is_mainnet_address
+        - is_p2pk_address
+        - get_address_type
+        - address_to_ergo_tree
+        - AddressError
+
+### Data Models
+
+::: ergo_agent.core.models.Box
+
+::: ergo_agent.core.models.Balance
+
+::: ergo_agent.core.models.Token
+
+::: ergo_agent.core.models.SwapQuote
+
+::: ergo_agent.core.models.Transaction
+
+---
+
+## DeFi
+
+### OracleReader
+
+::: ergo_agent.defi.oracle.OracleReader
+    options:
+      members:
+        - __init__
+        - get_erg_usd_price
+        - get_erg_usd_nanoerg_per_usd
+        - get_oracle_box_id
+        - get_price_history
+
+### SpectrumDEX
+
+::: ergo_agent.defi.spectrum.SpectrumDEX
+    options:
+      members:
+        - __init__
+        - get_pools
+        - get_erg_price_in_sigusd
+        - get_quote
+        - build_swap_order
+        - close
+
+---
+
+## Tools
+
+### ErgoToolkit
+
+::: ergo_agent.tools.toolkit.ErgoToolkit
+    options:
+      members:
+        - __init__
+        - get_wallet_balance
+        - get_erg_price
+        - get_swap_quote
+        - get_mempool_status
+        - get_safety_status
+        - send_erg
+        - swap_erg_for_token
+        - execute_tool
+        - to_openai_tools
+        - to_anthropic_tools
+        - to_langchain_tools
+
+### SafetyConfig
+
+::: ergo_agent.tools.safety.SafetyConfig
+    options:
+      members:
+        - validate_send
+        - validate_rate_limit
+        - record_action
+        - get_status
+
+::: ergo_agent.tools.safety.SafetyViolation