opengradient 0.4.7__py3-none-any.whl → 0.4.9__py3-none-any.whl

opengradient/__init__.py

@@ -14,9 +14,12 @@ from .types import (
     CandleType,
     CandleOrder,
     InferenceMode,
+    InferenceResult,
     LlmInferenceMode,
     TextGenerationOutput,
     ModelOutput,
+    ModelRepository,
+    FileUploadResult,
 )
 
 from . import llm, alphasense
@@ -61,7 +64,7 @@ def init(email: str, password: str, private_key: str, rpc_url=DEFAULT_RPC_URL, c
     return _client
 
 
-def upload(model_path, model_name, version):
+def upload(model_path, model_name, version) -> FileUploadResult:
     """Upload a model file to OpenGradient.
 
     Args:
@@ -70,7 +73,7 @@ def upload(model_path, model_name, version):
         version: Version string for this model upload
 
     Returns:
-        dict: Upload response containing file metadata
+        FileUploadResult: Upload response containing file metadata
 
     Raises:
         RuntimeError: If SDK is not initialized
@@ -80,7 +83,7 @@ def upload(model_path, model_name, version):
     return _client.upload(model_path, model_name, version)
 
 
-def create_model(model_name: str, model_desc: str, model_path: Optional[str] = None):
+def create_model(model_name: str, model_desc: str, model_path: Optional[str] = None) -> ModelRepository:
     """Create a new model repository.
 
     Args:
@@ -89,7 +92,7 @@ def create_model(model_name: str, model_desc: str, model_path: Optional[str] = N
         model_path: Optional path to model file to upload immediately
 
     Returns:
-        dict: Creation response with model metadata and optional upload results
+        ModelRepository: Creation response with model metadata and optional upload results
 
     Raises:
         RuntimeError: If SDK is not initialized
@@ -126,7 +129,7 @@ def create_version(model_name, notes=None, is_major=False):
     return _client.create_version(model_name, notes, is_major)
 
 
-def infer(model_cid, inference_mode, model_input, max_retries: Optional[int] = None):
+def infer(model_cid, inference_mode, model_input, max_retries: Optional[int] = None) -> InferenceResult:
     """Run inference on a model.
 
     Args:
@@ -136,7 +139,9 @@ def infer(model_cid, inference_mode, model_input, max_retries: Optional[int] = N
         max_retries: Maximum number of retries for failed transactions
 
     Returns:
-        InferenceResult: Transaction hash and model output
+        InferenceResult (InferenceResult): A dataclass object containing the transaction hash and model output.
+            * transaction_hash (str): Blockchain hash for the transaction
+            * model_output (Dict[str, np.ndarray]): Output of the ONNX model
 
     Raises:
         RuntimeError: If SDK is not initialized
@@ -319,7 +324,7 @@ def run_workflow(contract_address: str) -> ModelOutput:
     return _client.run_workflow(contract_address)
 
 
-def read_workflow_history(contract_address: str, num_results: int) -> List[Dict]:
+def read_workflow_history(contract_address: str, num_results: int) -> List[ModelOutput]:
     """
     Gets historical inference results from a workflow contract.
 

opengradient/alphasense/run_model_tool.py

@@ -1,20 +1,22 @@
 from enum import Enum
-from typing import Any, Callable, Dict, Type, Optional
+from typing import Any, Callable, List, Dict, Type, Optional, Union
 
 from langchain_core.tools import BaseTool, StructuredTool
 from pydantic import BaseModel
 
 import opengradient as og
 from .types import ToolType
+from opengradient import InferenceResult
+import numpy as np
 
 
 def create_run_model_tool(
     tool_type: ToolType,
     model_cid: str,
     tool_name: str,
-    input_getter: Callable,
-    output_formatter: Callable[..., str] = lambda x: x,
-    input_schema: Optional[Type[BaseModel]] = None,
+    model_input_provider: Callable[..., Dict[str, Union[str, int, float, List, np.ndarray]]],
+    model_output_formatter: Callable[[InferenceResult], str],
+    tool_input_schema: Optional[Type[BaseModel]] = None,
     tool_description: str = "Executes the given ML model",
     inference_mode: og.InferenceMode = og.InferenceMode.VANILLA,
 ) -> BaseTool | Callable:
@@ -33,14 +35,30 @@ def create_run_model_tool(
         model_cid (str): The CID of the OpenGradient model to be executed.
         tool_name (str): The name to assign to the created tool. This will be used to identify
             and invoke the tool within the agent.
-        input_getter (Callable): A function that returns the input data required by the model.
+        model_input_provider (Callable): A function that takes in the tool_input_schema with arguments
+            filled by the agent and returns input data required by the model.
+
             The function should return data in a format compatible with the model's expectations.
-        output_formatter (Callable[..., str], optional): A function that takes the model output and
-            formats it into a string. This is required to ensure the output is compatible
-            with the tool framework. Default returns string as is.
-        input_schema (Type[BaseModel], optional): A Pydantic BaseModel class defining the
-            input schema. This will be used directly for LangChain tools and converted
-            to appropriate annotations for Swarm tools. Default is None.
+        model_output_formatter (Callable[..., str]): A function that takes the output of
+            the OpenGradient infer method (with type InferenceResult) and formats it into a string.
+
+            This is required to ensure the output is compatible with the tool framework.
+
+            Default returns the InferenceResult object.
+
+            InferenceResult has attributes:
+                * transaction_hash (str): Blockchain hash for the transaction
+                * model_output (Dict[str, np.ndarray]): Output of the ONNX model
+        tool_input_schema (Type[BaseModel], optional): A Pydantic BaseModel class defining the
+            input schema.
+
+            For LangChain tools the schema will be used directly. The defined schema will be used as
+            input keyword arguments for the `model_input_provider` function. If no arguments are required
+            for the `model_input_provider` function then this schema can be unspecified.
+
+            For Swarm tools the schema will be converted to appropriate annotations.
+
+            Default is None -- an empty schema will be provided for LangChain.
         tool_description (str, optional): A description of what the tool does. Defaults to
             "Executes the given ML model".
         inference_mode (og.InferenceMode, optional): The inference mode to use when running
@@ -55,42 +73,62 @@ def create_run_model_tool(
 
     Examples:
         >>> from pydantic import BaseModel, Field
-        >>> class ClassifierInput(BaseModel):
-        ...     query: str = Field(description="User query to analyze")
-        ...     parameters: dict = Field(description="Additional parameters")
-        >>> def get_input():
-        ...     return {"text": "Sample input text"}
-        >>> def format_output(output):
-        ...     return str(output.get("class", "Unknown"))
-        >>> # Create a LangChain tool
-        >>> langchain_tool = create_og_model_tool(
+        >>> from enum import Enum
+        >>> from opengradient.alphasense import create_run_model_tool
+        >>> class Token(str, Enum):
+        ...     ETH = "ethereum"
+        ...     BTC = "bitcoin"
+        ...
+        >>> class InputSchema(BaseModel):
+        ...     token: Token = Field(default=Token.ETH, description="Token name specified by user.")
+        ...
+        >>> eth_model_input = {"price_series": [2010.1, 2012.3, 2020.1, 2019.2]}        # Example data
+        >>> btc_model_input = {"price_series": [100001.1, 100013.2, 100149.2, 99998.1]} # Example data
+        >>> def model_input_provider(**llm_input):
+        ...     token = llm_input.get("token")
+        ...     if token == Token.BTC:
+        ...             return btc_model_input
+        ...     elif token == Token.ETH:
+        ...             return eth_model_input
+        ...     else:
+        ...             raise ValueError("Unexpected token found")
+        ...
+        >>> def output_formatter(inference_result):
+        ...     return format(float(inference_result.model_output["std"].item()), ".3%")
+        ...
+        >>> run_model_tool = create_run_model_tool(
         ...     tool_type=ToolType.LANGCHAIN,
-        ...     model_cid="Qm...",
-        ...     tool_name="text_classifier",
-        ...     input_getter=get_input,
-        ...     output_formatter=format_output,
-        ...     input_schema=ClassifierInput
-        ...     tool_description="Classifies text into categories"
+        ...     model_cid="QmZdSfHWGJyzBiB2K98egzu3MypPcv4R1ASypUxwZ1MFUG",
+        ...     tool_name="Return_volatility_tool",
+        ...     model_input_provider=model_input_provider,
+        ...     model_output_formatter=output_formatter,
+        ...     tool_input_schema=InputSchema,
+        ...     tool_description="This tool takes a token and measures the return volatility (standard deviation of returns).",
+        ...     inference_mode=og.InferenceMode.VANILLA,
         ... )
     """
 
-    # define runnable
     def model_executor(**llm_input):
-        # Combine LLM input with input provided by code
-        combined_input = {**llm_input, **input_getter()}
+        # Pass LLM input arguments (formatted based on tool_input_schema) as parameters into model_input_provider
+        model_input = model_input_provider(**llm_input)
 
-        _, output = og.infer(model_cid=model_cid, inference_mode=inference_mode, model_input=combined_input)
+        inference_result = og.infer(model_cid=model_cid, inference_mode=inference_mode, model_input=model_input)
 
-        return output_formatter(output)
+        return model_output_formatter(inference_result)
 
     if tool_type == ToolType.LANGCHAIN:
-        return StructuredTool.from_function(func=model_executor, name=tool_name, description=tool_description, args_schema=input_schema)
+        if not tool_input_schema:
+            tool_input_schema = type("EmptyInputSchema", (BaseModel,), {})
+
+        return StructuredTool.from_function(
+            func=model_executor, name=tool_name, description=tool_description, args_schema=tool_input_schema
+        )
     elif tool_type == ToolType.SWARM:
         model_executor.__name__ = tool_name
         model_executor.__doc__ = tool_description
         # Convert Pydantic model to Swarm annotations if provided
-        if input_schema:
-            model_executor.__annotations__ = _convert_pydantic_to_annotations(input_schema)
+        if tool_input_schema:
+            model_executor.__annotations__ = _convert_pydantic_to_annotations(tool_input_schema)
         return model_executor
     else:
         raise ValueError(f"Invalid tooltype: {tool_type}")

opengradient/client.py

@@ -13,7 +13,6 @@ from web3 import Web3
 from web3.exceptions import ContractLogicError
 from web3.logs import DISCARD
 
-from . import utils
 from .exceptions import OpenGradientError
 from .proto import infer_pb2, infer_pb2_grpc
 from .types import (
@@ -26,8 +25,11 @@ from .types import (
     TextGenerationOutput,
     SchedulerParams,
     InferenceResult,
+    ModelRepository,
+    FileUploadResult,
 )
 from .defaults import DEFAULT_IMAGE_GEN_HOST, DEFAULT_IMAGE_GEN_PORT, DEFAULT_SCHEDULER_ADDRESS
+from .utils import convert_array_to_model_output, convert_to_model_input, convert_to_model_output
 
 _FIREBASE_CONFIG = {
     "apiKey": "AIzaSyDUVckVtfl-hiteBzPopy1pDD8Uvfncs7w",
@@ -53,7 +55,7 @@ class Client:
     _blockchain: Web3
     _wallet_account: LocalAccount
 
-    _hub_user: Dict
+    _hub_user: Optional[Dict]
     _inference_abi: Dict
 
     def __init__(self, private_key: str, rpc_url: str, contract_address: str, email: Optional[str], password: Optional[str]):
@@ -88,7 +90,7 @@ class Client:
             logging.error(f"Authentication failed: {str(e)}")
             raise
 
-    def create_model(self, model_name: str, model_desc: str, version: str = "1.00") -> dict:
+    def create_model(self, model_name: str, model_desc: str, version: str = "1.00") -> ModelRepository:
         """
         Create a new model with the given model_name and model_desc, and a specified version.
 
@@ -111,39 +113,21 @@ class Client:
         payload = {"name": model_name, "description": model_desc}
 
         try:
-            logging.debug(f"Create Model URL: {url}")
-            logging.debug(f"Headers: {headers}")
-            logging.debug(f"Payload: {payload}")
-
             response = requests.post(url, json=payload, headers=headers)
             response.raise_for_status()
+        except requests.HTTPError as e:
+            error_details = f"HTTP {e.response.status_code}: {e.response.text}"
+            raise OpenGradientError(f"Model creation failed: {error_details}") from e
 
-            json_response = response.json()
-            model_name = json_response.get("name")
-            if not model_name:
-                raise Exception(f"Model creation response missing 'name'. Full response: {json_response}")
-            logging.info(f"Model creation successful. Model name: {model_name}")
+        json_response = response.json()
+        model_name = json_response.get("name")
+        if not model_name:
+            raise Exception(f"Model creation response missing 'name'. Full response: {json_response}")
 
-            # Create the specified version for the newly created model
-            try:
-                version_response = self.create_version(model_name, version)
-                logging.info(f"Version creation successful. Version string: {version_response['versionString']}")
-            except Exception as ve:
-                logging.error(f"Version creation failed, but model was created. Error: {str(ve)}")
-                return {"name": model_name, "versionString": None, "version_error": str(ve)}
+        # Create the specified version for the newly created model
+        version_response = self.create_version(model_name, version)
 
-            return {"name": model_name, "versionString": version_response["versionString"]}
-
-        except requests.RequestException as e:
-            logging.error(f"Model creation failed: {str(e)}")
-            if hasattr(e, "response") and e.response is not None:
-                logging.error(f"Response status code: {e.response.status_code}")
-                logging.error(f"Response headers: {e.response.headers}")
-                logging.error(f"Response content: {e.response.text}")
-            raise Exception(f"Model creation failed: {str(e)}")
-        except Exception as e:
-            logging.error(f"Unexpected error during model creation: {str(e)}")
-            raise
+        return ModelRepository(model_name, version_response["versionString"])
 
     def create_version(self, model_name: str, notes: str = "", is_major: bool = False) -> dict:
         """
@@ -204,7 +188,7 @@ class Client:
             logging.error(f"Unexpected error during version creation: {str(e)}")
             raise
 
-    def upload(self, model_path: str, model_name: str, version: str) -> dict:
+    def upload(self, model_path: str, model_name: str, version: str) -> FileUploadResult:
         """
         Upload a model file to the server.
 
@@ -259,12 +243,9 @@ class Client:
                 if response.status_code == 201:
                     if response.content and response.content != b"null":
                         json_response = response.json()
-                        logging.info(f"JSON response: {json_response}")  # Log the parsed JSON response
-                        logging.info(f"Upload successful. CID: {json_response.get('ipfsCid', 'N/A')}")
-                        result = {"model_cid": json_response.get("ipfsCid"), "size": json_response.get("size")}
+                        return FileUploadResult(json_response.get("ipfsCid"), json_response.get("size"))
                     else:
-                        logging.warning("Empty or null response content received. Assuming upload was successful.")
-                        result = {"model_cid": None, "size": None}
+                        raise RuntimeError("Empty or null response content received. Assuming upload was successful.")
                 elif response.status_code == 500:
                     error_message = "Internal server error occurred. Please try again later or contact support."
                     logging.error(error_message)
@@ -274,8 +255,6 @@ class Client:
                     logging.error(f"Upload failed with status code {response.status_code}: {error_message}")
                     raise OpenGradientError(f"Upload failed: {error_message}", status_code=response.status_code)
 
-                return result
-
         except requests.RequestException as e:
             logging.error(f"Request exception during upload: {str(e)}")
             if hasattr(e, "response") and e.response is not None:
@@ -303,7 +282,9 @@ class Client:
             max_retries (int, optional): Maximum number of retry attempts. Defaults to 5.
 
         Returns:
-            InferenceResult: The transaction hash and the model output.
+            InferenceResult (InferenceResult): A dataclass object containing the transaction hash and model output.
+                transaction_hash (str): Blockchain hash for the transaction
+                model_output (Dict[str, np.ndarray]): Output of the ONNX model
 
         Raises:
             OpenGradientError: If the inference fails.
@@ -313,7 +294,7 @@ class Client:
             contract = self._blockchain.eth.contract(address=self._inference_hub_contract_address, abi=self._inference_abi)
 
             inference_mode_uint8 = inference_mode.value
-            converted_model_input = utils.convert_to_model_input(model_input)
+            converted_model_input = convert_to_model_input(model_input)
 
             run_function = contract.functions.run(model_cid, inference_mode_uint8, converted_model_input)
 
@@ -342,7 +323,7 @@ class Client:
                 raise OpenGradientError("InferenceResult event not found in transaction logs")
 
             # TODO: This should return a ModelOutput class object
-            model_output = utils.convert_to_model_output(parsed_logs[0]["args"])
+            model_output = convert_to_model_output(parsed_logs[0]["args"])
 
             return InferenceResult(tx_hash.hex(), model_output)
 
@@ -751,7 +732,7 @@ class Client:
     #         if channel:
     #             channel.close()
 
-    def _get_abi(self, abi_name) -> List[Dict]:
+    def _get_abi(self, abi_name) -> str:
         """
         Returns the ABI for the requested contract.
         """
@@ -759,7 +740,7 @@ class Client:
         with open(abi_path, "r") as f:
             return json.load(f)
 
-    def _get_bin(self, bin_name) -> List[Dict]:
+    def _get_bin(self, bin_name) -> str:
         """
         Returns the bin for the requested contract.
         """
@@ -781,17 +762,20 @@ class Client:
         """
         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.
+        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): IPFS CID of the model to be executed
-            input_query (HistoricalInputQuery): Query parameters for data input
+            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 to run in hours
+                - duration_hours: How long the schedule should live for
 
         Returns:
             str: Deployed contract address. If scheduler_params was provided, the workflow
@@ -910,7 +894,7 @@ class Client:
         # Get the result
         result = contract.functions.getInferenceResult().call()
 
-        return utils.convert_array_to_model_output(result)
+        return convert_array_to_model_output(result)
 
     def run_workflow(self, contract_address: str) -> ModelOutput:
         """
@@ -955,9 +939,9 @@ class Client:
         # Get the inference result from the contract
         result = contract.functions.getInferenceResult().call()
 
-        return utils.convert_array_to_model_output(result)
+        return convert_array_to_model_output(result)
 
-    def read_workflow_history(self, contract_address: str, num_results: int) -> List[Dict]:
+    def read_workflow_history(self, contract_address: str, num_results: int) -> List[ModelOutput]:
         """
         Gets historical inference results from a workflow contract.
 
@@ -969,18 +953,14 @@ class Client:
             num_results (int): Number of historical results to retrieve
 
         Returns:
-            List[Dict]: List of historical inference results, each containing:
-                - prediction values
-                - timestamps
-                - any additional metadata stored with the result
-
+            List[ModelOutput]: List of historical inference results
         """
         contract = self._blockchain.eth.contract(
             address=Web3.to_checksum_address(contract_address), abi=self._get_abi("PriceHistoryInference.abi")
         )
 
         results = contract.functions.getLastInferenceResults(num_results).call()
-        return [utils.convert_array_to_model_output(result) for result in results]
+        return [convert_array_to_model_output(result) for result in results]
 
 
 def run_with_retry(txn_function, max_retries=DEFAULT_MAX_RETRY, retry_delay=DEFAULT_RETRY_DELAY_SEC):

opengradient/types.py

@@ -47,29 +47,63 @@ class Number:
 
 @dataclass
 class NumberTensor:
+    """
+    A container for numeric tensor data used as input for ONNX models.
+
+    Attributes:
+
+        name: Identifier for this tensor in the model.
+
+        values: List of integer tuples representing the tensor data.
+    """
+
     name: str
     values: List[Tuple[int, int]]
 
 
 @dataclass
 class StringTensor:
+    """
+    A container for string tensor data used as input for ONNX models.
+
+    Attributes:
+
+        name: Identifier for this tensor in the model.
+
+        values: List of strings representing the tensor data.
+    """
+
     name: str
     values: List[str]
 
 
 @dataclass
 class ModelInput:
+    """
+    A collection of tensor inputs required for ONNX model inference.
+
+    Attributes:
+
+        numbers: Collection of numeric tensors for the model.
+
+        strings: Collection of string tensors for the model.
+    """
+
     numbers: List[NumberTensor]
     strings: List[StringTensor]
 
 
 class InferenceMode(Enum):
+    """Enum for the different inference modes available for inference (VANILLA, ZKML, TEE)"""
+
     VANILLA = 0
     ZKML = 1
     TEE = 2
 
 
 class LlmInferenceMode(Enum):
+    """Enum for differetn inference modes available for LLM inferences (VANILLA, TEE)"""
+
     VANILLA = 0
     TEE = 1
 
@@ -89,14 +123,14 @@ class ModelOutput:
 @dataclass
 class InferenceResult:
     """
-    Output for ML inference requests
+    Output for ML inference requests.
+    This class has two fields
+        transaction_hash (str): Blockchain hash for the transaction
+        model_output (Dict[str, np.ndarray]): Output of the ONNX model
     """
 
     transaction_hash: str
-    """Blockchain hash for the transaction."""
-
     model_output: Dict[str, np.ndarray]
-    """Output of ONNX model"""
 
 
 @dataclass
@@ -184,3 +218,15 @@ class SchedulerParams:
         if data is None:
             return None
         return SchedulerParams(frequency=data.get("frequency", 600), duration_hours=data.get("duration_hours", 2))
+
+
+@dataclass
+class ModelRepository:
+    name: str
+    initialVersion: str
+
+
+@dataclass
+class FileUploadResult:
+    modelCid: str
+    size: int

opengradient/workflow_models/__init__.py

@@ -0,0 +1,28 @@
+"""
+OpenGradient Hardcoded Models
+"""
+
+from .workflow_models import *
+from .types import WorkflowModelOutput
+
+__all__ = [
+    "read_eth_usdt_one_hour_volatility_forecast",
+    "read_btc_1_hour_price_forecast",
+    "read_eth_1_hour_price_forecast",
+    "read_sol_1_hour_price_forecast",
+    "read_sui_1_hour_price_forecast",
+    "read_sui_usdt_30_min_price_forecast",
+    "read_sui_usdt_6_hour_price_forecast",
+    "WorkflowModelOutput",
+]
+
+__pdoc__ = {
+    "read_eth_usdt_one_hour_volatility_forecast": False,
+    "read_btc_1_hour_price_forecast": False,
+    "read_eth_1_hour_price_forecast": False,
+    "read_sol_1_hour_price_forecast": False,
+    "read_sui_1_hour_price_forecast": False,
+    "read_sui_usdt_30_min_price_forecast": False,
+    "read_sui_usdt_6_hour_price_forecast": False,
+    "WorkflowModelOutput": False,
+}

opengradient/workflow_models/constants.py

@@ -0,0 +1,13 @@
+"""Constants used by the models module"""
+
+# URL for OpenGradient block explorer
+BLOCK_EXPLORER_URL = "https://explorer.opengradient.ai/"
+
+# Workflow Contract Addresses
+ETH_USDT_1_HOUR_VOLATILITY_ADDRESS = "0xD5629A5b95dde11e4B5772B5Ad8a13B933e33845"
+BTC_1_HOUR_PRICE_FORECAST_ADDRESS = "0xb4146E095c2CD2a7aA497EdfB513F1cB868Dcc3D"
+ETH_1_HOUR_PRICE_FORECAST_ADDRESS = "0x58826c6dc9A608238d9d57a65bDd50EcaE27FE99"
+SOL_1_HOUR_PRICE_FORECAST_ADDRESS = "0xaE12EC7314e91A612CF4Fa4DC07dC02cfCc4dF95"
+SUI_1_HOUR_PRICE_FORECAST_ADDRESS = "0x90FE6434C46838c96E9ACb8d394C0fdfe38C6182"
+SUI_30_MINUTE_PRICE_FORECAST_ADDRESS = "0xD85BA71f5701dc4C5BDf9780189Db49C6F3708D2"
+SUI_6_HOUR_PRICE_FORECAST_ADDRESS = "0x3C2E4DbD653Bd30F1333d456480c1b7aB122e946"

opengradient/workflow_models/types.py

@@ -0,0 +1,16 @@
+"""Type definitions for models module."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class WorkflowModelOutput:
+    """
+    Output definition for reading from a workflow model.
+    """
+
+    result: str
+    """Result of the workflow formatted as a string."""
+
+    block_explorer_link: str = field(default="")
+    """(Optional) Block explorer link for the smart contract address of the workflow."""

opengradient/workflow_models/utils.py

@@ -0,0 +1,39 @@
+"""Utility functions for the models module."""
+
+from .constants import BLOCK_EXPLORER_URL
+from typing import Callable, Any
+from .types import WorkflowModelOutput
+import opengradient as og
+
+
+def create_block_explorer_link_smart_contract(transaction_hash: str) -> str:
+    """Create block explorer link for smart contract."""
+    block_explorer_url = BLOCK_EXPLORER_URL + "address/" + transaction_hash
+    return block_explorer_url
+
+
+def create_block_explorer_link_transaction(transaction_hash: str) -> str:
+    """Create block explorer link for transaction."""
+    block_explorer_url = BLOCK_EXPLORER_URL + "tx/" + transaction_hash
+    return block_explorer_url
+
+
+def read_workflow_wrapper(contract_address: str, format_function: Callable[..., str]) -> WorkflowModelOutput:
+    """
+    Wrapper function for reading from models through workflows.
+    Args:
+        contract_address (str): Smart contract address of the workflow
+        format_function (Callable): Function for formatting the result returned by read_workflow
+    """
+    try:
+        result = og.read_workflow_result(contract_address)
+
+        formatted_result = format_function(result)
+        block_explorer_link = create_block_explorer_link_smart_contract(contract_address)
+
+        return WorkflowModelOutput(
+            result=formatted_result,
+            block_explorer_link=block_explorer_link,
+        )
+    except Exception as e:
+        raise RuntimeError(f"Error reading from workflow with address {contract_address}: {e!s}")

opengradient/workflow_models/workflow_models.py

@@ -0,0 +1,97 @@
+"""Repository of OpenGradient quantitative workflow models."""
+
+import opengradient as og
+from .constants import (
+    ETH_USDT_1_HOUR_VOLATILITY_ADDRESS,
+    BTC_1_HOUR_PRICE_FORECAST_ADDRESS,
+    ETH_1_HOUR_PRICE_FORECAST_ADDRESS,
+    SOL_1_HOUR_PRICE_FORECAST_ADDRESS,
+    SUI_1_HOUR_PRICE_FORECAST_ADDRESS,
+    SUI_30_MINUTE_PRICE_FORECAST_ADDRESS,
+    SUI_6_HOUR_PRICE_FORECAST_ADDRESS,
+)
+from .utils import read_workflow_wrapper
+from .types import WorkflowModelOutput
+
+
+def read_eth_usdt_one_hour_volatility_forecast() -> WorkflowModelOutput:
+    """
+    Read from the ETH/USDT one hour volatility forecast model workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-1hr-volatility-ethusdt.
+    """
+    return read_workflow_wrapper(
+        contract_address=ETH_USDT_1_HOUR_VOLATILITY_ADDRESS, format_function=lambda x: format(float(x.numbers["Y"].item()), ".10%")
+    )
+
+
+def read_btc_1_hour_price_forecast() -> WorkflowModelOutput:
+    """
+    Read from the BTC one hour return forecast workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-btc-1hr-forecast.
+    """
+    return read_workflow_wrapper(
+        contract_address=BTC_1_HOUR_PRICE_FORECAST_ADDRESS,
+        format_function=lambda x: format(float(x.numbers["regression_output"].item()), ".10%"),
+    )
+
+
+def read_eth_1_hour_price_forecast() -> WorkflowModelOutput:
+    """
+    Read from the ETH one hour return forecast workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-eth-1hr-forecast.
+    """
+    return read_workflow_wrapper(
+        contract_address=ETH_1_HOUR_PRICE_FORECAST_ADDRESS,
+        format_function=lambda x: format(float(x.numbers["regression_output"].item()), ".10%"),
+    )
+
+
+def read_sol_1_hour_price_forecast() -> WorkflowModelOutput:
+    """
+    Read from the SOL one hour return forecast workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-sol-1hr-forecast.
+    """
+    return read_workflow_wrapper(
+        contract_address=SOL_1_HOUR_PRICE_FORECAST_ADDRESS,
+        format_function=lambda x: format(float(x.numbers["regression_output"].item()), ".10%"),
+    )
+
+
+def read_sui_1_hour_price_forecast() -> WorkflowModelOutput:
+    """
+    Read from the SUI one hour return forecast workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-sui-1hr-forecast.
+    """
+    return read_workflow_wrapper(
+        contract_address=SUI_1_HOUR_PRICE_FORECAST_ADDRESS,
+        format_function=lambda x: format(float(x.numbers["regression_output"].item()), ".10%"),
+    )
+
+
+def read_sui_usdt_30_min_price_forecast() -> WorkflowModelOutput:
+    """
+    Read from the SUI/USDT pair 30 min return forecast workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-30min-return-suiusdt.
+    """
+    return read_workflow_wrapper(
+        contract_address=SUI_30_MINUTE_PRICE_FORECAST_ADDRESS,
+        format_function=lambda x: format(float(x.numbers["destandardized_prediction"].item()), ".10%"),
+    )
+
+
+def read_sui_usdt_6_hour_price_forecast() -> WorkflowModelOutput:
+    """
+    Read from the SUI/USDT pair 6 hour return forecast workflow on the OpenGradient network.
+
+    More information on this model can be found at https://hub.opengradient.ai/models/OpenGradient/og-6h-return-suiusdt.
+    """
+    return read_workflow_wrapper(
+        contract_address=SUI_6_HOUR_PRICE_FORECAST_ADDRESS,
+        format_function=lambda x: format(float(x.numbers["destandardized_prediction"].item()), ".10%"),
+    )

{opengradient-0.4.7.dist-info → opengradient-0.4.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: opengradient
-Version: 0.4.7
+Version: 0.4.9
 Summary: Python SDK for OpenGradient decentralized model management & inference services
 Author-email: OpenGradient <oliver@opengradient.ai>
 License: MIT License

{opengradient-0.4.7.dist-info → opengradient-0.4.9.dist-info}/RECORD

@@ -1,17 +1,17 @@
-opengradient/__init__.py,sha256=CBZiyZhnuqbhWylFTi6KVAADBTt2X09aUH00vxpw7kk,12066
+opengradient/__init__.py,sha256=jNQwQmGa3r8BaPZP01mNwmhOU-16ggqUR4D2U4VrRZw,12422
 opengradient/account.py,sha256=5wrYpws_1lozjOFjLCTHtxgoxK-LmObDAaVy9eDcJY4,1145
 opengradient/cli.py,sha256=12fezJJvuceUaPSllsMqrBFoSpd2sTJjMpZ1_Dhzskg,25426
-opengradient/client.py,sha256=IGykQOcn2kQBhtcATqa8ka19K5ZK8dYxzdkRqYIMx10,44925
+opengradient/client.py,sha256=Dy9H_30WtB-hsRAk42HP4NZznuPIqB_kiyZeS_iBMh8,43971
 opengradient/defaults.py,sha256=Dqc64Qv7RdLv7ZBjXzvxRRqBDc1HhyVbbdImpmzyrzU,490
 opengradient/exceptions.py,sha256=88tfegboGtlehQcwhxsl6ZzhLJWZWlkf_bkHTiCtXpo,3391
-opengradient/types.py,sha256=wbLjrwurGG_74Dn9OZwkR-Kv985X5psSD8kgpiBwf3Q,4614
+opengradient/types.py,sha256=JH8hjpcq4H7gQki74cuJpH4PcyQpwivLiqn9iq0evrI,5715
 opengradient/utils.py,sha256=NMXg_mi5cHVeV01O4fFQJCcbwgGuGFbdYNrAG9K2Um0,8337
 opengradient/abi/PriceHistoryInference.abi,sha256=ZB3fZdx1kaFlp2wt1vTbTZZG1k8HPvmNtkG5Q8Bnajw,5098
 opengradient/abi/WorkflowScheduler.abi,sha256=yEGs76qO4S1z980KL5hBdfyXiJ6k-kERcB1O_o73AEU,416
 opengradient/abi/inference.abi,sha256=MR5u9npZ-Yx2EqRW17_M-UnGgFF3mMEMepOwaZ-Bkgc,7040
 opengradient/alphasense/__init__.py,sha256=Ah6IpoPTb6UkY7ImOWLJs3tjlxDJx6vZVR7p5IwP_Ks,292
 opengradient/alphasense/read_workflow_tool.py,sha256=ojCf-eMO6e0ib77nqjgEJtXxTxdLZmc_-MvyRemYFY0,3216
-opengradient/alphasense/run_model_tool.py,sha256=_Yh143Cq6zVlNMhBot30GwCR3Zbi6G1PK1nViU50lfA,5002
+opengradient/alphasense/run_model_tool.py,sha256=wlDqXVHa1xpqQy_hmht_wWegxtqdYgYBXNbRP3qbfwM,6945
 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
@@ -21,9 +21,14 @@ opengradient/proto/__init__.py,sha256=AhaSmrqV0TXGzCKaoPV8-XUvqs2fGAJBM2aOmDpkNb
 opengradient/proto/infer.proto,sha256=13eaEMcppxkBF8yChptsX9HooWFwJKze7oLZNl-LEb8,1217
 opengradient/proto/infer_pb2.py,sha256=sGWDDVumYhXoCJTG9rLyvKu4XyaEjPE_b038kbNlj7w,3484
 opengradient/proto/infer_pb2_grpc.py,sha256=q42_eZ7OZCMTXdWocYA4Ka3B0c3B74dOhfqdaIOO5AU,6700
-opengradient-0.4.7.dist-info/LICENSE,sha256=xEcvQ3AxZOtDkrqkys2Mm6Y9diEnaSeQRKvxi-JGnNA,1069
-opengradient-0.4.7.dist-info/METADATA,sha256=GC5oaUwycu1UodnPUEvBVvCI9cqBWJdLFo4W0oY83jo,5214
-opengradient-0.4.7.dist-info/WHEEL,sha256=nn6H5-ilmfVryoAQl3ZQ2l8SH5imPWFpm1A5FgEuFV4,91
-opengradient-0.4.7.dist-info/entry_points.txt,sha256=yUKTaJx8RXnybkob0J62wVBiCp_1agVbgw9uzsmaeJc,54
-opengradient-0.4.7.dist-info/top_level.txt,sha256=oC1zimVLa2Yi1LQz8c7x-0IQm92milb5ax8gHBHwDqU,13
-opengradient-0.4.7.dist-info/RECORD,,
+opengradient/workflow_models/__init__.py,sha256=pAGRaMZOXmuPnqG5gAQB1FeFLYxQ4F4bmYdrqXIez7c,826
+opengradient/workflow_models/constants.py,sha256=viIkb_LGcfVprqQNaA80gBTj6cfYam0r6b6MHW9XGFA,740
+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.4.9.dist-info/LICENSE,sha256=xEcvQ3AxZOtDkrqkys2Mm6Y9diEnaSeQRKvxi-JGnNA,1069
+opengradient-0.4.9.dist-info/METADATA,sha256=cT5_VHiQRqJkjoWwiAPMy6Rm-TvoNo4250d01Fdl_1U,5214
+opengradient-0.4.9.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+opengradient-0.4.9.dist-info/entry_points.txt,sha256=yUKTaJx8RXnybkob0J62wVBiCp_1agVbgw9uzsmaeJc,54
+opengradient-0.4.9.dist-info/top_level.txt,sha256=oC1zimVLa2Yi1LQz8c7x-0IQm92milb5ax8gHBHwDqU,13
+opengradient-0.4.9.dist-info/RECORD,,

{opengradient-0.4.7.dist-info → opengradient-0.4.9.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.1)
+Generator: setuptools (75.8.2)
 Root-Is-Purelib: true
 Tag: py3-none-any