lionagi 0.0.111__py3-none-any.whl → 0.0.113__py3-none-any.whl

lionagi/services/service_objs.py

@@ -0,0 +1,282 @@
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, NoReturn
+
+
+# should be fine ------------------------------------------------------------------
+@dataclass
+class StatusTracker:
+    """
+    Class for keeping track of various task statuses.
+    
+    This class serves as a simple way to monitor different types of task
+    outcomes and errors within a system. It uses dataclasses for easy
+    creation and management of state.
+    
+    Attributes:
+        num_tasks_started:
+            The number of tasks that have been initiated.
+        num_tasks_in_progress:
+            The number of tasks currently being processed.
+        num_tasks_succeeded:
+            The number of tasks that have completed successfully.
+        num_tasks_failed:
+            The number of tasks that have failed.
+        num_rate_limit_errors:
+            The number of tasks that failed due to rate limiting.
+        num_api_errors:
+            The number of tasks that failed due to API errors.
+        num_other_errors:
+            The number of tasks that failed due to other errors.
+    """
+    num_tasks_started: int = 0
+    num_tasks_in_progress: int = 0
+    num_tasks_succeeded: int = 0
+    num_tasks_failed: int = 0
+    num_rate_limit_errors: int = 0
+    num_api_errors: int = 0
+    num_other_errors: int = 0
+
+
+class AsyncQueue:
+    """
+    A queue class that handles asynchronous operations using asyncio.
+
+    This class provides an asynchronous queue that can enqueue items, process them
+    asynchronously, and support graceful shutdowns. It is designed to facilitate
+    concurrent task processing in an orderly and controlled manner.
+
+    Attributes:
+        queue (asyncio.Queue):
+            A queue to hold items for asynchronous processing.
+        _stop_event (asyncio.Event):
+            An event to signal when the queue should stop processing.
+
+    Methods:
+        enqueue(item):
+            Add an item to the queue for processing.
+        dequeue():
+            Remove and return an item from the queue.
+        join():
+            Wait until all items in the queue have been processed.
+        stop():
+            Signal to stop processing new items in the queue.
+        stopped():
+            Check if the queue has been signaled to stop.
+        process_requests(func):
+            Process items using a provided function.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes an AsyncQueue object with an empty asyncio Queue and a stop event.
+        """
+        self.queue = asyncio.Queue()
+        self._stop_event = asyncio.Event()
+
+    async def enqueue(self, item: Any) -> None:
+        """
+        Asynchronously add an item to the queue for processing.
+
+        Parameters:
+            item (Any): The item to be added to the queue.
+
+        Example:
+            >>> async_queue = AsyncQueue()
+            >>> asyncio.run(async_queue.enqueue('Task 1'))
+        """
+        await self.queue.put(item)
+
+    async def dequeue(self) -> Any:
+        """
+        Asynchronously remove and return an item from the queue.
+
+        If the queue is empty, this method will wait until an item is available.
+
+        Returns:
+            Any: The next item from the queue.
+
+        Example:
+            >>> async_queue = AsyncQueue()
+            >>> asyncio.run(async_queue.enqueue('Task 1'))
+            >>> asyncio.run(async_queue.dequeue())
+            'Task 1'
+        """
+        return await self.queue.get()
+
+    async def join(self) -> None:
+        """
+        Asynchronously wait until all items in the queue have been processed.
+
+        This method blocks until every item that has been enqueued is processed, 
+        ensuring that all tasks are completed.
+
+        Example:
+            >>> async_queue = AsyncQueue()
+            >>> asyncio.run(async_queue.enqueue('Task 1'))
+            >>> asyncio.run(async_queue.join())  # This will block until 'Task 1' is processed.
+        """
+        await self.queue.join()
+
+    async def stop(self) -> None:
+        """
+        Signal the queue to stop processing new items.
+
+        Once called, the queue will not process any new items after the current ones
+        are completed, allowing for a graceful shutdown.
+
+        Example:
+            >>> async_queue = AsyncQueue()
+            >>> asyncio.run(async_queue.stop())  # This signals the queue to stop processing.
+        """
+        self._stop_event.set()
+
+    def stopped(self) -> bool:
+        """
+        Check if the queue has been signaled to stop processing.
+
+        Returns:
+            bool: True if a stop has been signaled, False otherwise.
+
+        Example:
+            >>> async_queue = AsyncQueue()
+            >>> asyncio.run(async_queue.stop())
+            >>> async_queue.stopped()
+            True
+        """
+        return self._stop_event.is_set()
+
+    async def process_requests(self, func: Callable[[Any], Any]) -> None:
+        """
+        Asynchronously process items from the queue using the provided function.
+
+        Continuously dequeues items and applies the given function to each. 
+        The processing stops when the queue is signaled to stop or a sentinel value (`None`) is dequeued.
+
+        Parameters:
+            func (Callable[[Any], Any]): A coroutine function to process items from the queue.
+
+        Example:
+            >>> async def sample_processing(task):
+            ...     print("Processing:", task)
+            >>> async_queue = AsyncQueue()
+            >>> asyncio.run(async_queue.enqueue('Task 1'))
+            >>> asyncio.run(async_queue.process_requests(sample_processing))
+            Processing: Task 1
+        """
+        while not self.stopped():
+            item = await self.dequeue()
+            if item is None:  # Using `None` as a sentinel value to cease processing.
+                await self.stop()
+                break
+            await func(item)
+
+
+class BaseService(ABC):
+    
+    @abstractmethod
+    def __init__(self) -> None:
+        ...
+
+    @abstractmethod
+    async def serve(self) -> Any:     
+        ...
+
+
+
+class RateLimiter(ABC):
+    """
+    An abstract base class for rate limiting mechanisms.
+
+    This class defines a structure for rate limiters, which are used to control the frequency
+    of requests sent to or received from a network interface controller or an API.
+
+    Attributes:
+        max_requests_per_minute (int):
+            Maximum number of requests permitted per minute.
+        max_tokens_per_minute (int):
+            Maximum number of tokens that can accumulate per minute.
+        available_request_capacity (int):
+            Current number of available request slots.
+        available_token_capacity (int):
+            Current number of available tokens.
+
+    Methods:
+        rate_limit_replenisher:
+            Coroutine to replenish rate limits over time.
+        calculate_num_token:
+            Method to calculate required tokens for a request.
+    """
+    
+    def __init__(self, max_requests_per_minute: int, max_tokens_per_minute: int) -> None:
+        """
+        Initializes the RateLimiter with specified maximum request and token limits.
+
+        Parameters:
+            max_requests_per_minute (int): Maximum requests allowed per minute.
+
+            max_tokens_per_minute (int): Maximum tokens allowed to accumulate per minute.
+
+        Example:
+            >>> class MyRateLimiter(RateLimiter):
+            ...     async def rate_limit_replenisher(self) -> NoReturn:
+            ...         # Implementation for rate replenishment.
+            ...     def calculate_num_token(self, payload: Dict[str, Any], api_endpoint: str) -> int:
+            ...         # Implementation for token calculation.
+            ...
+            >>> limiter = MyRateLimiter(100, 200)
+        """
+        self.max_requests_per_minute = max_requests_per_minute
+        self.max_tokens_per_minute = max_tokens_per_minute
+        self.available_request_capacity = max_requests_per_minute
+        self.available_token_capacity = max_tokens_per_minute
+    
+    @abstractmethod
+    async def rate_limit_replenisher(self) -> NoReturn:
+        """
+        Asynchronously replenishes rate limit capacities.
+
+        This coroutine should be implemented to periodically restore `available_request_capacity`
+        and `available_token_capacity` according to specific rules defined in subclasses.
+
+        Example:
+            >>> class MyRateLimiter(RateLimiter):
+            ...     async def rate_limit_replenisher(self) -> NoReturn:
+            ...         while True:
+            ...             # Replenishment logic here
+            ...
+            >>> limiter = MyRateLimiter(100, 200)
+        """
+        
+        ...
+    
+    @abstractmethod
+    def calculate_num_token(self, payload: Dict[str, Any], api_endpoint: str) -> int:
+        """
+        Calculates required tokens for a request.
+
+        Subclasses should implement this method to determine the number of tokens needed based
+        on the request payload and target endpoint.
+
+        Parameters:
+            payload (Dict[str, Any]): Payload of the request.
+
+            api_endpoint (str): Target API endpoint for the request.
+
+        Returns:
+            int: Calculated number of tokens required for the request.
+
+        Example:
+            >>> class MyRateLimiter(RateLimiter):
+            ...     def calculate_num_token(self, payload: Dict[str, Any], api_endpoint: str) -> int:
+            ...         return len(payload.get('data', '')) // 10
+            ...
+            >>> limiter = MyRateLimiter(100, 200)
+            >>> limiter.calculate_num_token({'data': '12345'}, 'api/send')
+            0
+        """
+        
+        ...
+
+

lionagi/structure/__init__.py

@@ -0,0 +1,7 @@
+from .relationship import Relationship
+from .structure import Structure
+
+__all__=[
+    "Relationship",
+    "Structure"
+]

lionagi/structure/relationship.py

@@ -0,0 +1,128 @@
+from pydantic import Field
+from typing import Dict, Optional, Any
+from ..schema.base_schema import BaseNode
+
+
+class Relationship(BaseNode):
+    """
+    Relationship class represents a relationship between two nodes in a graph.
+
+    Inherits from BaseNode and adds functionality to manage conditions and relationships 
+    between source and target nodes.
+
+    Attributes:
+        source_node_id (str): The identifier of the source node.
+        target_node_id (str): The identifier of the target node.
+        condition (Dict[str, Any]): A dictionary representing conditions for the relationship.
+    """
+
+    source_node_id: str
+    target_node_id: str
+    condition: dict = Field(default={})
+
+    def add_condition(self, condition: Dict[str, Any]) -> None:
+        """
+        Adds a condition to the relationship.
+
+        Parameters:
+            condition (Dict[str, Any]): The condition to be added.
+        """
+        self.condition.update(condition)
+
+    def remove_condition(self, condition_key: str) -> Any:
+        """
+        Removes a condition from the relationship.
+
+        Parameters:
+            condition_key (str): The key of the condition to be removed.
+
+        Returns:
+            Any: The value of the removed condition.
+
+        Raises:
+            KeyError: If the condition key is not found.
+        """
+        if condition_key not in self.condition.keys():
+            raise KeyError(f'condition {condition_key} is not found')
+        return self.condition.pop(condition_key)
+
+    def condition_exists(self, condition_key: str) -> bool:
+        """
+        Checks if a condition exists in the relationship.
+
+        Parameters:
+            condition_key (str): The key of the condition to check.
+
+        Returns:
+            bool: True if the condition exists, False otherwise.
+        """
+        if condition_key in self.condition.keys():
+            return True
+        else:
+            return False
+
+    def get_condition(self, condition_key: Optional[str] = None) -> Any:
+        """
+        Retrieves a specific condition or all conditions of the relationship.
+
+        Parameters:
+            condition_key (Optional[str]): The key of the specific condition. Defaults to None.
+
+        Returns:
+            Any: The requested condition or all conditions if no key is provided.
+
+        Raises:
+            ValueError: If the specified condition key does not exist.
+        """
+        if condition_key is None:
+            return self.condition
+        if self.condition_exists(condition_key=condition_key):
+            return self.condition[condition_key]
+        else:
+            raise ValueError(f"Condition {condition_key} does not exist")
+    
+    def _source_existed(self, obj: Dict[str, Any]) -> bool:
+        """
+        Checks if the source node exists in a given object.
+
+        Parameters:
+            obj (Dict[str, Any]): The object to check.
+
+        Returns:
+            bool: True if the source node exists, False otherwise.
+        """
+        return self.source_node_id in obj.keys()
+    
+    def _target_existed(self, obj: Dict[str, Any]) -> bool:
+        """
+        Checks if the target node exists in a given object.
+
+        Parameters:
+            obj (Dict[str, Any]): The object to check.
+
+        Returns:
+            bool: True if the target node exists, False otherwise.
+        """
+        return self.target_node_id in obj.keys()
+    
+    def _is_in(self, obj: Dict[str, Any]) -> bool:
+        """
+        Validates the existence of both source and target nodes in a given object.
+
+        Parameters:
+            obj (Dict[str, Any]): The object to check.
+
+        Returns:
+            bool: True if both nodes exist.
+
+        Raises:
+            ValueError: If either the source or target node does not exist.
+        """
+        if self._source_existed(obj) and self._target_existed(obj):
+            return True
+        
+        elif self._source_existed(obj):
+            raise ValueError(f"Target node {self.source_node_id} does not exist")
+        else :
+            raise ValueError(f"Source node {self.target_node_id} does not exist")
+        

lionagi/structure/structure.py

@@ -0,0 +1,160 @@
+from typing import TypeVar, Dict, Optional, Any, Type, Union, List
+from pydantic import Field
+from ..schema.base_schema import BaseNode
+from .relationship import Relationship
+
+T = TypeVar('T', bound='BaseNode')
+R = TypeVar('R', bound='Relationship')
+
+
+class Structure(BaseNode):
+    """
+    Represents the structure of a graph consisting of nodes and relationships.
+    """
+    nodes: Dict[str, T] = Field(default_factory=dict)
+    relationships: Dict[str, R] = Field(default_factory=dict)
+    node_relationships: Dict[str, Dict[str, Dict[str, str]]] = Field(default_factory=dict)
+
+    def add_node(self, node: T) -> None:
+        """
+        Adds a node to the structure.
+        
+        Args:
+            node (T): The node instance to be added.
+        """
+        self.nodes[node.id_] = node
+        self.node_relationships[node.id_] = {'in': {}, 'out': {}}
+
+    def add_relationship(self, relationship: R) -> None:
+        """
+        Adds a relationship to the structure.
+        
+        Args:
+            relationship (R): The relationship instance to be added.
+        """
+        id_, source_, target_ = (
+            relationship.id_, relationship.source_node_id, relationship.target_node_id
+            )
+        
+        self.relationships.update({id_ : relationship})
+        self.node_relationships[source_]['out'].update({id_ : target_})
+        self.node_relationships[target_]['in'].update({id_ : source_})
+
+    # type can be dict or list
+    @staticmethod
+    def _typed_return(type: Type[Union[Dict, List]], 
+                      obj: Optional[Dict[str, Any]] = None
+                      ) -> Union[Dict[str, Any], List[Any]]:
+        """
+        Returns the object in the specified type format.
+        
+        Args:
+            type (Type[Union[Dict, List]]): The type to return the object as (dict or list).
+            
+            obj (Optional[Dict[str, Any]]): The object to be converted.
+            
+        Returns:
+            Union[Dict[str, Any], List[Any]]: The object in the specified type format.
+        """
+        if type is list:
+            return list(obj.values())
+        return obj
+    
+    def get_relationships(self, type: Type = dict) -> Union[Dict[str, R], List[R]]:
+        """
+        Returns the relationships in the specified type format.
+        
+        Args:
+            type (Type): The type to return the relationships as (dict or list).
+            
+        Returns:
+            Union[Dict[str, R], List[R]]: The relationships in the specified type format.
+        """
+        return self._typed_return(self.relationships, type=type)
+        
+    def get_node_relationships(self, id_: str, in_out: str, type: Type = dict
+                               ) -> Union[Dict[str, str], List[str]]:
+        """
+        Returns the relationships of a node in the specified type format.
+        
+        Args:
+            id_ (str): The ID of the node.
+            
+            in_out (str): 'in' for incoming relationships, 'out' for outgoing relationships.
+            
+            type (Type): The type to return the relationships as (dict or list).
+            
+        Returns:
+            Union[Dict[str, str], List[str]]: The relationships of the node in the specified type format.
+        """
+        node_relationships = self.node_relationships[id_][in_out]
+        return self._typed_return(node_relationships, type=type)
+
+    def node_exist(self, node: Union[T, str]) -> bool:
+        """
+        Checks if a node exists in the structure.
+        
+        Args:
+            node (Union[T, str]): The node instance or node ID to check for existence.
+            
+        Returns:
+            bool: True if the node exists, False otherwise.
+        """
+
+        return node.id_ in self.nodes.keys()
+    
+    def relationship_exist(self, relationship: R) -> bool:
+        """
+        Checks if a relationship exists in the structure.
+        
+        Args:
+            relationship (R): The relationship instance to check for existence.
+            
+        Returns:
+            bool: True if the relationship exists, False otherwise.
+        """
+        return relationship.id_ in self.relationships.keys()
+        
+    def remove_node_relationships(self, relationship_dict: Dict[str, str], in_out: str) -> None:
+        """
+        Removes relationships of a node from the structure.
+        
+        Args:
+            relationship_dict (Dict[str, str]): A dictionary of relationship IDs to node IDs.
+            
+            in_out (str): 'in' to remove incoming relationships, 'out' to remove outgoing relationships.
+        """
+        for relationship_id, node_id in relationship_dict.items():
+            self.node_relationships[node_id][in_out].pop(relationship_id)
+            self.relationships.pop(relationship_id)
+
+    def remove_node(self, node: Union[T, str]) -> None:
+        """
+        Removes a node and its associated relationships from the structure.
+        
+        Args:
+            node (Union[T, str]): The node instance or node ID to be removed.
+        """
+        node_id = node if isinstance(node, str) else node.id_
+        out_ = self.get_node_relationships(node_id, 'out')
+        in_ = self.get_node_relationships(node_id, 'in')
+        
+        self.remove_node_relationships(out_, 'in')
+        self.remove_node_relationships(in_, 'out')
+        self.node_relationships.pop(node_id)
+
+    def remove_relationship(self, relationship: R) -> None:
+        """
+        Removes a relationship from the structure.
+        
+        Args:
+            relationship (R): The relationship instance to be removed.
+        """
+        id_, source_, target_ = (relationship.id_, 
+                                 relationship.source_node_id, 
+                                 relationship.target_node_id)
+        
+        self.node_relationships[source_]['out'].pop(id_)
+        self.node_relationships[target_]['in'].pop(id_)
+        self.relationships.pop(id_)
+