agentpool 2.1.9__py3-none-any.whl

agentpool/common_types.py

@@ -0,0 +1,226 @@
+"""Type definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Literal,
+    Protocol,
+    get_args,
+    get_origin,
+    runtime_checkable,
+)
+
+from pydantic import BaseModel, ConfigDict, field_validator
+from pydantic_ai import AgentStreamEvent, RunContext
+from pydantic_ai.models import Model
+from tokonomics.model_names import ModelId
+from toprompt.to_prompt import AnyPromptType
+from upathtools import JoinablePathLike
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+    from uuid import UUID
+
+    from agentpool.agents.events import RichAgentStreamEvent
+    from agentpool.messaging import ChatMessage
+    from agentpool.messaging.messagenode import MessageNode
+    from agentpool.tools.base import Tool
+
+    # Type alias for team streaming return type (node + event tuples)
+    type TeamStreamEvent = tuple[MessageNode[Any, Any], RichAgentStreamEvent[Any]]
+    type AnyTransformFn[T] = Callable[[T], T | Awaitable[T]]
+    type OptionalAwaitable[T] = T | Awaitable[T]
+    type ToolType = str | AnyCallable | Tool
+    # Define what we consider JSON-serializable
+    type JsonPrimitive = None | bool | int | float | str
+    type SessionIdType = str | UUID | None
+    type ProcessorCallback[TResult] = Callable[..., TResult | Awaitable[TResult]]
+
+# In reflex for example, the complex ones create issues..
+SimpleJsonType = dict[
+    str, bool | int | float | str | list[str] | dict[str, bool | int | float | str]
+]
+type JsonValue = JsonPrimitive | JsonArray | JsonObject
+type JsonObject = dict[str, JsonValue]
+type JsonArray = list[JsonValue]
+
+
+NodeName = str
+TeamName = str
+AgentName = str
+MessageRole = Literal["user", "assistant"]
+PartType = Literal["text", "image", "audio", "video"]
+ModelType = Model | ModelId | str | None
+EnvironmentType = Literal["file", "inline"]
+ToolSource = Literal["agent", "builtin", "dynamic", "task", "mcp", "toolset"]
+AnyCallable = Callable[..., Any]
+AsyncFilterFn = Callable[..., Awaitable[bool]]
+SyncFilterFn = Callable[..., bool]
+AnyFilterFn = Callable[..., bool | Awaitable[bool]]
+# Event handler types for composable event processing
+# Individual event handler for composability - takes single events
+IndividualEventHandler = Callable[[RunContext, AgentStreamEvent], Awaitable[None]]
+BuiltinEventHandlerType = Literal["simple", "detailed"]
+PromptCompatible = AnyPromptType | JoinablePathLike
+# P = ParamSpec("P")
+# SyncAsync = Callable[P, OptionalAwaitable[T]]
+EndStrategy = Literal["early", "exhaustive"]
+QueueStrategy = Literal["concat", "latest", "buffer"]
+"""The strategy for handling multiple tool calls when a final result is found.
+
+- `'early'`: Stop processing other tool calls once a final result is found
+- `'exhaustive'`: Process all tool calls even after finding a final result
+"""
+
+
+class SupportsStructuredOutput(Protocol):
+    """Protocol for nodes that support structured output via run().
+
+    This protocol is used for components that need to call run() with
+    an output_type parameter (e.g., picker agents, Interactions).
+    """
+
+    async def run(self, *prompts: Any, output_type: Any = ...) -> ChatMessage[Any]: ...
+
+
+@runtime_checkable
+class SupportsRunStream[TResult](Protocol):
+    """Protocol for nodes that support streaming via run_stream().
+
+    Used by Team and TeamRun to check if a node can be streamed.
+
+    Return type is a union because:
+    - Agent returns `AsyncIterator[RichAgentStreamEvent[TResult]]`
+    - Team/TeamRun return `AsyncIterator[tuple[MessageNode, RichAgentStreamEvent]]`
+    """
+
+    def run_stream(
+        self, *prompts: Any, **kwargs: Any
+    ) -> AsyncIterator[RichAgentStreamEvent[TResult] | TeamStreamEvent]: ...
+
+
+class BaseCode(BaseModel):
+    """Base class for syntax-validated code."""
+
+    code: str
+    """The source code."""
+
+    @field_validator("code")
+    @classmethod
+    def validate_syntax(cls, code: str) -> str:
+        """Override in subclasses."""
+        return code
+
+    model_config = ConfigDict(use_attribute_docstrings=True)
+
+
+def _validate_type_args(data: Any, args: tuple[Any, ...]) -> None:
+    """Validate data against type arguments."""
+    match data:
+        case dict() if len(args) == 2:  # noqa: PLR2004
+            key_type, value_type = args
+            for k, v in data.items():
+                if not isinstance(k, key_type):
+                    msg = f"Invalid key type: {type(k)}, expected {key_type}"
+                    raise ValueError(msg)  # noqa: TRY004
+                if not isinstance(v, value_type):
+                    msg = f"Invalid value type: {type(v)}, expected {value_type}"
+                    raise ValueError(msg)  # noqa: TRY004
+        case list() if len(args) == 1:
+            item_type = args[0]
+            for item in data:
+                if not isinstance(item, item_type):
+                    msg = f"Invalid item type: {type(item)}, expected {item_type}"
+                    raise ValueError(msg)  # noqa: TRY004
+
+
+class ConfigCode[T](BaseCode):
+    """Base class for configuration code that validates against a specific type.
+
+    Generic type T specifies the type to validate against.
+    """
+
+    validator_type: ClassVar[type]
+
+    @field_validator("code")
+    @classmethod
+    def validate_syntax(cls, code: str) -> str:
+        """Validate both YAML syntax and type constraints."""
+        import yamling
+
+        try:
+            # First validate YAML syntax
+            data = yamling.load(code, mode="yaml")
+
+            # Then validate against target type
+            match cls.validator_type:
+                case type() as model_cls if issubclass(model_cls, BaseModel):
+                    model_cls.model_validate(data)
+                case _ if origin := get_origin(cls.validator_type):
+                    # Handle generics like dict[str, int]
+                    if not isinstance(data, origin):
+                        msg = f"Expected {origin.__name__}, got {type(data).__name__}"
+                        raise ValueError(msg)  # noqa: TRY004, TRY301
+                    # Validate type arguments if present
+                    if args := get_args(cls.validator_type):
+                        _validate_type_args(data, args)
+                case _:
+                    msg = f"Unsupported validation type: {cls.validator_type}"
+                    raise TypeError(msg)  # noqa: TRY301
+
+        except Exception as e:
+            msg = f"Invalid YAML for {cls.validator_type.__name__}: {e}"
+            raise ValueError(msg) from e
+
+        return code
+
+    @classmethod
+    def for_config[TConfig](
+        cls,
+        base_type: type[TConfig],
+        *,
+        name: str | None = None,
+        error_msg: str | None = None,
+    ) -> type[ConfigCode[TConfig]]:
+        """Create a new ConfigCode class for a specific type.
+
+        Args:
+            base_type: The type to validate against
+            name: Optional name for the new class
+            error_msg: Optional custom error message
+
+        Returns:
+            New ConfigCode subclass with type-specific validation
+        """
+
+        class TypedConfigCode(ConfigCode[TConfig]):
+            validator_type = base_type
+
+            @field_validator("code")
+            @classmethod
+            def validate_syntax(cls, code: str) -> str:
+                try:
+                    return super().validate_syntax(code)
+                except ValueError as e:
+                    msg = error_msg or str(e)
+                    raise ValueError(msg) from e
+
+        if name:
+            TypedConfigCode.__name__ = name
+
+        return TypedConfigCode
+
+
+if __name__ == "__main__":
+    from agentpool.models.manifest import AgentsManifest
+
+    AgentsManifestCode = ConfigCode.for_config(
+        AgentsManifest,
+        name="AgentsManifestCode",
+        error_msg="Invalid agents manifest YAML",
+    )

agentpool/config_resources/__init__.py

@@ -0,0 +1,16 @@
+"""Package resources for AgentPool configuration."""
+
+from __future__ import annotations
+
+import importlib.resources
+from typing import Final
+
+_RESOURCES = importlib.resources.files("agentpool.config_resources")
+
+AGENTS_TEMPLATE: Final[str] = str(_RESOURCES / "agents_template.yml")
+"""Path to the agents template configuration."""
+
+ACP_ASSISTANT: Final[str] = str(_RESOURCES / "acp_assistant.yml")
+"""Path to default ACP assistant configuration."""
+
+__all__ = ["ACP_ASSISTANT", "AGENTS_TEMPLATE"]

agentpool/config_resources/acp_assistant.yml

@@ -0,0 +1,24 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+# Default ACP assistant configuration
+# Used when starting ACP server without explicit config file
+
+agents:
+  assistant:
+    display_name: "AI Assistant"
+    description: "General-purpose assistant with file system and code execution access"
+    model:
+      type: anthropic
+      identifier: claude-haiku-4-5
+      cache_instructions: true
+      cache_tool_definitions: true
+      cache_messages: true
+    system_prompt:
+      - |
+        You are a helpful AI assistant with access to the file system and can execute code.
+        You can help with coding, writing, analysis, file operations, and more.
+        Be concise but thorough in your responses.
+    toolsets:
+      - type: execution
+      - type: file_access
+      - type: code
+      - type: search

agentpool/config_resources/agents.yml

@@ -0,0 +1,109 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+responses:
+  BasicResult:
+    response_schema:
+      type: inline
+      description: "Simple operation result"
+      fields:
+        success:
+          type: bool
+          description: "Whether operation succeeded"
+        message:
+          type: str
+          description: "Operation result message"
+
+  SystemInfoResult:
+    response_schema:
+      type: inline
+      description: "System information result"
+      fields:
+        platform:
+          type: str
+          description: "Platform information"
+        cpu_count:
+          type: int
+          description: "Number of CPUs"
+        memory_used:
+          type: float
+          description: "Memory usage in GB"
+        summary:
+          type: str
+          description: "Formatted system summary"
+
+  FileInfoResult:
+    response_schema:
+      description: "File system information result"
+      type: inline
+      fields:
+        current_dir:
+          type: str
+          description: "Current working directory"
+        files:
+          type: list[str]
+          description: "List of files found"
+        details:
+          type: str
+          description: "Formatted file information"
+
+agents:
+  url_opener:
+    tools:
+      - type: import
+        import_path: "webbrowser.open"
+        description: "Open URL in default browser"
+      - type: import
+        import_path: "getpass.getuser"
+        description: "Get current system username"
+    model: openai:gpt-5-mini
+    output_type: BasicResult
+    system_prompt:
+      - |
+        You help users open websites. Use the open_url tool to open URLs.
+        When given a website name, find its URL in the bookmarks resource.
+        Always confirm what you're about to open.
+
+  system_inspector:
+    tools:
+      - type: import
+        import_path: "platform.platform"
+        description: "Get platform information"
+      - type: import
+        import_path: "os.cpu_count"
+        description: "Get number of CPUs"
+      - type: import
+        import_path: "psutil.virtual_memory"
+        description: "Get memory information"
+    model: openai:gpt-5-mini
+    output_type: SystemInfoResult
+    system_prompt:
+      - |
+        You provide system information in a clear, formatted way.
+        Use the platform_info, cpu_count, and memory_info tools
+        to gather system information.
+      - |
+        Format it using the template from the system_template resource.
+
+  file_explorer:
+    tools:
+      - type: import
+        import_path: "os.listdir"
+        description: "List directory contents"
+      - type: import
+        name: file_info
+        import_path: "os.stat"
+        description: "Get file information"
+      - type: import
+        import_path: "os.getcwd"
+        name: current_dir
+        description: "Get current working directory"
+    model: openai:gpt-5-mini
+    output_type: FileInfoResult
+    system_prompt:
+      - |
+        You help users explore their file system.
+        Available tools:
+        - list_dir: List contents of current directory
+        - file_info: Get file information
+        - current_dir: Get current working directory
+
+        Use these tools to help users explore files.

agentpool/config_resources/agents_template.yml

@@ -0,0 +1,18 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+agents:
+  simple_agent:
+    description: "Basic agent with one tool to open webbrowsers."
+    model: openai:gpt-5-mini
+    tools:
+      - type: import
+        import_path: webbrowser.open
+        description: "Open URL in browser"
+    system_prompt: "You are a helpful assistant."
+  simple_agent_2:
+    type: native
+    model: openai:gpt-5-mini
+    system_prompt: "You are a helpful assistant."
+  simple_agent_3:
+    type: native
+    model: openai:gpt-5-mini
+    system_prompt: "You are a helpful assistant."

agentpool/config_resources/agui_test.yml

@@ -0,0 +1,18 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+#
+# Test configuration for AG-UI agent.
+#
+# Usage:
+#   from agentpool import AgentPool
+#   async with AgentPool("src/agentpool/config_resources/agui_test.yml") as pool:
+#       agent = pool.get_agent("test_agui")
+#       result = await agent.run("Hello!")
+
+agents:
+  test_agui:
+    type: agui
+    endpoint: http://127.0.0.1:8765/agent/run
+    description: "AG-UI test client with auto-started server"
+    startup_command: "uv run python tests/test_server_agui.py --port 8765 --with-tools"
+    startup_delay: 3.0
+    timeout: 60.0

agentpool/config_resources/claude_code_agent.yml

@@ -0,0 +1,16 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+# Default ACP assistant configuration
+# Used when starting ACP server without explicit config file
+
+agents:
+  claude:
+    type: claude_code
+    display_name: "AI Assistant"
+    builtin_tools: []
+    description: "Claude code agent with enhanced tools"
+    toolsets:
+      - type: execution
+      - type: file_access
+      - type: code
+      - type: search
+      - type: plan

agentpool/config_resources/claude_style_subagent.md

@@ -0,0 +1,30 @@
+---
+name: data-scientist
+description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
+tools: Bash, Read, Write
+model: sonnet
+---
+
+You are a data scientist specializing in SQL and BigQuery analysis.
+
+When invoked:
+1. Understand the data analysis requirement
+2. Write efficient SQL queries
+3. Use BigQuery command line tools (bq) when appropriate
+4. Analyze and summarize results
+5. Present findings clearly
+
+Key practices:
+- Write optimized SQL queries with proper filters
+- Use appropriate aggregations and joins
+- Include comments explaining complex logic
+- Format results for readability
+- Provide data-driven recommendations
+
+For each analysis:
+- Explain the query approach
+- Document any assumptions
+- Highlight key findings
+- Suggest next steps based on data
+
+Always ensure queries are efficient and cost-effective.

agentpool/config_resources/external_acp_agents.yml

@@ -0,0 +1,77 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+agents:
+  # ACP-enabled agent with terminal and file access
+  claude:
+    type: acp
+    provider: claude
+    display_name: "Claude Code"
+    description: "Claude Code through ACP"
+    env: # override to make sure subscription is used
+      ANTHROPIC_API_KEY: ""
+
+    toolsets:
+      - type: code
+      - type: subagent
+  codex:
+    type: acp
+    provider: codex
+    display_name: "Codex"
+    description: "Codex Code through ACP"
+  # opencode:
+  #   type: acp
+  #   provider: opencode
+  #   display_name: "OpenCode"
+  #   description: "OpenCode through ACP"
+  # goose:
+  #   type: acp
+  #   provider: goose
+  #   display_name: "Goose"
+  #   description: "Block's Goose agent through ACP"
+  # fast-agent:
+  #   type: acp
+  #   provider: fast-agent
+  #   display_name: "Fast Agent"
+  #   description: "fast-agent through ACP"
+  #   model: openai.gpt-4o
+  # amp:
+  #   type: acp
+  #   provider: amp
+  #   display_name: "Amp (AmpCode)"
+  #   description: "Open-source ACP adapter for Amp CLI through ACP"
+  # auggie:
+  #   type: acp
+  #   provider: auggie
+  #   display_name: "Auggie (Augment Code)"
+  #   description: "Augment Code's AI agent through ACP"
+  # kimi:
+  #   type: acp
+  #   provider: kimi
+  #   display_name: "Kimi CLI"
+  #   description: "Moonshot AI's Kimi agent through ACP"
+  # stakpak:
+  #   type: acp
+  #   provider: stakpak
+  #   display_name: "Stakpak Agent"
+  #   description: "Terminal-native DevOps Agent through ACP"
+
+  # cagent:
+  #   type: acp
+  #   provider: cagent
+  #   display_name: "Docker cagent"
+  #   description: "Docker's Agent Builder and Runtime through ACP"
+  # vtcode:
+  #   type: acp
+  #   provider: vtcode
+  #   display_name: "VT Code"
+  #   description: "Rust-based semantic coding agent through ACP"
+  # openhands:
+  #   type: acp
+  #   provider: openhands
+  #   display_name: "OpenHands"
+  #   description: "OpenHands (formerly OpenDevin) through ACP"
+  # gemini:
+  #   type: acp
+  #   provider: gemini
+  #   display_name: "Gemini"
+  #   description: "Gemini Code through ACP"
+  #   # Note: --experimental-acp flag appears non-functional as of v0.19.3

agentpool/config_resources/opencode_style_subagent.md

@@ -0,0 +1,19 @@
+---
+description: Reviews code for quality and best practices
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+You are in code review mode. Focus on:
+
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance implications
+- Security considerations
+
+Provide constructive feedback without making direct changes.

agentpool/config_resources/tts_test_agents.yml

@@ -0,0 +1,78 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
+#
+# Test configuration for TTS synchronization modes.
+# Each agent demonstrates a different TTS mode.
+#
+# Usage:
+#   uv run agentpool chat --config src/agentpool/config_resources/tts_test_agents.yml --agent tts_sync_sentence
+#
+# Modes:
+#   - sync_sentence: Block per sentence (audio syncs with text output)
+#   - sync_run: Block at run end (fast streaming, wait for audio before next run)
+#   - async_queue: Fully async, multiple runs queue up
+#   - async_cancel: Fully async, new run cancels previous audio
+
+agents:
+  tts_sync_sentence:
+    type: native
+    description: "TTS with sync_sentence mode - blocks per sentence, most synchronized"
+    model: openai:gpt-4.1-nano
+    system_prompt:
+      - |
+        You are a storyteller. Tell engaging short stories in 3-4 sentences.
+        Speak naturally with clear sentence breaks.
+    event_handlers:
+      - type: builtin
+        handler: simple
+      - type: tts-openai
+        voice: alloy
+        mode: sync_sentence
+        min_text_length: 15
+
+  tts_sync_run:
+    type: native
+    description: "TTS with sync_run mode - fast streaming, waits at run end"
+    model: openai:gpt-4.1-nano
+    system_prompt:
+      - |
+        You are a storyteller. Tell engaging short stories in 3-4 sentences.
+        Speak naturally with clear sentence breaks.
+    event_handlers:
+      - type: builtin
+        handler: simple
+      - type: tts-openai
+        voice: echo
+        mode: sync_run
+        min_text_length: 15
+
+  tts_async_queue:
+    type: native
+    description: "TTS with async_queue mode - fully async, runs queue up"
+    model: openai:gpt-4.1-nano
+    system_prompt:
+      - |
+        You are a storyteller. Tell engaging short stories in 3-4 sentences.
+        Speak naturally with clear sentence breaks.
+    event_handlers:
+      - type: builtin
+        handler: simple
+      - type: tts-openai
+        voice: fable
+        mode: async_queue
+        min_text_length: 15
+
+  tts_async_cancel:
+    type: native
+    description: "TTS with async_cancel mode - fully async, new run cancels previous"
+    model: openai:gpt-4.1-nano
+    system_prompt:
+      - |
+        You are a storyteller. Tell engaging short stories in 3-4 sentences.
+        Speak naturally with clear sentence breaks.
+    event_handlers:
+      - type: builtin
+        handler: simple
+      - type: tts-openai
+        voice: nova
+        mode: async_cancel
+        min_text_length: 15

agentpool/delegation/__init__.py

@@ -0,0 +1,8 @@
+"""Agent delegation and collaboration functionality."""
+
+from agentpool.delegation.pool import AgentPool
+from agentpool.delegation.base_team import BaseTeam
+from agentpool.delegation.teamrun import TeamRun
+from agentpool.delegation.team import Team
+
+__all__ = ["AgentPool", "BaseTeam", "Team", "TeamRun"]