opengradient 0.5.7__py3-none-any.whl → 0.5.8__py3-none-any.whl

opengradient/__init__.py

@@ -20,6 +20,7 @@ from .types import (
     ModelOutput,
     ModelRepository,
     FileUploadResult,
+    x402SettlementMode,
 )
 
 from . import llm, alphasense
@@ -47,10 +48,25 @@ def new_client(
         contract_address: Optional inference contract address
     """
 
-    return Client(email=email, password=password, private_key=private_key, rpc_url=rpc_url, api_url=api_url, contract_address=contract_address, **kwargs)
+    return Client(
+        email=email,
+        password=password,
+        private_key=private_key,
+        rpc_url=rpc_url,
+        api_url=api_url,
+        contract_address=contract_address,
+        **kwargs,
+    )
 
 
-def init(email: str, password: str, private_key: str, rpc_url=DEFAULT_RPC_URL, api_url=DEFAULT_API_URL, contract_address=DEFAULT_INFERENCE_CONTRACT_ADDRESS):
+def init(
+    email: str,
+    password: str,
+    private_key: str,
+    rpc_url=DEFAULT_RPC_URL,
+    api_url=DEFAULT_API_URL,
+    contract_address=DEFAULT_INFERENCE_CONTRACT_ADDRESS,
+):
     """Initialize the OpenGradient SDK with authentication and network settings.
 
     Args:
@@ -62,8 +78,10 @@ def init(email: str, password: str, private_key: str, rpc_url=DEFAULT_RPC_URL, a
         contract_address: Optional inference contract address
     """
     global _client
-    
-    _client = Client(private_key=private_key, rpc_url=rpc_url, api_url=api_url, email=email, password=password, contract_address=contract_address)
+
+    _client = Client(
+        private_key=private_key, rpc_url=rpc_url, api_url=api_url, email=email, password=password, contract_address=contract_address
+    )
     return _client
 
 
@@ -162,6 +180,7 @@ def llm_completion(
     stop_sequence: Optional[List[str]] = None,
     temperature: float = 0.0,
     max_retries: Optional[int] = None,
+    x402_settlement_mode: Optional[x402SettlementMode] = x402SettlementMode.SETTLE_BATCH,
 ) -> TextGenerationOutput:
     """Generate text completion using an LLM.
 
@@ -173,6 +192,7 @@ def llm_completion(
         stop_sequence: Optional list of sequences where generation should stop
         temperature: Sampling temperature (0.0 = deterministic, 1.0 = creative)
         max_retries: Maximum number of retries for failed transactions
+        x402_settlement_mode: Settlement modes for x402 payment protocol transactions (enum x402SettlementMode)
 
     Returns:
         TextGenerationOutput: Transaction hash and generated text
@@ -190,6 +210,7 @@ def llm_completion(
         stop_sequence=stop_sequence,
         temperature=temperature,
         max_retries=max_retries,
+        x402_settlement_mode=x402_settlement_mode
     )
 
 
@@ -203,6 +224,7 @@ def llm_chat(
     tools: Optional[List[Dict]] = None,
     tool_choice: Optional[str] = None,
     max_retries: Optional[int] = None,
+    x402_settlement_mode: Optional[x402SettlementMode] = x402SettlementMode.SETTLE_BATCH,
 ) -> TextGenerationOutput:
     """Have a chat conversation with an LLM.
 
@@ -216,6 +238,7 @@ def llm_chat(
         tools: Optional list of tools the model can use
         tool_choice: Optional specific tool to use
         max_retries: Maximum number of retries for failed transactions
+        x402_settlement_mode: Settlement modes for x402 payment protocol transactions (enum x402SettlementMode)
 
     Returns:
         TextGenerationOutput
@@ -235,6 +258,7 @@ def llm_chat(
         tools=tools,
         tool_choice=tool_choice,
         max_retries=max_retries,
+        x402_settlement_mode=x402_settlement_mode
     )
 
 

opengradient/cli.py

@@ -80,6 +80,7 @@ x402SettlementModes = {
     "settle-metadata": x402SettlementMode.SETTLE_METADATA,
 }
 
+
 def initialize_config(ctx):
     """Interactively initialize OpenGradient config"""
     if ctx.obj:  # Check if config data already exists
@@ -140,7 +141,7 @@ def cli(ctx):
             openai_api_key = ctx.obj.get("openai_api_key")
             anthropic_api_key = ctx.obj.get("anthropic_api_key")
             google_api_key = ctx.obj.get("google_api_key")
-            
+
             ctx.obj["client"] = Client(
                 private_key=ctx.obj["private_key"],
                 rpc_url=DEFAULT_RPC_URL,
@@ -219,9 +220,9 @@ def clear(ctx):
 def set_api_key(ctx, provider: str, key: str):
     """
     Set API key for external LLM providers.
-    
+
     Example usage:
-    
+
     \b
     opengradient config set-api-key --provider openai --key ..
     opengradient config set-api-key --provider anthropic --key ...
@@ -230,7 +231,7 @@ def set_api_key(ctx, provider: str, key: str):
     config_key = f"{provider}_api_key"
     ctx.obj[config_key] = key
     save_og_config(ctx)
-    
+
     click.secho(f"✅ API key for {provider} has been set", fg="green")
     click.echo("You can now use models from this provider in completion and chat commands.")
 
@@ -241,9 +242,9 @@ def set_api_key(ctx, provider: str, key: str):
 def remove_api_key(ctx, provider: str):
     """
     Remove API key for an external LLM provider.
-    
+
     Example usage:
-    
+
     \b
     opengradient config remove-api-key --provider openai
     """
@@ -417,52 +418,68 @@ def infer(ctx, model_cid: str, inference_mode: str, input_data, input_file: Path
     help="Model identifier (local model from LLM enum or external model like 'gpt-4o', 'gemini-2.5-flash-lite', etc.)",
 )
 @click.option(
-    "--mode", 
-    "inference_mode", 
-    type=click.Choice(LlmInferenceModes.keys()), 
-    default="VANILLA", 
-    help="Inference mode (only applies to local models, default: VANILLA)"
+    "--mode",
+    "inference_mode",
+    type=click.Choice(LlmInferenceModes.keys()),
+    default="VANILLA",
+    help="Inference mode (only applies to local models, default: VANILLA)",
 )
 @click.option("--prompt", "-p", required=True, help="Input prompt for the LLM completion")
 @click.option("--max-tokens", type=int, default=100, help="Maximum number of tokens for LLM completion output")
 @click.option("--stop-sequence", multiple=True, help="Stop sequences for LLM")
 @click.option("--temperature", type=float, default=0.0, help="Temperature for LLM inference (0.0 to 1.0)")
 @click.option("--local", is_flag=True, help="Force use of local model even if not in LLM enum")
-@click.option("--x402-settlement-mode", "x402_settlement_mode", type=click.Choice(x402SettlementModes.keys()), default="settle-batch", help="Settlement mode for x402 payload")
+@click.option(
+    "--x402-settlement-mode",
+    "x402_settlement_mode",
+    type=click.Choice(x402SettlementModes.keys()),
+    default="settle-batch",
+    help="Settlement mode for x402 payments: settle (hashes only), settle-batch (batched, default), settle-metadata (full data)",
+)
 @click.pass_context
-def completion(ctx, model_cid: str, inference_mode: str, x402_settlement_mode: str, prompt: str, max_tokens: int, stop_sequence: List[str], temperature: float, local: bool):
+def completion(
+    ctx,
+    model_cid: str,
+    inference_mode: str,
+    x402_settlement_mode: str,
+    prompt: str,
+    max_tokens: int,
+    stop_sequence: List[str],
+    temperature: float,
+    local: bool,
+):
     """
     Run completion inference on an LLM model (local or external).
 
-    This command supports both local OpenGradient models and external providers 
-    (OpenAI, Anthropic, Google, etc.). For external models, make sure to set 
+    This command supports both local OpenGradient models and external providers
+    (OpenAI, Anthropic, Google, etc.). For external models, make sure to set
     the appropriate API key using 'opengradient config set-api-key'.
 
     Example usage:
 
     \b
-    # Local model
-    opengradient completion --model meta-llama/Meta-Llama-3-8B-Instruct --prompt "Hello, how are you?" --max-tokens 50
-    
+    # TEE model
+    opengradient completion --model anthropic/claude-3.5-haiku --prompt "Hello, how are you?" --max-tokens 50
+
     # External OpenAI model
     opengradient completion --model gpt-4o --prompt "Translate to French: Hello world" --max-tokens 50
-    
+
     # External Anthropic model
-    opengradient completion --model claude-haiku-4-5-20251001--prompt "Write a haiku about coding" --max-tokens 100
-    
+    opengradient completion --model claude-haiku-4-5-20251001 --prompt "Write a haiku about coding" --max-tokens 100
+
     # External Google model
     opengradient completion --model gemini-2.5-flash-lite --prompt "Explain quantum computing" --max-tokens 200
     """
     client: Client = ctx.obj["client"]
-    
+
     try:
         is_local = local or model_cid in [llm.value for llm in LLM]
-        
+
         if is_local:
             click.echo(f'Running LLM completion inference for local model "{model_cid}"\n')
         else:
             click.echo(f'Running LLM completion inference for external model "{model_cid}"\n')
-        
+
         completion_output = client.llm_completion(
             model_cid=model_cid,
             inference_mode=LlmInferenceModes[inference_mode],
@@ -475,7 +492,7 @@ def completion(ctx, model_cid: str, inference_mode: str, x402_settlement_mode: s
         )
 
         print_llm_completion_result(model_cid, completion_output.transaction_hash, completion_output.completion_output, is_local)
-        
+
     except Exception as e:
         click.echo(f"Error running LLM completion: {str(e)}")
 
@@ -485,7 +502,7 @@ def print_llm_completion_result(model_cid, tx_hash, llm_output, is_local=True):
     click.echo("──────────────────────────────────────")
     click.echo("Model: ", nl=False)
     click.secho(model_cid, fg="cyan", bold=True)
-    
+
     if is_local and tx_hash != "external":
         click.echo("Transaction hash: ", nl=False)
         click.secho(tx_hash, fg="cyan", bold=True)
@@ -495,7 +512,7 @@ def print_llm_completion_result(model_cid, tx_hash, llm_output, is_local=True):
     else:
         click.echo("Source: ", nl=False)
         click.secho("External Provider", fg="cyan", bold=True)
-    
+
     click.echo("──────────────────────────────────────")
     click.secho("LLM Output:", fg="yellow", bold=True)
     click.echo()
@@ -512,11 +529,11 @@ def print_llm_completion_result(model_cid, tx_hash, llm_output, is_local=True):
     help="Model identifier (local model from LLM enum or external model like 'gpt-4o', 'gemini-2.5-flash-lite', etc.)",
 )
 @click.option(
-    "--mode", 
-    "inference_mode", 
-    type=click.Choice(LlmInferenceModes.keys()), 
-    default="VANILLA", 
-    help="Inference mode (only applies to local models, default: VANILLA)"
+    "--mode",
+    "inference_mode",
+    type=click.Choice(LlmInferenceModes.keys()),
+    default="VANILLA",
+    help="Inference mode (only applies to local models, default: VANILLA)",
 )
 @click.option("--messages", type=str, required=False, help="Input messages for the chat inference in JSON format")
 @click.option(
@@ -530,14 +547,16 @@ def print_llm_completion_result(model_cid, tx_hash, llm_output, is_local=True):
 @click.option("--temperature", type=float, default=0.0, help="Temperature for LLM inference (0.0 to 1.0)")
 @click.option("--tools", type=str, default=None, help="Tool configurations in JSON format")
 @click.option(
-    "--tools-file", 
-    type=click.Path(exists=True, path_type=Path), 
-    required=False, 
-    help="Path to JSON file containing tool configurations"
+    "--tools-file", type=click.Path(exists=True, path_type=Path), required=False, help="Path to JSON file containing tool configurations"
 )
 @click.option("--tool-choice", type=str, default="", help="Specific tool choice for the LLM")
 @click.option("--local", is_flag=True, help="Force use of local model even if not in LLM enum")
-@click.option("--x402-settlement-mode", type=click.Choice(x402SettlementModes.keys()), default="settle-batch", help="Settlement mode for x402 payload")
+@click.option(
+    "--x402-settlement-mode",
+    type=click.Choice(x402SettlementModes.keys()),
+    default="settle-batch",
+    help="Settlement mode for x402 payments: settle (hashes only), settle-batch (batched, default), settle-metadata (full data)",
+)
 @click.pass_context
 def chat(
     ctx,
@@ -563,25 +582,25 @@ def chat(
     Example usage:
 
     \b
-    # Local model
-    opengradient chat --model meta-llama/Meta-Llama-3-8B-Instruct --messages '[{"role":"user","content":"hello"}]' --max-tokens 50
-    
+    # TEE model
+    opengradient chat --model anthropic/claude-3.5-haiku --messages '[{"role":"user","content":"hello"}]' --max-tokens 50
+
     # External OpenAI model with tools
     opengradient chat --model gpt-4o --messages-file messages.json --tools-file tools.json --max-tokens 200
-    
+
     # External Anthropic model
     opengradient chat --model claude-haiku-4-5-20251001 --messages '[{"role":"user","content":"Write a poem"}]' --max-tokens 100
     """
     client: Client = ctx.obj["client"]
-    
+
     try:
         is_local = local or model_cid in [llm.value for llm in LLM]
-        
+
         if is_local:
             click.echo(f'Running LLM chat inference for local model "{model_cid}"\n')
         else:
             click.echo(f'Running LLM chat inference for external model "{model_cid}"\n')
-        
+
         # Parse messages
         if not messages and not messages_file:
             click.echo("Must specify either messages or messages-file")
@@ -651,13 +670,9 @@ def chat(
         )
 
         print_llm_chat_result(
-            model_cid, 
-            completion_output.transaction_hash, 
-            completion_output.finish_reason, 
-            completion_output.chat_output,
-            is_local
+            model_cid, completion_output.transaction_hash, completion_output.finish_reason, completion_output.chat_output, is_local
         )
-        
+
     except Exception as e:
         click.echo(f"Error running LLM chat inference: {str(e)}")
 
@@ -667,7 +682,7 @@ def print_llm_chat_result(model_cid, tx_hash, finish_reason, chat_output, is_loc
     click.echo("──────────────────────────────────────")
     click.echo("Model: ", nl=False)
     click.secho(model_cid, fg="cyan", bold=True)
-    
+
     if is_local and tx_hash != "external":
         click.echo("Transaction hash: ", nl=False)
         click.secho(tx_hash, fg="cyan", bold=True)
@@ -677,7 +692,7 @@ def print_llm_chat_result(model_cid, tx_hash, finish_reason, chat_output, is_loc
     else:
         click.echo("Source: ", nl=False)
         click.secho("External Provider", fg="cyan", bold=True)
-    
+
     click.echo("──────────────────────────────────────")
     click.secho("Finish Reason: ", fg="yellow", bold=True)
     click.echo()

opengradient/client.py

@@ -35,11 +35,12 @@ from .types import (
     FileUploadResult,
 )
 from .defaults import (
-    DEFAULT_IMAGE_GEN_HOST, 
-    DEFAULT_IMAGE_GEN_PORT, 
+    DEFAULT_IMAGE_GEN_HOST,
+    DEFAULT_IMAGE_GEN_PORT,
     DEFAULT_SCHEDULER_ADDRESS,
-    DEFAULT_LLM_SERVER_URL, 
-    DEFAULT_OPENGRADIENT_LLM_SERVER_URL)
+    DEFAULT_LLM_SERVER_URL,
+    DEFAULT_OPENGRADIENT_LLM_SERVER_URL,
+)
 from .utils import convert_array_to_model_output, convert_to_model_input, convert_to_model_output
 
 _FIREBASE_CONFIG = {
@@ -65,6 +66,7 @@ PRECOMPILE_CONTRACT_ADDRESS = "0x00000000000000000000000000000000000000F4"
 X402_PROCESSING_HASH_HEADER = "x-processing-hash"
 X402_PLACEHOLDER_API_KEY = "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
 
+
 class Client:
     _inference_hub_contract_address: str
     _blockchain: Web3
@@ -76,20 +78,21 @@ class Client:
     _precompile_abi: Dict
     _llm_server_url: str
     _external_api_keys: Dict[str, str]
+
     def __init__(
-        self, 
-        private_key: str, 
-        rpc_url: str, 
-        api_url: str, 
-        contract_address: str, 
-        email: Optional[str] = None, 
-        password: Optional[str] = None, 
+        self,
+        private_key: str,
+        rpc_url: str,
+        api_url: str,
+        contract_address: str,
+        email: Optional[str] = None,
+        password: Optional[str] = None,
         llm_server_url: Optional[str] = DEFAULT_LLM_SERVER_URL,
         og_llm_server_url: Optional[str] = DEFAULT_OPENGRADIENT_LLM_SERVER_URL,
         openai_api_key: Optional[str] = None,
         anthropic_api_key: Optional[str] = None,
         google_api_key: Optional[str] = None,
-        ):
+    ):
         """
         Initialize the Client with private key, RPC URL, and contract address.
 
@@ -120,7 +123,7 @@ class Client:
 
         self._llm_server_url = llm_server_url
         self._og_llm_server_url = og_llm_server_url
-        
+
         self._external_api_keys = {}
         if openai_api_key or os.getenv("OPENAI_API_KEY"):
             self._external_api_keys["openai"] = openai_api_key or os.getenv("OPENAI_API_KEY")
@@ -132,7 +135,7 @@ class Client:
     def set_api_key(self, provider: str, api_key: str):
         """
         Set or update API key for an external provider.
-        
+
         Args:
             provider: Provider name (e.g., 'openai', 'anthropic', 'google')
             api_key: The API key for the provider
@@ -142,10 +145,10 @@ class Client:
     def _is_local_model(self, model_cid: str) -> bool:
         """
         Check if a model is hosted locally on OpenGradient.
-        
+
         Args:
             model_cid: Model identifier
-            
+
         Returns:
             True if model is local, False if it should use external provider
         """
@@ -158,7 +161,7 @@ class Client:
     def _get_provider_from_model(self, model: str) -> str:
         """Infer provider from model name."""
         model_lower = model.lower()
-        
+
         if "gpt" in model_lower or model.startswith("openai/"):
             return "openai"
         elif "claude" in model_lower or model.startswith("anthropic/"):
@@ -173,10 +176,10 @@ class Client:
     def _get_api_key_for_model(self, model: str) -> Optional[str]:
         """
         Get the appropriate API key for a model.
-        
+
         Args:
             model: Model identifier
-            
+
         Returns:
             API key string or None
         """
@@ -451,11 +454,17 @@ class Client:
             temperature (float): Temperature for LLM inference, between 0 and 1. Default is 0.0.
             max_retries (int, optional): Maximum number of retry attempts for blockchain transactions.
             local_model (bool, optional): Force use of local model even if not in LLM enum.
+            x402_settlement_mode (x402SettlementMode, optional): Settlement mode for x402 payments.
+                - SETTLE: Records input/output hashes only (most privacy-preserving).
+                - SETTLE_BATCH: Aggregates multiple inferences into batch hashes (most cost-efficient).
+                - SETTLE_METADATA: Records full model info, complete input/output data, and all metadata.
+                Defaults to SETTLE_BATCH.
 
         Returns:
             TextGenerationOutput: Generated text results including:
                 - Transaction hash (or "external" for external providers)
                 - String of completion output
+                - Payment hash for x402 transactions (when using x402 settlement)
 
         Raises:
             OpenGradientError: If the inference fails.
@@ -467,14 +476,14 @@ class Client:
                 return OpenGradientError("That model CID is not supported yet for TEE inference")
 
             return self._external_llm_completion(
-                model=model_cid.split('/')[1],
+                model=model_cid.split("/")[1],
                 prompt=prompt,
                 max_tokens=max_tokens,
                 stop_sequence=stop_sequence,
                 temperature=temperature,
                 x402_settlement_mode=x402_settlement_mode,
             )
-        
+
         # Original local model logic
         def execute_transaction():
             if inference_mode != LlmInferenceMode.VANILLA:
@@ -482,10 +491,10 @@ class Client:
 
             if model_cid not in [llm.value for llm in LLM]:
                 raise OpenGradientError("That model CID is not yet supported for inference")
-            
+
             model_name = model_cid
             if model_cid in [llm.value for llm in TEE_LLM]:
-                model_name = model_cid.split('/')[1]
+                model_name = model_cid.split("/")[1]
 
             contract = self._blockchain.eth.contract(address=self._inference_hub_contract_address, abi=self._inference_abi)
 
@@ -523,55 +532,49 @@ class Client:
     ) -> TextGenerationOutput:
         """
         Route completion request to external LLM server with x402 payments.
-        
+
         Args:
             model: Model identifier
             prompt: Input prompt
             max_tokens: Maximum tokens to generate
             stop_sequence: Stop sequences
             temperature: Sampling temperature
-            
+
         Returns:
             TextGenerationOutput with completion
-            
+
         Raises:
             OpenGradientError: If request fails
         """
         api_key = self._get_api_key_for_model(model)
-    
+
         if api_key:
             logging.debug("External LLM completions using API key")
             url = f"{self._llm_server_url}/v1/completions"
-            
-            headers = {
-                "Content-Type": "application/json",
-                "Authorization": f"Bearer {api_key}"
-            }
-            
+
+            headers = {"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"}
+
             payload = {
                 "model": model,
                 "prompt": prompt,
                 "max_tokens": max_tokens,
                 "temperature": temperature,
             }
-            
+
             if stop_sequence:
                 payload["stop"] = stop_sequence
-            
+
             try:
                 response = requests.post(url, json=payload, headers=headers, timeout=60)
                 response.raise_for_status()
-                
+
                 result = response.json()
-                
-                return TextGenerationOutput(
-                    transaction_hash="external",
-                    completion_output=result.get("completion")
-                )
-                
+
+                return TextGenerationOutput(transaction_hash="external", completion_output=result.get("completion"))
+
             except requests.RequestException as e:
                 error_msg = f"External LLM completion failed: {str(e)}"
-                if hasattr(e, 'response') and e.response is not None:
+                if hasattr(e, "response") and e.response is not None:
                     try:
                         error_detail = e.response.json()
                         error_msg += f" - {error_detail}"
@@ -591,20 +594,20 @@ class Client:
                     "Authorization": f"Bearer {X402_PLACEHOLDER_API_KEY}",
                     "X-SETTLEMENT-TYPE": x402_settlement_mode,
                 }
-                
+
                 payload = {
                     "model": model,
                     "prompt": prompt,
                     "max_tokens": max_tokens,
                     "temperature": temperature,
                 }
-                
+
                 if stop_sequence:
                     payload["stop"] = stop_sequence
-                
+
                 try:
                     response = await client.post("/v1/completions", json=payload, headers=headers, timeout=60)
-                    
+
                     # Read the response content
                     content = await response.aread()
                     result = json.loads(content.decode())
@@ -612,24 +615,22 @@ class Client:
 
                     if X402_PROCESSING_HASH_HEADER in response.headers:
                         payment_hash = response.headers[X402_PROCESSING_HASH_HEADER]
-                    
+
                     return TextGenerationOutput(
-                        transaction_hash="external",
-                        completion_output=result.get("completion"),
-                        payment_hash=payment_hash
+                        transaction_hash="external", completion_output=result.get("completion"), payment_hash=payment_hash
                     )
-                    
+
                 except Exception as e:
                     error_msg = f"External LLM completion request failed: {str(e)}"
                     logging.error(error_msg)
                     raise OpenGradientError(error_msg)
-        
+
         try:
             # Run the async function in a sync context
             return asyncio.run(make_request())
         except Exception as e:
             error_msg = f"External LLM completion failed: {str(e)}"
-            if hasattr(e, 'response') and e.response is not None:
+            if hasattr(e, "response") and e.response is not None:
                 try:
                     error_detail = e.response.json()
                     error_msg += f" - {error_detail}"
@@ -666,9 +667,18 @@ class Client:
             tool_choice (str, optional): Sets a specific tool to choose.
             max_retries (int, optional): Maximum number of retry attempts.
             local_model (bool, optional): Force use of local model.
+            x402_settlement_mode (x402SettlementMode, optional): Settlement mode for x402 payments.
+                - SETTLE: Records input/output hashes only (most privacy-preserving).
+                - SETTLE_BATCH: Aggregates multiple inferences into batch hashes (most cost-efficient).
+                - SETTLE_METADATA: Records full model info, complete input/output data, and all metadata.
+                Defaults to SETTLE_BATCH.
 
         Returns:
-            TextGenerationOutput: Generated text results.
+            TextGenerationOutput: Generated text results including:
+                - chat_output: Dict with role, content, and tool_calls
+                - transaction_hash: Blockchain hash (or "external" for external providers)
+                - finish_reason: Reason for completion (e.g., "stop", "tool_call")
+                - payment_hash: Payment hash for x402 transactions (when using x402 settlement)
 
         Raises:
             OpenGradientError: If the inference fails.
@@ -680,7 +690,7 @@ class Client:
                 return OpenGradientError("That model CID is not supported yet for TEE inference")
 
             return self._external_llm_chat(
-                model=model_cid.split('/')[1],
+                model=model_cid.split("/")[1],
                 messages=messages,
                 max_tokens=max_tokens,
                 stop_sequence=stop_sequence,
@@ -689,18 +699,18 @@ class Client:
                 tool_choice=tool_choice,
                 x402_settlement_mode=x402_settlement_mode,
             )
-        
+
         # Original local model logic
         def execute_transaction():
             if inference_mode != LlmInferenceMode.VANILLA:
                 raise OpenGradientError("Invalid inference mode %s: Inference mode must be VANILLA or TEE" % inference_mode)
-            
+
             if model_cid not in [llm.value for llm in LLM]:
                 raise OpenGradientError("That model CID is not yet supported for inference")
-            
+
             model_name = model_cid
             if model_cid in [llm.value for llm in TEE_LLM]:
-                model_name = model_cid.split('/')[1]
+                model_name = model_cid.split("/")[1]
 
             contract = self._blockchain.eth.contract(address=self._inference_hub_contract_address, abi=self._inference_abi)
 
@@ -771,7 +781,7 @@ class Client:
     ) -> TextGenerationOutput:
         """
         Route chat request to external LLM server with x402 payments.
-        
+
         Args:
             model: Model identifier
             messages: List of chat messages
@@ -780,53 +790,48 @@ class Client:
             temperature: Sampling temperature
             tools: Function calling tools
             tool_choice: Tool selection strategy
-            
+
         Returns:
             TextGenerationOutput with chat completion
-            
+
         Raises:
             OpenGradientError: If request fails
         """
         api_key = self._get_api_key_for_model(model)
-    
+
         if api_key:
             logging.debug("External LLM completion using API key")
             url = f"{self._llm_server_url}/v1/chat/completions"
-            
-            headers = {
-                "Content-Type": "application/json",
-                "Authorization": f"Bearer {api_key}"
-            }
-            
+
+            headers = {"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"}
+
             payload = {
                 "model": model,
                 "messages": messages,
                 "max_tokens": max_tokens,
                 "temperature": temperature,
             }
-            
+
             if stop_sequence:
                 payload["stop"] = stop_sequence
-            
+
             if tools:
                 payload["tools"] = tools
                 payload["tool_choice"] = tool_choice or "auto"
-            
+
             try:
                 response = requests.post(url, json=payload, headers=headers, timeout=60)
                 response.raise_for_status()
-                
+
                 result = response.json()
-                
+
                 return TextGenerationOutput(
-                    transaction_hash="external",
-                    finish_reason=result.get("finish_reason"),
-                    chat_output=result.get("message")
+                    transaction_hash="external", finish_reason=result.get("finish_reason"), chat_output=result.get("message")
                 )
-                
+
             except requests.RequestException as e:
                 error_msg = f"External LLM chat failed: {str(e)}"
-                if hasattr(e, 'response') and e.response is not None:
+                if hasattr(e, "response") and e.response is not None:
                     try:
                         error_detail = e.response.json()
                         error_msg += f" - {error_detail}"
@@ -844,26 +849,26 @@ class Client:
                 headers = {
                     "Content-Type": "application/json",
                     "Authorization": f"Bearer {X402_PLACEHOLDER_API_KEY}",
-                    "X-SETTLEMENT-TYPE": x402_settlement_mode
+                    "X-SETTLEMENT-TYPE": x402_settlement_mode,
                 }
-                
+
                 payload = {
                     "model": model,
                     "messages": messages,
                     "max_tokens": max_tokens,
                     "temperature": temperature,
                 }
-                
+
                 if stop_sequence:
                     payload["stop"] = stop_sequence
-                
+
                 if tools:
                     payload["tools"] = tools
                     payload["tool_choice"] = tool_choice or "auto"
-                
+
                 try:
                     response = await client.post("/v1/chat/completions", json=payload, headers=headers, timeout=60)
-                    
+
                     # Read the response content
                     content = await response.aread()
                     result = json.loads(content.decode())
@@ -873,29 +878,29 @@ class Client:
                     payment_hash = ""
                     if X402_PROCESSING_HASH_HEADER in response.headers:
                         payment_hash = response.headers[X402_PROCESSING_HASH_HEADER]
-                    
+
                     choices = result.get("choices")
                     if not choices:
                         raise OpenGradientError(f"Invalid response: 'choices' missing or empty in {result}")
-                    
+
                     return TextGenerationOutput(
                         transaction_hash="external",
                         finish_reason=choices[0].get("finish_reason"),
                         chat_output=choices[0].get("message"),
-                        payment_hash=payment_hash
+                        payment_hash=payment_hash,
                     )
-                    
+
                 except Exception as e:
                     error_msg = f"External LLM chat request failed: {str(e)}"
                     logging.error(error_msg)
                     raise OpenGradientError(error_msg)
-        
+
         try:
             # Run the async function in a sync context
             return asyncio.run(make_request())
         except Exception as e:
             error_msg = f"External LLM chat failed: {str(e)}"
-            if hasattr(e, 'response') and e.response is not None:
+            if hasattr(e, "response") and e.response is not None:
                 try:
                     error_detail = e.response.json()
                     error_msg += f" - {error_detail}"
@@ -1104,12 +1109,12 @@ class Client:
         except ContractLogicError as e:
             try:
                 run_function.call({"from": self._wallet_account.address})
-                
+
             except ContractLogicError as call_err:
                 raise ContractLogicError(f"simulation failed with revert reason: {call_err.args[0]}")
-            
+
             raise ContractLogicError(f"simulation failed with no revert reason. Reason: {e}")
-        
+
         gas_limit = int(estimated_gas * 3)
 
         transaction = run_function.build_transaction(
@@ -1128,10 +1133,10 @@ class Client:
         if tx_receipt["status"] == 0:
             try:
                 run_function.call({"from": self._wallet_account.address})
-                
+
             except ContractLogicError as call_err:
                 raise ContractLogicError(f"Transaction failed with revert reason: {call_err.args[0]}")
-            
+
             raise ContractLogicError(f"Transaction failed with no revert reason. Receipt: {tx_receipt}")
 
         return tx_hash, tx_receipt
@@ -1346,45 +1351,42 @@ class Client:
         results = contract.functions.getLastInferenceResults(num_results).call()
         return [convert_array_to_model_output(result) for result in results]
 
-
     def _get_inference_result_from_node(self, inference_id: str, inference_mode: InferenceMode) -> Dict:
         """
         Get the inference result from node.
-        
+
         Args:
             inference_id (str): Inference id for a inference request
-            
+
         Returns:
             Dict: The inference result as returned by the node
-            
+
         Raises:
             OpenGradientError: If the request fails or returns an error
         """
         try:
-            encoded_id = urllib.parse.quote(inference_id, safe='')
+            encoded_id = urllib.parse.quote(inference_id, safe="")
             url = f"{self._api_url}/artela-network/artela-rollkit/inference/tx/{encoded_id}"
-        
+
             response = requests.get(url)
             if response.status_code == 200:
                 resp = response.json()
                 inference_result = resp.get("inference_results", {})
                 if inference_result:
                     decoded_bytes = base64.b64decode(inference_result[0])
-                    decoded_string = decoded_bytes.decode('utf-8')
-                    output = json.loads(decoded_string).get("InferenceResult",{})
+                    decoded_string = decoded_bytes.decode("utf-8")
+                    output = json.loads(decoded_string).get("InferenceResult", {})
                     if output is None:
                         raise OpenGradientError("Missing InferenceResult in inference output")
-                    
+
                     match inference_mode:
                         case InferenceMode.VANILLA:
                             if "VanillaResult" not in output:
                                 raise OpenGradientError("Missing VanillaResult in inference output")
                             if "model_output" not in output["VanillaResult"]:
                                 raise OpenGradientError("Missing model_output in VanillaResult")
-                            return {
-                                "output": output["VanillaResult"]["model_output"]
-                            }
-                    
+                            return {"output": output["VanillaResult"]["model_output"]}
+
                         case InferenceMode.TEE:
                             if "TeeNodeResult" not in output:
                                 raise OpenGradientError("Missing TeeNodeResult in inference output")
@@ -1393,34 +1395,30 @@ class Client:
                             if "VanillaResponse" in output["TeeNodeResult"]["Response"]:
                                 if "model_output" not in output["TeeNodeResult"]["Response"]["VanillaResponse"]:
                                     raise OpenGradientError("Missing model_output in VanillaResponse")
-                                return {
-                                    "output": output["TeeNodeResult"]["Response"]["VanillaResponse"]["model_output"]
-                                }
-                    
+                                return {"output": output["TeeNodeResult"]["Response"]["VanillaResponse"]["model_output"]}
+
                             else:
                                 raise OpenGradientError("Missing VanillaResponse in TeeNodeResult Response")
-                                
+
                         case InferenceMode.ZKML:
                             if "ZkmlResult" not in output:
                                 raise OpenGradientError("Missing ZkmlResult in inference output")
                             if "model_output" not in output["ZkmlResult"]:
                                 raise OpenGradientError("Missing model_output in ZkmlResult")
-                            return {
-                                "output": output["ZkmlResult"]["model_output"]
-                            }
-                    
+                            return {"output": output["ZkmlResult"]["model_output"]}
+
                         case _:
                             raise OpenGradientError(f"Invalid inference mode: {inference_mode}")
                 else:
                     return None
-                    
+
             else:
                 error_message = f"Failed to get inference result: HTTP {response.status_code}"
                 if response.text:
                     error_message += f" - {response.text}"
                 logging.error(error_message)
                 raise OpenGradientError(error_message)
-                
+
         except requests.RequestException as e:
             logging.error(f"Request exception when getting inference result: {str(e)}")
             raise OpenGradientError(f"Failed to get inference result: {str(e)}")
@@ -1428,6 +1426,7 @@ class Client:
             logging.error(f"Unexpected error when getting inference result: {str(e)}", exc_info=True)
             raise OpenGradientError(f"Failed to get inference result: {str(e)}")
 
+
 def run_with_retry(txn_function: Callable, max_retries=DEFAULT_MAX_RETRY, retry_delay=DEFAULT_RETRY_DELAY_SEC):
     """
     Execute a blockchain transaction with retry logic.

opengradient/defaults.py

@@ -9,4 +9,4 @@ DEFAULT_BLOCKCHAIN_EXPLORER = "https://explorer.opengradient.ai/tx/"
 DEFAULT_IMAGE_GEN_HOST = "18.217.25.69"
 DEFAULT_IMAGE_GEN_PORT = 5125
 DEFAULT_LLM_SERVER_URL = "http://35.225.197.84:8000"
-DEFAULT_OPENGRADIENT_LLM_SERVER_URL = "https://llm.opengradient.ai"
+DEFAULT_OPENGRADIENT_LLM_SERVER_URL = "https://llm.opengradient.ai"

opengradient/llm/og_langchain.py

@@ -36,7 +36,12 @@ class OpenGradientChatModel(BaseChatModel):
         super().__init__()
 
         self._client = Client(
-            private_key=private_key, rpc_url=DEFAULT_RPC_URL, api_url=DEFAULT_API_URL, contract_address=DEFAULT_INFERENCE_CONTRACT_ADDRESS, email=None, password=None
+            private_key=private_key,
+            rpc_url=DEFAULT_RPC_URL,
+            api_url=DEFAULT_API_URL,
+            contract_address=DEFAULT_INFERENCE_CONTRACT_ADDRESS,
+            email=None,
+            password=None,
         )
         self._model_cid = model_cid
         self._max_tokens = max_tokens

opengradient/types.py

@@ -6,10 +6,37 @@ import numpy as np
 
 
 class x402SettlementMode(StrEnum):
+    """
+    Settlement modes for x402 payment protocol transactions.
+
+    These modes control how inference data is recorded on-chain for payment settlement
+    and auditability. Each mode offers different trade-offs between data completeness,
+    privacy, and transaction costs.
+
+    Attributes:
+        SETTLE: Individual settlement with input/output hashes only.
+            Records cryptographic hashes of the inference input and output.
+            Most privacy-preserving option - actual data is not stored on-chain.
+            Suitable for applications where only proof of execution is needed.
+
+        SETTLE_METADATA: Individual settlement with full metadata.
+            Records complete model information, full input and output data,
+            and all inference metadata on-chain.
+            Provides maximum transparency and auditability.
+            Higher gas costs due to larger data storage.
+
+        SETTLE_BATCH: Batch settlement for multiple inferences.
+            Aggregates multiple inference requests into a single settlement transaction
+            using batch hashes.
+            Most cost-efficient for high-volume applications.
+            Reduced per-inference transaction overhead.
+    """
+
     SETTLE = "settle"
     SETTLE_METADATA = "settle-metadata"
     SETTLE_BATCH = "settle-batch"
 
+
 class CandleOrder(IntEnum):
     ASCENDING = 0
     DESCENDING = 1
@@ -107,7 +134,7 @@ class InferenceMode(Enum):
 
 
 class LlmInferenceMode(Enum):
-    """Enum for differetn inference modes available for LLM inferences (VANILLA, TEE)"""
+    """Enum for different inference modes available for LLM inference (VANILLA, TEE)"""
 
     VANILLA = 0
     TEE = 1
@@ -205,23 +232,23 @@ class LLM(str, Enum):
     # META_LLAMA_3_1_70B_INSTRUCT = "meta-llama/Llama-3.1-70B-Instruct"
     # DOBBY_UNHINGED_3_1_8B = "SentientAGI/Dobby-Mini-Unhinged-Llama-3.1-8B"
     # DOBBY_LEASHED_3_1_8B = "SentientAGI/Dobby-Mini-Leashed-Llama-3.1-8B"
-    
+
     # OpenAI models via TEE
     GPT_4_1_2025_04_14 = "openai/gpt-4.1-2025-04-14"
     GPT_4O = "openai/gpt-4o"
     O4_MINI = "openai/o4-mini"
-    
+
     # Anthropic models via TEE
     CLAUDE_3_7_SONNET = "anthropic/claude-3.7-sonnet"
     CLAUDE_3_5_HAIKU = "anthropic/claude-3.5-haiku"
     CLAUDE_4_0_SONNET = "anthropic/claude-4.0-sonnet"
-    
+
     # Google models via TEE
     GEMINI_2_5_FLASH = "google/gemini-2.5-flash"
     GEMINI_2_5_PRO = "google/gemini-2.5-pro"
     GEMINI_2_0_FLASH = "google/gemini-2.0-flash"
     GEMINI_2_5_FLASH_LITE = "google/gemini-2.5-flash-lite"
-    
+
     # xAI Grok models via TEE
     GROK_3_MINI_BETA = "x-ai/grok-3-mini-beta"
     GROK_3_BETA = "x-ai/grok-3-beta"
@@ -230,28 +257,29 @@ class LLM(str, Enum):
     GROK_4_1_FAST = "x-ai/grok-4.1-fast"
     GROK_4_1_FAST_NON_REASONING = "x-ai/grok-4-1-fast-non-reasoning"
 
+
 class TEE_LLM(str, Enum):
     """Enum for LLM models available for TEE execution"""
-    
+
     # Existing (Currently turned off)
     # META_LLAMA_3_1_70B_INSTRUCT = "meta-llama/Llama-3.1-70B-Instruct"
-    
+
     # OpenAI models via TEE
     GPT_4_1_2025_04_14 = "openai/gpt-4.1-2025-04-14"
     GPT_4O = "openai/gpt-4o"
     O4_MINI = "openai/o4-mini"
-    
+
     # Anthropic models via TEE
     CLAUDE_3_7_SONNET = "anthropic/claude-3.7-sonnet"
     CLAUDE_3_5_HAIKU = "anthropic/claude-3.5-haiku"
     CLAUDE_4_0_SONNET = "anthropic/claude-4.0-sonnet"
-    
+
     # Google models via TEE
     GEMINI_2_5_FLASH = "google/gemini-2.5-flash"
     GEMINI_2_5_PRO = "google/gemini-2.5-pro"
     GEMINI_2_0_FLASH = "google/gemini-2.0-flash"
     GEMINI_2_5_FLASH_LITE = "google/gemini-2.5-flash-lite"
-    
+
     # xAI Grok models via TEE
     GROK_3_MINI_BETA = "x-ai/grok-3-mini-beta"
     GROK_3_BETA = "x-ai/grok-3-beta"

{opengradient-0.5.7.dist-info → opengradient-0.5.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opengradient
-Version: 0.5.7
+Version: 0.5.8
 Summary: Python SDK for OpenGradient decentralized model management & inference services
 Author-email: OpenGradient <kyle@vannalabs.ai>
 License-Expression: MIT
@@ -24,7 +24,6 @@ Requires-Dist: langchain>=0.3.7
 Requires-Dist: openai>=1.58.1
 Requires-Dist: pydantic>=2.9.2
 Requires-Dist: og-test-x402==0.0.1
-Requires-Dist: x402==0.2.1
 Dynamic: license-file
 
 # OpenGradient Python SDK
@@ -133,6 +132,10 @@ For comprehensive documentation, API reference, and examples, visit:
 - [OpenGradient Documentation](https://docs.opengradient.ai/)
 - [API Reference](https://docs.opengradient.ai/api_reference/python_sdk/)
 
+### Claude Code Users
+
+If you use [Claude Code](https://claude.ai/code), copy [docs/CLAUDE_SDK_USERS.md](docs/CLAUDE_SDK_USERS.md) to your project's `CLAUDE.md` to help Claude assist you with OpenGradient SDK development.
+
 ## Support
 
 - Run `opengradient --help` for CLI command reference

{opengradient-0.5.7.dist-info → opengradient-0.5.8.dist-info}/RECORD

@@ -1,10 +1,10 @@
-opengradient/__init__.py,sha256=wVg0KTFNBl7RnZF9huR5-m_q1E7tO-YyQwY7AD9JFoc,12635
+opengradient/__init__.py,sha256=7UkGoQRDtSb0lh3vobxmyJct_uFfm1Re_oz5s0s9dOs,13263
 opengradient/account.py,sha256=5wrYpws_1lozjOFjLCTHtxgoxK-LmObDAaVy9eDcJY4,1145
-opengradient/cli.py,sha256=RksBEGVcZgUg6ng53Fgz-Ncv1erBwdADgblB2HmKkwk,29868
-opengradient/client.py,sha256=lzuC4rEwyf1EgHw49PMXjIyjyTsBIAP2XmCNp0cCNzg,63113
-opengradient/defaults.py,sha256=w8-dr5ciF2TGnqbm_ib0Yz4U0YL5ikpNqkcPVpmXzP8,673
+opengradient/cli.py,sha256=4IUKxecZV9la-_nEVxObOIjm6qQ9aEHhq5-m5clzzHc,29901
+opengradient/client.py,sha256=nozp80z8KSYQewKQmSVXZQIdVtsSjv53reS3TBRwlXc,63071
+opengradient/defaults.py,sha256=yiZnpIOLyHEmZhCEQXgWpT2eJin10UVsivJY6r61xmo,674
 opengradient/exceptions.py,sha256=88tfegboGtlehQcwhxsl6ZzhLJWZWlkf_bkHTiCtXpo,3391
-opengradient/types.py,sha256=L60W1O3xmlYxbJ9ouN6nKNKJSdTW3yzCDsU0lozWF8U,7837
+opengradient/types.py,sha256=DSkJAcD4fRQ78bG3Ny5-_OqcfptFSIpliS4qKKYE2jU,9026
 opengradient/utils.py,sha256=ZUq4OBIml2vsC0tRqus4Zwb_e3g4woo00apByrafuVw,8058
 opengradient/abi/InferencePrecompile.abi,sha256=reepTHg6Q01UrFP0Gexc-JayplsvOLPfG7jrEZ-cV28,10197
 opengradient/abi/PriceHistoryInference.abi,sha256=ZB3fZdx1kaFlp2wt1vTbTZZG1k8HPvmNtkG5Q8Bnajw,5098
@@ -16,7 +16,7 @@ opengradient/alphasense/run_model_tool.py,sha256=wlDqXVHa1xpqQy_hmht_wWegxtqdYgY
 opengradient/alphasense/types.py,sha256=uxk4JQKbaS2cM3ZiKpdHQb234OJ5ylprNR5vi01QFzA,220
 opengradient/bin/PriceHistoryInference.bin,sha256=nU2FZpGHIKBZ7NSK9Sr-p9lr-nXja_40ISPN9yckDq8,41276
 opengradient/llm/__init__.py,sha256=eYFBrOf1GZr0VGbIw-gSFr8hM3Rbw74ye8l-pnBPNuA,1104
-opengradient/llm/og_langchain.py,sha256=inJmu28aWA1RAWJx8G0h8w4FGXSKMCzJVOBGUwiKqnI,4904
+opengradient/llm/og_langchain.py,sha256=fVHEq_hJbWrLLVZXKSH5wwSG5kQEt_PGnmAOLUnEgmw,4965
 opengradient/llm/og_openai.py,sha256=26W_NDnLaICIaWbi9aou40v5ZJXLlmLdztDrdFoDGAU,3789
 opengradient/proto/__init__.py,sha256=AhaSmrqV0TXGzCKaoPV8-XUvqs2fGAJBM2aOmDpkNbE,55
 opengradient/proto/infer.proto,sha256=13eaEMcppxkBF8yChptsX9HooWFwJKze7oLZNl-LEb8,1217
@@ -27,9 +27,9 @@ opengradient/workflow_models/constants.py,sha256=viIkb_LGcfVprqQNaA80gBTj6cfYam0
 opengradient/workflow_models/types.py,sha256=Z22hF6c8Y4D2GlzVEIBODGwsqSjSrQvUcpZ7R-mIJdI,409
 opengradient/workflow_models/utils.py,sha256=ySfpuiOBqLTlfto6ZxZf2vc7K6RGIja0l4eaVm5AOzY,1503
 opengradient/workflow_models/workflow_models.py,sha256=d4C_gs39DAfy4cdY9Ee6GMXpPfzwvKFpmxzK1A7LNgU,3900
-opengradient-0.5.7.dist-info/licenses/LICENSE,sha256=xEcvQ3AxZOtDkrqkys2Mm6Y9diEnaSeQRKvxi-JGnNA,1069
-opengradient-0.5.7.dist-info/METADATA,sha256=WmJWW2IPbsKD_fuhafHf_cZeLiCz9_2T8qZUcvw0saU,4019
-opengradient-0.5.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-opengradient-0.5.7.dist-info/entry_points.txt,sha256=yUKTaJx8RXnybkob0J62wVBiCp_1agVbgw9uzsmaeJc,54
-opengradient-0.5.7.dist-info/top_level.txt,sha256=oC1zimVLa2Yi1LQz8c7x-0IQm92milb5ax8gHBHwDqU,13
-opengradient-0.5.7.dist-info/RECORD,,
+opengradient-0.5.8.dist-info/licenses/LICENSE,sha256=xEcvQ3AxZOtDkrqkys2Mm6Y9diEnaSeQRKvxi-JGnNA,1069
+opengradient-0.5.8.dist-info/METADATA,sha256=DyqayJvXV39OUn5H9jUqVsKqX9ilHMAaQ2-u4GnqIwM,4215
+opengradient-0.5.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+opengradient-0.5.8.dist-info/entry_points.txt,sha256=yUKTaJx8RXnybkob0J62wVBiCp_1agVbgw9uzsmaeJc,54
+opengradient-0.5.8.dist-info/top_level.txt,sha256=oC1zimVLa2Yi1LQz8c7x-0IQm92milb5ax8gHBHwDqU,13
+opengradient-0.5.8.dist-info/RECORD,,