flop-sdk 0.2.0__py3-none-any.whl

flop_sdk/__init__.py

@@ -0,0 +1,299 @@
+"""
+FLOP Network Python SDK
+
+Async Python library for interacting with the FLOP Network.
+"""
+
+from .agent_wallet import (
+    AgentWalletConfig,
+    OnChainSessionInfo,
+    OnChainWalletInfo,
+    WalletGuard,
+    generate_session_keypair,
+    get_owner_wallet_count,
+    get_session_info,
+    get_total_wallets,
+    get_wallet_info,
+)
+from .agent_wallet import (
+    agent_transfer as agent_transfer_onchain,
+)
+from .agent_wallet import (
+    create_agent_wallet as create_agent_wallet_onchain,
+)
+from .agent_wallet import (
+    create_session as create_session_onchain,
+)
+from .agent_wallet import (
+    deactivate_wallet as deactivate_wallet_onchain,
+)
+from .agent_wallet import (
+    execute_via_session as execute_via_session_onchain,
+)
+from .agent_wallet import (
+    fund_agent_wallet as fund_agent_wallet_onchain,
+)
+from .agent_wallet import (
+    owner_withdraw as owner_withdraw_onchain,
+)
+from .agent_wallet import (
+    reactivate_wallet as reactivate_wallet_onchain,
+)
+from .agent_wallet import (
+    revoke_session as revoke_session_onchain,
+)
+from .client import (
+    SUPPORTED_SPEC_VERSION_RANGE,
+    SUPPORTED_SPEC_VERSIONS,
+    FlopClient,
+    FLOPError,
+)
+from .compute_channel import (
+    TranscriptLeafVersion,
+    TurnRecord,
+    channel_id_v1,
+    compact_u32,
+    decode_compact_u32,
+    decode_transcript_blob,
+    encode_transcript_blob,
+    encode_verified_turn,
+    h_ids,
+    leaf_preimage,
+    merkle_path,
+    merkle_root,
+    receipt_message_v1,
+    root_from_path,
+    task_hash_v1,
+    transcript_leaf,
+)
+from .da_client import (
+    PROVIDER_SOVEREIGN_VALIDATORS,
+    lease_deposit,
+    leased_data_ref,
+    reactivate_blob,
+    register_blob,
+    set_model_weights_ref,
+    top_up_lease,
+    upload_model_weights,
+    withdraw_lease,
+)
+from .hardware import (
+    NvidiaGpuInfo,
+    detect_nvidia_gpus,
+    get_gpu_info,
+    has_cuda_support,
+    is_nvidia_available,
+)
+from .staking_client import (
+    claim_unbonded,
+    delegate_stake,
+    deregister_miner,
+    get_block_rewards_info,
+    get_delegator_stake,
+    get_halving_info,
+    get_miner_contribution,
+    get_miner_info,
+    get_total_miners,
+    get_total_stake,
+    get_unbonding_requests,
+    register_miner,
+    set_commission,
+    set_miner_status,
+    unbond,
+)
+from .staking_types import (
+    BlockRewardsInfo,
+    DelegatorStake,
+    HalvingInfo,
+    MinerContribution,
+    MinerInfo,
+    StakingConstants,
+    UnbondingRequest,
+    perbill_to_percent,
+    percent_to_perbill,
+)
+from .stream import (
+    FlopStream,
+    StreamEvent,
+    StreamHandle,
+    StreamOptions,
+)
+from .substrate import (
+    SessionInfo,
+    SubstrateClient,
+    SubstrateOptions,
+    WalletInfo,
+    agent_transfer,
+    create_agent_wallet,
+    create_session,
+    execute_via_session,
+    fund_agent_wallet,
+    get_agent_wallet,
+    owner_withdraw,
+    revoke_session,
+)
+from .types import (
+    AccountInfo,
+    BuyInferenceParams,
+    ComputeTask,
+    CreateHtlcResult,
+    FlopClientOptions,
+    HealthResponse,
+    HtlcInfo,
+    HtlcStatus,
+    InferenceReceipt,
+    PoUISubmission,
+    TeeQuote,
+)
+from .utils import (
+    flop_to_raw,
+    format_address,
+    format_flop,
+    generate_agent_id,
+    generate_htlc_secrets,
+    raw_to_flop,
+    sign_message,
+    validate_address,
+)
+from .x402 import (
+    PaymentInstructions,
+    X402FetchOptions,
+    build_payment_headers,
+    generate_payment_secret,
+    parse_payment_headers,
+    x402_fetch,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    # Client
+    "FlopClient",
+    "SubstrateClient",
+    "SubstrateOptions",
+    "FLOPError",
+    "SUPPORTED_SPEC_VERSION_RANGE",
+    "SUPPORTED_SPEC_VERSIONS",
+    # Types
+    "FlopClientOptions",
+    "HtlcStatus",
+    "HtlcInfo",
+    "ComputeTask",
+    "TeeQuote",
+    "CreateHtlcResult",
+    "AccountInfo",
+    "HealthResponse",
+    "PoUISubmission",
+    "WalletInfo",
+    "SessionInfo",
+    "NvidiaGpuInfo",
+    # Wallet
+    "create_agent_wallet",
+    "fund_agent_wallet",
+    "agent_transfer",
+    "owner_withdraw",
+    "create_session",
+    "revoke_session",
+    "execute_via_session",
+    "get_agent_wallet",
+    # Utils
+    "generate_htlc_secrets",
+    "sign_message",
+    "format_flop",
+    "flop_to_raw",
+    "raw_to_flop",
+    "format_address",
+    "validate_address",
+    "generate_agent_id",
+    # Hardware
+    "detect_nvidia_gpus",
+    "get_gpu_info",
+    "is_nvidia_available",
+    "has_cuda_support",
+    # x402
+    "PaymentInstructions",
+    "X402FetchOptions",
+    "build_payment_headers",
+    "generate_payment_secret",
+    "parse_payment_headers",
+    "x402_fetch",
+    # Agent Wallet (on-chain)
+    "AgentWalletConfig",
+    "OnChainWalletInfo",
+    "OnChainSessionInfo",
+    "WalletGuard",
+    "generate_session_keypair",
+    "create_agent_wallet_onchain",
+    "fund_agent_wallet_onchain",
+    "agent_transfer_onchain",
+    "owner_withdraw_onchain",
+    "deactivate_wallet_onchain",
+    "reactivate_wallet_onchain",
+    "get_wallet_info",
+    "get_total_wallets",
+    "get_owner_wallet_count",
+    "create_session_onchain",
+    "revoke_session_onchain",
+    "execute_via_session_onchain",
+    "get_session_info",
+    # Streaming
+    "FlopStream",
+    "StreamHandle",
+    "StreamOptions",
+    "StreamEvent",
+    # New Types
+    "InferenceReceipt",
+    "BuyInferenceParams",
+    # Staking & Block Rewards
+    "MinerInfo",
+    "DelegatorStake",
+    "UnbondingRequest",
+    "StakingConstants",
+    "BlockRewardsInfo",
+    "HalvingInfo",
+    "MinerContribution",
+    "perbill_to_percent",
+    "percent_to_perbill",
+    # Staking Client
+    "register_miner",
+    "deregister_miner",
+    "delegate_stake",
+    "unbond",
+    "claim_unbonded",
+    "set_commission",
+    "set_miner_status",
+    "get_miner_info",
+    "get_delegator_stake",
+    "get_unbonding_requests",
+    "get_total_stake",
+    "get_total_miners",
+    "get_block_rewards_info",
+    "get_halving_info",
+    "get_miner_contribution",
+    # DA Registry Client
+    "PROVIDER_SOVEREIGN_VALIDATORS",
+    "leased_data_ref",
+    "lease_deposit",
+    "register_blob",
+    "top_up_lease",
+    "withdraw_lease",
+    "reactivate_blob",
+    "set_model_weights_ref",
+    "upload_model_weights",
+    # Compute channel
+    "TranscriptLeafVersion",
+    "TurnRecord",
+    "channel_id_v1",
+    "compact_u32",
+    "decode_compact_u32",
+    "decode_transcript_blob",
+    "encode_transcript_blob",
+    "encode_verified_turn",
+    "h_ids",
+    "leaf_preimage",
+    "merkle_path",
+    "merkle_root",
+    "receipt_message_v1",
+    "root_from_path",
+    "task_hash_v1",
+    "transcript_leaf",
+]

flop_sdk/agent/errors.py

@@ -0,0 +1,158 @@
+"""
+Agent SDK - Error Codes and Error Classes
+
+Machine-readable error handling for autonomous agents.
+All errors include error codes for programmatic handling.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class AgentErrorCode(Enum):
+    """Error code taxonomy for agent operations."""
+
+    # Session Errors (S001-S099)
+    SESSION_EXPIRED = "S001"
+    SPENDING_LIMIT_EXCEEDED = "S002"
+    INVALID_DELEGATE = "S003"
+    PALLET_NOT_ALLOWED = "S004"
+
+    # Retry Errors (R001-R099)
+    MAX_RETRIES_EXCEEDED = "R001"
+    BACKOFF_TIMEOUT = "R002"
+    NON_RETRYABLE_ERROR = "R003"
+
+    # Budget Errors (B001-B099)
+    INSUFFICIENT_FUNDS = "B001"
+    BUDGET_EXHAUSTED = "B002"
+    COST_ESTIMATE_MISMATCH = "B003"
+
+    # Batch Errors (K001-K099)
+    BATCH_PARTIAL_FAILURE = "K001"
+    BATCH_TIMEOUT = "K002"
+    INVALID_BATCH_OPERATION = "K003"
+
+    # Event Errors (E001-E099)
+    EVENT_STREAM_DISCONNECTED = "E001"
+    EVENT_TIMEOUT = "E002"
+    INVALID_EVENT_PAYLOAD = "E003"
+
+    # Coordination Errors (C001-C099)
+    AGENT_NOT_FOUND = "C001"
+    COORDINATION_TIMEOUT = "C002"
+    INVALID_COORDINATION_REQUEST = "C003"
+
+
+@dataclass
+class AgentError(Exception):
+    """Base agent error with machine-readable code."""
+
+    code: AgentErrorCode
+    message: str
+    retryable: bool = False
+    retry_after_ms: int | None = None
+    context: dict[str, Any] | None = field(default_factory=dict)
+
+    def __post_init__(self):
+        super().__init__(f"[{self.code.value}] {self.message}")
+
+
+class SessionExpiredError(AgentError):
+    """Session expired - needs renewal."""
+
+    def __init__(self, message: str = "Session expired"):
+        super().__init__(
+            code=AgentErrorCode.SESSION_EXPIRED,
+            message=message,
+            retryable=True,
+            retry_after_ms=5000,
+        )
+
+
+class SpendingLimitExceededError(AgentError):
+    """Spending limit exceeded."""
+
+    def __init__(self, available: float, required: float, shortfall: float):
+        super().__init__(
+            code=AgentErrorCode.SPENDING_LIMIT_EXCEEDED,
+            message=f"Available: {available} FLOP, Required: {required} FLOP, Shortfall: {shortfall} FLOP",
+            retryable=False,
+            context={"available": available, "required": required, "shortfall": shortfall},
+        )
+
+
+class InsufficientFundsError(AgentError):
+    """Insufficient funds for operation."""
+
+    def __init__(self, available: float, required: float):
+        super().__init__(
+            code=AgentErrorCode.INSUFFICIENT_FUNDS,
+            message=f"Available: {available} FLOP, Required: {required} FLOP",
+            retryable=False,
+            context={
+                "available": available,
+                "required": required,
+                "shortfall": required - available,
+            },
+        )
+
+
+class MaxRetriesExceededError(AgentError):
+    """Maximum retry attempts exceeded."""
+
+    def __init__(self, attempts: int, last_error: Exception | None = None):
+        super().__init__(
+            code=AgentErrorCode.MAX_RETRIES_EXCEEDED,
+            message=f"Max retries exceeded after {attempts} attempts",
+            retryable=False,
+            context={"attempts": attempts, "last_error": str(last_error) if last_error else None},
+        )
+
+
+class BatchPartialFailureError(AgentError):
+    """Batch operation had partial failures."""
+
+    def __init__(
+        self,
+        total: int,
+        success_count: int,
+        failure_count: int,
+        failures: list[dict[str, Any]] | None = None,
+    ):
+        super().__init__(
+            code=AgentErrorCode.BATCH_PARTIAL_FAILURE,
+            message=f"Batch partial failure: {success_count}/{total} succeeded",
+            retryable=False,
+            context={
+                "total": total,
+                "success_count": success_count,
+                "failure_count": failure_count,
+                "failures": failures or [],
+            },
+        )
+
+
+class EventStreamDisconnectedError(AgentError):
+    """Event stream disconnected."""
+
+    def __init__(self, message: str = "Event stream disconnected"):
+        super().__init__(
+            code=AgentErrorCode.EVENT_STREAM_DISCONNECTED,
+            message=message,
+            retryable=True,
+            retry_after_ms=10000,
+        )
+
+
+__all__ = [
+    "AgentErrorCode",
+    "AgentError",
+    "SessionExpiredError",
+    "SpendingLimitExceededError",
+    "InsufficientFundsError",
+    "MaxRetriesExceededError",
+    "BatchPartialFailureError",
+    "EventStreamDisconnectedError",
+]