bedrock-agentcore-starter-toolkit 0.0.1__py3-none-any.whl → 0.1.1__py3-none-any.whl

bedrock_agentcore_starter_toolkit/utils/runtime/config.py

@@ -0,0 +1,129 @@
+"""Configuration utilities for Bedrock AgentCore SDK."""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from .schema import BedrockAgentCoreAgentSchema, BedrockAgentCoreConfigSchema
+
+log = logging.getLogger(__name__)
+
+# def _clean_authorizer_config(config_dict: Dict[str, Any]) -> Dict[str, Any]:
+#     """Remove unwanted snake_case authorizer configurations."""
+#     if "authorizer_configuration" in config_dict:
+#         auth_config = config_dict["authorizer_configuration"]
+#         # Remove snake_case version if it exists
+#         if "custom_jwt_authorizer" in auth_config:
+#             del auth_config["custom_jwt_authorizer"]
+#         # If no valid camelCase configuration exists and auth_config is empty, remove it
+#         if not auth_config:
+#             del config_dict["authorizer_configuration"]
+#     return config_dict
+
+
+def is_project_config_format(config_path: Path) -> bool:
+    """Check if config file uses project format (has 'agents' key)."""
+    if not config_path.exists():
+        return False
+    with open(config_path, "r") as f:
+        data = yaml.safe_load(f) or {}
+    return isinstance(data, dict) and "agents" in data
+
+
+def _is_legacy_format(data: dict) -> bool:
+    """Detect old single-agent format."""
+    return isinstance(data, dict) and "agents" not in data and "name" in data and "entrypoint" in data
+
+
+def _transform_legacy_to_multi_agent(data: dict) -> BedrockAgentCoreConfigSchema:
+    """Transform old format to new format at runtime."""
+    agent_config = BedrockAgentCoreAgentSchema.model_validate(data)
+    return BedrockAgentCoreConfigSchema(default_agent=agent_config.name, agents={agent_config.name: agent_config})
+
+
+def load_config(config_path: Path) -> BedrockAgentCoreConfigSchema:
+    """Load config with automatic legacy format transformation."""
+    if not config_path.exists():
+        raise FileNotFoundError(f"Configuration not found: {config_path}")
+
+    with open(config_path, "r") as f:
+        data = yaml.safe_load(f) or {}
+
+    # Auto-detect and transform legacy format
+    if _is_legacy_format(data):
+        return _transform_legacy_to_multi_agent(data)
+
+    # New format
+    try:
+        return BedrockAgentCoreConfigSchema.model_validate(data)
+    except Exception as e:
+        raise ValueError(f"Invalid configuration format: {e}") from e
+
+
+def save_config(config: BedrockAgentCoreConfigSchema, config_path: Path):
+    """Save configuration to YAML file.
+
+    Args:
+        config: BedrockAgentCoreConfigSchema instance to save
+        config_path: Path to save configuration file
+    """
+    with open(config_path, "w") as f:
+        yaml.dump(config.model_dump(), f, default_flow_style=False, sort_keys=False)
+
+
+def load_config_if_exists(config_path: Path) -> Optional[BedrockAgentCoreConfigSchema]:
+    """Load configuration if file exists, otherwise return None.
+
+    Args:
+        config_path: Path to configuration file
+
+    Returns:
+        BedrockAgentCoreConfigSchema instance or None if file doesn't exist
+    """
+    if not config_path.exists():
+        return None
+    return load_config(config_path)
+
+
+def merge_agent_config(
+    config_path: Path, agent_name: str, new_config: BedrockAgentCoreAgentSchema
+) -> BedrockAgentCoreConfigSchema:
+    """Merge agent configuration into config.
+
+    Args:
+        config_path: Path to configuration file
+        agent_name: Name of the agent to add/update
+        new_config: Agent configuration to merge
+
+    Returns:
+        Updated project configuration
+    """
+    config = load_config_if_exists(config_path)
+
+    # Handle None case - create new config
+    if config is None:
+        config = BedrockAgentCoreConfigSchema()
+
+    # Preserve deployment info if agent exists
+    if agent_name in config.agents:
+        new_config.bedrock_agentcore = config.agents[agent_name].bedrock_agentcore
+
+    # Add/update agent
+    config.agents[agent_name] = new_config
+
+    # Log default agent change and always set current agent as default
+    old_default = config.default_agent
+    if old_default != agent_name:
+        if old_default:
+            log.info("Changing default agent from '%s' to '%s'", old_default, agent_name)
+        else:
+            log.info("Setting '%s' as default agent", agent_name)
+    else:
+        log.info("Keeping '%s' as default agent", agent_name)
+
+    # Always set current agent as default (the agent being configured becomes the new default)
+    config.default_agent = agent_name
+
+    return config

bedrock_agentcore_starter_toolkit/utils/runtime/container.py

@@ -0,0 +1,310 @@
+"""Container runtime management for Bedrock AgentCore SDK."""
+
+import logging
+import platform
+import subprocess  # nosec B404 - Required for container runtime operations
+import time
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from jinja2 import Template
+
+from ...cli.common import _handle_warn
+from .entrypoint import detect_dependencies, get_python_version
+
+log = logging.getLogger(__name__)
+
+
+class ContainerRuntime:
+    """Container runtime for Docker, Finch, and Podman."""
+
+    DEFAULT_RUNTIME = "auto"
+    DEFAULT_PLATFORM = "linux/arm64"
+
+    def __init__(self, runtime_type: Optional[str] = None):
+        """Initialize container runtime.
+
+        Args:
+            runtime_type: Runtime type to use, defaults to auto-detection
+        """
+        runtime_type = runtime_type or self.DEFAULT_RUNTIME
+        self.available_runtimes = ["finch", "docker", "podman"]
+
+        if runtime_type == "auto":
+            for runtime in self.available_runtimes:
+                if self._is_runtime_installed(runtime):
+                    self.runtime = runtime
+                    break
+            else:
+                raise RuntimeError("No container runtime found. Please install Docker, Finch, or Podman.")
+        elif runtime_type in self.available_runtimes:
+            if self._is_runtime_installed(runtime_type):
+                self.runtime = runtime_type
+            else:
+                raise RuntimeError(f"{runtime_type.capitalize()} is not installed")
+        else:
+            raise ValueError(f"Unsupported runtime: {runtime_type}")
+
+    def _is_runtime_installed(self, runtime: str) -> bool:
+        """Check if runtime is installed."""
+        try:
+            result = subprocess.run([runtime, "version"], capture_output=True, check=False)  # nosec B603
+            return result.returncode == 0
+        except (FileNotFoundError, OSError):
+            return False
+
+    def get_name(self) -> str:
+        """Get runtime name."""
+        return self.runtime.capitalize()
+
+    def image_exists(self, tag: str) -> bool:
+        """Check if image exists."""
+        try:
+            result = subprocess.run([self.runtime, "images", "-q", tag], capture_output=True, text=True, check=False)  # nosec B603
+            return bool(result.stdout.strip())
+        except (subprocess.SubprocessError, OSError):
+            return False
+
+    def generate_dockerfile(
+        self,
+        agent_path: Path,
+        output_dir: Path,
+        agent_name: str,
+        aws_region: Optional[str] = None,
+        enable_observability: bool = True,
+        requirements_file: Optional[str] = None,
+    ) -> Path:
+        """Generate Dockerfile from template."""
+        current_platform = self._get_current_platform()
+        required_platform = self.DEFAULT_PLATFORM
+
+        if current_platform != required_platform:
+            _handle_warn(
+                f"[WARNING] Platform mismatch: Current system is '{current_platform}' "
+                f"but Bedrock AgentCore requires '{required_platform}'.\n"
+                "For deployment options and workarounds, see: "
+                "https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/getting-started-custom.html\n"
+            )
+
+        template_path = Path(__file__).parent / "templates" / "Dockerfile.j2"
+
+        if not template_path.exists():
+            log.error("Dockerfile template not found: %s", template_path)
+            raise FileNotFoundError(f"Dockerfile template not found: {template_path}")
+
+        with open(template_path) as f:
+            template = Template(f.read())
+
+        # Generate .dockerignore if it doesn't exist
+        self._ensure_dockerignore(output_dir)
+
+        # Validate module path before generating Dockerfile
+        self._validate_module_path(agent_path, output_dir)
+
+        # Calculate module path relative to project root
+        agent_module_path = self._get_module_path(agent_path, output_dir)
+
+        wheelhouse_dir = output_dir / "wheelhouse"
+
+        # Detect dependencies using the new DependencyInfo class
+        deps = detect_dependencies(output_dir, explicit_file=requirements_file)
+
+        # Add logic to avoid duplicate installation
+        has_current_package = False
+        if (output_dir / "pyproject.toml").exists():
+            # Only install current package if deps isn't already pointing to it
+            if not (deps.found and deps.is_root_package):
+                has_current_package = True
+
+        context = {
+            "python_version": get_python_version(),
+            "agent_file": agent_path.name,
+            "agent_module": agent_path.stem,
+            "agent_module_path": agent_module_path,
+            "agent_var": agent_name,
+            "has_wheelhouse": wheelhouse_dir.exists() and wheelhouse_dir.is_dir(),
+            "has_current_package": has_current_package,
+            "dependencies_file": deps.file,
+            "dependencies_install_path": deps.install_path,
+            "aws_region": aws_region,
+            "system_packages": [],
+            "observability_enabled": enable_observability,
+        }
+
+        dockerfile_path = output_dir / "Dockerfile"
+        dockerfile_path.write_text(template.render(**context))
+        return dockerfile_path
+
+    def _ensure_dockerignore(self, project_dir: Path) -> None:
+        """Create .dockerignore if it doesn't exist."""
+        dockerignore_path = project_dir / ".dockerignore"
+        if not dockerignore_path.exists():
+            template_path = Path(__file__).parent / "templates" / "dockerignore.template"
+            if template_path.exists():
+                dockerignore_path.write_text(template_path.read_text())
+                log.info("Generated .dockerignore")
+
+    def _validate_module_path(self, agent_path: Path, project_root: Path) -> None:
+        """Validate that the agent path can be converted to a valid Python module path."""
+        try:
+            agent_path = agent_path.resolve()
+            relative_path = agent_path.relative_to(project_root)
+            for part in relative_path.parts[:-1]:  # Check all directory parts
+                if "-" in part:
+                    raise ValueError(
+                        f"Directory name '{part}' contains hyphens which are not valid in Python module paths. "
+                        f"Please rename '{part}' to '{part.replace('-', '_')}' or move your agent file to a "
+                        f"directory with valid Python identifiers."
+                    )
+        except ValueError as e:
+            if "does not start with" in str(e):
+                raise ValueError("Entrypoint file must be within the current project directory") from e
+            raise
+
+    def _get_module_path(self, agent_path: Path, project_root: Path) -> str:
+        """Get the Python module path for the agent file."""
+        try:
+            agent_path = agent_path.resolve()
+            # Get relative path from project root
+            relative_path = agent_path.relative_to(project_root)
+            # Convert to module path (e.g., src/agents/my_agent.py -> src.agents.my_agent)
+            parts = list(relative_path.parts[:-1]) + [relative_path.stem]
+            module_path = ".".join(parts)
+
+            # Handle notebook-generated handlers that start with .bedrock_agentcore
+            if module_path.startswith(".bedrock_agentcore"):
+                # Remove leading dot to make it a valid Python import
+                module_path = module_path[1:]
+
+            return module_path
+        except ValueError:
+            # If agent is outside project root, just use the filename
+            return agent_path.stem
+
+    def _get_current_platform(self) -> str:
+        """Get the current system platform in standardized format."""
+        machine = platform.machine().lower()
+        arch_map = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}
+        arch = arch_map.get(machine, machine)
+        return f"linux/{arch}"
+
+    def build(self, dockerfile_dir: Path, tag: str, platform: Optional[str] = None) -> Tuple[bool, List[str]]:
+        """Build container image."""
+        if not dockerfile_dir.exists():
+            return False, [f"Directory not found: {dockerfile_dir}"]
+
+        dockerfile_path = dockerfile_dir / "Dockerfile"
+        if not dockerfile_path.exists():
+            return False, [f"Dockerfile not found in {dockerfile_dir}"]
+
+        cmd = [self.runtime, "build", "-t", tag]
+        build_platform = platform or self.DEFAULT_PLATFORM
+        cmd.extend(["--platform", build_platform])
+        cmd.append(str(dockerfile_dir))
+
+        return self._execute_command(cmd)
+
+    def run_local(self, tag: str, port: int = 8080, env_vars: Optional[dict] = None) -> subprocess.CompletedProcess:
+        """Run container locally.
+
+        Args:
+            tag: Docker image tag to run
+            port: Port to expose (default: 8080)
+            env_vars: Additional environment variables to pass to container
+        """
+        container_name = f"{tag.split(':')[0]}-{int(time.time())}"
+        cmd = [self.runtime, "run", "-it", "--rm", "-p", f"{port}:8080", "--name", container_name]
+
+        # Use boto3 to get current credentials
+        try:
+            import boto3
+
+            session = boto3.Session()
+            credentials = session.get_credentials()
+
+            if not credentials:
+                raise RuntimeError("No AWS credentials found. Please configure AWS credentials.")
+
+            # Get the frozen credentials (resolves temporary credentials too)
+            frozen_creds = credentials.get_frozen_credentials()
+
+            cmd.extend(["-e", f"AWS_ACCESS_KEY_ID={frozen_creds.access_key}"])
+            cmd.extend(["-e", f"AWS_SECRET_ACCESS_KEY={frozen_creds.secret_key}"])
+
+            if frozen_creds.token:
+                cmd.extend(["-e", f"AWS_SESSION_TOKEN={frozen_creds.token}"])
+
+        except ImportError:
+            raise RuntimeError("boto3 is required for local mode. Please install it.") from None
+
+        # Add additional environment variables if provided
+        if env_vars:
+            for key, value in env_vars.items():
+                cmd.extend(["-e", f"{key}={value}"])
+
+        cmd.append(tag)
+        return subprocess.run(cmd, check=False)  # nosec B603
+
+    def login(self, registry: str, username: str, password: str) -> bool:
+        """Login to registry."""
+        log.info("Authenticating with registry...")
+        try:
+            subprocess.run(  # nosec B603
+                [self.runtime, "login", "--username", username, "--password-stdin", registry],
+                input=password.encode(),
+                capture_output=True,
+                check=True,
+            )
+            log.info("Registry authentication successful")
+            return True
+        except subprocess.CalledProcessError:
+            log.error("Registry authentication failed")
+            return False
+
+    def tag(self, source: str, target: str) -> bool:
+        """Tag an image."""
+        log.info("Tagging image: %s -> %s", source, target)
+        try:
+            subprocess.run([self.runtime, "tag", source, target], check=True)  # nosec B603
+            return True
+        except subprocess.CalledProcessError:
+            log.error("Failed to tag image")
+            return False
+
+    def push(self, tag: str) -> bool:
+        """Push image to registry."""
+        log.info("Pushing image to registry...")
+        try:
+            subprocess.run([self.runtime, "push", tag], check=True)  # nosec B603
+            log.info("Image pushed successfully")
+            return True
+        except subprocess.CalledProcessError:
+            log.error("Failed to push image")
+            return False
+
+    def _execute_command(self, cmd: List[str]) -> Tuple[bool, List[str]]:
+        """Execute command and capture output."""
+        try:
+            process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1)  # nosec B603
+
+            output_lines = []
+            if process.stdout:
+                for line in process.stdout:
+                    line = line.rstrip()
+                    if line:
+                        # Log output at source as it streams
+                        if "error" in line.lower() or "failed" in line.lower():
+                            log.error("Build: %s", line)
+                        elif "Successfully" in line:
+                            log.info("Build: %s", line)
+                        else:
+                            log.debug("Build: %s", line)
+
+                        output_lines.append(line)
+
+            process.wait()
+            return process.returncode == 0, output_lines
+
+        except (subprocess.SubprocessError, OSError) as e:
+            log.error("Command execution failed: %s", str(e))
+            return False, [str(e)]

bedrock_agentcore_starter_toolkit/utils/runtime/entrypoint.py

@@ -0,0 +1,197 @@
+"""Bedrock AgentCore utility functions for parsing and importing Bedrock AgentCore applications."""
+
+import logging
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Tuple
+
+log = logging.getLogger(__name__)
+
+
+def parse_entrypoint(entrypoint: str) -> Tuple[Path, str]:
+    """Parse entrypoint into file path and name.
+
+    Args:
+        entrypoint: Entrypoint specification (e.g., "app.py")
+
+    Returns:
+        Tuple of (file_path, bedrock_agentcore_name)
+
+    Raises:
+        ValueError: If entrypoint cannot be parsed or file doesn't exist
+    """
+    file_path = Path(entrypoint).resolve()
+    if not file_path.exists():
+        log.error("Entrypoint file not found: %s", file_path)
+        raise ValueError(f"File not found: {file_path}")
+
+    file_name = file_path.stem
+
+    log.info("Entrypoint parsed: file=%s, bedrock_agentcore_name=%s", file_path, file_name)
+    return file_path, file_name
+
+
+def handle_requirements_file(
+    requirements_file: Optional[str] = None, build_dir: Optional[Path] = None
+) -> Optional[str]:
+    """Handle requirements file selection and validation.
+
+    Args:
+        requirements_file: Optional path to requirements file
+        build_dir: Build directory, defaults to current directory
+
+    Returns:
+        Validated requirements file path or None
+
+    Raises:
+        ValueError: If specified requirements file is invalid
+    """
+    if build_dir is None:
+        build_dir = Path.cwd()
+
+    if requirements_file:
+        log.info("Validating requirements file: %s", requirements_file)
+        # Validate provided requirements file
+        try:
+            deps = validate_requirements_file(build_dir, requirements_file)
+            log.info("Requirements file validated: %s", requirements_file)
+            return requirements_file
+        except (FileNotFoundError, ValueError) as e:
+            log.error("Requirements file validation failed: %s", e)
+            raise ValueError(str(e)) from e
+
+    # Auto-detect dependencies (no validation needed, just detection)
+    log.info("Auto-detecting dependencies in: %s", build_dir)
+    deps = detect_dependencies(build_dir)
+
+    if deps.found:
+        log.info("Dependencies detected: %s", deps.file)
+        return None  # Let operations handle the detected file
+    else:
+        log.info("No dependency files found")
+        return None  # No file found or specified
+
+
+@dataclass
+class DependencyInfo:
+    """Information about project dependencies."""
+
+    file: Optional[str]  # Relative path for Docker context
+    type: str  # "requirements", "pyproject", or "notfound"
+    resolved_path: Optional[str] = None  # Absolute path for validation
+    install_path: Optional[str] = None  # Path for pip install command
+
+    @property
+    def found(self) -> bool:
+        """Whether a dependency file was found."""
+        return self.file is not None
+
+    @property
+    def is_pyproject(self) -> bool:
+        """Whether this is a pyproject.toml file."""
+        return self.type == "pyproject"
+
+    @property
+    def is_requirements(self) -> bool:
+        """Whether this is a requirements file."""
+        return self.type == "requirements"
+
+    @property
+    def is_root_package(self) -> bool:
+        """Whether this dependency points to the root package."""
+        return self.is_pyproject and self.install_path == "."
+
+
+def detect_dependencies(package_dir: Path, explicit_file: Optional[str] = None) -> DependencyInfo:
+    """Detect dependency file, with optional explicit override."""
+    if explicit_file:
+        return _handle_explicit_file(package_dir, explicit_file)
+
+    # Check for requirements.txt first (prioritized for notebook workflows)
+    requirements_path = package_dir / "requirements.txt"
+    if requirements_path.exists():
+        return DependencyInfo(
+            file="requirements.txt", type="requirements", resolved_path=str(requirements_path.resolve())
+        )
+
+    # Check for pyproject.toml
+    pyproject_path = package_dir / "pyproject.toml"
+    if pyproject_path.exists():
+        return DependencyInfo(
+            file="pyproject.toml",
+            type="pyproject",
+            resolved_path=str(pyproject_path.resolve()),
+            install_path=".",  # Install from current directory
+        )
+
+    return DependencyInfo(file=None, type="notfound")
+
+
+def _handle_explicit_file(package_dir: Path, explicit_file: str) -> DependencyInfo:
+    """Handle explicitly provided dependency file."""
+    # Handle both absolute and relative paths
+    explicit_path = Path(explicit_file)
+    if not explicit_path.is_absolute():
+        explicit_path = package_dir / explicit_path
+
+    # Resolve the path to handle .. and . components
+    explicit_path = explicit_path.resolve()
+
+    if not explicit_path.exists():
+        raise FileNotFoundError(f"Specified requirements file not found: {explicit_path}")
+
+    # Ensure file is within project directory for Docker context
+    try:
+        relative_path = explicit_path.relative_to(package_dir.resolve())
+        file_path = str(relative_path)
+    except ValueError:
+        raise ValueError(
+            f"Requirements file must be within project directory. File: {explicit_path}, Project: {package_dir}"
+        ) from None
+
+    # Determine type and install path
+    file_type = "requirements" if explicit_file.endswith((".txt", ".in")) else "pyproject"
+    install_path = None
+
+    if file_type == "pyproject":
+        if "/" in file_path:
+            # pyproject.toml in subdirectory - install from that directory
+            install_path = str(Path(file_path).parent)
+        else:
+            # pyproject.toml in root - install from current directory
+            install_path = "."
+
+    return DependencyInfo(file=file_path, type=file_type, resolved_path=str(explicit_path), install_path=install_path)
+
+
+def validate_requirements_file(build_dir: Path, requirements_file: str) -> DependencyInfo:
+    """Validate the provided requirements file path and return DependencyInfo."""
+    # Check if the provided path exists and is a file
+    file_path = Path(requirements_file)
+    if not file_path.is_absolute():
+        file_path = build_dir / file_path
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    if file_path.is_dir():
+        raise ValueError(
+            f"Path is a directory, not a file: {file_path}. "
+            f"Please specify a requirements file (requirements.txt, pyproject.toml, etc.)"
+        )
+
+    # Validate that it's a recognized dependency file type (flexible validation)
+    if not (file_path.suffix in [".txt", ".in"] or file_path.name == "pyproject.toml"):
+        raise ValueError(
+            f"'{file_path.name}' is not a supported dependency file. "
+            f"Supported formats: *.txt, *.in (pip requirements), or pyproject.toml"
+        )
+
+    # Use the existing detect_dependencies function to process the file
+    return detect_dependencies(build_dir, explicit_file=requirements_file)
+
+
+def get_python_version() -> str:
+    """Get Python version for Docker image."""
+    return f"{sys.version_info.major}.{sys.version_info.minor}"

bedrock_agentcore_starter_toolkit/utils/runtime/logs.py

@@ -0,0 +1,33 @@
+"""Utility functions for agent log information."""
+
+from typing import Optional, Tuple
+
+
+def get_agent_log_paths(agent_id: str, endpoint_name: Optional[str] = None) -> Tuple[str, str]:
+    """Get CloudWatch log group paths for an agent.
+
+    Args:
+        agent_id: The agent ID
+        endpoint_name: The endpoint name (defaults to "DEFAULT")
+
+    Returns:
+        Tuple of (runtime_log_group, otel_log_group)
+    """
+    endpoint_name = endpoint_name or "DEFAULT"
+    runtime_log_group = f"/aws/bedrock-agentcore/runtimes/{agent_id}-{endpoint_name}"
+    otel_log_group = f"/aws/bedrock-agentcore/runtimes/{agent_id}-{endpoint_name}/runtime-logs"
+    return runtime_log_group, otel_log_group
+
+
+def get_aws_tail_commands(log_group: str) -> tuple[str, str]:
+    """Get AWS CLI tail commands for a log group.
+
+    Args:
+        log_group: The CloudWatch log group path
+
+    Returns:
+        Tuple of (follow_command, since_command)
+    """
+    follow_cmd = f"aws logs tail {log_group} --follow"
+    since_cmd = f"aws logs tail {log_group} --since 1h"
+    return follow_cmd, since_cmd