opengradient 0.3.17__py3-none-any.whl → 0.3.18__py3-none-any.whl

opengradient/__init__.py

@@ -1,3 +1,7 @@
+"""
+OpenGradient Python SDK for interacting with AI models and infrastructure.
+"""
+
 from typing import Dict, List, Optional, Tuple
 
 from .client import Client
@@ -5,7 +9,7 @@ from .defaults import DEFAULT_INFERENCE_CONTRACT_ADDRESS, DEFAULT_RPC_URL
 from .types import InferenceMode, LlmInferenceMode, LLM, TEE_LLM
 from . import llm
 
-__version__ = "0.3.17"
+__version__ = "0.3.18"
 
 _client = None
 
@@ -14,15 +18,50 @@ def init(email: str,
          private_key: str,
          rpc_url=DEFAULT_RPC_URL,
          contract_address=DEFAULT_INFERENCE_CONTRACT_ADDRESS):
+    """Initialize the OpenGradient SDK with authentication and network settings.
+
+    Args:
+        email: User's email address for authentication
+        password: User's password for authentication
+        private_key: Ethereum private key for blockchain transactions
+        rpc_url: Optional RPC URL for the blockchain network, defaults to mainnet
+        contract_address: Optional inference contract address
+    """
     global _client
     _client = Client(private_key=private_key, rpc_url=rpc_url, contract_address=contract_address, email=email, password=password)
 
 def upload(model_path, model_name, version):
+    """Upload a model file to OpenGradient.
+
+    Args:
+        model_path: Path to the model file on local filesystem
+        model_name: Name of the model repository
+        version: Version string for this model upload
+
+    Returns:
+        dict: Upload response containing file metadata
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.upload(model_path, model_name, version)
 
 def create_model(model_name: str, model_desc: str, model_path: str = None):
+    """Create a new model repository.
+
+    Args:
+        model_name: Name for the new model repository
+        model_desc: Description of the model
+        model_path: Optional path to model file to upload immediately
+
+    Returns:
+        dict: Creation response with model metadata and optional upload results
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     
@@ -36,22 +75,37 @@ def create_model(model_name: str, model_desc: str, model_path: str = None):
     return result
 
 def create_version(model_name, notes=None, is_major=False):
+    """Create a new version for an existing model.
+
+    Args:
+        model_name: Name of the model repository
+        notes: Optional release notes for this version
+        is_major: If True, creates a major version bump instead of minor
+
+    Returns:
+        dict: Version creation response with version metadata
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.create_version(model_name, notes, is_major)
 
 def infer(model_cid, inference_mode, model_input, max_retries: Optional[int] = None):
-    """
-    Perform inference on a model.
+    """Run inference on a model.
 
     Args:
-        model_cid: Model CID to use for inference
+        model_cid: CID of the model to use
         inference_mode: Mode of inference (e.g. VANILLA)
         model_input: Input data for the model
-        max_retries: Optional maximum number of retry attempts for transaction errors
+        max_retries: Maximum number of retries for failed transactions
 
     Returns:
-        Tuple of (transaction hash, model output)
+        Tuple[str, Any]: Transaction hash and model output
+
+    Raises:
+        RuntimeError: If SDK is not initialized
     """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
@@ -64,6 +118,23 @@ def llm_completion(model_cid: LLM,
                   stop_sequence: Optional[List[str]] = None, 
                   temperature: float = 0.0,
                   max_retries: Optional[int] = None) -> Tuple[str, str]:
+    """Generate text completion using an LLM.
+
+    Args:
+        model_cid: CID of the LLM model to use
+        prompt: Text prompt for completion
+        inference_mode: Mode of inference, defaults to VANILLA
+        max_tokens: Maximum tokens to generate
+        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
+
+    Returns:
+        Tuple[str, str]: Transaction hash and generated text
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.llm_completion(model_cid=model_cid, 
@@ -83,6 +154,25 @@ def llm_chat(model_cid: LLM,
              tools: Optional[List[Dict]] = None,
              tool_choice: Optional[str] = None,
              max_retries: Optional[int] = None) -> Tuple[str, str, Dict]:
+    """Have a chat conversation with an LLM.
+
+    Args:
+        model_cid: CID of the LLM model to use
+        messages: List of chat messages, each with 'role' and 'content'
+        inference_mode: Mode of inference, defaults to VANILLA
+        max_tokens: Maximum tokens to generate
+        stop_sequence: Optional list of sequences where generation should stop
+        temperature: Sampling temperature (0.0 = deterministic, 1.0 = creative)
+        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
+
+    Returns:
+        Tuple[str, str, Dict]: Transaction hash, model response, and metadata
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.llm_chat(model_cid=model_cid, 
@@ -96,32 +186,82 @@ def llm_chat(model_cid: LLM,
                           max_retries=max_retries)
 
 def login(email: str, password: str):
+    """Login to OpenGradient.
+
+    Args:
+        email: User's email address
+        password: User's password
+
+    Returns:
+        dict: Login response with authentication tokens
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.login(email, password)
 
 def list_files(model_name: str, version: str) -> List[Dict]:
+    """List files in a model repository version.
+
+    Args:
+        model_name: Name of the model repository
+        version: Version string to list files from
+
+    Returns:
+        List[Dict]: List of file metadata dictionaries
+
+    Raises:
+        RuntimeError: If SDK is not initialized
+    """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.list_files(model_name, version)
 
 def generate_image(model: str, prompt: str, height: Optional[int] = None, width: Optional[int] = None) -> bytes:
-    """
-    Generate an image using the specified model and prompt.
+    """Generate an image from a text prompt.
 
     Args:
-        model (str): The model identifier (e.g. "stabilityai/stable-diffusion-xl-base-1.0")
-        prompt (str): The text prompt to generate the image from
-        height (Optional[int]): Height of the generated image. Default is None.
-        width (Optional[int]): Width of the generated image. Default is None.
+        model: Model identifier (e.g. "stabilityai/stable-diffusion-xl-base-1.0")
+        prompt: Text description of the desired image
+        height: Optional height of the generated image in pixels
+        width: Optional width of the generated image in pixels
 
     Returns:
-        bytes: The raw image data bytes
+        bytes: Raw image data as bytes
 
     Raises:
-        RuntimeError: If the client is not initialized
-        OpenGradientError: If the image generation fails
+        RuntimeError: If SDK is not initialized
+        OpenGradientError: If image generation fails
     """
     if _client is None:
         raise RuntimeError("OpenGradient client not initialized. Call og.init() first.")
     return _client.generate_image(model, prompt, height=height, width=width)
+
+__all__ = [
+    'generate_image',
+    'list_files'
+    'login',
+    'llm_chat',
+    'llm_completion',
+    'infer',
+    'create_version',
+    'create_model',
+    'upload',
+    'init',
+    'LLM',
+    'TEE_LLM'
+]
+
+__pdoc__ = {
+    'account': False,
+    'cli': False,
+    'client': False,
+    'defaults': False,
+    'exceptions': False,
+    'llm': True,
+    'proto': False,
+    'types': False,
+    'utils': False
+}

opengradient/llm/__init__.py

@@ -1,5 +1,38 @@
-from .chat import *
+"""
+OpenGradient LLM Adapters
+
+This module provides adapter interfaces to use OpenGradient LLMs with popular AI frameworks
+like LangChain and OpenAI. These adapters allow seamless integration of OpenGradient models
+into existing applications and agent frameworks.
+"""
+
+from .og_langchain import *
+from .og_openai import *
+
+def langchain_adapter(private_key: str, model_cid: str, max_tokens: int = 300) -> OpenGradientChatModel:
+    """
+    Returns an OpenGradient LLM that implements LangChain's LLM interface
+    and can be plugged into LangChain agents.
+    """
+    return OpenGradientChatModel(
+        private_key=private_key,
+        model_cid=model_cid,
+        max_tokens=max_tokens)
+
+def openai_adapter(private_key: str) -> OpenGradientOpenAIClient:
+    """
+    Returns an generic OpenAI LLM client that can be plugged into Swarm and can
+    be used with any LLM model on OpenGradient. The LLM is usually defined in the
+    agent.
+    """
+    return OpenGradientOpenAIClient(private_key=private_key)
 
 __all__ = [
-    'OpenGradientChatModel'
-]
+    'langchain_adapter',
+    'openai_adapter',
+]
+
+__pdoc__ = {
+    'og_langchain': False,
+    'og_openai': False
+}

opengradient/llm/og_openai.py

@@ -0,0 +1,121 @@
+from openai.types.chat import ChatCompletion
+import opengradient as og
+from opengradient.defaults import DEFAULT_RPC_URL, DEFAULT_INFERENCE_CONTRACT_ADDRESS
+
+from typing import List
+import time
+import json
+import uuid
+
+class OGCompletions(object):
+    client: og.Client
+
+    def __init__(self, client: og.Client):
+        self.client = client
+
+    def create(
+        self, 
+        model: str, 
+        messages: List[object], 
+        tools: List[object], 
+        tool_choice: str, 
+        stream: bool = False, 
+        parallel_tool_calls: bool = False) -> ChatCompletion:
+
+        # convert OpenAI message format so it's compatible with the SDK
+        sdk_messages = OGCompletions.convert_to_abi_compatible(messages)
+
+        _, finish_reason, chat_completion = self.client.llm_chat(
+            model_cid=model,
+            messages=sdk_messages,
+            max_tokens=200,
+            tools=tools,
+            tool_choice=tool_choice, 
+            temperature=0.25,
+            inference_mode=og.LlmInferenceMode.VANILLA
+        )
+
+        choice = {
+            'index': 0,  # Add missing index field
+            'finish_reason': finish_reason,
+            'message': {
+                'role': chat_completion['role'],
+                'content': chat_completion['content'],
+                'tool_calls': [
+                    {
+                        'id': tool_call['id'],
+                        'type': 'function',  # Add missing type field
+                        'function': {        # Add missing function field
+                            'name': tool_call['name'],
+                            'arguments': tool_call['arguments']
+                        }
+                    }
+                    for tool_call in chat_completion.get('tool_calls', [])
+                ] 
+            }
+        }
+
+        return ChatCompletion(
+            id=str(uuid.uuid4()),
+            created=int(time.time()),
+            model=model,
+            object='chat.completion',
+            choices=[choice]
+        )
+
+    @staticmethod
+    @staticmethod
+    def convert_to_abi_compatible(messages):
+        sdk_messages = []
+
+        for message in messages:
+            role = message['role']
+            sdk_message = {
+                'role': role
+            }
+
+            if role == 'system':
+                sdk_message['content'] = message['content']
+            elif role == 'user':
+                sdk_message['content'] = message['content']
+            elif role == 'tool':
+                sdk_message['content'] = message['content']
+                sdk_message['tool_call_id'] = message['tool_call_id']
+            elif role == 'assistant':
+                flattened_calls = []
+                for tool_call in message['tool_calls']:
+                    # OpenAI format
+                    flattened_call = {
+                        'id': tool_call['id'],
+                        'name': tool_call['function']['name'],
+                        'arguments': tool_call['function']['arguments']
+                    }
+                    flattened_calls.append(flattened_call)
+
+                sdk_message['tool_calls'] = flattened_calls
+                sdk_message['content'] = message['content']
+
+            sdk_messages.append(sdk_message)
+
+        return sdk_messages
+
+class OGChat(object):
+    completions: OGCompletions
+
+    def __init__(self, client: og.Client):
+        self.completions = OGCompletions(client)
+
+class OpenGradientOpenAIClient(object):
+    """OpenAI client implementation"""
+    client: og.Client
+    chat: OGChat
+
+    def __init__(self, private_key: str):
+        self.client = og.Client(
+            private_key=private_key,
+            rpc_url=DEFAULT_RPC_URL,
+            contract_address=DEFAULT_INFERENCE_CONTRACT_ADDRESS,
+            email=None,
+            password=None
+        )
+        self.chat = OGChat(self.client)

opengradient/types.py

@@ -79,6 +79,8 @@ class Abi:
         return result
     
 class LLM(str, Enum):
+    """Enum for available LLM models"""
+
     META_LLAMA_3_8B_INSTRUCT = "meta-llama/Meta-Llama-3-8B-Instruct"
     LLAMA_3_2_3B_INSTRUCT = "meta-llama/Llama-3.2-3B-Instruct"
     MISTRAL_7B_INSTRUCT_V3 = "mistralai/Mistral-7B-Instruct-v0.3"
@@ -86,4 +88,6 @@ class LLM(str, Enum):
     META_LLAMA_3_1_70B_INSTRUCT = "meta-llama/Llama-3.1-70B-Instruct"
 
 class TEE_LLM(str, Enum):
+    """Enum for LLM models available for TEE execution"""
+
     META_LLAMA_3_1_70B_INSTRUCT = "meta-llama/Llama-3.1-70B-Instruct"

{opengradient-0.3.17.dist-info → opengradient-0.3.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: opengradient
-Version: 0.3.17
+Version: 0.3.18
 Summary: Python SDK for OpenGradient decentralized model management & inference services
 Project-URL: Homepage, https://opengradient.ai
 Author-email: OpenGradient <oliver@opengradient.ai>
@@ -25,6 +25,7 @@ License: MIT License
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
+License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -85,6 +86,7 @@ Requires-Dist: langchain==0.3.7
 Requires-Dist: more-itertools==10.5.0
 Requires-Dist: msgpack==1.1.0
 Requires-Dist: multidict==6.1.0
+Requires-Dist: openai==1.58.1
 Requires-Dist: packaging==24.1
 Requires-Dist: pandas==2.2.3
 Requires-Dist: parsimonious==0.10.0

{opengradient-0.3.17.dist-info → opengradient-0.3.18.dist-info}/RECORD

@@ -1,20 +1,21 @@
-opengradient/__init__.py,sha256=Ijf4XB8tJsj6mGwv5xpkcXF8RZj0ex3vGnP-b-dGwEg,5306
+opengradient/__init__.py,sha256=CRII5thG_vRVtEqyhc48IWgYwjif2S4kOBbBf6MgH8I,9262
 opengradient/account.py,sha256=2B7rtCXQDX-yF4U69h8B9-OUreJU4IqoGXG_1Hn9nWs,1150
 opengradient/cli.py,sha256=niN8tlLaiVEpdtkdWEUbxidG75nxrlb6mMUfUAIjiVw,26400
 opengradient/client.py,sha256=axMbfqAQ6OWq3sM_D4bGVWrpAd-15Ru-bOHJ6R6GruA,35197
 opengradient/defaults.py,sha256=6tsW9Z84z6YtITCsULTTgnN0KRUZjfSoeWJZqdWkYCo,384
 opengradient/exceptions.py,sha256=v4VmUGTvvtjhCZAhR24Ga42z3q-DzR1Y5zSqP_yn2Xk,3366
-opengradient/types.py,sha256=QwvPAO_N3SqESqoKDuj3eiGlhiqHUAUPqI0sa4FW3mg,2364
+opengradient/types.py,sha256=-lGWv_yfXMN48bbvARKIFrj1L0AotIwr2c7GOv1JBcI,2464
 opengradient/utils.py,sha256=lUDPmyPqLwpZI-owyN6Rm3QvUjOn5pLN5G1QyriVm-E,6994
 opengradient/abi/inference.abi,sha256=MR5u9npZ-Yx2EqRW17_M-UnGgFF3mMEMepOwaZ-Bkgc,7040
-opengradient/llm/__init__.py,sha256=n_11WFPoU8YtGc6wg9cK6gEy9zBISf1183Loip3dAbI,62
-opengradient/llm/chat.py,sha256=F32yN1o8EvRbzZSJkUwI0-FmSVAWMuMTI9ho7wgW5hk,4470
+opengradient/llm/__init__.py,sha256=J1W_AKPntqlDqLeflhn2x7A0i-dkMT-ol3jlEdFgMWU,1135
+opengradient/llm/og_langchain.py,sha256=F32yN1o8EvRbzZSJkUwI0-FmSVAWMuMTI9ho7wgW5hk,4470
+opengradient/llm/og_openai.py,sha256=GilEkIVDac5Cacennb7YNXD6BKwUj69mfnMkvxkiW5Y,3865
 opengradient/proto/__init__.py,sha256=AhaSmrqV0TXGzCKaoPV8-XUvqs2fGAJBM2aOmDpkNbE,55
 opengradient/proto/infer.proto,sha256=13eaEMcppxkBF8yChptsX9HooWFwJKze7oLZNl-LEb8,1217
 opengradient/proto/infer_pb2.py,sha256=wg2vjLQCNv6HRhYuIqgj9xivi3nO4IPz6E5wh2dhDqY,3446
 opengradient/proto/infer_pb2_grpc.py,sha256=y5GYwD1EdNs892xx58jdfyA0fO5QC7k3uZOtImTHMiE,6891
-opengradient-0.3.17.dist-info/METADATA,sha256=okJDsHtoeVnLZjrcq97Bw6bbquqIuoHJTgVg7BTe_jw,8692
-opengradient-0.3.17.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-opengradient-0.3.17.dist-info/entry_points.txt,sha256=yUKTaJx8RXnybkob0J62wVBiCp_1agVbgw9uzsmaeJc,54
-opengradient-0.3.17.dist-info/licenses/LICENSE,sha256=xEcvQ3AxZOtDkrqkys2Mm6Y9diEnaSeQRKvxi-JGnNA,1069
-opengradient-0.3.17.dist-info/RECORD,,
+opengradient-0.3.18.dist-info/METADATA,sha256=eH1-0CRuheW8Ho8mMbiivn2WIrgAKZf37c4zlFMloes,8744
+opengradient-0.3.18.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+opengradient-0.3.18.dist-info/entry_points.txt,sha256=yUKTaJx8RXnybkob0J62wVBiCp_1agVbgw9uzsmaeJc,54
+opengradient-0.3.18.dist-info/licenses/LICENSE,sha256=xEcvQ3AxZOtDkrqkys2Mm6Y9diEnaSeQRKvxi-JGnNA,1069
+opengradient-0.3.18.dist-info/RECORD,,

{opengradient-0.3.17.dist-info → opengradient-0.3.18.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.26.3
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any