agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/config_bundle/diff_versions.py

@@ -0,0 +1,52 @@
+"""Client-side deep diff of config bundle components (port of operations/config-bundle/diff-versions.ts)."""
+
+from typing import Any
+
+_MISSING: Any = object()
+
+
+def _js_type(value: Any) -> str:
+    if value is _MISSING:
+        return "undefined"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    return "object"  # dict, list, None
+
+
+def deep_diff(from_value: Any, to_value: Any, prefix: str = "") -> list[dict[str, Any]]:
+    """Flat list of {path, type: added|removed|changed, oldValue?, newValue?} with dot paths."""
+    entries: list[dict[str, Any]] = []
+    if from_value is to_value or (_js_type(from_value) == _js_type(to_value) != "object" and from_value == to_value):
+        return entries
+    if from_value is None or to_value is None or _js_type(from_value) != _js_type(to_value):
+        if from_value is _MISSING:
+            entries.append({"path": prefix, "type": "added", "newValue": to_value})
+        elif to_value is _MISSING:
+            entries.append({"path": prefix, "type": "removed", "oldValue": from_value})
+        else:
+            entries.append({"path": prefix, "type": "changed", "oldValue": from_value, "newValue": to_value})
+        return entries
+    if _js_type(from_value) != "object":
+        entries.append({"path": prefix, "type": "changed", "oldValue": from_value, "newValue": to_value})
+        return entries
+    if isinstance(from_value, list) or isinstance(to_value, list):
+        if not isinstance(from_value, list) or not isinstance(to_value, list) or len(from_value) != len(to_value):
+            entries.append({"path": prefix, "type": "changed", "oldValue": from_value, "newValue": to_value})
+            return entries
+        for i, (a, b) in enumerate(zip(from_value, to_value, strict=True)):
+            entries.extend(deep_diff(a, b, f"{prefix}[{i}]"))
+        return entries
+    keys = list(dict.fromkeys([*from_value.keys(), *to_value.keys()]))
+    for key in keys:
+        child = f"{prefix}.{key}" if prefix else key
+        if key not in from_value:
+            entries.append({"path": child, "type": "added", "newValue": to_value[key]})
+        elif key not in to_value:
+            entries.append({"path": child, "type": "removed", "oldValue": from_value[key]})
+        else:
+            entries.extend(deep_diff(from_value[key], to_value[key], child))
+    return entries

agentcore/operations/config_bundle/resolve_bundle.py

@@ -0,0 +1,65 @@
+"""Resolve a config bundle name to its bundle ID (port of operations/config-bundle/resolve-bundle.ts).
+
+Fast path: deployed-state.json. Fallback: the list API by (project-prefixed) name.
+"""
+
+from dataclasses import dataclass
+
+from agentcore.aws import agentcore_config_bundles as api
+from agentcore.lib import ConfigIO
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.operations.config_bundle.bundle_name_variants import get_bundle_name_variants
+
+
+@dataclass
+class ResolvedBundle:
+    bundle_id: str
+    region: str
+    bundle_arn: str | None = None
+    version_id: str | None = None
+
+
+def resolve_bundle_by_name(bundle_name: str, region: str, config_io: ConfigIO | None = None) -> ResolvedBundle:
+    config_io = config_io or ConfigIO()
+    deployed = to_jsonable(config_io.read_deployed_state())
+    for target in (deployed.get("targets") or {}).values():
+        bundle = ((((target or {}).get("resources")) or {}).get("configBundles") or {}).get(bundle_name)
+        if bundle:
+            try:
+                versions = api.list_configuration_bundle_versions(
+                    region=region, bundle_id=bundle["bundleId"], max_results=1
+                )
+                latest = versions["versions"][0] if versions["versions"] else None
+                return ResolvedBundle(
+                    bundle_id=bundle["bundleId"],
+                    bundle_arn=bundle.get("bundleArn"),
+                    version_id=(latest or {}).get("versionId") or bundle.get("versionId"),
+                    region=region,
+                )
+            except Exception:  # noqa: BLE001, S110 - stale entry: fall through to the API lookup
+                pass
+
+    project_name = None
+    try:
+        project_name = config_io.read_project_spec().name
+    except Exception:  # noqa: BLE001, S110
+        pass
+    variants = get_bundle_name_variants(bundle_name, project_name)
+    match = None
+    next_token = None
+    while True:
+        page = api.list_configuration_bundles(region=region, max_results=100, next_token=next_token)
+        match = next((b for b in page["bundles"] if b.get("bundleName") in variants), None)
+        next_token = page.get("nextToken")
+        if match or not next_token:
+            break
+    if not match:
+        raise Exception(f'Configuration bundle "{bundle_name}" not found. Has it been deployed?')
+    versions = api.list_configuration_bundle_versions(region=region, bundle_id=match["bundleId"], max_results=1)
+    latest = versions["versions"][0] if versions["versions"] else None
+    return ResolvedBundle(
+        bundle_id=match["bundleId"],
+        bundle_arn=match.get("bundleArn"),
+        version_id=(latest or {}).get("versionId"),
+        region=region,
+    )

agentcore/operations/connectors/__init__.py

@@ -0,0 +1,3 @@
+from agentcore.operations.connectors.translators import ConfigurationEntry, ParameterOverride, translate_connector
+
+__all__ = ["ConfigurationEntry", "ParameterOverride", "translate_connector"]

agentcore/operations/connectors/translators.py

@@ -0,0 +1,63 @@
+"""Connector translators (port of operations/connectors/translators.ts).
+
+Convert validated CLI inputs into the ``configurations[]`` array of a connector gateway target
+(which mirrors the CFN wire format): one entry per connector operation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+
+class ParameterOverride(TypedDict, total=False):
+    path: str
+    description: str
+    visible: bool
+
+
+class ConfigurationEntry(TypedDict):
+    name: str
+    description: str
+    parameterValues: dict[str, Any]
+    parameterOverrides: list[ParameterOverride]
+
+
+def _translate_web_search(exclude_domains: list[str] | None) -> list[ConfigurationEntry]:
+    parameter_values: dict[str, Any] = {}
+    if exclude_domains:
+        parameter_values["domainFilter"] = {"exclude": list(exclude_domains)}
+    return [{"name": "WebSearch", "description": "", "parameterValues": parameter_values, "parameterOverrides": []}]
+
+
+def _translate_knowledge_bases(knowledge_base_id: str) -> list[ConfigurationEntry]:
+    return [
+        {
+            "name": "AgenticRetrieveStream",
+            "description": (
+                "Streaming endpoint for agentic retrieval from knowledge bases. Performs multi-step retrieval with "
+                "planning and returns results as a stream of events."
+            ),
+            "parameterValues": {
+                "retrievers": [{"configuration": {"knowledgeBase": {"knowledgeBaseId": knowledge_base_id}}}],
+                "agenticRetrieveConfiguration": {"foundationModelType": "MANAGED", "rerankingModelType": "MANAGED"},
+            },
+            "parameterOverrides": [],
+        },
+        {
+            "name": "Retrieve",
+            "description": "Queries a knowledge base and retrieves information from it.",
+            "parameterValues": {"knowledgeBaseId": knowledge_base_id},
+            "parameterOverrides": [],
+        },
+    ]
+
+
+def translate_connector(
+    connector_id: Literal["web-search", "bedrock-knowledge-bases"], input: dict[str, Any]
+) -> list[ConfigurationEntry]:
+    """``input`` is ``{"excludeDomains": [...]}`` for web-search, ``{"knowledgeBaseId": ...}`` for KBs."""
+    if connector_id == "web-search":
+        return _translate_web_search(input.get("excludeDomains"))
+    if connector_id == "bedrock-knowledge-bases":
+        return _translate_knowledge_bases(input["knowledgeBaseId"])
+    raise ValueError(f"Unknown connector: {connector_id}")

agentcore/operations/dataset/__init__.py

@@ -0,0 +1,21 @@
+"""Dataset operations (port of operations/dataset/index.ts)."""
+
+from agentcore.operations.dataset.delete import delete_dataset_version
+from agentcore.operations.dataset.publish import publish_dataset
+from agentcore.operations.dataset.pull import pull_dataset
+from agentcore.operations.dataset.push import push_dataset
+from agentcore.operations.dataset.resolve_dataset import ResolvedDataset, get_dataset_names, resolve_dataset
+from agentcore.operations.dataset.status import get_dataset_status
+from agentcore.operations.dataset.wait import wait_for_dataset_active
+
+__all__ = [
+    "ResolvedDataset",
+    "delete_dataset_version",
+    "get_dataset_names",
+    "get_dataset_status",
+    "publish_dataset",
+    "pull_dataset",
+    "push_dataset",
+    "resolve_dataset",
+    "wait_for_dataset_active",
+]

agentcore/operations/dataset/delete.py

@@ -0,0 +1,7 @@
+"""Delete one published dataset version (port of operations/dataset/delete.ts)."""
+
+from agentcore.aws import agentcore_datasets as api
+
+
+def delete_dataset_version(*, region: str, dataset_id: str, version: str) -> None:
+    api.delete_dataset_version_api(region=region, dataset_id=dataset_id, version=version)

agentcore/operations/dataset/publish.py

@@ -0,0 +1,16 @@
+"""Publish the dataset DRAFT as a new immutable version (port of operations/dataset/publish.ts)."""
+
+from agentcore.aws import agentcore_datasets as api
+from agentcore.operations.dataset import wait as _wait
+
+
+def publish_dataset(*, region: str, dataset_id: str) -> dict:
+    """{"version", "exampleCount", "draftStatus"}."""
+    version = api.create_dataset_version(region=region, dataset_id=dataset_id)
+    _wait.wait_for_dataset_active(region, dataset_id)
+    info = api.get_dataset(region=region, dataset_id=dataset_id)
+    return {
+        "version": version["datasetVersion"],
+        "exampleCount": info.get("exampleCount"),
+        "draftStatus": info.get("draftStatus") or "UNMODIFIED",
+    }

agentcore/operations/dataset/pull.py

@@ -0,0 +1,21 @@
+"""Pull dataset content from the service to the local file (port of operations/dataset/pull.ts)."""
+
+import os
+
+from agentcore.aws import agentcore_datasets as api
+
+
+def pull_dataset(
+    *, region: str, dataset_id: str, local_file_path: str, config_base_dir: str, version: str | None = None
+) -> dict:
+    """Stream the dataset to disk. {"exampleCount", "version"}."""
+    absolute = os.path.abspath(os.path.join(config_base_dir, local_file_path))
+    info = api.get_dataset(region=region, dataset_id=dataset_id, version=version)
+    if info.get("status") != "ACTIVE":
+        raise Exception(f"Dataset is not ready (status: {info.get('status')}). Please try again later.")
+    if not info.get("downloadUrl"):
+        raise Exception(
+            "Dataset has no download URL available. The dataset may not be ready yet. Please try again later."
+        )
+    line_count = api.download_dataset(info["downloadUrl"], mode="stream", file_path=absolute)
+    return {"exampleCount": line_count, "version": info.get("datasetVersion")}

agentcore/operations/dataset/push.py

@@ -0,0 +1,201 @@
+"""Push a local dataset file to the service DRAFT by incremental diff (port of operations/dataset/push.ts).
+
+1. Read the local JSONL file  2. Download the remote DRAFT  3. Diff by exampleId
+4. Delete removed, update changed, add new  5. Write new exampleIds back to the local file
+"""
+
+import json
+import math
+import os
+import time
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from agentcore.aws import agentcore_datasets as api
+from agentcore.aws.retry import is_retryable_aws_error
+from agentcore.operations.dataset import wait as _wait
+
+API_BATCH_LIMIT = 1000
+BATCH_MAX_RETRIES = 3
+BATCH_RETRY_BASE_MS = 1_000
+
+# Injectable for tests.
+sleep: Callable[[float], None] = time.sleep
+
+
+def _js_stringify(value: Any) -> str:
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def _stable_stringify(value: Any) -> str:
+    """fast-json-stable-stringify: recursively sorted keys, compact."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _parse_error_message(exc: ValueError) -> str:
+    return str(exc)
+
+
+def _parse_local_file(content: str) -> list[dict[str, Any]]:
+    lines = [line for line in content.split("\n") if line.strip() != ""]
+    out = []
+    for index, line in enumerate(lines):
+        try:
+            obj = json.loads(line)
+        except ValueError as exc:
+            snippet = line[:120] + "..." if len(line) > 120 else line
+            raise Exception(f"Invalid JSON at line {index + 1}: {_parse_error_message(exc)}\n  {snippet}") from None
+        example_id = obj.get("exampleId") if isinstance(obj, dict) else None
+        out.append({"exampleId": example_id, "content": obj, "lineIndex": index})
+    return out
+
+
+def _parse_remote_jsonl(content: str) -> dict[str, dict[str, Any]]:
+    remote: dict[str, dict[str, Any]] = {}
+    for line in content.split("\n"):
+        if line.strip() == "":
+            continue
+        obj = json.loads(line)
+        if obj.get("exampleId"):
+            remote[obj["exampleId"]] = obj
+    return remote
+
+
+def _strip_example_id(obj: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in obj.items() if k != "exampleId"}
+
+
+def _content_equals(a: dict[str, Any], b: dict[str, Any]) -> bool:
+    return _stable_stringify(_strip_example_id(a)) == _stable_stringify(_strip_example_id(b))
+
+
+def _with_retry(op: Callable[[], Any]) -> Any:
+    for attempt in range(BATCH_MAX_RETRIES):
+        try:
+            return op()
+        except Exception as exc:
+            if attempt == BATCH_MAX_RETRIES - 1 or not is_retryable_aws_error(exc):
+                raise
+            sleep(BATCH_RETRY_BASE_MS * 2**attempt / 1000)
+    return None  # pragma: no cover
+
+
+def _batch_operation(
+    items: list[Any], operation: Callable[[list[Any], str], Any], phase_name: str, region: str, dataset_id: str
+) -> list[Any]:
+    if not items:
+        return []
+    total = math.ceil(len(items) / API_BATCH_LIMIT)
+    completed = 0
+    results = []
+    try:
+        for i in range(0, len(items), API_BATCH_LIMIT):
+            batch = items[i : i + API_BATCH_LIMIT]
+            token = str(uuid.uuid4())
+            results.append(_with_retry(lambda batch=batch, token=token: operation(batch, token)))
+            completed += 1
+            if i + API_BATCH_LIMIT < len(items):
+                _wait.wait_for_dataset_active(region, dataset_id)
+    except Exception as exc:
+        raise Exception(
+            f"Push failed during {phase_name} phase ({completed}/{total} batches completed). "
+            "Re-run `agentcore dataset push` to retry and reconcile. "
+            f"Original error: {exc}"
+        ) from exc
+    return results
+
+
+def _rewrite_local_file_with_ids(
+    file_path: str, all_examples: list[dict[str, Any]], new_ids: list[str], added: list[dict[str, Any]] | None = None
+) -> None:
+    index = 0
+    lines = []
+    added_ids = {id(e) for e in added} if added is not None else None
+    for example in all_examples:
+        if added_ids is None or id(example) in added_ids:
+            content = _strip_example_id(example["content"])
+            new_id = new_ids[index] if index < len(new_ids) else None
+            lines.append(_js_stringify({"exampleId": new_id, **content} if new_id is not None else content))
+            index += 1
+        else:
+            lines.append(_js_stringify(example["content"]))
+    with open(file_path, "w", encoding="utf-8", newline="") as fh:
+        fh.write("\n".join(lines) + "\n")
+
+
+def push_dataset(
+    *, region: str, dataset_id: str, local_file_path: str, config_base_dir: str, force: bool = False
+) -> dict[str, int]:
+    """{"added", "updated", "deleted", "unchanged", "totalRemote"}."""
+    absolute = os.path.abspath(os.path.join(config_base_dir, local_file_path))
+    with open(absolute, encoding="utf-8") as fh:
+        local_examples = _parse_local_file(fh.read())
+
+    info = api.get_dataset(region=region, dataset_id=dataset_id)
+    remote: dict[str, dict[str, Any]] = {}
+    if info.get("downloadUrl") and (info.get("exampleCount") or 0) > 0:
+        remote = _parse_remote_jsonl(api.download_dataset(info["downloadUrl"], mode="buffer"))
+
+    def delete(batch: list[str], token: str) -> Any:
+        return api.delete_dataset_examples(region=region, dataset_id=dataset_id, example_ids=batch, client_token=token)
+
+    def add(batch: list[dict[str, Any]], token: str) -> Any:
+        return api.add_dataset_examples(region=region, dataset_id=dataset_id, examples=batch, client_token=token)
+
+    def update(batch: list[dict[str, Any]], token: str) -> Any:
+        return api.update_dataset_examples(region=region, dataset_id=dataset_id, examples=batch, client_token=token)
+
+    if force:
+        if remote:
+            _batch_operation(list(remote), delete, "delete", region, dataset_id)
+            _wait.wait_for_dataset_active(region, dataset_id)
+        to_add = [_strip_example_id(e["content"]) for e in local_examples]
+        new_ids: list[str] = []
+        for r in _batch_operation(to_add, add, "add", region, dataset_id):
+            new_ids.extend(r.get("exampleIds") or [])
+        _rewrite_local_file_with_ids(absolute, local_examples, new_ids)
+        return {
+            "added": len(local_examples),
+            "updated": 0,
+            "deleted": len(remote),
+            "unchanged": 0,
+            "totalRemote": len(local_examples),
+        }
+
+    to_add_examples: list[dict[str, Any]] = []
+    to_update: list[dict[str, Any]] = []
+    local_ids: set[str] = set()
+    unchanged = 0
+    for local in local_examples:
+        example_id = local["exampleId"]
+        if example_id and example_id in remote:
+            local_ids.add(example_id)
+            if _content_equals(local["content"], remote[example_id]):
+                unchanged += 1
+            else:
+                to_update.append(local)
+        else:
+            to_add_examples.append(local)  # new, or stale exampleId not in remote
+    to_delete = [rid for rid in remote if rid not in local_ids]
+
+    if to_delete:
+        _batch_operation(to_delete, delete, "delete", region, dataset_id)
+        _wait.wait_for_dataset_active(region, dataset_id)
+    if to_update:
+        _batch_operation([e["content"] for e in to_update], update, "update", region, dataset_id)
+        _wait.wait_for_dataset_active(region, dataset_id)
+    new_ids = []
+    if to_add_examples:
+        payload = [_strip_example_id(e["content"]) for e in to_add_examples]
+        for r in _batch_operation(payload, add, "add", region, dataset_id):
+            new_ids.extend(r.get("exampleIds") or [])
+    if new_ids:
+        _rewrite_local_file_with_ids(absolute, local_examples, new_ids, to_add_examples)
+    return {
+        "added": len(to_add_examples),
+        "updated": len(to_update),
+        "deleted": len(to_delete),
+        "unchanged": unchanged,
+        "totalRemote": len(local_examples),
+    }

agentcore/operations/dataset/resolve_dataset.py

@@ -0,0 +1,65 @@
+"""Resolve a dataset name to its deployed state (port of operations/dataset/resolve-dataset.ts)."""
+
+from dataclasses import dataclass
+
+from agentcore.lib import ConfigIO
+from agentcore.lib.schemas.io.config_io import to_jsonable
+
+
+@dataclass
+class ResolvedDataset:
+    name: str
+    dataset_id: str
+    dataset_arn: str
+    region: str
+    location: str
+
+
+def _field(obj, key: str, snake: str):
+    return obj.get(key) if isinstance(obj, dict) else getattr(obj, snake, None)
+
+
+def resolve_dataset(name: str | None = None, config_io: ConfigIO | None = None) -> ResolvedDataset:
+    """By name; with no name and exactly one dataset, auto-selects it."""
+    config_io = config_io or ConfigIO()
+    project = to_jsonable(config_io.read_project_spec())
+    datasets = project.get("datasets") or []
+    if not datasets:
+        raise Exception("No datasets found in agentcore.json. Run `agentcore add dataset` first.")
+    available = ", ".join(d["name"] for d in datasets)
+    if name:
+        dataset = next((d for d in datasets if d["name"] == name), None)
+        if dataset is None:
+            raise Exception(f'Dataset "{name}" not found. Available: {available}')
+    elif len(datasets) == 1:
+        dataset = datasets[0]
+    else:
+        raise Exception(f"Multiple datasets found. Specify --name. Available: {available}")
+
+    targets = config_io.resolve_aws_deployment_targets()
+    if not targets:
+        raise Exception("No AWS deployment targets configured. Run `agentcore deploy` first.")
+    region = _field(targets[0], "region", "region")
+    target_name = _field(targets[0], "name", "name")
+
+    try:
+        deployed = to_jsonable(config_io.read_deployed_state())
+    except Exception:  # noqa: BLE001
+        deployed = None
+    state = (
+        ((((deployed or {}).get("targets") or {}).get(target_name) or {}).get("resources") or {}).get("datasets") or {}
+    ).get(dataset["name"])
+    if not state:
+        raise Exception(f'Dataset "{dataset["name"]}" has not been deployed. Run `agentcore deploy` first.')
+    return ResolvedDataset(
+        name=dataset["name"],
+        dataset_id=state["datasetId"],
+        dataset_arn=state["datasetArn"],
+        region=region,
+        location=dataset["config"]["managed"]["location"],
+    )
+
+
+def get_dataset_names(config_io: ConfigIO | None = None) -> list[str]:
+    project = to_jsonable((config_io or ConfigIO()).read_project_spec())
+    return [d["name"] for d in project.get("datasets") or []]

agentcore/operations/dataset/status.py

@@ -0,0 +1,18 @@
+"""Dataset status: DRAFT info and version history (port of operations/dataset/status.ts)."""
+
+from agentcore.aws import agentcore_datasets as api
+
+
+def get_dataset_status(*, region: str, dataset_id: str, name: str) -> dict:
+    info = api.get_dataset(region=region, dataset_id=dataset_id)
+    versions = api.list_dataset_versions(region=region, dataset_id=dataset_id)
+    return {
+        "name": name,
+        "datasetId": dataset_id,
+        "schemaType": info.get("schemaType"),
+        "status": info.get("status"),
+        "draftExampleCount": info.get("exampleCount"),
+        "draftStatus": info.get("draftStatus") or "UNKNOWN",
+        "updatedAt": info.get("updatedAt"),
+        "versions": versions.get("versions"),
+    }

agentcore/operations/dataset/wait.py

@@ -0,0 +1,25 @@
+"""Wait until a dataset is ACTIVE after an async mutation (port of operations/dataset/wait.ts)."""
+
+import time
+from collections.abc import Callable
+
+from agentcore.aws import agentcore_datasets as api
+
+DEFAULT_MAX_WAIT_MS = 60_000
+POLL_INTERVAL_MS = 2_000
+
+# Injectable for tests.
+sleep: Callable[[float], None] = time.sleep
+
+
+def wait_for_dataset_active(region: str, dataset_id: str, max_wait_ms: int = DEFAULT_MAX_WAIT_MS) -> None:
+    start = time.monotonic() * 1000
+    while time.monotonic() * 1000 - start < max_wait_ms:
+        result = api.get_dataset(region=region, dataset_id=dataset_id)
+        status = result.get("status") or ""
+        if status == "ACTIVE":
+            return
+        if status.endswith("_FAILED"):
+            raise Exception(f"Dataset entered failed state: {status}")
+        sleep(POLL_INTERVAL_MS / 1000)
+    raise Exception(f"Timed out waiting for dataset to become ACTIVE (waited {max_wait_ms / 1000:g}s)")