sandboxy 0.0.1__py3-none-any.whl

sandboxy/__init__.py

@@ -0,0 +1,3 @@
+"""Sandboxy - Open-source agent simulation and benchmarking platform."""
+
+__version__ = "0.1.0"

sandboxy/agents/__init__.py

@@ -0,0 +1,21 @@
+"""Agents module - Agent interface, loader, and implementations."""
+
+from sandboxy.agents.base import Agent, AgentAction, AgentConfig, AgentKind, BaseAgent
+from sandboxy.agents.llm_prompt import LlmPromptAgent
+from sandboxy.agents.loader import (
+    AgentLoader,
+    create_agent_from_config,
+    create_agent_from_model,
+)
+
+__all__ = [
+    "Agent",
+    "AgentAction",
+    "AgentConfig",
+    "AgentKind",
+    "AgentLoader",
+    "BaseAgent",
+    "LlmPromptAgent",
+    "create_agent_from_config",
+    "create_agent_from_model",
+]

sandboxy/agents/base.py

@@ -0,0 +1,66 @@
+"""Base agent interface and models."""
+
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, Field
+
+from sandboxy.core.state import Message
+
+AgentKind = Literal["llm-prompt", "python-module", "http-endpoint"]
+
+
+class AgentConfig(BaseModel):
+    """Configuration for an agent."""
+
+    id: str
+    name: str
+    kind: AgentKind
+    model: str = ""
+    system_prompt: str = ""
+    tools: list[str] = Field(default_factory=list)
+    params: dict[str, Any] = Field(default_factory=dict)
+    impl: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentAction(BaseModel):
+    """Action returned by an agent after processing."""
+
+    type: Literal["message", "tool_call", "stop"]
+    content: str | None = None
+    tool_name: str | None = None
+    tool_action: str | None = None
+    tool_args: dict[str, Any] | None = None
+    tool_call_id: str | None = None
+
+
+class Agent(Protocol):
+    """Protocol for agent implementations."""
+
+    config: AgentConfig
+
+    def step(
+        self, history: list[Message], available_tools: list[dict[str, Any]] | None = None
+    ) -> AgentAction:
+        """Process conversation history and return next action.
+
+        Args:
+            history: Conversation history as list of messages.
+            available_tools: Optional list of available tool schemas for function calling.
+
+        Returns:
+            Next action to take (message, tool call, or stop).
+        """
+        ...
+
+
+class BaseAgent:
+    """Base class for agent implementations."""
+
+    def __init__(self, config: AgentConfig) -> None:
+        self.config = config
+
+    def step(
+        self, history: list[Message], available_tools: list[dict[str, Any]] | None = None
+    ) -> AgentAction:
+        """Process history and return action. Override in subclasses."""
+        return AgentAction(type="stop")

sandboxy/agents/llm_prompt.py

@@ -0,0 +1,308 @@
+"""LLM-based prompt agent using OpenAI SDK."""
+
+import json
+import logging
+import os
+import time
+from typing import Any
+
+from sandboxy.agents.base import AgentAction, AgentConfig, BaseAgent
+from sandboxy.core.state import Message
+
+logger = logging.getLogger(__name__)
+
+# Retry configuration
+MAX_RETRIES = 3
+RETRY_DELAY_BASE = 1.0  # seconds
+
+
+class LlmPromptAgent(BaseAgent):
+    """Agent that uses an LLM via OpenAI-compatible API.
+
+    Supports both direct OpenAI and OpenRouter (for 400+ models).
+    Uses OpenRouter when model contains "/" (e.g., "openai/gpt-4o").
+    """
+
+    def __init__(self, config: AgentConfig) -> None:
+        """Initialize the agent.
+
+        Args:
+            config: Agent configuration.
+        """
+        super().__init__(config)
+        self._client: Any = None
+        self._is_openrouter = "/" in (config.model or "")
+        # Token usage tracking
+        self._total_input_tokens = 0
+        self._total_output_tokens = 0
+
+    @property
+    def api_key(self) -> str:
+        """Get the appropriate API key based on model type."""
+        if self._is_openrouter:
+            return os.getenv("OPENROUTER_API_KEY", "")
+        return os.getenv("OPENAI_API_KEY", "")
+
+    @property
+    def client(self) -> Any:
+        """Lazy-load OpenAI client with appropriate configuration."""
+        if self._client is None:
+            from openai import OpenAI
+
+            if self._is_openrouter:
+                logger.debug("Initializing OpenRouter client for model: %s", self.config.model)
+                self._client = OpenAI(
+                    api_key=self.api_key,
+                    base_url="https://openrouter.ai/api/v1",
+                )
+            else:
+                logger.debug("Initializing OpenAI client for model: %s", self.config.model)
+                self._client = OpenAI(api_key=self.api_key)
+        return self._client
+
+    def step(
+        self,
+        history: list[Message],
+        available_tools: list[dict[str, Any]] | None = None,
+    ) -> AgentAction:
+        """Process conversation and return next action using LLM."""
+        if not self.api_key:
+            return self._stub_response(history)
+
+        messages = self._build_messages(history)
+        tools = self._build_tools(available_tools) if available_tools else None
+
+        last_error = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = self._call_api(messages, tools)
+                return self._parse_response(response)
+            except Exception as e:
+                last_error = e
+                is_retryable = self._is_retryable_error(e)
+
+                if is_retryable and attempt < MAX_RETRIES - 1:
+                    delay = RETRY_DELAY_BASE * (2**attempt)
+                    logger.warning(
+                        "LLM call failed (attempt %d/%d), retrying in %.1fs: %s",
+                        attempt + 1,
+                        MAX_RETRIES,
+                        delay,
+                        e,
+                    )
+                    time.sleep(delay)
+                else:
+                    logger.error("Error calling LLM: %s", e, exc_info=True)
+                    break
+
+        return AgentAction(
+            type="message",
+            content=f"Error calling LLM: {last_error}",
+        )
+
+    def _is_retryable_error(self, error: Exception) -> bool:
+        """Check if an error is retryable."""
+        error_str = str(error).lower()
+        retryable_patterns = [
+            "rate limit",
+            "timeout",
+            "connection",
+            "503",
+            "502",
+            "500",
+            "overloaded",
+        ]
+        return any(pattern in error_str for pattern in retryable_patterns)
+
+    def _build_messages(self, history: list[Message]) -> list[dict[str, Any]]:
+        """Convert history to OpenAI message format."""
+        messages: list[dict[str, Any]] = []
+
+        if self.config.system_prompt:
+            messages.append(
+                {
+                    "role": "system",
+                    "content": self.config.system_prompt,
+                }
+            )
+
+        for msg in history:
+            if msg.role == "tool":
+                messages.append(
+                    {
+                        "role": "tool",
+                        "content": msg.content,
+                        "tool_call_id": msg.tool_call_id or msg.tool_name or "unknown",
+                    }
+                )
+            elif msg.role == "assistant" and msg.tool_calls:
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": msg.content or None,
+                        "tool_calls": [
+                            {
+                                "id": tc.id,
+                                "type": "function",
+                                "function": {
+                                    "name": tc.name,
+                                    "arguments": tc.arguments,
+                                },
+                            }
+                            for tc in msg.tool_calls
+                        ],
+                    }
+                )
+            else:
+                messages.append(
+                    {
+                        "role": msg.role,
+                        "content": msg.content,
+                    }
+                )
+
+        return messages
+
+    def _build_tools(self, available_tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Build OpenAI tools format from available tools."""
+        tools = []
+        for tool in available_tools:
+            actions = tool.get("actions", [])
+            for action in actions:
+                tools.append(
+                    {
+                        "type": "function",
+                        "function": {
+                            "name": f"{tool['name']}__{action['name']}",
+                            "description": action.get("description", ""),
+                            "parameters": action.get(
+                                "parameters", {"type": "object", "properties": {}}
+                            ),
+                        },
+                    }
+                )
+        return tools
+
+    def _call_api(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None,
+    ) -> Any:
+        """Make API call to OpenAI/OpenRouter."""
+        model = self.config.model or "gpt-4o-mini"
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+        }
+
+        # Add temperature (some models don't support it)
+        if "nano" not in model.lower():
+            kwargs["temperature"] = self.config.params.get("temperature", 0.7)
+
+        # Add max tokens
+        max_tokens = self.config.params.get("max_tokens", 2048)
+        kwargs["max_completion_tokens"] = max_tokens
+
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "auto"
+
+        return self.client.chat.completions.create(**kwargs)
+
+    def _parse_response(self, response: Any) -> AgentAction:
+        """Parse OpenAI response into AgentAction."""
+        # Track token usage
+        if hasattr(response, "usage") and response.usage:
+            self._total_input_tokens += getattr(response.usage, "prompt_tokens", 0)
+            self._total_output_tokens += getattr(response.usage, "completion_tokens", 0)
+
+        choice = response.choices[0]
+        message = choice.message
+
+        if message.tool_calls:
+            tool_call = message.tool_calls[0]
+            function = tool_call.function
+
+            full_name = function.name
+            if "__" in full_name:
+                tool_name, tool_action = full_name.split("__", 1)
+            else:
+                parts = full_name.rsplit("_", 1)
+                if len(parts) == 2:
+                    tool_name, tool_action = parts
+                else:
+                    tool_name = full_name
+                    tool_action = "invoke"
+
+            try:
+                tool_args = json.loads(function.arguments)
+            except json.JSONDecodeError:
+                tool_args = {}
+
+            return AgentAction(
+                type="tool_call",
+                tool_name=tool_name,
+                tool_action=tool_action,
+                tool_args=tool_args,
+                tool_call_id=tool_call.id,
+            )
+
+        if choice.finish_reason == "stop" and not message.content:
+            return AgentAction(type="stop")
+
+        return AgentAction(
+            type="message",
+            content=message.content or "",
+        )
+
+    def get_usage(self) -> dict[str, int]:
+        """Get accumulated token usage across all API calls.
+
+        Returns:
+            Dictionary with input_tokens and output_tokens counts.
+        """
+        return {
+            "input_tokens": self._total_input_tokens,
+            "output_tokens": self._total_output_tokens,
+        }
+
+    def reset_usage(self) -> None:
+        """Reset token usage counters."""
+        self._total_input_tokens = 0
+        self._total_output_tokens = 0
+
+    def _stub_response(self, history: list[Message]) -> AgentAction:
+        """Return stub response when no API key is configured."""
+        last_user = next(
+            (m for m in reversed(history) if m.role == "user"),
+            None,
+        )
+
+        if last_user:
+            content = last_user.content.lower()
+            if "refund" in content:
+                return AgentAction(
+                    type="message",
+                    content=(
+                        "I understand you're inquiring about a refund. "
+                        "Let me look into that for you. Could you please "
+                        "provide your order number?"
+                    ),
+                )
+            if "order" in content:
+                return AgentAction(
+                    type="message",
+                    content=(
+                        "I'd be happy to help you with your order. "
+                        "What would you like to know about it?"
+                    ),
+                )
+
+        key_name = "OPENROUTER_API_KEY" if self._is_openrouter else "OPENAI_API_KEY"
+        return AgentAction(
+            type="message",
+            content=(
+                f"[STUB] No API key configured. "
+                f"Set {key_name} environment variable to enable LLM calls."
+            ),
+        )

sandboxy/agents/loader.py

@@ -0,0 +1,222 @@
+"""Agent loader - loads agent configurations and instantiates agents."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from sandboxy.agents.base import Agent, AgentConfig
+from sandboxy.agents.llm_prompt import LlmPromptAgent
+
+logger = logging.getLogger(__name__)
+
+# Default directories to search for agent specs (user's directories only)
+DEFAULT_AGENT_DIRS = [
+    Path.home() / ".sandboxy" / "agents",
+]
+
+
+def get_agent_dirs() -> list[Path]:
+    """Get agent directories, including local if in local mode.
+
+    Returns:
+        List of directories to search for agents.
+    """
+    from sandboxy.local.context import get_local_context, is_local_mode
+
+    dirs: list[Path] = []
+
+    if is_local_mode():
+        ctx = get_local_context()
+        if ctx and ctx.agents_dir.exists():
+            dirs.append(ctx.agents_dir)
+
+    dirs.extend(DEFAULT_AGENT_DIRS)
+    return dirs
+
+
+class AgentLoader:
+    """Loader for agent configurations and instantiation."""
+
+    def __init__(self, dirs: list[Path] | None = None) -> None:
+        """Initialize loader with directories to search.
+
+        Args:
+            dirs: Directories to search for agent specs. Uses defaults if None.
+        """
+        self.dirs = dirs if dirs is not None else DEFAULT_AGENT_DIRS
+        self._configs: dict[str, AgentConfig] = {}
+        self._load_configs()
+
+    def _load_configs(self) -> None:
+        """Load all agent configurations from directories."""
+        for d in self.dirs:
+            if not d.exists():
+                continue
+
+            for path in d.glob("**/*.yaml"):
+                self._load_config_file(path)
+            for path in d.glob("**/*.yml"):
+                self._load_config_file(path)
+
+    def _load_config_file(self, path: Path) -> None:
+        """Load a single agent configuration file."""
+        try:
+            raw: dict[str, Any] = yaml.safe_load(path.read_text())
+            if not raw or "id" not in raw:
+                logger.debug("Skipping %s: missing 'id' field", path)
+                return
+
+            config = AgentConfig(
+                id=raw["id"],
+                name=raw.get("name", raw["id"]),
+                kind=raw.get("kind", "llm-prompt"),
+                model=raw.get("model", ""),
+                system_prompt=raw.get("system_prompt", ""),
+                tools=raw.get("tools", []),
+                params=raw.get("params", {}),
+                impl=raw.get("impl", {}),
+            )
+            self._configs[config.id] = config
+            logger.debug("Loaded agent config: %s from %s", config.id, path)
+        except yaml.YAMLError as e:
+            logger.warning("Failed to parse YAML file %s: %s", path, e)
+        except KeyError as e:
+            logger.warning("Missing required field in %s: %s", path, e)
+
+    def list_ids(self) -> list[str]:
+        """Get list of available agent IDs.
+
+        Returns:
+            List of agent IDs.
+        """
+        return list(self._configs.keys())
+
+    def get_config(self, agent_id: str) -> AgentConfig | None:
+        """Get agent configuration by ID.
+
+        Args:
+            agent_id: Agent identifier.
+
+        Returns:
+            Agent configuration or None if not found.
+        """
+        return self._configs.get(agent_id)
+
+    def load(self, agent_id: str) -> Agent:
+        """Load and instantiate an agent by ID.
+
+        Args:
+            agent_id: Agent identifier. Can be either:
+                - A predefined agent ID from user's YAML files
+                - A model ID (e.g., "openai/gpt-4o", "anthropic/claude-3.5-haiku")
+
+        Returns:
+            Instantiated agent.
+
+        Raises:
+            ValueError: If agent ID not found.
+        """
+        config = self._configs.get(agent_id)
+        if config is None:
+            # Check if it's a model ID (contains a /)
+            if "/" in agent_id:
+                # Create a dynamic agent config for this model
+                config = AgentConfig(
+                    id=agent_id,
+                    name=agent_id.split("/")[-1].replace("-", " ").title(),
+                    kind="llm-prompt",
+                    model=agent_id,
+                    system_prompt="You are a helpful assistant. Use the available tools to complete tasks.",
+                    tools=[],
+                    params={"temperature": 0.7, "max_tokens": 2048},
+                    impl={},
+                )
+            else:
+                msg = f"Agent not found: {agent_id}"
+                raise ValueError(msg)
+        return self._instantiate(config)
+
+    def load_default(self) -> Agent:
+        """Load the default agent.
+
+        Returns:
+            Default agent instance.
+
+        Raises:
+            ValueError: If no agents are available and no model specified.
+        """
+        # Use any available agent from user's config
+        if self._configs:
+            config = next(iter(self._configs.values()))
+            return self._instantiate(config)
+
+        raise ValueError("No agents available. Specify a model with -m (e.g., -m openai/gpt-4o)")
+
+    def _instantiate(self, config: AgentConfig) -> Agent:
+        """Create agent instance from configuration.
+
+        Args:
+            config: Agent configuration.
+
+        Returns:
+            Agent instance.
+
+        Raises:
+            ValueError: If agent kind is not supported.
+        """
+        return _instantiate_agent(config)
+
+
+def _instantiate_agent(config: AgentConfig) -> Agent:
+    """Create agent instance from configuration.
+
+    Args:
+        config: Agent configuration.
+
+    Returns:
+        Agent instance.
+
+    Raises:
+        ValueError: If agent kind is not supported.
+    """
+    if config.kind == "llm-prompt":
+        return LlmPromptAgent(config)
+    msg = f"Unsupported agent kind: {config.kind}"
+    raise ValueError(msg)
+
+
+def create_agent_from_config(config: AgentConfig) -> Agent:
+    """Create an agent instance directly from configuration.
+
+    Args:
+        config: Agent configuration.
+
+    Returns:
+        Agent instance.
+    """
+    return _instantiate_agent(config)
+
+
+def create_agent_from_model(model_id: str, system_prompt: str = "") -> Agent:
+    """Create an agent directly from a model ID.
+
+    Args:
+        model_id: Model identifier (e.g., "openai/gpt-4o", "anthropic/claude-3.5-sonnet")
+        system_prompt: Optional system prompt override.
+
+    Returns:
+        Agent instance configured for the model.
+    """
+    config = AgentConfig(
+        id=model_id,
+        name=model_id.split("/")[-1].replace("-", " ").title() if "/" in model_id else model_id,
+        kind="llm-prompt",
+        model=model_id,
+        system_prompt=system_prompt or "You are a helpful assistant.",
+        tools=[],
+        params={"temperature": 0.7, "max_tokens": 4096},
+        impl={},
+    )
+    return _instantiate_agent(config)

sandboxy/api/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI application for Sandboxy."""
+
+from sandboxy.api.app import create_local_app
+
+__all__ = ["create_local_app"]