supyagent 0.1.0__py3-none-any.whl

supyagent/core/session_manager.py

@@ -0,0 +1,233 @@
+"""
+Session manager for persistent conversation storage.
+
+Sessions are stored as JSONL files with the following format:
+- First line: Session metadata with type="meta"
+- Subsequent lines: Messages in chronological order
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from supyagent.models.session import Message, Session, SessionMeta
+
+
+class SessionManager:
+    """
+    Manages session persistence using JSONL files.
+
+    Directory structure:
+        .supyagent/sessions/<agent>/<session_id>.jsonl
+        .supyagent/sessions/<agent>/current.json
+    """
+
+    def __init__(self, base_dir: Path | None = None):
+        """
+        Initialize the session manager.
+
+        Args:
+            base_dir: Base directory for session storage (default: .supyagent/sessions)
+        """
+        if base_dir is None:
+            base_dir = Path(".supyagent/sessions")
+        self.base_dir = base_dir
+
+    def _agent_dir(self, agent: str) -> Path:
+        """Get the directory for an agent's sessions, creating if needed."""
+        path = self.base_dir / agent
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def _session_path(self, agent: str, session_id: str) -> Path:
+        """Get the path to a session file."""
+        return self._agent_dir(agent) / f"{session_id}.jsonl"
+
+    def _current_path(self, agent: str) -> Path:
+        """Get the path to the current session pointer file."""
+        return self._agent_dir(agent) / "current.json"
+
+    def create_session(self, agent: str, model: str) -> Session:
+        """
+        Create a new session for an agent.
+
+        Args:
+            agent: Agent name
+            model: Model being used
+
+        Returns:
+            The newly created session
+        """
+        meta = SessionMeta(agent=agent, model=model)
+        session = Session(meta=meta)
+        self._save_session(session)
+        self._set_current(agent, meta.session_id)
+        return session
+
+    def load_session(self, agent: str, session_id: str) -> Session | None:
+        """
+        Load a session from disk.
+
+        Args:
+            agent: Agent name
+            session_id: Session ID to load
+
+        Returns:
+            The loaded session, or None if not found
+        """
+        path = self._session_path(agent, session_id)
+        if not path.exists():
+            return None
+
+        messages: list[Message] = []
+        meta: SessionMeta | None = None
+
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+
+                data = json.loads(line)
+
+                if data.get("type") == "meta":
+                    # Remove the type field before parsing as SessionMeta
+                    data.pop("type")
+                    meta = SessionMeta(**data)
+                else:
+                    messages.append(Message(**data))
+
+        if meta is None:
+            return None
+
+        return Session(meta=meta, messages=messages)
+
+    def get_current_session(self, agent: str) -> Session | None:
+        """
+        Get the current active session for an agent.
+
+        Args:
+            agent: Agent name
+
+        Returns:
+            The current session, or None if no current session
+        """
+        current_path = self._current_path(agent)
+        if not current_path.exists():
+            return None
+
+        with open(current_path) as f:
+            data = json.load(f)
+
+        return self.load_session(agent, data["session_id"])
+
+    def _set_current(self, agent: str, session_id: str) -> None:
+        """Set the current session for an agent."""
+        with open(self._current_path(agent), "w") as f:
+            json.dump({"session_id": session_id}, f)
+
+    def append_message(self, session: Session, message: Message) -> None:
+        """
+        Append a message to a session and persist it.
+
+        Args:
+            session: The session to append to
+            message: The message to append
+        """
+        session.messages.append(message)
+        session.meta.updated_at = message.ts
+
+        # Append to file
+        path = self._session_path(session.meta.agent, session.meta.session_id)
+        with open(path, "a") as f:
+            f.write(message.model_dump_json() + "\n")
+
+        # Update title if this is the first user message
+        if message.type == "user" and session.meta.title is None:
+            self._update_title(session, message.content or "")
+
+    def _update_title(self, session: Session, first_message: str) -> None:
+        """Generate and save a title from the first user message."""
+        # Simple truncation for now
+        title = first_message[:50]
+        if len(first_message) > 50:
+            title += "..."
+
+        session.meta.title = title
+
+        # Rewrite the session file to update meta
+        self._save_session(session)
+
+    def _save_session(self, session: Session) -> None:
+        """Save the full session to disk."""
+        path = self._session_path(session.meta.agent, session.meta.session_id)
+
+        with open(path, "w") as f:
+            # Write meta first with type marker
+            meta_dict: dict[str, Any] = session.meta.model_dump()
+            meta_dict["type"] = "meta"
+            # Convert datetime to string
+            meta_dict["created_at"] = session.meta.created_at.isoformat()
+            meta_dict["updated_at"] = session.meta.updated_at.isoformat()
+            f.write(json.dumps(meta_dict) + "\n")
+
+            # Write messages
+            for msg in session.messages:
+                f.write(msg.model_dump_json() + "\n")
+
+    def list_sessions(self, agent: str) -> list[SessionMeta]:
+        """
+        List all sessions for an agent.
+
+        Args:
+            agent: Agent name
+
+        Returns:
+            List of session metadata, sorted by updated_at (newest first)
+        """
+        agent_dir = self._agent_dir(agent)
+        sessions: list[SessionMeta] = []
+
+        for path in agent_dir.glob("*.jsonl"):
+            try:
+                with open(path) as f:
+                    first_line = f.readline().strip()
+                    if not first_line:
+                        continue
+
+                    data = json.loads(first_line)
+                    if data.get("type") == "meta":
+                        data.pop("type")
+                        sessions.append(SessionMeta(**data))
+            except (json.JSONDecodeError, KeyError):
+                # Skip invalid session files
+                continue
+
+        return sorted(sessions, key=lambda s: s.updated_at, reverse=True)
+
+    def delete_session(self, agent: str, session_id: str) -> bool:
+        """
+        Delete a session.
+
+        Args:
+            agent: Agent name
+            session_id: Session ID to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        path = self._session_path(agent, session_id)
+        if path.exists():
+            path.unlink()
+
+            # If this was the current session, clear the current pointer
+            current_path = self._current_path(agent)
+            if current_path.exists():
+                with open(current_path) as f:
+                    data = json.load(f)
+                if data.get("session_id") == session_id:
+                    current_path.unlink()
+
+            return True
+        return False

supyagent/core/tools.py

@@ -0,0 +1,235 @@
+"""
+Supypowers tool integration.
+
+Discovers and executes tools from supypowers.
+"""
+
+import json
+import subprocess
+from typing import Any
+
+from supyagent.models.agent_config import ToolPermissions
+
+
+# Special tool that allows LLM to request credentials from user
+REQUEST_CREDENTIAL_TOOL: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "request_credential",
+        "description": (
+            "Request an API key, token, or other credential from the user. "
+            "Use this when you need authentication to use a service or API. "
+            "The user will be prompted to enter the credential securely."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "The environment variable name (e.g., SLACK_API_TOKEN, OPENAI_API_KEY)",
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Explain to the user why this credential is needed and how to get it",
+                },
+                "service": {
+                    "type": "string",
+                    "description": "The service this credential is for (e.g., 'Slack', 'GitHub', 'OpenAI')",
+                },
+            },
+            "required": ["name", "description"],
+        },
+    },
+}
+
+
+def is_credential_request(tool_call: Any) -> bool:
+    """Check if a tool call is a credential request."""
+    return tool_call.function.name == "request_credential"
+
+
+def discover_tools() -> list[dict[str, Any]]:
+    """
+    Discover available tools from supypowers.
+
+    Runs `supypowers docs --format json` and parses the output.
+
+    Returns:
+        List of tool definitions from supypowers
+    """
+    try:
+        result = subprocess.run(
+            ["supypowers", "docs", "--format", "json"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+
+        if result.returncode != 0:
+            return []
+
+        return json.loads(result.stdout)
+
+    except FileNotFoundError:
+        # supypowers not installed
+        return []
+    except json.JSONDecodeError:
+        return []
+    except subprocess.TimeoutExpired:
+        return []
+
+
+def execute_tool(
+    script: str,
+    func: str,
+    args: dict[str, Any],
+    secrets: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """
+    Execute a supypowers function.
+
+    Args:
+        script: Script name (e.g., 'web_search')
+        func: Function name (e.g., 'search')
+        args: Function arguments as a dict
+        secrets: Optional secrets to pass as environment variables
+
+    Returns:
+        Result dict with 'ok' and 'data' or 'error'
+    """
+    cmd = ["supypowers", "run", f"{script}:{func}", json.dumps(args)]
+
+    # Add secrets
+    if secrets:
+        for key, value in secrets.items():
+            cmd.extend(["--secrets", f"{key}={value}"])
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=300,  # 5 minute timeout for tool execution
+        )
+
+        if result.returncode != 0:
+            # Try to parse error from stderr or stdout
+            error_msg = result.stderr or result.stdout or "Unknown error"
+            return {"ok": False, "error": error_msg.strip()}
+
+        return json.loads(result.stdout)
+
+    except FileNotFoundError:
+        return {"ok": False, "error": "supypowers not installed"}
+    except json.JSONDecodeError as e:
+        return {"ok": False, "error": f"Invalid JSON response: {e}"}
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "error": "Tool execution timed out"}
+
+
+def _matches_pattern(name: str, pattern: str) -> bool:
+    """
+    Check if a tool name matches a permission pattern.
+
+    Patterns:
+    - "web_search:*" matches all functions in web_search
+    - "web_search:search" matches exactly web_search:search
+    - "*" matches everything
+    """
+    if pattern == "*":
+        return True
+
+    if pattern.endswith(":*"):
+        script_pattern = pattern[:-2]
+        script_name = name.split("__")[0] if "__" in name else name.split(":")[0]
+        return script_name == script_pattern
+
+    # Exact match (convert : to __ for comparison)
+    normalized_pattern = pattern.replace(":", "__")
+    return name == normalized_pattern or name == pattern
+
+
+def filter_tools(
+    tools: list[dict[str, Any]],
+    permissions: ToolPermissions,
+) -> list[dict[str, Any]]:
+    """
+    Filter tools based on permissions.
+
+    Args:
+        tools: List of tool definitions
+        permissions: Allow/deny patterns
+
+    Returns:
+        Filtered list of tools
+    """
+    if not permissions.allow and not permissions.deny:
+        # No restrictions - allow all
+        return tools
+
+    filtered = []
+
+    for tool in tools:
+        name = tool.get("function", {}).get("name", "")
+
+        # Check deny list first
+        denied = any(_matches_pattern(name, pattern) for pattern in permissions.deny)
+        if denied:
+            continue
+
+        # Check allow list (if specified)
+        if permissions.allow:
+            allowed = any(_matches_pattern(name, pattern) for pattern in permissions.allow)
+            if not allowed:
+                continue
+
+        filtered.append(tool)
+
+    return filtered
+
+
+def supypowers_to_openai_tools(sp_tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Convert supypowers tool definitions to OpenAI function calling format.
+
+    Supypowers docs output format:
+    {
+        "script": "hello",
+        "function": "hello",
+        "description": "...",
+        "input_schema": {...}
+    }
+
+    OpenAI format:
+    {
+        "type": "function",
+        "function": {
+            "name": "hello__hello",
+            "description": "...",
+            "parameters": {...}
+        }
+    }
+    """
+    openai_tools = []
+
+    for sp_tool in sp_tools:
+        script = sp_tool.get("script", "")
+        func = sp_tool.get("function", "")
+        description = sp_tool.get("description", "No description")
+        input_schema = sp_tool.get("input_schema", {"type": "object", "properties": {}})
+
+        # Use double underscore to join script:function (since : isn't allowed in function names)
+        name = f"{script}__{func}"
+
+        openai_tool = {
+            "type": "function",
+            "function": {
+                "name": name,
+                "description": description,
+                "parameters": input_schema,
+            },
+        }
+
+        openai_tools.append(openai_tool)
+
+    return openai_tools

supyagent/models/__init__.py

@@ -0,0 +1,6 @@
+"""Data models for supyagent."""
+
+from supyagent.models.agent_config import AgentConfig, load_agent_config
+from supyagent.models.session import Message, Session, SessionMeta
+
+__all__ = ["AgentConfig", "load_agent_config", "Message", "Session", "SessionMeta"]

supyagent/models/agent_config.py

@@ -0,0 +1,86 @@
+"""
+Agent configuration models.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class ModelConfig(BaseModel):
+    """LLM model configuration."""
+
+    provider: str = Field(..., description="LiteLLM model identifier (e.g., 'anthropic/claude-3-5-sonnet-20241022')")
+    temperature: float = Field(default=0.7, ge=0, le=2)
+    max_tokens: int = Field(default=4096, gt=0)
+
+
+class ToolPermissions(BaseModel):
+    """Tool permission settings."""
+
+    allow: list[str] = Field(default_factory=list, description="Allowed tool patterns (e.g., 'web_search:*')")
+    deny: list[str] = Field(default_factory=list, description="Denied tool patterns")
+
+
+class CredentialSpec(BaseModel):
+    """Credential specification."""
+
+    name: str = Field(..., description="Environment variable name")
+    description: str = Field(default="", description="Description of what this credential is for")
+    required: bool = Field(default=False)
+
+
+class AgentConfig(BaseModel):
+    """
+    Agent configuration loaded from YAML.
+    """
+
+    name: str = Field(..., min_length=1, max_length=50)
+    description: str = Field(default="")
+    version: str = Field(default="1.0")
+    type: Literal["interactive", "execution"] = Field(default="interactive")
+    model: ModelConfig
+    system_prompt: str = Field(..., min_length=1)
+    tools: ToolPermissions = Field(default_factory=ToolPermissions)
+    delegates: list[str] = Field(default_factory=list)
+    credentials: list[CredentialSpec] = Field(default_factory=list)
+    limits: dict = Field(default_factory=dict)
+
+
+class AgentNotFoundError(Exception):
+    """Raised when an agent configuration is not found."""
+
+    def __init__(self, name: str):
+        self.name = name
+        super().__init__(f"Agent '{name}' not found. Check agents/ directory.")
+
+
+def load_agent_config(name: str, agents_dir: Path | None = None) -> AgentConfig:
+    """
+    Load and validate an agent configuration from YAML.
+
+    Args:
+        name: Agent name (without .yaml extension)
+        agents_dir: Directory containing agent YAML files (default: ./agents)
+
+    Returns:
+        Validated AgentConfig
+
+    Raises:
+        AgentNotFoundError: If agent YAML doesn't exist
+        ValidationError: If YAML is invalid
+    """
+    if agents_dir is None:
+        agents_dir = Path("agents")
+
+    config_path = agents_dir / f"{name}.yaml"
+
+    if not config_path.exists():
+        raise AgentNotFoundError(name)
+
+    with open(config_path) as f:
+        data = yaml.safe_load(f)
+
+    return AgentConfig(**data)

supyagent/models/session.py

@@ -0,0 +1,43 @@
+"""
+Session models for persistent conversation history.
+"""
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+class SessionMeta(BaseModel):
+    """Metadata for a session."""
+
+    session_id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
+    agent: str
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    model: str
+    title: str | None = None  # Auto-generated from first message
+
+
+class Message(BaseModel):
+    """A single message in the conversation."""
+
+    type: Literal["user", "assistant", "tool_result", "system"]
+    content: str | None = None
+    tool_calls: list[dict[str, Any]] | None = None
+    tool_call_id: str | None = None
+    name: str | None = None  # For tool results
+    ts: datetime = Field(default_factory=_utcnow)
+
+
+class Session(BaseModel):
+    """A conversation session with history."""
+
+    meta: SessionMeta
+    messages: list[Message] = Field(default_factory=list)

supyagent/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions for supyagent."""

supyagent/utils/paths.py

@@ -0,0 +1,31 @@
+"""
+Path utilities for supyagent.
+"""
+
+from pathlib import Path
+
+
+def get_agents_dir() -> Path:
+    """Get the agents directory."""
+    return Path("agents")
+
+
+def get_supyagent_dir() -> Path:
+    """Get the .supyagent runtime directory."""
+    path = Path(".supyagent")
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_sessions_dir() -> Path:
+    """Get the sessions directory."""
+    path = get_supyagent_dir() / "sessions"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_credentials_dir() -> Path:
+    """Get the credentials directory."""
+    path = get_supyagent_dir() / "credentials"
+    path.mkdir(parents=True, exist_ok=True)
+    return path