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

opengradient/__init__.py

@@ -17,14 +17,19 @@ from .types import (
     InferenceResult,
     LlmInferenceMode,
     TextGenerationOutput,
+    TextGenerationStream,
     ModelOutput,
     ModelRepository,
     FileUploadResult,
     x402SettlementMode,
 )
+from .alpha import _AlphaNamespace
 
 from . import llm, alphasense
 
+# Module-level alpha namespace for workflow/ML execution features (Alpha Testnet only)
+alpha = _AlphaNamespace()
+
 _client = None
 
 
@@ -225,7 +230,8 @@ def llm_chat(
     tool_choice: Optional[str] = None,
     max_retries: Optional[int] = None,
     x402_settlement_mode: Optional[x402SettlementMode] = x402SettlementMode.SETTLE_BATCH,
-) -> TextGenerationOutput:
+    stream: Optional[bool] = False,
+) -> Union[TextGenerationOutput, TextGenerationStream]:
     """Have a chat conversation with an LLM.
 
     Args:
@@ -239,9 +245,10 @@ def llm_chat(
         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)
+        stream: Optional boolean to enable streaming
 
     Returns:
-        TextGenerationOutput
+        TextGenerationOutput or TextGenerationStream
 
     Raises:
         RuntimeError: If SDK is not initialized
@@ -258,7 +265,8 @@ def llm_chat(
         tools=tools,
         tool_choice=tool_choice,
         max_retries=max_retries,
-        x402_settlement_mode=x402_settlement_mode
+        x402_settlement_mode=x402_settlement_mode,
+        stream=stream,
     )
 
 
@@ -280,93 +288,6 @@ def list_files(model_name: str, version: str) -> List[Dict]:
     return _client.list_files(model_name, version)
 
 
-def new_workflow(
-    model_cid: str,
-    input_query: HistoricalInputQuery,
-    input_tensor_name: str,
-    scheduler_params: Optional[SchedulerParams] = None,
-) -> str:
-    """
-    Deploy a new workflow contract with the specified parameters.
-
-    This function deploys a new workflow contract and optionally registers it with
-    the scheduler for automated execution. If scheduler_params is not provided,
-    the workflow will be deployed without automated execution scheduling.
-
-    Args:
-        model_cid: IPFS CID of the model
-        input_query: HistoricalInputQuery containing query parameters
-        input_tensor_name: Name of the input tensor
-        scheduler_params: Optional scheduler configuration as SchedulerParams instance
-            If not provided, the workflow will be deployed without scheduling.
-
-    Returns:
-        str: Deployed contract address. If scheduler_params was provided, the workflow
-             will be automatically executed according to the specified schedule.
-    """
-    if _client is None:
-        raise RuntimeError("OpenGradient client not initialized. Call og.init(...) first.")
-
-    return _client.new_workflow(
-        model_cid=model_cid, input_query=input_query, input_tensor_name=input_tensor_name, scheduler_params=scheduler_params
-    )
-
-
-def read_workflow_result(contract_address: str) -> ModelOutput:
-    """
-    Reads the latest inference result from a deployed workflow contract.
-
-    This function retrieves the most recent output from a deployed model executor contract.
-    It includes built-in retry logic to handle blockchain state delays.
-
-    Args:
-        contract_address (str): Address of the deployed workflow contract
-
-    Returns:
-        Dict[str, Union[str, Dict]]: A dictionary containing:
-            - status: "success" or "error"
-            - result: The model output data if successful
-            - error: Error message if status is "error"
-
-    Raises:
-        RuntimeError: If OpenGradient client is not initialized
-    """
-    if _client is None:
-        raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
-    return _client.read_workflow_result(contract_address)
-
-
-def run_workflow(contract_address: str) -> ModelOutput:
-    """
-    Executes the workflow by calling run() on the contract to pull latest data and perform inference.
-
-    Args:
-        contract_address (str): Address of the deployed workflow contract
-
-    Returns:
-        Dict[str, Union[str, Dict]]: Status of the run operation
-    """
-    if _client is None:
-        raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
-    return _client.run_workflow(contract_address)
-
-
-def read_workflow_history(contract_address: str, num_results: int) -> List[ModelOutput]:
-    """
-    Gets historical inference results from a workflow contract.
-
-    Args:
-        contract_address (str): Address of the deployed workflow contract
-        num_results (int): Number of historical results to retrieve
-
-    Returns:
-        List[Dict]: List of historical inference results
-    """
-    if _client is None:
-        raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
-    return _client.read_workflow_history(contract_address, num_results)
-
-
 __all__ = [
     "list_files",
     "login",
@@ -379,10 +300,7 @@ __all__ = [
     "init",
     "LLM",
     "TEE_LLM",
-    "new_workflow",
-    "read_workflow_result",
-    "run_workflow",
-    "read_workflow_history",
+    "alpha",
     "InferenceMode",
     "LlmInferenceMode",
     "HistoricalInputQuery",

opengradient/alpha.py

@@ -0,0 +1,375 @@
+"""
+Alpha Testnet features for OpenGradient SDK.
+
+This module contains features that are only available on the Alpha Testnet,
+including workflow management and ML model execution.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional
+
+from web3 import Web3
+from web3.exceptions import ContractLogicError
+
+from .defaults import DEFAULT_SCHEDULER_ADDRESS
+from .types import HistoricalInputQuery, ModelOutput, SchedulerParams
+from .utils import convert_array_to_model_output
+
+if TYPE_CHECKING:
+    from .client import Client
+
+# How much time we wait for txn to be included in chain
+INFERENCE_TX_TIMEOUT = 120
+REGULAR_TX_TIMEOUT = 30
+
+
+class Alpha:
+    """
+    Alpha Testnet features namespace.
+
+    This class provides access to features that are only available on the Alpha Testnet,
+    including workflow deployment and execution.
+
+    Usage:
+        client = og.new_client(...)
+        result = client.alpha.new_workflow(model_cid, input_query, input_tensor_name)
+    """
+
+    def __init__(self, client: "Client"):
+        self._client = client
+
+    def _get_abi(self, abi_name: str) -> dict:
+        """Returns the ABI for the requested contract."""
+        abi_path = Path(__file__).parent / "abi" / abi_name
+        with open(abi_path, "r") as f:
+            return json.load(f)
+
+    def _get_bin(self, bin_name: str) -> str:
+        """Returns the bin for the requested contract."""
+        bin_path = Path(__file__).parent / "bin" / bin_name
+        with open(bin_path, "r", encoding="utf-8") as f:
+            bytecode = f.read().strip()
+            if not bytecode.startswith("0x"):
+                bytecode = "0x" + bytecode
+            return bytecode
+
+    def new_workflow(
+        self,
+        model_cid: str,
+        input_query: HistoricalInputQuery,
+        input_tensor_name: str,
+        scheduler_params: Optional[SchedulerParams] = None,
+    ) -> str:
+        """
+        Deploy a new workflow contract with the specified parameters.
+
+        This function deploys a new workflow contract on OpenGradient that connects
+        an AI model with its required input data. When executed, the workflow will fetch
+        the specified model, evaluate the input query to get data, and perform inference.
+
+        The workflow can be set to execute manually or automatically via a scheduler.
+
+        Args:
+            model_cid (str): CID of the model to be executed from the Model Hub
+            input_query (HistoricalInputQuery): Input definition for the model inference,
+                will be evaluated at runtime for each inference
+            input_tensor_name (str): Name of the input tensor expected by the model
+            scheduler_params (Optional[SchedulerParams]): Scheduler configuration for automated execution:
+                - frequency: Execution frequency in seconds
+                - duration_hours: How long the schedule should live for
+
+        Returns:
+            str: Deployed contract address. If scheduler_params was provided, the workflow
+                 will be automatically executed according to the specified schedule.
+
+        Raises:
+            Exception: If transaction fails or gas estimation fails
+        """
+        from .client import run_with_retry
+
+        # Get contract ABI and bytecode
+        abi = self._get_abi("PriceHistoryInference.abi")
+        bytecode = self._get_bin("PriceHistoryInference.bin")
+
+        def deploy_transaction():
+            contract = self._client._blockchain.eth.contract(abi=abi, bytecode=bytecode)
+            query_tuple = input_query.to_abi_format()
+            constructor_args = [model_cid, input_tensor_name, query_tuple]
+
+            try:
+                # Estimate gas needed
+                estimated_gas = contract.constructor(*constructor_args).estimate_gas(
+                    {"from": self._client._wallet_account.address}
+                )
+                gas_limit = int(estimated_gas * 1.2)
+            except Exception as e:
+                print(f"⚠️ Gas estimation failed: {str(e)}")
+                gas_limit = 5000000  # Conservative fallback
+                print(f"📊 Using fallback gas limit: {gas_limit}")
+
+            transaction = contract.constructor(*constructor_args).build_transaction(
+                {
+                    "from": self._client._wallet_account.address,
+                    "nonce": self._client._blockchain.eth.get_transaction_count(
+                        self._client._wallet_account.address, "pending"
+                    ),
+                    "gas": gas_limit,
+                    "gasPrice": self._client._blockchain.eth.gas_price,
+                    "chainId": self._client._blockchain.eth.chain_id,
+                }
+            )
+
+            signed_txn = self._client._wallet_account.sign_transaction(transaction)
+            tx_hash = self._client._blockchain.eth.send_raw_transaction(signed_txn.raw_transaction)
+
+            tx_receipt = self._client._blockchain.eth.wait_for_transaction_receipt(tx_hash, timeout=60)
+
+            if tx_receipt["status"] == 0:
+                raise Exception(f"❌ Contract deployment failed, transaction hash: {tx_hash.hex()}")
+
+            return tx_receipt.contractAddress
+
+        contract_address = run_with_retry(deploy_transaction)
+
+        if scheduler_params:
+            self._register_with_scheduler(contract_address, scheduler_params)
+
+        return contract_address
+
+    def _register_with_scheduler(self, contract_address: str, scheduler_params: SchedulerParams) -> None:
+        """
+        Register the deployed workflow contract with the scheduler for automated execution.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+            scheduler_params (SchedulerParams): Scheduler configuration containing:
+                - frequency: Execution frequency in seconds
+                - duration_hours: How long to run in hours
+                - end_time: Unix timestamp when scheduling should end
+
+        Raises:
+            Exception: If registration with scheduler fails. The workflow contract will
+                      still be deployed and can be executed manually.
+        """
+        scheduler_abi = self._get_abi("WorkflowScheduler.abi")
+
+        # Scheduler contract address
+        scheduler_address = DEFAULT_SCHEDULER_ADDRESS
+        scheduler_contract = self._client._blockchain.eth.contract(address=scheduler_address, abi=scheduler_abi)
+
+        try:
+            # Register the workflow with the scheduler
+            scheduler_tx = scheduler_contract.functions.registerTask(
+                contract_address, scheduler_params.end_time, scheduler_params.frequency
+            ).build_transaction(
+                {
+                    "from": self._client._wallet_account.address,
+                    "gas": 300000,
+                    "gasPrice": self._client._blockchain.eth.gas_price,
+                    "nonce": self._client._blockchain.eth.get_transaction_count(
+                        self._client._wallet_account.address, "pending"
+                    ),
+                    "chainId": self._client._blockchain.eth.chain_id,
+                }
+            )
+
+            signed_scheduler_tx = self._client._wallet_account.sign_transaction(scheduler_tx)
+            scheduler_tx_hash = self._client._blockchain.eth.send_raw_transaction(signed_scheduler_tx.raw_transaction)
+            self._client._blockchain.eth.wait_for_transaction_receipt(scheduler_tx_hash, timeout=REGULAR_TX_TIMEOUT)
+        except Exception as e:
+            print(f"❌ Error registering contract with scheduler: {str(e)}")
+            print("  The workflow contract is still deployed and can be executed manually.")
+
+    def read_workflow_result(self, contract_address: str) -> ModelOutput:
+        """
+        Reads the latest inference result from a deployed workflow contract.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+
+        Returns:
+            ModelOutput: The inference result from the contract
+
+        Raises:
+            ContractLogicError: If the transaction fails
+            Web3Error: If there are issues with the web3 connection or contract interaction
+        """
+        # Get the contract interface
+        contract = self._client._blockchain.eth.contract(
+            address=Web3.to_checksum_address(contract_address), abi=self._get_abi("PriceHistoryInference.abi")
+        )
+
+        # Get the result
+        result = contract.functions.getInferenceResult().call()
+
+        return convert_array_to_model_output(result)
+
+    def run_workflow(self, contract_address: str) -> ModelOutput:
+        """
+        Triggers the run() function on a deployed workflow contract and returns the result.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+
+        Returns:
+            ModelOutput: The inference result from the contract
+
+        Raises:
+            ContractLogicError: If the transaction fails
+            Web3Error: If there are issues with the web3 connection or contract interaction
+        """
+        # Get the contract interface
+        contract = self._client._blockchain.eth.contract(
+            address=Web3.to_checksum_address(contract_address), abi=self._get_abi("PriceHistoryInference.abi")
+        )
+
+        # Call run() function
+        nonce = self._client._blockchain.eth.get_transaction_count(self._client._wallet_account.address, "pending")
+
+        run_function = contract.functions.run()
+        transaction = run_function.build_transaction(
+            {
+                "from": self._client._wallet_account.address,
+                "nonce": nonce,
+                "gas": 30000000,
+                "gasPrice": self._client._blockchain.eth.gas_price,
+                "chainId": self._client._blockchain.eth.chain_id,
+            }
+        )
+
+        signed_txn = self._client._wallet_account.sign_transaction(transaction)
+        tx_hash = self._client._blockchain.eth.send_raw_transaction(signed_txn.raw_transaction)
+        tx_receipt = self._client._blockchain.eth.wait_for_transaction_receipt(tx_hash, timeout=INFERENCE_TX_TIMEOUT)
+
+        if tx_receipt.status == 0:
+            raise ContractLogicError(f"Run transaction failed. Receipt: {tx_receipt}")
+
+        # Get the inference result from the contract
+        result = contract.functions.getInferenceResult().call()
+
+        return convert_array_to_model_output(result)
+
+    def read_workflow_history(self, contract_address: str, num_results: int) -> List[ModelOutput]:
+        """
+        Gets historical inference results from a workflow contract.
+
+        Retrieves the specified number of most recent inference results from the contract's
+        storage, with the most recent result first.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+            num_results (int): Number of historical results to retrieve
+
+        Returns:
+            List[ModelOutput]: List of historical inference results
+        """
+        contract = self._client._blockchain.eth.contract(
+            address=Web3.to_checksum_address(contract_address), abi=self._get_abi("PriceHistoryInference.abi")
+        )
+
+        results = contract.functions.getLastInferenceResults(num_results).call()
+        return [convert_array_to_model_output(result) for result in results]
+
+
+class _AlphaNamespace:
+    """
+    Module-level alpha namespace for use with og.init().
+
+    Usage:
+        og.init(...)
+        result = og.alpha.new_workflow(model_cid, input_query, input_tensor_name)
+    """
+
+    def new_workflow(
+        self,
+        model_cid: str,
+        input_query: HistoricalInputQuery,
+        input_tensor_name: str,
+        scheduler_params: Optional[SchedulerParams] = None,
+    ) -> str:
+        """
+        Deploy a new workflow contract with the specified parameters.
+
+        This function deploys a new workflow contract and optionally registers it with
+        the scheduler for automated execution. If scheduler_params is not provided,
+        the workflow will be deployed without automated execution scheduling.
+
+        Args:
+            model_cid: IPFS CID of the model
+            input_query: HistoricalInputQuery containing query parameters
+            input_tensor_name: Name of the input tensor
+            scheduler_params: Optional scheduler configuration as SchedulerParams instance
+                If not provided, the workflow will be deployed without scheduling.
+
+        Returns:
+            str: Deployed contract address. If scheduler_params was provided, the workflow
+                 will be automatically executed according to the specified schedule.
+        """
+        from . import _client
+
+        if _client is None:
+            raise RuntimeError("OpenGradient client not initialized. Call og.init(...) first.")
+
+        return _client.alpha.new_workflow(
+            model_cid=model_cid,
+            input_query=input_query,
+            input_tensor_name=input_tensor_name,
+            scheduler_params=scheduler_params,
+        )
+
+    def read_workflow_result(self, contract_address: str) -> ModelOutput:
+        """
+        Reads the latest inference result from a deployed workflow contract.
+
+        This function retrieves the most recent output from a deployed model executor contract.
+        It includes built-in retry logic to handle blockchain state delays.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+
+        Returns:
+            ModelOutput: The inference result from the contract
+
+        Raises:
+            RuntimeError: If OpenGradient client is not initialized
+        """
+        from . import _client
+
+        if _client is None:
+            raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
+        return _client.alpha.read_workflow_result(contract_address)
+
+    def run_workflow(self, contract_address: str) -> ModelOutput:
+        """
+        Executes the workflow by calling run() on the contract to pull latest data and perform inference.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+
+        Returns:
+            ModelOutput: The inference result from the contract
+        """
+        from . import _client
+
+        if _client is None:
+            raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
+        return _client.alpha.run_workflow(contract_address)
+
+    def read_workflow_history(self, contract_address: str, num_results: int) -> List[ModelOutput]:
+        """
+        Gets historical inference results from a workflow contract.
+
+        Args:
+            contract_address (str): Address of the deployed workflow contract
+            num_results (int): Number of historical results to retrieve
+
+        Returns:
+            List[ModelOutput]: List of historical inference results
+        """
+        from . import _client
+
+        if _client is None:
+            raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
+        return _client.alpha.read_workflow_history(contract_address, num_results)

opengradient/alphasense/read_workflow_tool.py

@@ -64,7 +64,7 @@ def create_read_workflow_tool(
 
     # define runnable
     def read_workflow():
-        output = og.read_workflow_result(contract_address=workflow_contract_address)
+        output = og.alpha.read_workflow_result(contract_address=workflow_contract_address)
         return output_formatter(output)
 
     if tool_type == ToolType.LANGCHAIN:

opengradient/cli.py

@@ -6,6 +6,7 @@ import logging
 import webbrowser
 from pathlib import Path
 from typing import Dict, List, Optional
+import sys
 
 import click
 
@@ -557,6 +558,7 @@ def print_llm_completion_result(model_cid, tx_hash, llm_output, is_local=True):
     default="settle-batch",
     help="Settlement mode for x402 payments: settle (hashes only), settle-batch (batched, default), settle-metadata (full data)",
 )
+@click.option("--stream", is_flag=True, default=False, help="Stream the output from the LLM")
 @click.pass_context
 def chat(
     ctx,
@@ -572,6 +574,7 @@ def chat(
     tool_choice: Optional[str],
     x402_settlement_mode: Optional[str],
     local: bool,
+    stream: bool,
 ):
     """
     Run chat inference on an LLM model (local or external).
@@ -590,6 +593,9 @@ def chat(
 
     # External Anthropic model
     opengradient chat --model claude-haiku-4-5-20251001 --messages '[{"role":"user","content":"Write a poem"}]' --max-tokens 100
+
+    # Stream output
+    opengradient chat --model anthropic/claude-3.5-haiku --messages '[{"role":"user","content":"How are clouds formed?"}]' --max-tokens 250 --stream
     """
     client: Client = ctx.obj["client"]
 
@@ -656,7 +662,7 @@ def chat(
         if not tools and not tools_file:
             parsed_tools = None
 
-        completion_output = client.llm_chat(
+        result = client.llm_chat(
             model_cid=model_cid,
             inference_mode=LlmInferenceModes[inference_mode],
             messages=messages,
@@ -667,11 +673,16 @@ def chat(
             tool_choice=tool_choice,
             local_model=local,
             x402_settlement_mode=x402_settlement_mode,
+            stream=stream,
         )
 
-        print_llm_chat_result(
-            model_cid, completion_output.transaction_hash, completion_output.finish_reason, completion_output.chat_output, is_local
-        )
+        # Handle response based on streaming flag
+        if stream:
+            print_streaming_chat_result(model_cid, result, is_local)
+        else:
+            print_llm_chat_result(
+                model_cid, result.transaction_hash, result.finish_reason, result.chat_output, is_local
+            )
 
     except Exception as e:
         click.echo(f"Error running LLM chat inference: {str(e)}")
@@ -706,6 +717,80 @@ def print_llm_chat_result(model_cid, tx_hash, finish_reason, chat_output, is_loc
     click.echo()
 
 
+def print_streaming_chat_result(model_cid, stream, is_local=True):
+    """Handle streaming chat response with typed chunks - prints in real-time"""
+    click.secho("🌊 Streaming LLM Chat", fg="green", bold=True)
+    click.echo("──────────────────────────────────────")
+    click.echo("Model: ", nl=False)
+    click.secho(model_cid, fg="cyan", bold=True)
+    
+    if is_local:
+        click.echo("Source: ", nl=False)
+        click.secho("OpenGradient TEE", fg="cyan", bold=True)
+    else:
+        click.echo("Source: ", nl=False)
+        click.secho("External Provider", fg="cyan", bold=True)
+    
+    click.echo("──────────────────────────────────────")
+    click.secho("Response:", fg="yellow", bold=True)
+    click.echo()
+    
+    try:
+        content_parts = []
+        chunk_count = 0
+        
+        for chunk in stream:
+            chunk_count += 1
+            
+            if chunk.choices[0].delta.content:
+                content = chunk.choices[0].delta.content
+                sys.stdout.write(content)
+                sys.stdout.flush()
+                content_parts.append(content)
+            
+            # Handle tool calls
+            if chunk.choices[0].delta.tool_calls:
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+                click.secho("Tool Calls:", fg="yellow", bold=True)
+                for tool_call in chunk.choices[0].delta.tool_calls:
+                    click.echo(f"  Function: {tool_call['function']['name']}")
+                    click.echo(f"  Arguments: {tool_call['function']['arguments']}")
+            
+            # Print final info when stream completes
+            if chunk.is_final:
+                sys.stdout.write("\n\n")
+                sys.stdout.flush()
+                click.echo("──────────────────────────────────────")
+                
+                if chunk.usage:
+                    click.secho("Token Usage:", fg="cyan")
+                    click.echo(f"  Prompt tokens: {chunk.usage.prompt_tokens}")
+                    click.echo(f"  Completion tokens: {chunk.usage.completion_tokens}")
+                    click.echo(f"  Total tokens: {chunk.usage.total_tokens}")
+                    click.echo()
+                
+                if chunk.choices[0].finish_reason:
+                    click.echo("Finish reason: ", nl=False)
+                    click.secho(chunk.choices[0].finish_reason, fg="green")
+                
+                click.echo("──────────────────────────────────────")
+                click.echo(f"Chunks received: {chunk_count}")
+                click.echo(f"Content length: {len(''.join(content_parts))} characters")
+                click.echo()
+        
+    except KeyboardInterrupt:
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+        click.secho("Stream interrupted by user", fg="yellow")
+        click.echo()
+    except Exception as e:
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+        click.secho(f"Streaming error: {str(e)}", fg="red", bold=True)
+        click.echo()
+
+
 @cli.command()
 def create_account():
     """Create a new test account for OpenGradient inference and model management"""