agirails 2.0.0__tar.gz

agirails-2.0.0/.env.example

@@ -0,0 +1,55 @@
+# AGIRAILS Python SDK - Environment Variables
+# Copy this file to .env and fill in your values
+#
+# IMPORTANT: Never commit .env to version control!
+
+# =============================================================================
+# Wallet Configuration (Required for testnet/mainnet)
+# =============================================================================
+
+# Client wallet (requester) - Your private key for sending transactions
+# Generate a new wallet for testing: https://vanity-eth.tk/
+CLIENT_PRIVATE_KEY=0x_your_client_private_key_here
+
+# Provider wallet - Private key for receiving payments (optional)
+PROVIDER_PRIVATE_KEY=0x_your_provider_private_key_here
+
+# =============================================================================
+# Network Configuration
+# =============================================================================
+
+# Base Sepolia Testnet (default)
+RPC_URL=https://sepolia.base.org
+CHAIN_ID=84532
+
+# Base Mainnet (for production)
+# RPC_URL=https://mainnet.base.org
+# CHAIN_ID=8453
+
+# =============================================================================
+# Contract Addresses (Base Sepolia)
+# =============================================================================
+
+# MockUSDC contract for testnet
+MOCK_USDC_ADDRESS=0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb
+
+# ACTP Kernel contract
+# ACTP_KERNEL_ADDRESS=0xD199070F8e9FB9a127F6Fe730Bc13300B4b3d962
+
+# Escrow Vault contract
+# ESCROW_VAULT_ADDRESS=0x948b9Ea081C4Cec1E112Af2e539224c531d4d585
+
+# =============================================================================
+# EAS (Ethereum Attestation Service)
+# =============================================================================
+
+# Delivery proof schema UID on Base Sepolia
+EAS_DELIVERY_SCHEMA_UID=0x1525e033c59c1c34aa5ab5f38fc0524641835476bca08b2e5c5e076b9ba7ed84
+
+# =============================================================================
+# Local Development (Optional)
+# =============================================================================
+
+# Anvil fork URL for local blockchain testing
+# Run: anvil --fork-url https://sepolia.base.org
+# ANVIL_RPC_URL=http://localhost:8545

agirails-2.0.0/.github/workflows/test.yml

@@ -0,0 +1,388 @@
+name: Python SDK Tests
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/test.yml'
+  workflow_dispatch:  # Allow manual trigger
+
+env:
+  PYTHON_VERSION: '3.11'
+  COVERAGE_THRESHOLD: 85
+
+jobs:
+  # =============================================================================
+  # Fast Unit Tests (< 5 minutes)
+  # =============================================================================
+  test-fast:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    strategy:
+      matrix:
+        python-version: ['3.9', '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 }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: |
+          pytest tests/ \
+            --ignore=tests/integration/ \
+            --ignore=tests/benchmarks/ \
+            -v \
+            --tb=short \
+            -x  # Stop on first failure
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: test-results-${{ matrix.python-version }}
+          path: |
+            pytest.log
+            .pytest_cache/
+
+  # =============================================================================
+  # Coverage Report
+  # =============================================================================
+  test-coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: test-fast
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install pytest-cov
+
+      - name: Run tests with coverage
+        run: |
+          pytest tests/ \
+            --ignore=tests/integration/ \
+            --ignore=tests/benchmarks/ \
+            --cov=src/agirails \
+            --cov-report=xml \
+            --cov-report=html \
+            --cov-report=term-missing \
+            --cov-fail-under=${{ env.COVERAGE_THRESHOLD }}
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: unittests
+          name: python-sdk-coverage
+          fail_ci_if_error: false
+
+      - name: Upload coverage HTML report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: htmlcov/
+
+  # =============================================================================
+  # Security Tests
+  # =============================================================================
+  test-security:
+    name: Security Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: test-fast
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install bandit pip-audit safety
+
+      - name: Run security tests
+        run: |
+          pytest tests/test_security/ -v --tb=short
+
+      - name: Run bandit security linter
+        run: |
+          bandit -r src/agirails -ll -ii --format json -o bandit-report.json || true
+          bandit -r src/agirails -ll -ii
+
+      - name: Run pip-audit for dependency vulnerabilities
+        run: |
+          pip-audit --format json --output pip-audit-report.json || true
+          pip-audit
+
+      - name: Upload security reports
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: security-reports
+          path: |
+            bandit-report.json
+            pip-audit-report.json
+
+  # =============================================================================
+  # Property-Based Tests (Hypothesis)
+  # =============================================================================
+  test-properties:
+    name: Property-Based Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: test-fast
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run property-based tests
+        run: |
+          pytest tests/test_properties/ \
+            -v \
+            --tb=short \
+            --hypothesis-show-statistics \
+            --hypothesis-seed=0  # Reproducible
+
+  # =============================================================================
+  # Parity Tests (Python <-> TypeScript SDK)
+  # =============================================================================
+  test-parity:
+    name: SDK Parity Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: test-fast
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run parity tests
+        run: |
+          pytest tests/test_parity.py -v --tb=short
+
+      - name: Run fixture-based parity tests
+        run: |
+          pytest tests/fixtures/ -v --tb=short || true
+
+  # =============================================================================
+  # Integration Tests (Requires Anvil - Push only)
+  # =============================================================================
+  test-integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    if: github.event_name == 'push'
+    needs: [test-fast, test-security]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install Foundry (Anvil)
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Start Anvil in background
+        run: |
+          anvil --fork-url ${{ secrets.BASE_SEPOLIA_RPC_URL || 'https://sepolia.base.org' }} &
+          sleep 5  # Wait for Anvil to start
+
+      - name: Run integration tests
+        env:
+          ANVIL_RPC_URL: http://localhost:8545
+        run: |
+          pytest tests/integration/ -v --tb=short || echo "Integration tests completed (some may be skipped)"
+
+      - name: Stop Anvil
+        if: always()
+        run: pkill anvil || true
+
+  # =============================================================================
+  # Benchmarks (Main only)
+  # =============================================================================
+  test-benchmarks:
+    name: Performance Benchmarks
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: test-fast
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install pytest-benchmark
+
+      - name: Run benchmarks
+        run: |
+          pytest tests/benchmarks/ \
+            -v \
+            --benchmark-only \
+            --benchmark-json=benchmark-results.json \
+            --benchmark-min-rounds=10 \
+            --benchmark-warmup=on
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark-results.json
+
+      - name: Store benchmark result
+        uses: benchmark-action/github-action-benchmark@v1
+        if: github.event_name == 'push'
+        with:
+          tool: 'pytest'
+          output-file-path: benchmark-results.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true
+          alert-threshold: '150%'
+          comment-on-alert: true
+          fail-on-alert: false
+
+  # =============================================================================
+  # Linting & Type Checking
+  # =============================================================================
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+          pip install -e ".[dev]"
+
+      - name: Run Ruff linter
+        run: |
+          ruff check src/agirails --output-format github
+
+      - name: Run Ruff formatter check
+        run: |
+          ruff format --check src/agirails
+
+      - name: Run mypy type checker
+        run: |
+          mypy src/agirails --ignore-missing-imports --no-error-summary || true
+
+  # =============================================================================
+  # Summary Job
+  # =============================================================================
+  test-summary:
+    name: Test Summary
+    runs-on: ubuntu-latest
+    needs: [test-fast, test-coverage, test-security, test-properties, test-parity, lint]
+    if: always()
+
+    steps:
+      - name: Check test results
+        run: |
+          echo "## Test Results Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Job | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|-----|--------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Unit Tests | ${{ needs.test-fast.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Coverage | ${{ needs.test-coverage.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Security | ${{ needs.test-security.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Properties | ${{ needs.test-properties.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Parity | ${{ needs.test-parity.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Lint | ${{ needs.lint.result }} |" >> $GITHUB_STEP_SUMMARY
+
+      - name: Fail if any required job failed
+        if: |
+          needs.test-fast.result == 'failure' ||
+          needs.test-coverage.result == 'failure' ||
+          needs.test-security.result == 'failure' ||
+          needs.lint.result == 'failure'
+        run: exit 1

agirails-2.0.0/.gitignore

@@ -0,0 +1,89 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# ACTP mock state (created by MockRuntime)
+.actp/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets - never commit
+*.pem
+*.key
+.env.local
+.env.*.local
+secrets.json

agirails-2.0.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to AGIRAILS Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2024-12-25
+
+### Added
+
+#### Core SDK
+- `ACTPClient` - Main client with factory pattern and three-tier API access
+- `ACTPClientConfig` - Configuration dataclass for client initialization
+- `ACTPClientMode` - Enum for mock/blockchain modes
+
+#### Adapters
+- `BasicAdapter` - Simple `pay()` method for quick payments
+- `StandardAdapter` - Full lifecycle control with explicit steps
+- `BaseAdapter` - Shared utilities for amount/deadline parsing
+
+#### Runtime Layer
+- `MockRuntime` - Complete mock implementation for local testing
+- `MockStateManager` - File-based state persistence with atomic locking
+- `IACTPRuntime` - Abstract interface for runtime implementations
+- 8-state transaction lifecycle (INITIATED, QUOTED, COMMITTED, IN_PROGRESS, DELIVERED, SETTLED, DISPUTED, CANCELLED)
+
+#### Error Hierarchy (24 exception types)
+- `ACTPError` - Base exception with structured error codes
+- Transaction errors: `TransactionNotFoundError`, `InvalidStateTransitionError`, `EscrowNotFoundError`
+- Validation errors: `ValidationError`, `InvalidAddressError`, `InvalidAmountError`
+- Network errors: `NetworkError`, `TransactionRevertedError`, `SignatureVerificationError`
+- Storage errors: `StorageError`, `InvalidCIDError`, `UploadTimeoutError`, `DownloadTimeoutError`
+- Agent errors: `NoProviderFoundError`, `ProviderRejectedError`, `DeliveryFailedError`
+- Mock errors: `MockStateCorruptedError`, `MockStateVersionError`, `MockStateLockError`
+
+#### Utilities
+- `NonceTracker` - Thread-safe nonce management for Ethereum transactions
+- `Logger` - Structured logging with JSON output support
+- `LRUCache` - Generic LRU cache with size limits
+- `Semaphore` / `RateLimiter` - Concurrency control primitives
+- Security utilities: `timing_safe_equal()`, `validate_path()`, `safe_json_parse()`
+- Helpers: `USDC`, `Deadline`, `Address`, `Bytes32`, `StateHelper`, `DisputeWindow`
+
+#### Level 0 API (Low-level Primitives)
+- `ServiceDirectory` - Service registration and discovery
+- `ServiceEntry` / `ServiceQuery` - Service metadata and filtering
+- `Provider` / `ProviderConfig` - Provider management
+- `request()` / `provide()` - Core request/provide functions
+
+#### Level 1 API (Agent Framework)
+- `Agent` / `AgentConfig` - Agent abstraction with lifecycle management
+- `Job` / `JobContext` / `JobHandler` - Job handling framework
+- `PricingStrategy` / `CostModel` - Flexible pricing calculations
+- `ServiceConfig` / `ServiceFilter` - Service configuration
+
+#### Types
+- `AgentDID` / `DIDDocument` - Decentralized identity types
+- `Transaction` / `TransactionState` / `TransactionReceipt` - Transaction types
+- `EIP712Domain` / `SignedMessage` / `TypedData` - EIP-712 signing types
+- `ServiceRequest` / `ServiceResponse` / `DeliveryProof` - Message types
+
+#### Testing
+- 337 unit tests covering all modules
+- Async test support with pytest-asyncio
+- Mock runtime enables testing without blockchain
+
+### Changed
+- Full Python 3.9 compatibility (previously required 3.10+)
+- All type annotations now use `Optional[]`, `Union[]`, `List[]`, `Dict[]` from typing module
+- Added `from __future__ import annotations` for deferred evaluation
+
+### Security
+- Added `timing_safe_equal()` for constant-time signature verification
+- Added `safe_json_parse()` to prevent prototype pollution attacks
+- Added `validate_path()` to prevent directory traversal attacks
+- Added query cap limits (`QueryCapExceededError`) for DoS prevention
+- File locking in `MockStateManager` for atomic state operations
+
+### Fixed
+- Signature verification now emits warning instead of silently passing on missing crypto
+
+### Developer Experience
+- Comprehensive docstrings with usage examples
+- Type hints throughout codebase
+- Structured error codes for programmatic error handling
+- Three-tier API for different experience levels
+
+---
+
+## [Unreleased]
+
+### Planned for 2.1.0
+- `BlockchainRuntime` - Real blockchain integration
+- CLI tool implementation (`actp` command)
+- EAS attestation integration
+- Gas estimation and optimization
+
+### Planned for 2.2.0
+- WebSocket event streaming
+- Transaction batching
+- Multi-chain support
+
+---
+
+## Version History
+
+| Version | Date | Highlights |
+|---------|------|------------|
+| 2.0.0 | 2024-12-25 | Initial v2 release with Python 3.9 support |