chainix 0.1.0__py3-none-any.whl

chainix/__init__.py

@@ -0,0 +1,4 @@
+from .main import AsyncChainClient
+
+__version__ = "0.1.1"
+__all__ = ["AsyncChainClient"]

chainix/main.py

@@ -0,0 +1,223 @@
+import requests
+import time
+from typing import Dict, Callable, Any
+
+
+class AsyncChainClient:
+    """
+    Client for executing asynchronous chains with custom function callbacks.
+    """
+    
+    def __init__(
+        self,
+        chain_id: str,
+        api_key: str,
+        base_url: str = "https://chainix.ai",
+        max_wait_time: int = 300,
+        poll_interval: int = 5,
+        verbose: bool = True
+    ):
+        """
+        Initialize the AsyncChainClient.
+        
+        Args:
+            chain_id: Unique identifier for your chain
+            api_key: API key for authentication
+            base_url: Base URL of the chain server
+            max_wait_time: Maximum time to wait for chain completion in seconds
+            poll_interval: Time between status polls in seconds
+            verbose: Whether to print status messages (default True)
+        """
+        self.chain_id = chain_id
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.max_wait_time = max_wait_time
+        self.poll_interval = max(poll_interval, 3)
+        self.functions: Dict[str, Callable] = {}
+        self.verbose = verbose
+        
+        # Set up default headers
+        self.headers = {
+            'X-API-Key': self.api_key,
+            'Content-Type': 'application/json'
+        }
+
+    def _log(self, message: str):
+        """Print message if verbose mode is enabled."""
+        if self.verbose:
+            print(message)
+
+    
+    def register_function(self, function_id: str, function: Callable[[Dict[str, Any]], Any]) -> None:
+        """
+        Register a function that can be called during chain execution.
+        
+        Args:
+            function_id: Unique identifier for the function
+            function: Callable that takes a dictionary of arguments and returns a result
+        """
+        self.functions[function_id] = function
+    
+    def register_functions(self, functions: Dict[str, Callable[[Dict[str, Any]], Any]]) -> None:
+        """
+        Register multiple functions at once.
+        
+        Args:
+            functions: Dictionary mapping function IDs to callable functions
+        """
+        self.functions.update(functions)
+    
+    def poll_chain_status(self, task_id: str) -> Dict[str, Any]:
+        """
+        Poll the server for chain status until completion or timeout.
+        """
+        start_time = time.time()
+        status_url = f'{self.base_url}/api/chain-status/{self.chain_id}/{task_id}'
+
+        while time.time() - start_time < self.max_wait_time:
+            try:
+                status_response = requests.get(status_url, headers=self.headers)
+
+                if not status_response.ok:
+                    try:
+                        error_data = status_response.json()
+                        if error_data.get('detail'):
+                            self._log(f"Error polling chain status: {error_data['detail']}")
+                        else:
+                            self._log(f"Error response: {error_data}")
+                    except:
+                        self._log(f"Error {status_response.status_code}: {status_response.text}")
+                    time.sleep(self.poll_interval)
+                    continue
+
+                status_data = status_response.json()
+                self._log(f"Async status: {status_data.get('status', 'unknown')}")
+
+                if status_data.get('status') == 'complete':
+                    return status_data.get('result', {})
+                elif status_data.get('status') == 'failed':
+                    raise Exception(f"Chain failed: {status_data.get('result')}")
+
+                # Chain is still running, wait
+                time.sleep(self.poll_interval)
+            except requests.RequestException as e:
+                self._log(f"Error polling chain status: {e}")
+                time.sleep(self.poll_interval)
+
+        raise TimeoutError(f"Chain with run id {task_id} did not complete within {self.max_wait_time} seconds.")
+
+    def run_chain(
+        self,
+        initial_variables: Dict[str, Any],
+        test: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Execute an asynchronous chain with the provided initial_variables.
+        
+        Args:
+            initial_variables: Dictionary of initial variables for the chain
+            test: Whether this is a test run
+            vars_to_update: Optional dictionary of variables to update during execution
+            
+        Returns:
+            Dictionary containing the final chain result
+        """
+        url = f'{self.base_url}/api/run-chain/{self.chain_id}'
+
+        payload = {
+            'initial_variables': initial_variables,
+            'initial_run': True,
+            'test': test,
+        }
+
+        vars_to_update = {}
+
+        if vars_to_update:
+            payload['vars_to_update'] = vars_to_update
+
+        response = requests.post(url, json=payload, headers=self.headers)
+        if not response.ok:
+            try:
+                error_data = response.json()
+                if error_data.get('detail'):
+                    self._log(f"Error: {error_data['detail']}")
+                    self._log(f"Response: {error_data}")
+                else:
+                    self._log(f"Response: {error_data}")
+            except:
+                self._log(f"Error {response.status_code}: {response.text}")
+            return {}
+        
+        initial_response = response.json()
+        task_id = initial_response.get('data', {}).get('taskId')
+        if not task_id:
+            raise Exception("No task ID received from initial request.")
+
+        self._log(f"Chain started with task ID: {task_id}")
+        response = self.poll_chain_status(task_id)
+
+        while not response.get('complete', False):
+            # extract the run ID
+            run_id = response.get('run_id')
+            # the run is asking for a function call
+            func_info = response.get('function')
+            if not func_info:
+                raise Exception("No function call information found in the response.")
+
+            returned_function_id = func_info.get('id')
+            arguments = func_info.get('args')
+
+            if returned_function_id not in self.functions:
+                raise Exception(f"Function '{returned_function_id}' not implemented.")
+
+            function_to_call = self.functions[returned_function_id]
+            try:
+                result = function_to_call(arguments)
+            except Exception as e:
+                self._log(f"Function '{returned_function_id}' failed: {e}")
+                success = False
+                function_vars_to_update = {}
+            
+            else:
+                if not isinstance(result, dict):
+                    raise Exception(f"Function '{returned_function_id}' must return a dictionary, got {type(result)}")
+                    
+                if 'success' not in result:
+                    raise Exception(f"Function '{returned_function_id}' must return a dictionary with 'success' key to indicate if the function ran successfully.")
+                
+                if 'vars_to_update' not in result:
+                    raise Exception(f"Function '{returned_function_id}' must return a dictionary with 'vars_to_update' key. If there are no variables to update it should return an empty dictionary.")
+                
+                success = result['success']
+                function_vars_to_update = result['vars_to_update']
+                            
+
+            payload = {
+                'run_id': run_id, 
+                'success': success,
+                'initial_run': False,
+                'vars_to_update': function_vars_to_update
+            }
+
+            submit_resp = requests.post(url, json=payload, headers=self.headers)
+            if not submit_resp.ok:
+                try:
+                    error_data = submit_resp.json()
+                    if error_data.get('detail'):
+                        self._log(f"Error submitting function result: {error_data['detail']}")
+                    else:
+                        self._log(f"Error response: {error_data}")
+                except:
+                    self._log(f"Error {submit_resp.status_code}: {submit_resp.text}")
+                return {}
+
+            submit_response = submit_resp.json()
+            new_task_id = submit_response.get('data', {}).get('taskId')
+            if new_task_id:
+                self._log(f"Chain continued with task ID: {new_task_id}")
+                response = self.poll_chain_status(new_task_id)
+            else:
+                response = submit_response
+
+        self._log("Chain complete!")
+        return response

chainix-0.1.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: chainix
+Version: 0.1.0
+Summary: A client library for executing asynchronous chains with custom function callbacks
+Home-page: https://github.com/ChainixDev/chainix-python
+Author: Chainix
+Author-email: jack@chainix.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Chainix
+
+A Python client library for executing chains with chainix.ai
+
+## Installation
+
+```bash
+pip install chainix
+```
+
+## Quick Start
+
+```python
+from chainix import AsyncChainClient
+
+# Initialize the client
+client = AsyncChainClient(
+    chain_id="your-chains-id-here",
+    api_key="your-api-key-here",
+)
+
+# Define your custom functions
+def refund(args):
+    try:
+        order_id = args['order id']
+        print(f"Issuing a refund for order: {order_id}")
+    
+        # Your business logic here
+        # ... process refund ...
+        amount = 500
+        
+        return {
+            'success': True,
+            'vars_to_update': {
+                'refund_amount': amount
+            }
+        }
+    except Exception as e:
+        print(f"Failed to process refund: {e}")
+        return {
+            'success': False,
+            'vars_to_update': {}
+        }
+
+
+def cancel_order(args):
+    try:
+        order_id = args['order id']
+        print(f"Cancelling order: {order_id}")
+    
+        # Your business logic here
+        # ... perform cancellation ...
+        
+        return {
+            'success': True,
+            'vars_to_update': {}
+        }
+    except Exception as e:
+        print(f"Failed to cancel order: {e}")
+        return {
+            'success': False,
+            'vars_to_update': {}
+        }
+
+
+# Register your functions (use the actual function IDs from the chain on chainix.ai)
+client.register_function("your-cancel-function-id", cancel_order)
+client.register_function("your-refund-function-id", refund)
+
+# Or, bulk register your functions
+functions = {
+    "your-cancel-function-id": cancel_order,
+    "your-refund-function-id": refund,
+}
+client.register_functions(functions)
+
+# Execute a chain
+# Provide all initial variables needed to start the chain
+result = client.run_chain({
+    'message body': 'Hi, please cancel my order',
+    'order id': '33433',
+})
+
+print("Chain completed:", result)
+```
+
+## Function Requirements
+
+All registered functions **must** follow these requirements:
+
+### Function Signature
+Your functions should accept a single dictionary argument containing the inputs for that function call step:
+
+```python
+def my_function(args: dict) -> dict:
+    # Your business logic here
+    pass
+```
+
+**How it works:**
+1. You define variables in your chain on chainix.ai (e.g., `order id`, `user email`, `action`)
+2. You create function call steps in your chain and specify which variables should be passed as inputs to each step
+3. When the chain reaches a function call step, it stops and calls your registered function via it's id
+4. Your function receives a dictionary where each key is a variable you specified as an input for that step, and each value is the current value of that variable in the chain
+
+**Example:** If you have a function call step with `order id` and `user email` as inputs, your function will receive:
+```python
+{
+    'order id': '12345',
+    'user email': 'user@example.com'
+}
+```
+
+### Return Value
+Your functions **must** return a dictionary with exactly two keys:
+
+```python
+{
+    'success': bool,        # True if function executed successfully, False otherwise
+    'vars_to_update': dict  # Dictionary of variables to update in the chain (can be empty)
+}
+```
+
+**Important**: The keys in `vars_to_update` must exactly match the variable names you defined in your chain on chainix.ai. Only variables that exist in your chain can be updated. If you try to update a variable that doesn't exist in your chain, the chain will fail.
+
+### Example Function Structure
+
+```python
+def process_order(args):
+    try:
+        # Extract arguments
+        order_id = args['order id']
+        action = args.get('action', 'process')
+        
+        # Your business logic here
+        if action == 'cancel':
+            # ... cancellation logic ...
+            return {
+                'success': True,
+                'vars_to_update': {
+                    'order status': 'cancelled',        # Must match variable name in your chain
+                    'cancellation date': '2024-01-01'  # Must match variable name in your chain
+                }
+            }
+        elif action == 'fulfill':
+            # ... fulfillment logic ...
+            return {
+                'success': True,
+                'vars_to_update': {
+                    'order status': 'fulfilled',        # Must match variable name in your chain
+                    'fulfillment date': '2024-01-01'   # Must match variable name in your chain
+                }
+            }
+        else:
+            return {
+                'success': False,
+                'vars_to_update': {}
+            }
+            
+    except Exception as e:
+        print(f"Error processing order: {e}")
+        return {
+            'success': False,
+            'vars_to_update': {}
+        }
+```
+
+## Function Registration
+
+You can register functions individually or in bulk:
+
+```python
+# Individual registration
+client.register_function("function-id-1", my_function)
+
+# Bulk registration
+functions = {
+    "function-id-1": cancel_order,
+    "function-id-2": refund,
+    "function-id-3": process_order,
+}
+client.register_functions(functions)
+```
+
+## Configuration
+
+```python
+client = AsyncChainClient(
+    chain_id="your-chain-id",           # Your unique chain identifier
+    api_key="your-api-key",             # Your API key for authentication
+    base_url="https://chainix.ai",      # Base URL (optional, defaults to chainix.ai)
+    max_wait_time=300,                  # Max wait time in seconds (optional, default 300)
+    poll_interval=5,                    # How often to check status in seconds (optional, default 5, minimum 3)
+    verbose=True                        # Whether to print status messages (optional, default True)
+)
+```
+
+### Silent Mode
+
+For production environments or when you don't want status messages, you can disable verbose output:
+
+```python
+client = AsyncChainClient(
+    chain_id="your-chain-id",
+    api_key="your-api-key",
+    verbose=False  # Runs silently
+)
+```
+
+## Running Chains
+
+### Basic Usage
+
+```python
+result = client.run_chain(
+    initial_variables={
+        'message body': 'Hi, please cancel my order',
+        'user email': 'user@example.com',
+        'order id': '12345',
+    }
+)
+```
+
+### Test Mode
+
+You can run chains in test mode for development and debugging:
+
+```python
+result = client.run_chain(
+    initial_variables={
+        'message body': 'Hi, please cancel my order',
+        'user email': 'user@example.com',
+        'order id': '12345'
+    },
+    test=True  # Runs in test mode
+)
+```
+
+## Error Handling
+
+The client automatically handles several types of errors:
+
+- **Network errors**: Automatically retries with backoff
+- **Function execution errors**: Functions that throw exceptions are treated as failed (`success: False`)
+- **Invalid function returns**: If functions don't return the required structure, the chain will stop with a clear error message
+
+### Best Practices
+
+1. **Always wrap the body of your custom function in try-catch blocks**, catch any errors and set success to false in the return dictionary
+2. **Return meaningful error information** when functions fail
+3. **Validate input arguments** at the start of your functions
+4. **Use exact variable names** in `vars_to_update` that match your variables names on the chain configuration on chainix.ai
+
+```python
+def robust_function(args):
+    try:
+        # Validate inputs
+        if 'required_field' not in args:
+            raise ValueError("Missing required_field")
+            
+        # Your business logic
+        result = perform_business_logic(args)
+        
+        return {
+            'success': True,
+            'vars_to_update': {
+                'operation result': result,
+                'timestamp': datetime.now().isoformat()
+            }
+        }
+        
+    except ValueError as e:
+        print(f"Validation error: {e}")
+        return {
+            'success': False,
+            'vars_to_update': {'error type': 'validation_error'}
+        }
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        return {
+            'success': False,
+            'vars_to_update': {'error type': 'unexpected_error'}
+        }
+```
+
+## License
+
+MIT License

chainix-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+chainix/__init__.py,sha256=TbC8Nvsgo3n8s8IYr10U5qPc086Bn5ZxCl-lFfmhPe0,88
+chainix/main.py,sha256=ACrRB8RXU2qOViH69oCyKLjZ2FIU8FiDPU8_HWLfPqw,8656
+chainix-0.1.0.dist-info/METADATA,sha256=DcxsJbzx6k354W9ihrgM2E0PU1DzEUXp8gOBZJm7VDY,8915
+chainix-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+chainix-0.1.0.dist-info/top_level.txt,sha256=_urHgybqjX2rAy9bI04VrZGYvBXaZq6cjuUic5gkuLY,8
+chainix-0.1.0.dist-info/RECORD,,

chainix-0.1.0.dist-info/WHEEL

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

chainix-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chainix