agentpool 2.1.9__py3-none-any.whl

agentpool_config/jinja.py

@@ -0,0 +1,206 @@
+"""Jinja2 environment configuration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from schemez import Schema
+
+from agentpool_config.tools import ToolConfig
+
+
+if TYPE_CHECKING:
+    from jinja2 import Template
+    from jinjarope import Environment
+
+UndefinedBehaviour = Literal["default", "strict", "debug", "chainable", "lax"]
+NewLineType = Literal["\n", "\r\n", "\r"]
+
+
+class Jinja2EnvironmentConfig(Schema):
+    """Configuration for Jinja2 environment.
+
+    See: https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.Environment
+    """
+
+    model_config = ConfigDict(json_schema_extra={"title": "Jinja2 Environment Configuration"})
+
+    block_start_string: str = Field(default="{%", title="Block start string", examples=["{%", "<%"])
+    """String denoting the beginning of a block (default: '{%')."""
+
+    block_end_string: str = Field(default="%}", title="Block end string", examples=["%}", "%>"])
+    """String denoting the end of a block (default: '%}')."""
+
+    variable_start_string: str = Field(
+        default="{{",
+        title="Variable start string",
+        examples=["{{", "${"],
+    )
+    """String denoting the beginning of a variable (default: '{{')."""
+
+    variable_end_string: str = Field(
+        default="}}",
+        title="Variable end string",
+        examples=["}}", "}"],
+    )
+    """String denoting the end of a variable (default: '}}')."""
+
+    comment_start_string: str = Field(
+        default="{#",
+        title="Comment start string",
+        examples=["{#", "<!--"],
+    )
+    """String denoting the beginning of a comment (default: '{#')."""
+
+    comment_end_string: str = Field(
+        default="#}",
+        title="Comment end string",
+        examples=["#}", "-->"],
+    )
+    """String denoting the end of a comment (default: '#}')."""
+
+    line_statement_prefix: str | None = Field(
+        default=None,
+        title="Line statement prefix",
+        examples=["#", "%"],
+    )
+    """Prefix that begins a line-based statement (e.g., '#' for line statements)."""
+
+    line_comment_prefix: str | None = Field(
+        default=None,
+        title="Line comment prefix",
+        examples=["##", "//"],
+    )
+    """Prefix that begins a line-based comment."""
+
+    trim_blocks: bool = Field(default=False, title="Trim blocks")
+    """Remove first newline after a block (affects whitespace control)."""
+
+    lstrip_blocks: bool = Field(default=False, title="Left strip blocks")
+    """Remove leading spaces and tabs from the start of a line to a block."""
+
+    newline_sequence: NewLineType = Field(
+        default="\n",
+        title="Newline sequence",
+        examples=["\n", "\r\n", "\r"],
+    )
+    """Sequence that starts a newline (default: '\n')."""
+
+    keep_trailing_newline: bool = Field(default=False, title="Keep trailing newline")
+    """Preserve the trailing newline when rendering templates."""
+
+    extensions: list[str] = Field(
+        default_factory=list,
+        title="Jinja2 extensions",
+        examples=[["jinja2.ext.do", "jinja2.ext.loopcontrols"], ["jinja2.ext.i18n"]],
+    )
+    """List of Jinja2 extensions to load (e.g., 'jinja2.ext.do')."""
+
+    undefined: UndefinedBehaviour = Field(
+        default="default",
+        title="Undefined behavior",
+        examples=["strict", "debug", "chainable"],
+    )
+    """Behavior when accessing undefined variables (default, strict, debug, chainable)."""
+
+    filters: list[ToolConfig] = Field(default_factory=list, title="Custom filters")
+    """Custom filters as list of tool configurations."""
+
+    tests: list[ToolConfig] = Field(default_factory=list, title="Custom tests")
+    """Custom tests as list of tool configurations."""
+
+    globals: dict[str, BaseModel] = Field(default_factory=dict, title="Global variables")
+    """Global variables available to all templates."""
+
+    def create_environment(self, *, enable_async: bool = False) -> Environment:
+        """Create configured Jinja2 environment.
+
+        Args:
+            enable_async: Whether to enable async features
+        """
+        from jinjarope import Environment
+
+        return Environment(enable_async=enable_async, **self.create_environment_kwargs())
+
+    def create_environment_kwargs(self) -> dict[str, Any]:
+        """Convert config to Jinja2 environment kwargs.
+
+        Creates a dictionary of kwargs for jinja2.Environment with proper
+        conversion of special values.
+
+        Returns:
+            Dict of kwargs for jinja2.Environment constructor
+
+        Raises:
+            ValueError: If filter or test imports fail
+        """
+        # Basic config
+        kwargs = self.model_dump(exclude={"filters", "tests"})
+
+        try:
+            # Convert filters - use tool name as filter name
+            tools = [cfg.get_tool() for cfg in self.filters]
+            kwargs["filters"] = {tool.name: tool.callable for tool in tools}
+            tools = [cfg.get_tool() for cfg in self.tests]
+            kwargs["tests"] = {tool.name: tool.callable for tool in tools}
+
+        except Exception as exc:
+            msg = f"Failed to import Jinja2 filters/tests: {exc}"
+            raise ValueError(msg) from exc
+
+        return kwargs
+
+
+class Jinja2Template(Schema):
+    """Template with environment configuration."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Jinja2 Template Configuration"})
+
+    template: str = Field(
+        title="Template string",
+        examples=["Hello {{ name }}!", "{% for item in items %}{{ item }}{% endfor %}"],
+    )
+    """The template string to render."""
+
+    environment: Jinja2EnvironmentConfig = Field(
+        default_factory=Jinja2EnvironmentConfig,
+        title="Environment configuration",
+    )
+    """Environment configuration for this template."""
+
+    def get_template(self, *, enable_async: bool = False) -> Template:
+        """Get compiled Jinja2 template.
+
+        Args:
+            enable_async: Whether to enable async features
+
+        Returns:
+            Compiled template ready for rendering
+        """
+        env = self.environment.create_environment(enable_async=enable_async)
+        return env.from_string(self.template)
+
+    def render(self, **kwargs: Any) -> str:
+        """Render template with provided variables.
+
+        Args:
+            **kwargs: Template variables
+
+        Returns:
+            Rendered template string
+        """
+        template = self.get_template()
+        return template.render(**kwargs)
+
+    async def render_async(self, **kwargs: Any) -> str:
+        """Render template asynchronously.
+
+        Args:
+            **kwargs: Template variables
+
+        Returns:
+            Rendered template string
+        """
+        template = self.get_template(enable_async=True)
+        return await template.render_async(**kwargs)

agentpool_config/knowledge.py

@@ -0,0 +1,41 @@
+"""Knowledge configuration."""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+from schemez import Schema
+
+from agentpool.prompts.prompts import PromptType
+
+
+class Knowledge(Schema):
+    """Collection of context sources for an agent.
+
+    Supports both simple paths and rich resource types for content loading,
+    plus AgentPool's prompt system for dynamic content generation.
+
+    Docs: https://phil65.github.io/agentpool/YAML%20Configuration/knowledge_configuration/
+    """
+
+    model_config = ConfigDict(json_schema_extra={"title": "Knowledge Configuration"})
+
+    paths: list[str] = Field(
+        default_factory=list,
+        examples=[["docs/readme.md", "https://api.example.com/docs"], ["/data/context.txt"]],
+        title="Resource paths",
+    )
+    """Quick access to files and URLs."""
+
+    prompts: list[PromptType] = Field(default_factory=list, title="Dynamic prompts")
+    """Prompts for dynamic content generation:
+    - StaticPrompt: Fixed message templates
+    - DynamicPrompt: Python function-based
+    - FilePrompt: File-based with template support
+    """
+
+    convert_to_markdown: bool = Field(default=False, title="Convert to markdown")
+    """Whether to convert content to markdown when possible."""
+
+    def get_resources(self) -> list[PromptType | str]:
+        """Get all resources."""
+        return self.prompts + self.paths

agentpool_config/loaders.py

@@ -0,0 +1,350 @@
+"""Models for resource information."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence as TypingSequence
+import inspect
+from typing import Annotated, Literal
+import warnings
+
+from pydantic import ConfigDict, Field, SecretStr, model_validator
+from schemez import Schema
+from upathtools import to_upath
+
+from agentpool.common_types import JsonObject
+from agentpool.utils.importing import import_callable
+
+
+class BaseResourceLoaderConfig(Schema):
+    """Base class for all resource types."""
+
+    type: str = Field(init=False, title="Resource type")
+    """Type identifier for this resource."""
+
+    description: str = Field(
+        default="",
+        title="Resource description",
+        examples=["Configuration file", "User data", "API response"],
+    )
+    """Human-readable description of the resource."""
+
+    uri: str | None = Field(
+        default=None,
+        title="Resource URI",
+        examples=["file:///path/to/file", "https://api.example.com/data"],
+    )
+    """Canonical URI for this resource, set during registration if unset."""
+
+    # watch: WatchConfig | None = None
+    # """Configuration for file system watching, if supported."""
+
+    name: str | None = Field(
+        default=None,
+        exclude=True,
+        title="Resource name",
+        examples=["config", "user_data", "api_response"],
+    )
+    """Technical identifier (automatically set from config key during registration)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # @property
+    # def supports_watching(self) -> bool:
+    #     """Whether this resource instance supports watching."""
+    #     return False
+
+    # def is_watched(self) -> bool:
+    #     """Tell if this resource should be watched."""
+    #     return self.supports_watching and self.watch is not None and self.watch.enabled
+
+    def is_templated(self) -> bool:
+        """Whether this resource supports URI templates."""
+        return False  # Default: resources are static
+
+    @property
+    def mime_type(self) -> str:
+        """Get the MIME type for this resource.
+
+        This should be overridden by subclasses that can determine
+        their MIME type. Default is text/plain.
+        """
+        return "text/plain"
+
+
+class PathResourceLoaderConfig(BaseResourceLoaderConfig):
+    """Resource loaded from a file or URL."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Path Resource"})
+
+    type: Literal["path"] = Field(default="path", init=False, title="Resource type")
+    """Discriminator field identifying this as a path-based resource."""
+
+    path: str = Field(
+        title="File path or URL",
+        examples=["/path/to/file.txt", "https://example.com/data.json", "config/settings.yml"],
+    )
+    """Path to the file or URL to load."""
+
+    watch: WatchConfig | None = Field(default=None, title="Watch configuration")
+    """Configuration for watching the file for changes."""
+
+    def validate_resource(self) -> list[str]:
+        """Check if path exists for local files."""
+        warnings = []
+        path = to_upath(self.path)
+        prefixes = ("http://", "https://")
+        if not path.exists() and not path.as_uri().startswith(prefixes):
+            warnings.append(f"Resource path not found: {path}")
+        return warnings
+
+    @property
+    def supports_watching(self) -> bool:
+        """Whether this resource instance supports watching."""
+        if not to_upath(self.path).exists():
+            msg = f"Cannot watch non-existent path: {self.path}"
+            warnings.warn(msg, UserWarning, stacklevel=2)
+            return False
+        return True
+
+    @model_validator(mode="after")
+    def validate_path(self) -> PathResourceLoaderConfig:
+        """Validate that the path is not empty."""
+        if not self.path:
+            msg = "Path cannot be empty"
+            raise ValueError(msg)
+        return self
+
+    def is_templated(self) -> bool:
+        """Path resources are templated if they contain placeholders."""
+        return "{" in str(self.path)
+
+    @property
+    def mime_type(self) -> str:
+        """Get MIME type based on file extension."""
+        from agentpool.mime_utils import guess_type
+
+        return guess_type(str(self.path)) or "application/octet-stream"
+
+
+class TextResourceLoaderConfig(BaseResourceLoaderConfig):
+    """Raw text resource."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Text Resource"})
+
+    type: Literal["text"] = Field(default="text", init=False, title="Resource type")
+    """Discriminator field identifying this as a text-based resource."""
+
+    content: str = Field(
+        title="Text content",
+        examples=["Hello World", '{ "key": "value" }', "---\nkey: value"],
+    )
+    """The actual text content of the resource."""
+
+    _mime_type: str | None = None  # Optional override
+
+    @model_validator(mode="after")
+    def validate_content(self) -> TextResourceLoaderConfig:
+        """Validate that the content is not empty."""
+        if not self.content:
+            msg = "Content cannot be empty"
+            raise ValueError(msg)
+        return self
+
+    @property
+    def mime_type(self) -> str:
+        """Get MIME type, trying to detect JSON/YAML."""
+        if self._mime_type:
+            return self._mime_type
+        # Could add content inspection here
+        return "text/plain"
+
+
+class CLIResourceLoaderConfig(BaseResourceLoaderConfig):
+    """Resource from CLI command execution."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "CLI Resource"})
+
+    type: Literal["cli"] = Field(default="cli", init=False, title="Resource type")
+    """Discriminator field identifying this as a CLI-based resource."""
+
+    command: str | TypingSequence[str] = Field(
+        title="Command to execute",
+        examples=["ls -la", "git status", ["python", "script.py", "--arg"]],
+    )
+    """Command to execute (string or sequence of arguments)."""
+
+    shell: bool = Field(default=False, title="Use shell")
+    """Whether to run the command through a shell."""
+
+    cwd: str | None = Field(
+        default=None,
+        title="Working directory",
+        examples=["/path/to/project", "~/workspace"],
+    )
+    """Working directory for command execution."""
+
+    timeout: float | None = Field(
+        default=None,
+        title="Timeout in seconds",
+        examples=[30.0, 60.0, 120.0],
+    )
+    """Maximum time in seconds to wait for command completion."""
+
+    @model_validator(mode="after")
+    def validate_command(self) -> CLIResourceLoaderConfig:
+        """Validate command configuration."""
+        if not self.command:
+            msg = "Command cannot be empty"
+            raise ValueError(msg)
+        if (
+            isinstance(self.command, list | tuple)
+            and not self.shell
+            and not all(isinstance(part, str) for part in self.command)
+        ):
+            msg = "When shell=False, all command parts must be strings"
+            raise ValueError(msg)
+        return self
+
+
+class RepositoryResource(BaseResourceLoaderConfig):
+    """Git repository content."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Repository Resource"})
+
+    type: Literal["repository"] = Field(default="repository", init=False, title="Resource type")
+    """Repository resource configuration."""
+
+    repo_url: str = Field(
+        title="Repository URL",
+        examples=["https://github.com/user/repo.git", "git@github.com:user/repo.git"],
+    )
+    """URL of the git repository."""
+
+    ref: str = Field(
+        default="main",
+        title="Git reference",
+        examples=["main", "develop", "v1.0.0", "abc123def"],
+    )
+    """Git reference (branch, tag, or commit)."""
+
+    path: str = Field(
+        default="",
+        title="Repository path",
+        examples=["", "src/", "docs/README.md"],
+    )
+    """Path within the repository."""
+
+    sparse_checkout: list[str] | None = Field(
+        default=None,
+        title="Sparse checkout paths",
+        examples=[["src/", "docs/"], ["*.py", "requirements.txt"]],
+    )
+    """Optional list of paths for sparse checkout."""
+
+    user: str | None = Field(
+        default=None,
+        title="Username",
+        examples=["github_user", "git_username"],
+    )
+    """Optional user name for authentication."""
+
+    password: SecretStr | None = Field(default=None, title="Password")
+    """Optional password for authentication."""
+
+    def validate_resource(self) -> list[str]:
+        warnings = []
+        if self.user and not self.password:
+            warnings.append(f"Repository {self.repo_url} has user but no password")
+        return warnings
+
+
+class SourceResourceLoaderConfig(BaseResourceLoaderConfig):
+    """Resource from Python source code."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Source Resource"})
+
+    type: Literal["source"] = Field(default="source", init=False, title="Resource type")
+    """Source code resource configuration."""
+
+    import_path: str = Field(
+        title="Import path",
+        examples=["mypackage.module", "utils.helpers", "app.models.User"],
+    )
+    """Dotted import path to the Python module or object."""
+
+    recursive: bool = Field(default=False, title="Include recursively")
+    """Whether to include submodules recursively."""
+
+    include_tests: bool = Field(default=False, title="Include tests")
+    """Whether to include test files and directories."""
+
+    @model_validator(mode="after")
+    def validate_import_path(self) -> SourceResourceLoaderConfig:
+        """Validate that the import path is properly formatted."""
+        if not all(part.isidentifier() for part in self.import_path.split(".")):
+            msg = f"Invalid import path: {self.import_path}"
+            raise ValueError(msg)
+        return self
+
+
+class CallableResourceLoaderConfig(BaseResourceLoaderConfig):
+    """Resource from executing a Python callable."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Callable Resource"})
+
+    type: Literal["callable"] = Field(default="callable", init=False, title="Resource type")
+    """Callable-based resource configuration."""
+
+    import_path: str = Field(
+        title="Callable import path",
+        examples=["mymodule.get_data", "utils.generators.create_content"],
+    )
+    """Dotted import path to the callable to execute."""
+
+    keyword_args: JsonObject = Field(default_factory=dict, title="Keyword arguments")
+    """Keyword arguments to pass to the callable."""
+
+    @model_validator(mode="after")
+    def validate_import_path(self) -> CallableResourceLoaderConfig:
+        """Validate that the import path is properly formatted."""
+        if not all(part.isidentifier() for part in self.import_path.split(".")):
+            msg = f"Invalid import path: {self.import_path}"
+            raise ValueError(msg)
+        return self
+
+    def is_templated(self) -> bool:
+        """Callable resources are templated if they take parameters."""
+        fn = import_callable(self.import_path)
+        sig = inspect.signature(fn)
+        return bool(sig.parameters)
+
+
+Resource = Annotated[
+    PathResourceLoaderConfig
+    | TextResourceLoaderConfig
+    | CLIResourceLoaderConfig
+    | SourceResourceLoaderConfig
+    | CallableResourceLoaderConfig,
+    Field(discriminator="type"),
+]
+
+
+class WatchConfig(Schema):
+    """Watch configuration for resources."""
+
+    enabled: bool = Field(default=False, title="Watch enabled")
+    """Whether the watch is enabled"""
+
+    patterns: list[str] | None = Field(
+        default=None,
+        title="Watch patterns",
+        examples=[["*.py", "*.yml"], ["src/**", "!**/__pycache__"]],
+    )
+    """List of pathspec patterns (.gitignore style)"""
+
+    ignore_file: str | None = Field(
+        default=None,
+        title="Ignore file path",
+        examples=[".gitignore", ".watchignore"],
+    )
+    """Path to .gitignore-style file"""