tiny-agent-os 0.0.1__py3-none-any.whl

tinyagent/cli/spinner.py

@@ -0,0 +1,94 @@
+"""
+Spinner animation for the tinyAgent CLI.
+
+This module provides a spinner animation for the CLI to indicate ongoing processes.
+The spinner is implemented as a context manager for ease of use.
+"""
+
+import sys
+import threading
+import time
+import itertools
+from typing import Optional, Iterator
+
+from .colors import Colors
+
+
+class Spinner:
+    """
+    A simple spinner animation for the CLI.
+    
+    This class provides a spinner animation that runs in a separate thread
+    and can be used to indicate that a process is running. It is implemented
+    as a context manager for ease of use with the 'with' statement.
+    
+    Attributes:
+        message: The message to display next to the spinner
+        running: Flag indicating if the spinner is running
+        spinner: Iterator of spinner characters
+        thread: Thread running the spinner animation
+    """
+    
+    def __init__(self, message: str = "Processing"):
+        """
+        Initialize the spinner with a message.
+        
+        Args:
+            message: The message to display next to the spinner
+        """
+        self.message = message
+        self.running = False
+        self.spinner: Iterator[str] = itertools.cycle(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'])
+        self.thread: Optional[threading.Thread] = None
+    
+    def spin(self) -> None:
+        """
+        Run the spinner animation.
+        
+        This method runs in a separate thread and updates the spinner character
+        at regular intervals. It continues until the running flag is set to False.
+        """
+        while self.running:
+            sys.stdout.write(
+                f"\r{Colors.LIGHT_RED}{next(self.spinner)} "
+                f"{Colors.OFF_WHITE}{self.message}{Colors.RESET}"
+            )
+            sys.stdout.flush()
+            time.sleep(0.1)
+            
+        # Clear the spinner when done
+        sys.stdout.write('\r' + ' ' * (len(self.message) + 2) + '\r')
+        sys.stdout.flush()
+    
+    def __enter__(self) -> 'Spinner':
+        """
+        Start the spinner when entering a context.
+        
+        Returns:
+            The Spinner instance
+        """
+        self.running = True
+        self.thread = threading.Thread(target=self.spin)
+        self.thread.start()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Stop the spinner when exiting a context."""
+        self.running = False
+        if self.thread:
+            self.thread.join()
+    
+    def update_message(self, message: str) -> None:
+        """
+        Update the spinner message while it's running.
+        
+        Args:
+            message: New message to display
+        """
+        self.message = message
+    
+    def stop(self) -> None:
+        """Stop the spinner manually (if not using as a context manager)."""
+        self.running = False
+        if self.thread:
+            self.thread.join()

tinyagent/cli.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+"""
+tinyAgent - A simple yet powerful framework for building LLM-powered agents.
+
+This is the main entry point for the tinyAgent framework. It provides access to 
+all the core components of the framework through a clean, simple API.
+"""
+
+# Load environment variables first
+from dotenv import load_dotenv
+load_dotenv() 
+
+from tinyagent import (
+    # Core components
+    Agent, get_llm, Tool, ParamType, tool,
+    
+    # Exception classes
+    TinyAgentError, ConfigurationError, 
+    ToolError, ToolNotFoundError, ToolExecutionError,
+    RateLimitExceeded, ParsingError, 
+    AgentRetryExceeded, OrchestratorError, AgentNotFoundError,
+    
+    # Factory components
+    AgentFactory, DynamicAgentFactory, Orchestrator, TaskStatus,
+    
+    # Utilities
+    configure_logging, get_logger, load_config, get_config_value,
+    Colors, Spinner, CLI, run_chat_mode,
+    
+    # Version
+    __version__
+)
+
+# Built-in tools
+from tinyagent.tools import (
+    anon_coder_tool,
+    llm_serializer_tool,
+    brave_web_search_tool,
+    ripgrep_tool,
+    aider_tool,
+    load_external_tools
+)
+
+# Run CLI if executed directly
+if __name__ == "__main__":
+    # Call the core CLI implementation
+    CLI()

tinyagent/config/__init__.py

@@ -0,0 +1,14 @@
+"""
+Configuration management for the tinyAgent framework.
+
+This package provides utilities for loading, validating, and accessing
+configuration settings from different sources (files, environment variables, etc.).
+"""
+
+from .config import load_config, get_config_value, TinyAgentConfig
+
+__all__ = [
+    'load_config',
+    'get_config_value',
+    'TinyAgentConfig',
+]

tinyagent/config/config.py

@@ -0,0 +1,258 @@
+"""
+Configuration management for the tinyAgent framework.
+
+This module provides functions for loading, validating, and accessing configuration
+settings from different sources (files, environment variables, etc.).
+"""
+
+import os
+import yaml
+from typing import Dict, Any, Optional, TypedDict, Union, cast, List
+from dataclasses import dataclass, field
+
+from ..exceptions import ConfigurationError
+from ..logging import get_logger
+
+# Set up logger
+logger = get_logger(__name__)
+
+
+class ParsingConfig(TypedDict, total=False):
+    """Configuration for response parsing."""
+    strict_json: bool
+    fallback_parsers: Dict[str, bool]
+
+
+class ModelConfig(TypedDict, total=False):
+    """Configuration for models."""
+    default: str
+
+
+class RetriesConfig(TypedDict, total=False):
+    """Configuration for retry behavior."""
+    max_attempts: int
+
+
+class RateLimitConfig(TypedDict, total=False):
+    """Configuration for rate limiting."""
+    global_limit: int
+    tool_limits: Dict[str, int]
+
+
+class LoggingConfig(TypedDict, total=False):
+    """Configuration for logging."""
+    level: str  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    format: str  # Python logging format string
+    handlers: List[str]  # List of enabled handlers (console, file, etc)
+
+
+class AgentConfig(TypedDict, total=False):
+    """Configuration for agent behavior."""
+    max_steps: int  # Maximum number of steps per research phase
+    debug_level: int  # Debug level (0-2)
+    default_model: str  # Default model to use
+
+
+class APIConfig(TypedDict, total=False):
+    """Configuration for API behavior."""
+    enable_docs: bool
+    cors_origins: List[str]
+    port: int
+
+class TinyAgentConfig(TypedDict, total=False):
+    """Top-level configuration structure."""
+    parsing: ParsingConfig
+    model: ModelConfig
+    retries: RetriesConfig
+    rate_limits: RateLimitConfig
+    logging: LoggingConfig
+    agent: AgentConfig
+    api: APIConfig
+
+
+# Default configuration
+DEFAULT_CONFIG: TinyAgentConfig = {
+    "api": {
+        "app_name": "tinyAgent API",
+        "enable_docs": True,
+        "cors_origins": ["*"],
+        "port": 9000,
+        "chat_tool": "default_chat"
+    },
+    "parsing": {
+        "strict_json": False,
+        "fallback_parsers": {
+            "template": True,
+            "regex": True
+        }
+    },
+    "model": {
+        "default": "qwen/qwq-32B"
+    },
+    "retries": {
+        "max_attempts": 3
+    },
+    "rate_limits": {
+        "global_limit": 30,
+        "tool_limits": {}
+    },
+    "logging": {
+        "level": "INFO",  # Default to INFO to see configuration details
+        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        "handlers": ["console"]  # Default to console output
+    },
+    "agent": {
+        "max_steps": 2,  # Default to 2 steps per phase
+        "debug_level": 0,  # Default to no debug output
+        "default_model": "deepseek/deepseek-r1"  # Default model
+    }
+}
+
+
+def load_config(config_path: Optional[str] = None) -> TinyAgentConfig:
+    """
+    Load configuration from YAML file, with fallback to default values.
+    
+    This function attempts to load configuration from a YAML file. If the file
+    doesn't exist or there's an error loading it, it falls back to default values.
+    
+    Args:
+        config_path: Path to config.yml file. If None, uses config.yml from project root.
+        
+    Returns:
+        Dict containing configuration values
+        
+    Raises:
+        ConfigurationError: If there's an error with the configuration format
+    """
+    # 1. Check environment variable override
+    env_config = os.getenv("TINYAGENT_CONFIG")
+    if env_config and os.path.isfile(env_config):
+        config_path = env_config
+    else:
+        # 2. If no explicit path, check current working directory
+        if config_path is None:
+            cwd_config = os.path.join(os.getcwd(), 'config.yml')
+            if os.path.isfile(cwd_config):
+                config_path = cwd_config
+            else:
+                # 3. Fallback to package root
+                project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+                config_path = os.path.join(project_root, 'config.yml')
+        elif not os.path.isabs(config_path):
+            # If relative path provided, make it relative to project root
+            project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+            config_path = os.path.join(project_root, config_path)
+    
+    config = cast(TinyAgentConfig, DEFAULT_CONFIG.copy())
+    
+    try:
+        if os.path.exists(config_path):
+            with open(config_path, 'r', encoding='utf-8') as file:
+                yaml_config = yaml.safe_load(file)
+                
+                if yaml_config:
+                    # Validate the config
+                    if not isinstance(yaml_config, dict):
+                        raise ConfigurationError("Configuration must be a dictionary")
+                    
+                    # Update config with values from YAML
+                    _update_nested_dict(config, yaml_config)
+                    logger.info(f"Configuration loaded from {config_path}")
+                else:
+                    logger.warning(f"Empty configuration file: {config_path}")
+        else:
+            logger.info(f"Configuration file not found at {config_path}, using defaults")
+    except yaml.YAMLError as e:
+        logger.error(f"Error parsing YAML configuration: {str(e)}")
+        raise ConfigurationError(f"Invalid YAML in configuration file: {e}")
+    except Exception as e:
+        logger.error(f"Error loading configuration: {str(e)}")
+        logger.info("Using default configuration")
+    
+    return config
+
+
+def _update_nested_dict(base_dict: Dict[str, Any], update_dict: Dict[str, Any]) -> None:
+    """
+    Update a nested dictionary with values from another dictionary.
+    
+    This function recursively updates a nested dictionary with values from another
+    dictionary, preserving the structure of the base dictionary.
+    
+    Args:
+        base_dict: The dictionary to update
+        update_dict: The dictionary with new values
+    """
+    for key, value in update_dict.items():
+        if key in base_dict and isinstance(base_dict[key], dict) and isinstance(value, dict):
+            _update_nested_dict(base_dict[key], value)
+        else:
+            base_dict[key] = value
+
+
+def get_config_value(config: Dict[str, Any], key_path: str, default: Any = None) -> Any:
+    """
+    Get a value from the config using a dot-notation path.
+    
+    This function retrieves a value from a nested dictionary using a dot-notation
+    path. If the key doesn't exist, it returns the default value.
+    
+    Args:
+        config: The configuration dictionary
+        key_path: Dot-notation path to the desired value (e.g., 'parsing.strict_json')
+        default: Value to return if the key is not found
+        
+    Returns:
+        The configuration value or default if not found
+        
+    Examples:
+        >>> config = {"parsing": {"strict_json": True}}
+        >>> get_config_value(config, "parsing.strict_json")
+        True
+        >>> get_config_value(config, "parsing.unknown", False)
+        False
+    """
+    keys = key_path.split('.')
+    current = config
+    
+    for key in keys:
+        if isinstance(current, dict) and key in current:
+            current = current[key]
+        else:
+            return default
+    
+    return current
+
+
+def validate_config(config: TinyAgentConfig) -> None:
+    """
+    Validate the configuration to ensure it matches the expected format.
+    
+    Args:
+        config: The configuration to validate
+        
+    Raises:
+        ConfigurationError: If the configuration is invalid
+    """
+    # Validate model.default
+    if "model" in config and "default" in config["model"]:
+        if not isinstance(config["model"]["default"], str):
+            raise ConfigurationError("model.default must be a string")
+    
+    # Validate retries.max_attempts
+    if "retries" in config and "max_attempts" in config["retries"]:
+        if not isinstance(config["retries"]["max_attempts"], int):
+            raise ConfigurationError("retries.max_attempts must be an integer")
+        if config["retries"]["max_attempts"] < 1:
+            raise ConfigurationError("retries.max_attempts must be at least 1")
+    
+    # Validate parsing.strict_json
+    if "parsing" in config and "strict_json" in config["parsing"]:
+        if not isinstance(config["parsing"]["strict_json"], bool):
+            raise ConfigurationError("parsing.strict_json must be a boolean")
+    
+    # Validate rate_limits.global_limit
+    if "rate_limits" in config and "global_limit" in config["rate_limits"]:
+        if not isinstance(config["rate_limits"]["global_limit"], int):
+            raise ConfigurationError("rate_limits.global_limit must be an integer")

tinyagent/decorators.py

@@ -0,0 +1,187 @@
+"""
+Decorator functions for the tinyAgent framework.
+
+This module provides decorators used throughout the tinyAgent framework,
+particularly the `tool` decorator for transforming functions into Tool instances.
+"""
+
+import functools
+import inspect
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Union, cast, overload
+
+from .tool import Tool, ParamType
+
+
+# Type variables for better type annotations
+F = TypeVar('F', bound=Callable[..., Any])  # Function type
+T = TypeVar('T')  # Generic return type
+
+
+@overload
+def tool(func: F) -> F:
+    """Tool decorator usage without arguments."""
+    ...
+
+
+@overload
+def tool(
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    rate_limit: Optional[int] = None,
+    retry_limit: Optional[int] = None
+) -> Callable[[F], F]:
+    """Tool decorator usage with arguments."""
+    ...
+
+
+def tool(
+    name=None,
+    description=None,
+    rate_limit=None,
+    retry_limit=None
+):
+    """
+    Decorator to transform a function into a tool with optional rate limiting.
+    
+    This decorator provides a more intuitive and developer-friendly way to define tools.
+    Simply decorating a function transforms it into a registered tool.
+    
+    Args:
+        name: Optional name for the tool (defaults to function name)
+        description: Optional description for the tool (defaults to function docstring)
+        rate_limit: Optional rate limit for the tool (max number of calls allowed)
+        retry_limit: Optional retry limit for the tool (max retries on failure)
+        
+    Returns:
+        The decorated function wrapped as a tool with rate limiting
+        
+    Example:
+        @tool
+        def calculate_sum(a: int, b: int) -> int:
+            '''Calculate the sum of two integers.'''
+            return a + b
+        
+        @tool(rate_limit=5)
+        def rate_limited_api(query: str) -> str:
+            '''Make an API call with max 5 calls per session.'''
+            return make_api_call(query)
+    """
+    # Handle case where decorator is used without parentheses
+    if callable(name):
+        func = name
+        name = None
+        return _create_tool_wrapper(func, None, None, None, None)
+    
+    # Handle case where decorator is used with parameters
+    def decorator(func):
+        return _create_tool_wrapper(func, name, description, rate_limit, retry_limit)
+    
+    return decorator
+
+
+def _create_tool_wrapper(
+    func: F, 
+    name: Optional[str], 
+    description: Optional[str], 
+    rate_limit: Optional[int], 
+    retry_limit: Optional[int]
+) -> F:
+    """
+    Internal function to create a tool wrapper for a given function.
+    
+    Args:
+        func: The function to wrap as a tool
+        name: Optional name for the tool
+        description: Optional description for the tool
+        rate_limit: Optional rate limit for the tool
+        retry_limit: Optional retry limit for the tool
+        
+    Returns:
+        The wrapped function
+    """
+    # Get function signature and metadata
+    sig = inspect.signature(func)
+    
+    # Set tool name and description
+    tool_name = name or func.__name__.lower()
+    tool_description = description or func.__doc__ or f"Tool for {func.__name__}"
+    
+    # If rate limit specified, add it to description
+    if rate_limit is not None:
+        tool_description = f"{tool_description} (Limited to {rate_limit} calls per session)"
+    
+    # Convert Python type hints to ParamType
+    parameters = {}
+    for param_name, param in sig.parameters.items():
+        if param_name in ('self', 'cls'):
+            continue
+            
+        # Map Python types to ParamType
+        if param.annotation == int:
+            param_type = ParamType.INTEGER
+        elif param.annotation == float:
+            param_type = ParamType.FLOAT
+        elif param.annotation == str:
+            param_type = ParamType.STRING
+        else:
+            param_type = ParamType.ANY
+            
+        parameters[param_name] = param_type
+    
+    # Create tool instance with rate limiting
+    tool_instance = Tool(
+        name=tool_name,
+        description=tool_description,
+        parameters=parameters,
+        func=func,
+        rate_limit=rate_limit
+    )
+    
+    # Add retry limit if specified
+    if retry_limit is not None:
+        tool_instance.retry_limit = retry_limit
+    
+    # Add the tool instance as an attribute to the function
+    func._tool = tool_instance
+    
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # Convert positional arguments to keyword arguments if needed
+        if args and len(args) > 0:
+            sig = inspect.signature(func)
+            param_names = list(sig.parameters.keys())
+            # Skip self/cls if this is a method
+            if param_names and param_names[0] in ('self', 'cls') and len(args) > 0:
+                kwargs[param_names[1]] = args[0]
+                for i, arg in enumerate(args[1:], start=2):
+                    if i < len(param_names):
+                        kwargs[param_names[i]] = arg
+            else:
+                # Not a method
+                for i, arg in enumerate(args):
+                    if i < len(param_names):
+                        kwargs[param_names[i]] = arg
+        
+        # Filter out parameters that are not part of the function signature
+        # This prevents errors with unwanted parameters being passed
+        sig = inspect.signature(func)
+        valid_params = set(sig.parameters.keys())
+        
+        # Check if the function accepts **kwargs
+        accepts_kwargs = any(
+            param.kind == inspect.Parameter.VAR_KEYWORD 
+            for param in sig.parameters.values()
+        )
+        
+        # If function doesn't accept **kwargs, filter out invalid parameters
+        if not accepts_kwargs:
+            filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
+        else:
+            filtered_kwargs = kwargs  # Keep all parameters if the function accepts **kwargs
+        
+        # Use the tool instance directly to ensure rate limiting is applied
+        return tool_instance(**filtered_kwargs)
+        
+    wrapper._tool = tool_instance
+    
+    return cast(F, wrapper)

tinyagent/exceptions.py

@@ -0,0 +1,85 @@
+"""
+Exceptions for the tinyAgent framework.
+
+This module contains custom exceptions used throughout the tinyAgent framework.
+"""
+
+from typing import List, Dict, Any, Optional
+
+
+class AgentRetryExceeded(Exception):
+    """Exception raised when agent exceeds max retry attempts."""
+    def __init__(self, message, history=None):
+        self.message = message
+        self.history = history or []
+        super().__init__(message)
+
+
+class TinyAgentError(Exception):
+    """Base class for all tinyAgent exceptions."""
+    pass
+
+
+class ConfigurationError(TinyAgentError):
+    """Exception raised for configuration-related errors."""
+    pass
+
+
+class ToolError(TinyAgentError):
+    """Base class for tool-related errors."""
+    pass
+
+
+class ToolNotFoundError(ToolError):
+    """Exception raised when a requested tool is not found."""
+    def __init__(self, tool_name: str, available_tools: Optional[List[str]] = None):
+        self.tool_name = tool_name
+        self.available_tools = available_tools or []
+        message = f"Tool '{tool_name}' not found"
+        if available_tools:
+            message += f". Available tools: {', '.join(available_tools)}"
+        super().__init__(message)
+
+
+class ToolExecutionError(ToolError):
+    """Exception raised when a tool execution fails."""
+    def __init__(self, tool_name: str, args: Dict[str, Any], error_message: str):
+        self.tool_name = tool_name
+        self.args = args
+        self.error_message = error_message
+        super().__init__(f"Error executing tool {tool_name}: {error_message}")
+
+
+class RateLimitExceeded(ToolError):
+    """Exception raised when a tool's rate limit is exceeded."""
+    def __init__(self, tool_name: str, limit: int):
+        self.tool_name = tool_name
+        self.limit = limit
+        super().__init__(f"Rate limit exceeded for tool '{tool_name}'. Maximum: {limit} calls")
+
+
+class ParsingError(TinyAgentError):
+    """Exception raised when parsing LLM responses fails."""
+    def __init__(self, content: str, details: str = None):
+        self.content = content
+        self.details = details
+        message = "Failed to parse LLM response"
+        if details:
+            message += f": {details}"
+        super().__init__(message)
+
+
+class OrchestratorError(TinyAgentError):
+    """Exception raised for orchestrator-related errors."""
+    pass
+
+
+class AgentNotFoundError(OrchestratorError):
+    """Exception raised when a requested agent is not found."""
+    def __init__(self, agent_id: str, available_agents: Optional[List[str]] = None):
+        self.agent_id = agent_id
+        self.available_agents = available_agents or []
+        message = f"Agent '{agent_id}' not found"
+        if available_agents:
+            message += f". Available agents: {', '.join(available_agents)}"
+        super().__init__(message)