agentex-sdk 0.1.0a6__py3-none-any.whl

agentex/lib/sdk/config/agent_manifest.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import io
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import IO, Any
+
+from pydantic import Field
+
+from agentex.lib.sdk.config.agent_config import AgentConfig
+from agentex.lib.sdk.config.build_config import BuildConfig
+from agentex.lib.sdk.config.deployment_config import DeploymentConfig
+from agentex.lib.sdk.config.local_development_config import LocalDevelopmentConfig
+from agentex.lib.utils.logging import make_logger
+from agentex.lib.utils.model_utils import BaseModel
+
+logger = make_logger(__name__)
+
+
+class AgentManifest(BaseModel):
+    """
+    Represents a manifest file that describes how to build and deploy an agent.
+    """
+
+    build: BuildConfig
+    agent: AgentConfig
+    local_development: LocalDevelopmentConfig | None = Field(
+        default=None, description="Configuration for local development"
+    )
+    deployment: DeploymentConfig | None = Field(
+        default=None, description="Deployment configuration for the agent"
+    )
+
+    def context_manager(self, build_context_root: Path) -> BuildContextManager:
+        """
+        Creates a build context manager
+        """
+        return BuildContextManager(
+            agent_manifest=self, build_context_root=build_context_root
+        )
+
+
+class BuildContextManager:
+    """
+    A gateway used to manage the build context for a docker image
+    """
+
+    def __init__(self, agent_manifest: AgentManifest, build_context_root: Path):
+        self.agent_manifest = agent_manifest
+        self.build_context_root = build_context_root
+        self._temp_dir: tempfile.TemporaryDirectory | None = None
+
+        self.path: Path | None = None
+        self.dockerfile_path = "Dockerfile"
+        self.dockerignore_path = ".dockerignore"
+        self.directory_paths: list[Path] = []
+
+    def __enter__(self) -> BuildContextManager:
+        self._temp_dir = tempfile.TemporaryDirectory()
+        self.path = Path(self._temp_dir.name)
+
+        dockerfile_path = (
+            self.build_context_root / self.agent_manifest.build.context.dockerfile
+        )
+        self.add_dockerfile(root_path=self.path, dockerfile_path=dockerfile_path)
+
+        ignore_patterns = []
+        if self.agent_manifest.build.context.dockerignore:
+            dockerignore_path = (
+                self.build_context_root / self.agent_manifest.build.context.dockerignore
+            )
+            self.add_dockerignore(
+                root_path=self.path, dockerignore_path=dockerignore_path
+            )
+            ignore_patterns = _extract_dockerignore_patterns(dockerignore_path)
+
+        for directory in self.agent_manifest.build.context.include_paths:
+            directory_path = self.build_context_root / directory
+            self.add_directory(
+                root_path=self.path,
+                directory_path=directory_path,
+                context_root=self.build_context_root,
+                ignore_patterns=ignore_patterns,
+            )
+
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if self._temp_dir:
+            self._temp_dir.cleanup()
+
+    def add_dockerfile(self, root_path: Path, dockerfile_path: Path) -> None:
+        """
+        Copies a dockerfile to the temporary context directory root
+        """
+        shutil.copy2(dockerfile_path, root_path / self.dockerfile_path)
+
+    def add_dockerignore(self, root_path: Path, dockerignore_path: Path) -> None:
+        """
+        Copies a dockerignore to the temporary context directory root
+        """
+        shutil.copy2(str(dockerignore_path), root_path / self.dockerignore_path)
+
+    def add_directory(
+        self,
+        root_path: Path,
+        directory_path: Path,
+        context_root: Path,
+        ignore_patterns: list[str] | None = None,
+    ) -> None:
+        """
+        Copies a directory to the temporary context directory root while maintaining its relative
+        path to the context root.
+        """
+        directory_copy_start_time = time.time()
+        last_log_time = directory_copy_start_time
+
+        def copy_function_with_progress(src, dst):
+            nonlocal directory_copy_start_time
+            nonlocal last_log_time
+            logger.info(f"Adding {src} to build context...")
+            shutil.copy2(src, dst)
+            current_time = time.time()
+            time_elapsed = current_time - directory_copy_start_time
+
+            if time_elapsed > 1 and current_time - last_log_time >= 1:
+                logger.info(
+                    f"Time elapsed copying ({directory_path}): {time_elapsed} "
+                    f"seconds"
+                )
+                last_log_time = current_time
+            if time_elapsed > 5:
+                logger.warning(
+                    f"This may take a while... "
+                    f"Consider adding {directory_path} or {src} to your .dockerignore file."
+                )
+
+        directory_path_relative_to_root = directory_path.relative_to(context_root)
+        all_ignore_patterns = [f"{root_path}*"]
+        if ignore_patterns:
+            all_ignore_patterns += ignore_patterns
+        shutil.copytree(
+            src=directory_path,
+            dst=root_path / directory_path_relative_to_root,
+            ignore=shutil.ignore_patterns(*all_ignore_patterns),
+            dirs_exist_ok=True,
+            copy_function=copy_function_with_progress,
+        )
+        self.directory_paths.append(directory_path_relative_to_root)
+
+    @contextmanager
+    def zip_stream(self, root_path: Path | None = None) -> Iterator[IO[bytes]]:
+        """
+        Creates a tar archive of the temporary context directory
+        and returns a stream of the archive.
+        """
+        if not root_path:
+            raise ValueError("root_path must be provided")
+        context = str(root_path.absolute())
+        folders_to_include = "."
+        tar_command = ["tar", "-C", context, "-cf", "-"]
+        tar_command.extend(folders_to_include)
+
+        logger.info(f"Creating archive: {' '.join(tar_command)}")
+
+        with subprocess.Popen(
+            tar_command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+        ) as proc:
+            assert proc.stdout is not None
+            try:
+                yield proc.stdout
+            finally:
+                pass
+
+    @staticmethod
+    @contextmanager
+    def zipped(root_path: Path | None = None) -> Iterator[IO[bytes]]:
+        """
+        Creates a tar.gz archive of the temporary context directory
+        and returns a stream of the archive.
+        """
+        if not root_path:
+            raise ValueError("root_path must be provided")
+
+        tar_buffer = io.BytesIO()
+
+        with tarfile.open(fileobj=tar_buffer, mode="w:gz") as tar_file:
+            for path in Path(root_path).rglob(
+                "*"
+            ):  # Recursively add files to the tar.gz
+                if path.is_file():  # Ensure that we're only adding files
+                    tar_file.add(path, arcname=path.relative_to(root_path))
+
+        tar_buffer.seek(0)  # Reset the buffer position to the beginning
+        yield tar_buffer
+
+
+def _extract_dockerignore_patterns(dockerignore_path: Path) -> list[str]:
+    """
+    Extracts glob patterns to ignore from the dockerignore into a list of patterns
+    :param dockerignore_path: Path to the dockerignore to extract patterns from
+    :return: List of glob patterns to ignore
+    :rtype: List[str]
+    """
+    ignore_patterns = []
+    with open(dockerignore_path) as file:
+        for line in file:
+            ignored_filepath = line.split("#", 1)[0].strip()
+            if ignored_filepath:
+                ignore_patterns.append(ignored_filepath)
+    return ignore_patterns

agentex/lib/sdk/config/build_config.py

@@ -0,0 +1,35 @@
+from pydantic import Field
+
+from agentex.lib.utils.model_utils import BaseModel
+
+
+class BuildContext(BaseModel):
+    """
+    Represents the context in which the Docker image should be built.
+    """
+
+    root: str = Field(
+        ...,
+        description="The root directory of the build context. Should be specified relative to the location of the "
+        "build config file.",
+    )
+    include_paths: list[str] = Field(
+        default_factory=list,
+        description="The paths to include in the build context. Should be specified relative to the root directory.",
+    )
+    dockerfile: str = Field(
+        ...,
+        description="The path to the Dockerfile. Should be specified relative to the root directory.",
+    )
+    dockerignore: str | None = Field(
+        None,
+        description="The path to the .dockerignore file. Should be specified relative to the root directory.",
+    )
+
+
+class BuildConfig(BaseModel):
+    """
+    Represents a configuration for building the action as a Docker image.
+    """
+
+    context: BuildContext

agentex/lib/sdk/config/deployment_config.py

@@ -0,0 +1,117 @@
+from typing import Any
+
+from pydantic import Field
+
+from agentex.lib.utils.model_utils import BaseModel
+
+
+class ImageConfig(BaseModel):
+    """Configuration for container images"""
+
+    repository: str = Field(..., description="Container image repository URL")
+    tag: str = Field(default="latest", description="Container image tag")
+
+
+class ImagePullSecretConfig(BaseModel):
+    """Configuration for image pull secrets"""
+
+    name: str = Field(..., description="Name of the image pull secret")
+
+
+class ResourceRequirements(BaseModel):
+    """Resource requirements for containers"""
+
+    cpu: str = Field(
+        default="500m", description="CPU request/limit (e.g., '500m', '1')"
+    )
+    memory: str = Field(
+        default="1Gi", description="Memory request/limit (e.g., '1Gi', '512Mi')"
+    )
+
+
+class ResourceConfig(BaseModel):
+    """Resource configuration for containers"""
+
+    requests: ResourceRequirements = Field(
+        default_factory=ResourceRequirements, description="Resource requests"
+    )
+    limits: ResourceRequirements = Field(
+        default_factory=ResourceRequirements, description="Resource limits"
+    )
+
+
+class GlobalDeploymentConfig(BaseModel):
+    """Global deployment configuration that applies to all clusters"""
+
+    agent: dict[str, str] = Field(
+        default_factory=dict, description="Agent metadata (name, description)"
+    )
+    replicaCount: int = Field(default=1, description="Number of replicas to deploy")
+    resources: ResourceConfig = Field(
+        default_factory=ResourceConfig, description="Resource requirements"
+    )
+
+
+class DeploymentConfig(BaseModel):
+    """Main deployment configuration in the manifest"""
+
+    image: ImageConfig = Field(..., description="Container image configuration")
+    imagePullSecrets: list[ImagePullSecretConfig] | None = Field(
+        default=None, description="Image pull secrets to use for the deployment"
+    )
+    global_config: GlobalDeploymentConfig = Field(
+        default_factory=GlobalDeploymentConfig,
+        description="Global deployment settings",
+        alias="global",
+    )
+
+    class Config:
+        validate_by_name = True
+
+
+class ClusterConfig(BaseModel):
+    """Per-cluster deployment overrides"""
+
+    image: ImageConfig | None = Field(
+        default=None, description="Cluster-specific image overrides"
+    )
+    replicaCount: int | None = Field(
+        default=None, description="Cluster-specific replica count"
+    )
+    resources: ResourceConfig | None = Field(
+        default=None, description="Cluster-specific resource overrides"
+    )
+    env: list[dict[str, str]] | None = Field(
+        default=None, description="Additional environment variables for this cluster"
+    )
+    # Allow additional arbitrary overrides for advanced users
+    additional_overrides: dict[str, Any] | None = Field(
+        default=None, description="Additional helm chart value overrides"
+    )
+
+
+class InjectedImagePullSecretValues(BaseModel):
+    """Values for image pull secrets"""
+
+    registry: str = Field(..., description="Registry of the image pull secret")
+    username: str = Field(..., description="Username of the image pull secret")
+    password: str = Field(..., description="Password of the image pull secret")
+    email: str | None = Field(
+        default=None, description="Email of the image pull secret"
+    )
+
+
+class InjectedSecretsValues(BaseModel):
+    """Values for injected secrets"""
+
+    # Defined as a dictionary because the names need to be unique
+    credentials: dict[str, Any] = Field(
+        default_factory=dict, description="Secrets to inject into the deployment"
+    )
+    imagePullSecrets: dict[str, InjectedImagePullSecretValues] = Field(
+        default_factory=dict,
+        description="Image pull secrets to inject into the deployment",
+    )
+
+    class Config:
+        validate_by_name = True

agentex/lib/sdk/config/local_development_config.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from pydantic import Field, validator
+
+from agentex.lib.utils.model_utils import BaseModel
+
+
+class LocalAgentConfig(BaseModel):
+    """Configuration for local agent development"""
+
+    port: int = Field(
+        ...,
+        description="The port where the agent's ACP server is running locally",
+        gt=0,
+        lt=65536,
+    )
+    host_address: str = Field(
+        default="host.docker.internal",
+        description="The host address where the agent's ACP server can be reached (e.g., host.docker.internal for Docker, localhost for direct)",
+    )
+
+
+class LocalPathsConfig(BaseModel):
+    """Configuration for local file paths"""
+
+    acp: str = Field(
+        default="project/acp.py",
+        description="Path to the ACP server file. Can be relative to manifest directory or absolute.",
+    )
+    worker: str | None = Field(
+        default=None,
+        description="Path to the temporal worker file. Can be relative to manifest directory or absolute. (only for temporal agents)",
+    )
+
+    @validator("acp", "worker")
+    def validate_path_format(cls, v):
+        """Validate that the path is a reasonable format"""
+        if v is None:
+            return v
+
+        # Convert to Path to validate format
+        try:
+            Path(v)
+        except Exception as e:
+            raise ValueError(f"Invalid path format: {v}") from e
+
+        return v
+
+
+class LocalDevelopmentConfig(BaseModel):
+    """Configuration for local development environment"""
+
+    agent: LocalAgentConfig = Field(..., description="Local agent configuration")
+    paths: LocalPathsConfig | None = Field(
+        default=None, description="File paths for local development"
+    )

agentex/lib/sdk/config/project_config.py

@@ -0,0 +1,103 @@
+import os
+import re
+from pathlib import Path
+from typing import Any, TypeVar
+
+import yaml
+from jinja2 import BaseLoader, Environment, StrictUndefined, TemplateError
+
+T = TypeVar("T")
+
+
+class ConfigResolutionError(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.status_code = 400
+
+
+def _preprocess_template(template_str: str) -> str:
+    # Replace $env. and $variables. with unique internal names
+    return template_str.replace("{{ $env.", "{{ __special_env__.").replace(
+        "{{ $variables.", "{{ __special_variables__."
+    )
+
+
+def _extract_variables_section(raw_config_str: str) -> str:
+    # Use regex to extract the variables: ... block (YAML top-level)
+    match = re.search(
+        r"(^variables:.*?)(^config:|\Z)", raw_config_str, re.DOTALL | re.MULTILINE
+    )
+    if not match:
+        return ""
+    return match.group(1)
+
+
+def ProjectConfigLoader(
+    config_path: str, model: type[T] | None = None, env_path: str | None = None
+) -> dict[str, Any] | T:
+    config_path = Path(config_path)
+    env_path = Path(env_path) if env_path else config_path.parent / ".env"
+    env = _load_env(env_path)
+    raw_config_str = _load_file_as_str(config_path)
+    raw_config_str = _preprocess_template(raw_config_str)
+
+    # Extract and render only the variables section
+    variables_section_str = _extract_variables_section(raw_config_str)
+    env_context = {"__special_env__": env, "__special_variables__": {}}
+    try:
+        env_only_template = Environment(
+            loader=BaseLoader(),
+            undefined=StrictUndefined,
+            keep_trailing_newline=True,
+            autoescape=False,
+        ).from_string(variables_section_str)
+        rendered_variables_yaml = env_only_template.render(**env_context)
+        variables_dict = yaml.safe_load(rendered_variables_yaml).get("variables", {})
+    except Exception as e:
+        raise ConfigResolutionError(f"Error rendering variables with $env: {e}") from e
+    # Second pass: render the whole config with both __special_env__ and resolved __special_variables__
+    full_context = {"__special_env__": env, "__special_variables__": variables_dict}
+    rendered_config_str = _jinja_render(raw_config_str, full_context)
+    try:
+        rendered_config = yaml.safe_load(rendered_config_str)
+    except Exception as e:
+        raise ConfigResolutionError(f"Error loading rendered YAML: {e}") from e
+    if "config" not in rendered_config:
+        raise ConfigResolutionError("Missing 'config' section in config file.")
+    config_section = rendered_config["config"]
+    if model is not None:
+        return model(**config_section)
+    return config_section
+
+
+def _load_env(env_path: Path) -> dict[str, str]:
+    env = dict(os.environ)
+    if env_path.exists():
+        with open(env_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" in line:
+                    k, v = line.split("=", 1)
+                    env[k.strip()] = v.strip()
+    return env
+
+
+def _load_file_as_str(path: Path) -> str:
+    with open(path) as f:
+        return f.read()
+
+
+def _jinja_render(template_str: str, context: dict) -> str:
+    try:
+        env = Environment(
+            loader=BaseLoader(),
+            undefined=StrictUndefined,
+            keep_trailing_newline=True,
+            autoescape=False,
+        )
+        template = env.from_string(template_str)
+        return template.render(**context)
+    except TemplateError as e:
+        raise ConfigResolutionError(f"Jinja template error: {e}") from e

agentex/lib/sdk/fastacp/__init__.py

@@ -0,0 +1,3 @@
+from agentex.lib.sdk.fastacp.fastacp import FastACP
+
+__all__ = ["FastACP"]