agentcore-cli 0.31.1__py3-none-any.whl

agentcore/schema/schemas/agentcore_project.py

@@ -0,0 +1,530 @@
+"""Project spec, i.e. agentcore.json (port of ``schemas/agentcore-project.ts``).
+
+Flat resource model where agents, memories, credentials, etc. are top-level and all resources within
+a project implicitly have access to each other.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Final, Literal, get_args
+
+from pydantic import AfterValidator, Field, TypeAdapter, model_validator
+
+from .._zod import (
+    Issue,
+    StrictModel,
+    ZBool,
+    ZodModel,
+    array_checks,
+    js_regex,
+    js_trim,
+    raise_issues,
+    unique_by,
+    zint,
+    zstr,
+)
+from ..constants import is_reserved_project_name
+from .agent_env import AgentEnvSpec, CapacityProviderVolumeFilesystem
+from .mcp import REAL_KB_ID_PATTERN, AgentCoreGateway, AgentCoreGatewayTarget, AgentCoreMcpRuntimeTool
+from .primitives.ab_test import ABTest
+from .primitives.capacity_provider import CapacityProvider
+from .primitives.config_bundle import ConfigBundle
+from .primitives.dataset import Dataset
+from .primitives.evaluator import EvaluationLevel, EvaluatorConfig, EvaluatorName, KmsKeyArn
+from .primitives.harness import HarnessName
+from .primitives.knowledge_base import KnowledgeBase
+from .primitives.memory import MemoryStrategy
+from .primitives.online_eval_config import OnlineEvalConfig
+from .primitives.payment import PaymentManager, PaymentProvider
+from .primitives.policy import PolicyEngine
+from .primitives.tags import Tags
+
+# ============================================================================
+# ManagedBy
+# ============================================================================
+
+ManagedBy = Literal["CDK"]
+
+# ============================================================================
+# Project Name
+# ============================================================================
+
+# CLI-only concept; max 23 so projectName + "_" + agentName fits the 48-char runtime name limit.
+ProjectName = zstr(
+    min=1,
+    max=23,
+    min_msg="Project name is required",
+    max_msg="Project name must be 23 characters or less",
+    pattern=r"^[A-Za-z][A-Za-z0-9]{0,22}$",
+    pattern_msg="Project name must start with a letter and contain only alphanumeric characters",
+    refines=(
+        (
+            lambda name: not is_reserved_project_name(name),
+            "This name conflicts with a reserved package dependency. Please choose a different name.",
+        ),
+    ),
+)
+
+# ============================================================================
+# Memory
+# ============================================================================
+
+MemoryType = Literal["AgentCoreMemory"]
+
+# Same constraints as agent runtime names (API_CreateMemory).
+MemoryName = zstr(
+    min=1,
+    max=48,
+    min_msg="Name is required",
+    pattern=r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$",
+    pattern_msg="Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
+)
+
+StreamContentLevel = Literal["FULL_CONTENT", "METADATA_ONLY"]
+STREAM_CONTENT_LEVELS: Final[tuple[StreamContentLevel, ...]] = get_args(StreamContentLevel)
+
+
+class StreamContentConfiguration(ZodModel):
+    type: Literal["MEMORY_RECORDS"]
+    level: StreamContentLevel
+
+
+class KinesisStreamDelivery(ZodModel):
+    data_stream_arn: zstr(min=1)
+    content_configurations: Annotated[list[StreamContentConfiguration], array_checks(min=1)]
+
+
+class StreamDeliveryResource(ZodModel):
+    # Kinesis is currently the only supported delivery type.
+    kinesis: KinesisStreamDelivery
+
+
+class StreamDeliveryResources(ZodModel):
+    resources: Annotated[list[StreamDeliveryResource], array_checks(min=1)]
+
+
+IndexedKeyType = Literal["STRING", "STRINGLIST", "NUMBER"]
+INDEXED_KEY_TYPES: Final[tuple[IndexedKeyType, ...]] = get_args(IndexedKeyType)
+
+# Indexed metadata keys filter memory records on retrieval. They are append-only service-side.
+INDEXED_KEY_NAME_PATTERN: Final = js_regex(r"^[a-zA-Z0-9\s._:/=+@-]+$")
+INDEXED_KEY_NAME_PATTERN_MESSAGE: Final = (
+    "Must contain only alphanumeric characters, whitespace, or the symbols . _ : / = + @ -"
+)
+MAX_INDEXED_KEY_NAME_LENGTH: Final = 128
+MAX_INDEXED_KEYS: Final = 10
+
+
+class IndexedKey(ZodModel):
+    key: zstr(
+        min=1,
+        max=MAX_INDEXED_KEY_NAME_LENGTH,
+        pattern=INDEXED_KEY_NAME_PATTERN,
+        pattern_msg=INDEXED_KEY_NAME_PATTERN_MESSAGE,
+        refines=((lambda s: len(js_trim(s)) > 0, "Key cannot be only whitespace"),),
+    )
+    type: IndexedKeyType
+
+
+class Memory(ZodModel):
+    name: MemoryName
+    event_expiry_duration: zint(ge=3, le=365)
+    # Empty for short-term memory; long-term memory adds strategies.
+    strategies: Annotated[
+        list[MemoryStrategy],
+        array_checks(extra=[unique_by(lambda s: s.type, lambda t: f"Duplicate memory strategy type: {t}")]),
+        Field(default_factory=list),
+    ]
+    indexed_keys: (
+        Annotated[
+            list[IndexedKey],
+            array_checks(
+                max=MAX_INDEXED_KEYS,
+                extra=[unique_by(lambda e: e.key, lambda k: f"Duplicate indexed key: {k}")],
+            ),
+        ]
+        | None
+    ) = None
+    tags: Tags | None = None
+    encryption_key_arn: str | None = None
+    execution_role_arn: str | None = None
+    stream_delivery_resources: StreamDeliveryResources | None = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> Memory:
+        # Indexed keys only make sense for long-term memory (strategies produce LTM records).
+        if self.indexed_keys and not self.strategies:
+            raise_issues(
+                [(("indexedKeys",), "indexedKeys requires at least one memory strategy (long-term memory)")], self
+            )
+        return self
+
+
+# ============================================================================
+# Credentials
+# ============================================================================
+
+# API_CreateApiKeyCredentialProvider.
+CredentialName = zstr(
+    min=1,
+    max=128,
+    min_msg="Credential name is required",
+    max_msg="Credential name must be 128 characters or less",
+    pattern=r"^[a-zA-Z0-9\-_]+$",
+    pattern_msg="Must contain only alphanumeric characters, hyphens, and underscores (1-128 chars)",
+)
+
+CredentialType = Literal["ApiKeyCredentialProvider", "OAuthCredentialProvider", "PaymentCredentialProvider"]
+CREDENTIAL_TYPES: Final[tuple[CredentialType, ...]] = get_args(CredentialType)
+
+
+class ApiKeyCredential(ZodModel):
+    authorizer_type: Literal["ApiKeyCredentialProvider"]
+    name: CredentialName
+
+
+class OAuthCredential(ZodModel):
+    authorizer_type: Literal["OAuthCredentialProvider"]
+    name: CredentialName
+    # Optional for imported providers that already exist in the Identity service.
+    discovery_url: zstr(url=True) | None = None
+    scopes: list[str] | None = None
+    vendor: str = "CustomOauth2"
+    # Auto-created by the CLI (e.g. for CUSTOM_JWT inbound auth).
+    managed: ZBool | None = None
+    usage: Literal["inbound", "outbound"] | None = None
+
+
+class PaymentCredential(ZodModel):
+    authorizer_type: Literal["PaymentCredentialProvider"]
+    name: CredentialName
+    provider: PaymentProvider
+
+
+Credential = Annotated[ApiKeyCredential | OAuthCredential | PaymentCredential, Field(discriminator="authorizer_type")]
+
+# ============================================================================
+# Evaluator
+# ============================================================================
+
+EvaluatorType = Literal["CustomEvaluator"]
+
+
+class Evaluator(ZodModel):
+    name: EvaluatorName
+    level: EvaluationLevel
+    description: str | None = None
+    config: EvaluatorConfig
+    kms_key_arn: KmsKeyArn | None = None
+    tags: Tags | None = None
+
+
+# ============================================================================
+# Harness Registry
+# ============================================================================
+
+
+class HarnessRegistryEntry(ZodModel):
+    name: HarnessName
+    path: zstr(min=1, min_msg="Path to harness config directory is required")
+
+
+# ============================================================================
+# Project (Top Level)
+# ============================================================================
+
+_BUILTIN_EVALUATOR_PREFIX = "Builtin."
+_ARN_PREFIX = "arn:"
+_GATEWAY_REF = js_regex(r"^\{\{gateway:(.+)\}\}$")
+
+
+def _unique(label: str) -> AfterValidator:
+    return array_checks(extra=[unique_by(lambda x: x.name, lambda n: f"Duplicate {label} name: {n}")])
+
+
+def _unique_datasets(items: list[Dataset]) -> list[Dataset]:
+    # Upstream reports duplicates on the array itself (no index in the path).
+    seen: set[str] = set()
+    issues: list[Issue] = []
+    for ds in items:
+        if ds.name in seen:
+            issues.append(((), f"Duplicate dataset name: {ds.name}"))
+        seen.add(ds.name)
+    raise_issues(issues, items)
+    return items
+
+
+class AgentCoreProjectSpec(StrictModel):
+    schema_uri: Annotated[str | None, Field(alias="$schema")] = None
+    name: ProjectName
+    version: zint(ge=1)
+    managed_by: ManagedBy = "CDK"
+    tags: Tags | None = None
+
+    runtimes: Annotated[list[AgentEnvSpec], _unique("agent"), Field(default_factory=list)]
+    memories: Annotated[list[Memory], _unique("memory"), Field(default_factory=list)]
+    knowledge_bases: Annotated[list[KnowledgeBase], _unique("knowledge base"), Field(default_factory=list)]
+    credentials: Annotated[list[Credential], _unique("credential"), Field(default_factory=list)]
+    evaluators: Annotated[list[Evaluator], _unique("evaluator"), Field(default_factory=list)]
+    online_eval_configs: Annotated[list[OnlineEvalConfig], _unique("online eval config"), Field(default_factory=list)]
+    # MCP / Gateway resources (previously in mcp.json).
+    agent_core_gateways: Annotated[list[AgentCoreGateway], _unique("gateway"), Field(default_factory=list)]
+    mcp_runtime_tools: Annotated[list[AgentCoreMcpRuntimeTool], _unique("MCP runtime tool")] | None = None
+    unassigned_targets: Annotated[list[AgentCoreGatewayTarget], _unique("unassigned target")] | None = None
+    policy_engines: Annotated[list[PolicyEngine], _unique("policy engine"), Field(default_factory=list)]
+    config_bundles: Annotated[list[ConfigBundle], _unique("config bundle"), Field(default_factory=list)]
+    ab_tests: Annotated[list[ABTest], _unique("AB test"), Field(default_factory=list)]
+    harnesses: Annotated[list[HarnessRegistryEntry], _unique("harness"), Field(default_factory=list)]
+    datasets: Annotated[list[Dataset], AfterValidator(_unique_datasets)] | None = None
+    capacity_providers: Annotated[list[CapacityProvider], _unique("capacity provider")] | None = None
+    http_gateways: (
+        Annotated[
+            list[Any],
+            array_checks(
+                max=0,
+                max_msg='"httpGateways" is deprecated. Migrate to agentCoreGateways with protocolType: "None", or use '
+                '"agentcore import gateway".',
+            ),
+        ]
+        | None
+    ) = None
+    payments: Annotated[list[PaymentManager], _unique("payment manager")] | None = None
+
+    @model_validator(mode="after")
+    def _refine(self) -> AgentCoreProjectSpec:
+        issues: list[Issue] = []
+        self._check_online_eval_refs(issues)
+        self._check_http_runtime_refs(issues)
+        self._check_capacity_provider_refs(issues)
+        self._check_ab_test_refs(issues)
+        self._check_knowledge_base_refs(issues)
+        self._check_payment_credential_refs(issues)
+        raise_issues(issues, self)
+        return self
+
+    def _check_online_eval_refs(self, issues: list[Issue]) -> None:
+        agent_names = {a.name for a in self.runtimes}
+        evaluator_names = {e.name for e in self.evaluators}
+        for config in self.online_eval_configs:
+            # Only when agent is specified — custom log groups don't need one.
+            if config.agent and config.agent not in agent_names:
+                issues.append(((), f'Online eval config "{config.name}" references unknown agent "{config.agent}"'))
+            for eval_name in config.evaluators or []:
+                # Built-in evaluators and ARN references are externally managed.
+                if eval_name.startswith((_BUILTIN_EVALUATOR_PREFIX, _ARN_PREFIX)):
+                    continue
+                if eval_name not in evaluator_names:
+                    issues.append(
+                        ((), f'Online eval config "{config.name}" references unknown evaluator "{eval_name}"')
+                    )
+
+    def _check_http_runtime_refs(self, issues: list[Issue]) -> None:
+        runtimes = {r.name: r for r in self.runtimes}
+        for gw in self.agent_core_gateways:
+            for target in gw.targets:
+                if target.target_type != "httpRuntime" or target.http_runtime is None:
+                    continue
+                ref = target.http_runtime
+                runtime = runtimes.get(ref.runtime)
+                if runtime is None:
+                    issues.append(
+                        (
+                            (),
+                            (
+                                f'Gateway "{gw.name}" target "{target.name}" references unknown runtime "{ref.runtime}". '
+                                "Check spec.runtimes."
+                            ),
+                        )
+                    )
+                elif ref.runtime_endpoint and ref.runtime_endpoint not in ("DEFAULT", *(runtime.endpoints or {})):
+                    issues.append(
+                        (
+                            (),
+                            (
+                                f'Gateway "{gw.name}" target "{target.name}" references endpoint '
+                                f'"{ref.runtime_endpoint}" which does not exist on runtime "{ref.runtime}".'
+                            ),
+                        )
+                    )
+
+    def _check_capacity_provider_refs(self, issues: list[Issue]) -> None:
+        # A sibling name must resolve to a capacityProviders[] entry; ARNs are external and unchecked.
+        by_name = {cp.name: cp for cp in self.capacity_providers or []}
+        for runtime in self.runtimes:
+            cpc = runtime.capacity_provider_configuration
+            cp_name = cpc.capacity_provider_name if cpc else None
+            if cp_name and cp_name not in by_name:
+                issues.append(
+                    (
+                        (),
+                        (
+                            f'Runtime "{runtime.name}" references unknown capacity provider "{cp_name}". '
+                            "Check spec.capacityProviders."
+                        ),
+                    )
+                )
+            mounts = [
+                fc for fc in runtime.filesystem_configurations or [] if isinstance(fc, CapacityProviderVolumeFilesystem)
+            ]
+            cp = by_name.get(cp_name) if cp_name else None
+            if mounts and cp is not None:
+                defined = {v.ebs_configuration.name for v in cp.compute_configuration.ec2_configuration.volumes or []}
+                for fc in mounts:
+                    volume_name = fc.capacity_provider_volume.volume_name
+                    if volume_name not in defined:
+                        issues.append(
+                            (
+                                (),
+                                (
+                                    f'Runtime "{runtime.name}" mounts capacity provider volume "{volume_name}" which is '
+                                    f'not defined on capacity provider "{cp_name}". Check its '
+                                    "computeConfiguration.ec2Configuration.volumes."
+                                ),
+                            )
+                        )
+
+    def _check_ab_test_refs(self, issues: list[Issue]) -> None:
+        gateways = {gw.name: gw for gw in self.agent_core_gateways}
+        for test in self.ab_tests:
+            match = _GATEWAY_REF.search(test.gateway_ref)
+            if not match:
+                continue
+            gw_name = match.group(1)
+            gw = gateways.get(gw_name)
+            if gw is None:
+                issues.append(
+                    (
+                        (),
+                        f'AB test "{test.name}" references gateway "{gw_name}" which does not exist in agentCoreGateways',
+                    )
+                )
+            # Target-based tests: variant target names must exist on the gateway.
+            if test.mode == "target-based" and gw is not None:
+                target_names = {t.name for t in gw.targets}
+                for variant in test.variants:
+                    target = variant.variant_configuration.target
+                    if target is not None and target.target_name and target.target_name not in target_names:
+                        issues.append(
+                            (
+                                (),
+                                (
+                                    f'AB test "{test.name}" variant "{variant.name}" references target '
+                                    f'"{target.target_name}" which does not exist in gateway "{gw_name}" targets'
+                                ),
+                            )
+                        )
+
+    def _check_knowledge_base_refs(self, issues: list[Issue]) -> None:
+        # A KB reference is either a project KB name or a literal 10-char external KB ID.
+        kb_names = {kb.name for kb in self.knowledge_bases}
+
+        def validate(target: AgentCoreGatewayTarget, value: str, field_label: str) -> None:
+            if REAL_KB_ID_PATTERN.search(value):
+                if value in kb_names:
+                    issues.append(
+                        (
+                            (),
+                            (
+                                f'Connector target "{target.name}" {field_label} "{value}" looks like a literal KB ID but '
+                                "also matches a knowledgeBases[] entry. Rename the knowledge base or reference it by its "
+                                "project name instead."
+                            ),
+                        )
+                    )
+            elif value not in kb_names:
+                issues.append(
+                    (
+                        (),
+                        (
+                            f'Connector target "{target.name}" {field_label} "{value}" does not match any '
+                            "knowledgeBases[] entry. To wire an external KB that this project does not own, use its "
+                            "10-character KB ID."
+                        ),
+                    )
+                )
+
+        for gateway in self.agent_core_gateways:
+            for target in gateway.targets:
+                if target.target_type != "connector" or target.connector_id != "bedrock-knowledge-bases":
+                    continue
+                for cfg in target.configurations or []:
+                    pv = cfg.parameter_values or {}
+                    kb_id = pv.get("knowledgeBaseId")
+                    if cfg.name == "Retrieve" and kb_id and isinstance(kb_id, str):
+                        validate(target, kb_id, "configurations[].parameterValues.knowledgeBaseId")
+                    if cfg.name == "AgenticRetrieveStream":
+                        retrievers = pv.get("retrievers")
+                        if not isinstance(retrievers, list):
+                            continue
+                        for r in retrievers:
+                            if not r or not isinstance(r, dict):
+                                continue
+                            kb = ((r.get("configuration") or {}).get("knowledgeBase") or {}).get("knowledgeBaseId")
+                            if kb:
+                                validate(target, kb, "configurations[].parameterValues.retrievers[].knowledgeBaseId")
+
+    def _check_payment_credential_refs(self, issues: list[Issue]) -> None:
+        credentials = {c.name: c for c in reversed(self.credentials)}  # first match wins, like Array.find
+        for p_idx, payment in enumerate(self.payments or []):
+            for c_idx, connector in enumerate(payment.connectors):
+                if connector.provision_mode == "QUICK_CREATE":
+                    continue
+                path = ("payments", p_idx, "connectors", c_idx, "credentialName")
+                credential = credentials.get(connector.credential_name)  # type: ignore[arg-type]
+                if credential is None:
+                    issues.append(
+                        (
+                            path,
+                            (
+                                f'Payment connector "{connector.name}" in manager "{payment.name}" references credential '
+                                f'"{connector.credential_name}" which does not exist in credentials[]'
+                            ),
+                        )
+                    )
+                elif credential.authorizer_type != "PaymentCredentialProvider":
+                    issues.append(
+                        (
+                            path,
+                            (
+                                f'Payment connector "{connector.name}" in manager "{payment.name}" references credential '
+                                f'"{connector.credential_name}" which is a {credential.authorizer_type}, not a '
+                                "PaymentCredentialProvider"
+                            ),
+                        )
+                    )
+
+
+AgentCoreProjectSpecAdapter: Final = TypeAdapter(AgentCoreProjectSpec)
+
+__all__ = [
+    "CREDENTIAL_TYPES",
+    "INDEXED_KEY_NAME_PATTERN",
+    "INDEXED_KEY_NAME_PATTERN_MESSAGE",
+    "INDEXED_KEY_TYPES",
+    "MAX_INDEXED_KEYS",
+    "MAX_INDEXED_KEY_NAME_LENGTH",
+    "STREAM_CONTENT_LEVELS",
+    "AgentCoreProjectSpec",
+    "AgentCoreProjectSpecAdapter",
+    "ApiKeyCredential",
+    "Credential",
+    "CredentialName",
+    "CredentialType",
+    "Evaluator",
+    "EvaluatorType",
+    "HarnessRegistryEntry",
+    "IndexedKey",
+    "IndexedKeyType",
+    "KinesisStreamDelivery",
+    "ManagedBy",
+    "Memory",
+    "MemoryName",
+    "MemoryType",
+    "OAuthCredential",
+    "PaymentCredential",
+    "ProjectName",
+    "StreamContentConfiguration",
+    "StreamContentLevel",
+    "StreamDeliveryResource",
+    "StreamDeliveryResources",
+]