agentcore-cli 0.31.1__py3-none-any.whl

agentcore/templates/_js.py

@@ -0,0 +1,164 @@
+"""JavaScript value semantics needed to render Handlebars templates exactly like upstream.
+
+Template data is plain Python (dict / list / str / int / float / bool / None). ``None`` stands for
+JavaScript ``undefined`` (unset optional fields are omitted from the data), except inside containers
+passed to ``JSON.stringify`` where it serializes as ``null``.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from decimal import Decimal
+from typing import Any
+
+# Characters matched by JavaScript `\s`.
+_JS_WHITESPACE_CODEPOINTS = (
+    0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x20, 0xA0, 0x1680, *range(0x2000, 0x200B),
+    0x2028, 0x2029, 0x202F, 0x205F, 0x3000, 0xFEFF,
+)  # fmt: skip
+JS_WHITESPACE = "".join(map(chr, _JS_WHITESPACE_CODEPOINTS))
+JS_WS = "[" + re.escape(JS_WHITESPACE) + "]"
+
+_ARRAY_INDEX_RE = re.compile(r"0|[1-9][0-9]*")
+_MAX_ARRAY_INDEX = 2**32 - 2
+
+
+def is_number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def js_truthy(value: object) -> bool:
+    """``Boolean(value)``: empty containers are truthy, ``0``/``NaN``/``""``/null/undefined are not."""
+    if value is None or value is False:
+        return False
+    if is_number(value):
+        return not (value == 0 or (isinstance(value, float) and math.isnan(value)))
+    if isinstance(value, str):
+        return value != ""
+    return True
+
+
+def hb_is_empty(value: object) -> bool:
+    """Handlebars ``Utils.isEmpty``: falsy (except 0) or an empty array."""
+    if not js_truthy(value) and not (is_number(value) and value == 0):
+        return True
+    return isinstance(value, (list, tuple)) and len(value) == 0
+
+
+def _js_type(value: object) -> str:
+    if value is None:
+        return "undefined"
+    if isinstance(value, bool):
+        return "boolean"
+    if is_number(value):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    return "object"
+
+
+def js_strict_equals(a: object, b: object) -> bool:
+    """``a === b``."""
+    kind = _js_type(a)
+    if kind != _js_type(b):
+        return False
+    if kind == "object":
+        return a is b
+    return a == b  # NaN != NaN, matching JS.
+
+
+def js_same_value_zero(a: object, b: object) -> bool:
+    """SameValueZero, as used by ``Array.prototype.includes``."""
+    if is_number(a) and is_number(b) and math.isnan(a) and math.isnan(b):  # type: ignore[arg-type]
+        return True
+    return js_strict_equals(a, b)
+
+
+def js_number_to_string(value: float) -> str:
+    """``Number.prototype.toString()`` (ECMAScript Number::toString with radix 10)."""
+    if isinstance(value, int):
+        if abs(value) < 2**53:
+            return str(value)
+        value = float(value)
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    # repr() yields the shortest round-tripping digits, the same digits JavaScript picks.
+    _, digit_tuple, exponent = Decimal(repr(abs(value))).as_tuple()
+    digits = "".join(map(str, digit_tuple)).rstrip("0")
+    assert isinstance(exponent, int)
+    exponent += len("".join(map(str, digit_tuple))) - len(digits)
+    k = len(digits)
+    n = k + exponent  # value = 0.digits * 10**n
+    if k <= n <= 21:
+        body = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + digits
+    else:
+        e = n - 1
+        exp = f"e{'+' if e >= 0 else '-'}{abs(e)}"
+        body = digits + exp if k == 1 else digits[0] + "." + digits[1:] + exp
+    return sign + body
+
+
+def js_to_string(value: object) -> str:
+    """``String(value)`` for template data."""
+    if value is None:
+        return "undefined"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if is_number(value):
+        return js_number_to_string(value)  # type: ignore[arg-type]
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (list, tuple)):
+        return ",".join("" if item is None else js_to_string(item) for item in value)
+    return "[object Object]"
+
+
+def js_object_keys(obj: Mapping[Any, Any]) -> list[str]:
+    """``Object.keys`` order: array-index keys ascending, then string keys in insertion order."""
+    keys = [k if isinstance(k, str) else js_to_string(k) for k in obj]
+    index_keys = sorted((k for k in keys if _ARRAY_INDEX_RE.fullmatch(k) and int(k) <= _MAX_ARRAY_INDEX), key=int)
+    index_set = set(index_keys)
+    return index_keys + [k for k in keys if k not in index_set]
+
+
+def _json_value(value: object) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if is_number(value):
+        if isinstance(value, float) and not math.isfinite(value):
+            return "null"
+        return js_number_to_string(value)  # type: ignore[arg-type]
+    if isinstance(value, str):
+        # Python's escaping with ensure_ascii=False matches JSON.stringify (\b\f\n\r\t, \u00xx).
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_json_value(item) for item in value) + "]"
+    if isinstance(value, Mapping):
+        lookup = {(k if isinstance(k, str) else js_to_string(k)): v for k, v in value.items()}
+        return "{" + ",".join(f"{_json_value(k)}:{_json_value(lookup[k])}" for k in js_object_keys(value)) + "}"
+    raise TypeError(f"Cannot JSON.stringify value of type {type(value).__name__}")
+
+
+def json_stringify(value: object) -> str | None:
+    """``JSON.stringify(value)`` (compact). Returns None for undefined (top-level ``None``)."""
+    if value is None:
+        return None
+    return _json_value(value)
+
+
+def utf16_len(char: str) -> int:
+    return 2 if ord(char) > 0xFFFF else 1

agentcore/templates/base_renderer.py

@@ -0,0 +1,107 @@
+"""Base class of the agent template renderers (port of ``BaseRenderer.ts``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Any
+
+from agentcore.lib import APP_DIR
+from agentcore.templates.render import copy_and_render_dir
+from agentcore.templates.types import AgentRenderConfig
+
+
+@dataclass(frozen=True)
+class RendererContext:
+    output_dir: str
+
+
+class BaseRenderer:
+    def __init__(
+        self,
+        config: AgentRenderConfig,
+        sdk_name: str,
+        base_template_dir: Traversable,
+        protocol_mode: str | None = None,
+    ) -> None:
+        self.config = config
+        self.sdk_name = sdk_name
+        self.base_template_dir = base_template_dir
+        self.protocol_mode = (protocol_mode or config.protocol or "HTTP").lower()
+
+    def should_render_memory(self) -> bool:
+        return self.config.has_memory
+
+    def should_render_payment(self) -> bool:
+        return self.config.has_payment
+
+    def should_render_execution_limits(self) -> bool:
+        # Upstream: !!(maxIterations ?? maxTokens ?? timeoutSeconds) -- the first non-null value decides.
+        first = next(
+            (
+                v
+                for v in (self.config.max_iterations, self.config.max_tokens, self.config.timeout_seconds)
+                if v is not None
+            ),
+            None,
+        )
+        return bool(first)
+
+    def get_template_dir(self) -> Traversable:
+        language = self.config.target_language.lower()
+        return self.base_template_dir / language / self.protocol_mode / self.sdk_name
+
+    def template_data(self, context: RendererContext) -> dict[str, Any]:
+        return {
+            **self.config.to_template_data(),
+            "outputDir": context.output_dir,
+            "projectName": self.config.name,
+            "Name": self.config.name,
+        }
+
+    def render(self, context: RendererContext) -> None:
+        template_dir = self.get_template_dir()
+        # Agents are placed in app/<agentName>/.
+        project_dir = Path(context.output_dir) / APP_DIR / self.config.name
+        data = self.template_data(context)
+
+        copy_and_render_dir(template_dir / "base", project_dir, data)
+
+        # Capability templates render only when the SDK ships them.
+        if self.should_render_memory():
+            memory_dir = template_dir / "capabilities" / "memory"
+            if memory_dir.is_dir():
+                copy_and_render_dir(memory_dir, project_dir / "memory", data)
+
+        if self.should_render_payment():
+            payments_dir = template_dir / "capabilities" / "payments"
+            if payments_dir.is_dir():
+                capabilities_dir = project_dir / "capabilities"
+                capabilities_dir.mkdir(parents=True, exist_ok=True)
+                init_path = capabilities_dir / "__init__.py"
+                if not init_path.exists():
+                    init_path.write_text("")
+                copy_and_render_dir(payments_dir, capabilities_dir / "payments", data)
+
+        if self.should_render_execution_limits():
+            limits_dir = template_dir / "capabilities" / "execution-limits"
+            if limits_dir.is_dir():
+                copy_and_render_dir(limits_dir, project_dir, data)
+
+        # Container builds get a Dockerfile and .dockerignore.
+        if self.config.build_type == "Container":
+            language = self.config.target_language.lower()
+            container_dir = self.base_template_dir / "container" / language
+            if container_dir.is_dir():
+                exclude = {"Dockerfile"} if self.config.dockerfile else None
+                enable_otel = self.config.enable_otel if self.config.enable_otel is not None else True
+                copy_and_render_dir(
+                    container_dir,
+                    project_dir,
+                    {**data, "entrypoint": "main", "enableOtel": enable_otel},
+                    exclude=exclude,
+                )
+
+
+__all__ = ["BaseRenderer", "RendererContext"]

agentcore/templates/cdk_renderer.py

@@ -0,0 +1,129 @@
+"""Vends the CDK project into a new AgentCore project (port of ``CDKRenderer.ts``)."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from agentcore.cdk.constants import CDK_PROJECT_DIR
+from agentcore.lib import CONFIG_DIR, run_subprocess_capture
+from agentcore.templates.render import copy_dir
+from agentcore.templates.schema_assets import LLM_CONTEXT_FILES
+from agentcore.templates.template_root import get_template_path
+
+LLM_CONTEXT_DIR = ".llm-context"
+BUNDLED_CDK_TARBALL = "bundled-agentcore-cdk.tgz"
+
+
+class CreateLogger(Protocol):
+    """The progress-logging subset of upstream's ``CreateLogger`` used here."""
+
+    def log_sub_step(self, message: str) -> None: ...
+
+    def log_command(self, command: str, args: list[str]) -> None: ...
+
+    def log_command_output(self, output: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class CDKRendererContext:
+    # The project root; the CDK project is created at <project_root>/agentcore/cdk/.
+    project_root: str | os.PathLike[str]
+    logger: CreateLogger | None = None
+
+
+class CDKRenderer:
+    """Creates ``<project_root>/agentcore/cdk/`` and writes AGENTS.md, README.md and ``.llm-context/``."""
+
+    def __init__(self) -> None:
+        self.template_dir = get_template_path("cdk")
+        self.agents_template_dir = get_template_path("agents")
+        self.assets_dir = get_template_path()
+
+    def render(self, context: CDKRendererContext) -> Path:
+        logger = context.logger
+        project_root = Path(context.project_root)
+        config_dir = project_root / CONFIG_DIR
+        output_dir = config_dir / CDK_PROJECT_DIR
+
+        _sub_step(logger, "Copying CDK project template...")
+        copy_dir(self.template_dir, output_dir)
+        _sub_step(logger, "CDK template copied")
+
+        _sub_step(logger, "Copying AGENTS.md template...")
+        (project_root / "AGENTS.md").write_bytes((self.agents_template_dir / "AGENTS.md").read_bytes())
+        _sub_step(logger, "AGENTS.md copied")
+
+        _sub_step(logger, "Copying README.md template...")
+        (project_root / "README.md").write_bytes((self.assets_dir / "README.md").read_bytes())
+        _sub_step(logger, "README.md copied")
+
+        _sub_step(logger, "Writing LLM context files...")
+        self._write_llm_context(config_dir)
+        _sub_step(logger, "LLM context files written")
+
+        # Skip slow npm operations in test mode.
+        if os.environ.get("AGENTCORE_SKIP_INSTALL"):
+            return output_dir
+
+        _sub_step(logger, "Running npm install (this may take a while)...")
+        started = time.monotonic()
+        self._run_npm(output_dir, ["install"], logger, "npm install failed with code {code}: {stderr}")
+        _sub_step(logger, f"npm install completed ({time.monotonic() - started:.1f}s)")
+
+        # A CLI built with a bundled CDK constructs tarball overrides the registry version.
+        self._install_bundled_cdk_if_present(output_dir, logger)
+
+        _sub_step(logger, "Running npm run format...")
+        self._run_npm(output_dir, ["run", "format"], logger, "npm run format failed with code {code}: {stderr}")
+        _sub_step(logger, "Formatting completed")
+
+        return output_dir
+
+    @staticmethod
+    def _run_npm(cwd: Path, args: list[str], logger: CreateLogger | None, error: str, log_command: bool = True) -> None:
+        if logger and log_command:
+            logger.log_command("npm", args)
+        result = run_subprocess_capture("npm", args, cwd=cwd)
+        if logger:
+            if result.stdout:
+                logger.log_command_output(result.stdout)
+            if result.stderr:
+                logger.log_command_output(result.stderr)
+        if result.code != 0:
+            raise RuntimeError(error.format(code=result.code, stderr=result.stderr))
+
+    def _install_bundled_cdk_if_present(self, cdk_project_dir: Path, logger: CreateLogger | None) -> None:
+        bundled = self.assets_dir / BUNDLED_CDK_TARBALL
+        if not bundled.is_file():
+            return
+        # Copied into the project so the file: reference in package.json stays valid for later installs.
+        (cdk_project_dir / BUNDLED_CDK_TARBALL).write_bytes(bundled.read_bytes())
+        _sub_step(logger, "Installing bundled @aws/agentcore-cdk override...")
+        self._run_npm(
+            cdk_project_dir,
+            ["install", f"./{BUNDLED_CDK_TARBALL}"],
+            logger,
+            "Failed to install bundled @aws/agentcore-cdk: {stderr}",
+            log_command=False,
+        )
+        _sub_step(logger, "Bundled @aws/agentcore-cdk installed")
+
+    @staticmethod
+    def _write_llm_context(config_dir: Path) -> None:
+        llm_context_dir = config_dir / LLM_CONTEXT_DIR
+        llm_context_dir.mkdir(parents=True, exist_ok=True)
+        for filename, content in LLM_CONTEXT_FILES.items():
+            with open(llm_context_dir / filename, "w", encoding="utf-8", newline="") as fh:
+                fh.write(content)
+
+
+def _sub_step(logger: CreateLogger | None, message: str) -> None:
+    if logger:
+        logger.log_sub_step(message)
+
+
+__all__ = ["LLM_CONTEXT_DIR", "CDKRenderer", "CDKRendererContext", "CreateLogger"]

agentcore/templates/evaluator_renderer.py

@@ -0,0 +1,39 @@
+"""Evaluator project templates (port of ``EvaluatorRenderer.ts``)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, TypedDict
+
+from agentcore.templates.render import copy_and_render_dir
+from agentcore.templates.template_root import get_template_path
+
+
+def render_code_based_evaluator_template(evaluator_name: str, output_dir: str | os.PathLike[str]) -> None:
+    """Render the code-based (Lambda) evaluator template; ``{{ Name }}`` is the evaluator name."""
+    copy_and_render_dir(get_template_path("evaluators", "python-lambda"), output_dir, {"Name": evaluator_name})
+
+
+class ThirdPartyEvaluatorTemplateData(TypedDict, total=False):
+    Name: str
+    EvaluatorClass: str
+    EvaluatorParams: str
+    # True when the LLM judge runs on Bedrock instead of the library's default (OpenAI).
+    ModelProviderBedrock: bool
+    # Bedrock model ID (required when ModelProviderBedrock is true).
+    Model: str
+
+
+def render_third_party_evaluator_template(
+    template_dir_name: str,
+    data: ThirdPartyEvaluatorTemplateData | dict[str, Any],
+    output_dir: str | os.PathLike[str],
+) -> None:
+    copy_and_render_dir(get_template_path("evaluators", template_dir_name), output_dir, dict(data))
+
+
+__all__ = [
+    "ThirdPartyEvaluatorTemplateData",
+    "render_code_based_evaluator_template",
+    "render_third_party_evaluator_template",
+]

agentcore/templates/gateway_target_renderer.py

@@ -0,0 +1,69 @@
+"""Gateway target (MCP tool) project templates (port of ``GatewayTargetRenderer.ts``)."""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from agentcore.schema import ToolDefinition
+from agentcore.templates.render import copy_and_render_dir
+from agentcore.templates.template_root import get_template_path
+
+ComputeHost = Literal["Lambda", "AgentCoreRuntime"]
+
+
+def _tool(name: str, description: str, input_schema: dict[str, object]) -> ToolDefinition:
+    return ToolDefinition.model_validate({"name": name, "description": description, "inputSchema": input_schema})
+
+
+# Tools of the Lambda template, each with a complete inputSchema for gateway integration.
+LAMBDA_TEMPLATE_TOOLS: tuple[ToolDefinition, ...] = (
+    _tool(
+        "lookup_ip",
+        "Look up geolocation and network info for an IP address",
+        {
+            "type": "object",
+            "properties": {"ip_address": {"type": "string", "description": "IPv4 or IPv6 address to look up"}},
+            "required": ["ip_address"],
+        },
+    ),
+    _tool("get_random_user", "Generate a random user profile for testing or mock data", {"type": "object"}),
+    _tool(
+        "fetch_post",
+        "Fetch a post by ID from JSONPlaceholder API",
+        {
+            "type": "object",
+            "properties": {"post_id": {"type": "integer", "description": "The post ID (1-100)"}},
+            "required": ["post_id"],
+        },
+    ),
+)
+
+
+def get_template_tool_definitions(tool_name: str, host: ComputeHost) -> list[ToolDefinition]:
+    """Tool definitions for a template: the Lambda tools prefixed with ``tool_name``, or one generic tool."""
+    if host == "Lambda":
+        # The prefix avoids conflicts when several Lambda tools are added to the same project.
+        return [tool.model_copy(update={"name": f"{tool_name}_{tool.name}"}) for tool in LAMBDA_TEMPLATE_TOOLS]
+    return [_tool(tool_name, f"Tool for {tool_name}", {"type": "object"})]
+
+
+def render_gateway_target_template(
+    tool_name: str,
+    output_dir: str | os.PathLike[str],
+    language: str,
+    host: ComputeHost = "AgentCoreRuntime",
+) -> None:
+    """Render a gateway target project; ``{{ Name }}`` is the tool name. Only Python is supported."""
+    if language != "Python":
+        raise ValueError(f"Gateway target templates for {language} are not yet supported.")
+    template_subdir = "python-lambda" if host == "Lambda" else "python"
+    copy_and_render_dir(get_template_path("mcp", template_subdir), output_dir, {"Name": tool_name})
+
+
+__all__ = [
+    "LAMBDA_TEMPLATE_TOOLS",
+    "ComputeHost",
+    "get_template_tool_definitions",
+    "render_gateway_target_template",
+]

agentcore/templates/llm_context/README.md

@@ -0,0 +1,16 @@
+# LLM Context Files
+
+**DO NOT EDIT THESE FILES** - They are read-only reference for AI coding assistants.
+
+## Files
+
+| File             | JSON Config        | Purpose                               |
+| ---------------- | ------------------ | ------------------------------------- |
+| `agentcore.ts`   | `agentcore.json`   | Project resources, including gateways |
+| `aws-targets.ts` | `aws-targets.json` | Deployment targets (account + region) |
+
+## Usage
+
+When editing AgentCore JSON config files, reference the corresponding `.ts` file here for type definitions, exact enum
+values, defaults, and validation constraints (marked with `@regex`, `@min`, and `@max`). Run `agentcore validate` after
+making changes.