agentcore-cli 0.31.1__py3-none-any.whl

agentcore/aws/agentcore_ab_tests.py

@@ -0,0 +1,230 @@
+"""A/B test operations (port of ``agentcore-ab-tests.ts``).
+
+Upstream calls the AgentCore data plane (``bedrock-agentcore``) with SigV4-signed ``fetch``
+requests; this port keeps the raw signed requests so paths, payloads and the passthrough of the
+service JSON (including fields absent from botocore's model) are unchanged.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Literal, NotRequired, TypedDict
+
+from agentcore.aws._http import query_string, signed_request
+from agentcore.aws._util import drop_none
+from agentcore.aws.stage_endpoint import data_plane_endpoint
+from agentcore.lib.errors.types import JobNotFoundError
+from agentcore.lib.utils.json_format import to_json_string
+
+VariantName = Literal["C", "T1"]
+
+
+class ABTestVariant(TypedDict):
+    name: VariantName
+    weight: float
+    variantConfiguration: dict[str, Any]
+    """``{"configurationBundle"?: {bundleArn, bundleVersion}, "target"?: {name}}``"""
+
+
+# ``{"onlineEvaluationConfigArn": str}`` or
+# ``{"perVariantOnlineEvaluationConfig": [{"name": "C"|"T1", "onlineEvaluationConfigArn": str}]}``
+ABTestEvaluationConfig = dict[str, Any]
+
+
+class GatewayFilter(TypedDict):
+    targetPaths: list[str]
+
+
+class TrafficAllocationConfig(TypedDict):
+    routeOnHeader: dict[str, str]
+
+
+class ConfidenceInterval(TypedDict, total=False):
+    lower: float
+    upper: float
+
+
+class ControlStats(TypedDict):
+    treatmentName: str
+    sampleSize: int
+    mean: float
+
+
+class VariantResult(TypedDict):
+    treatmentName: str
+    sampleSize: int
+    mean: float
+    absoluteChange: NotRequired[float]
+    percentChange: NotRequired[float]
+    pValue: NotRequired[float]
+    confidenceInterval: NotRequired[ConfidenceInterval]
+    isSignificant: bool
+
+
+class EvaluatorMetric(TypedDict):
+    evaluatorArn: str
+    controlStats: ControlStats
+    variantResults: list[VariantResult]
+
+
+class ABTestResults(TypedDict):
+    analysisTimestamp: NotRequired[str]
+    evaluatorMetrics: list[EvaluatorMetric]
+
+
+class CreateABTestResult(TypedDict):
+    abTestId: str
+    abTestArn: str
+    name: NotRequired[str]
+    status: str
+    executionStatus: str
+    createdAt: str
+
+
+class GetABTestResult(TypedDict):
+    abTestId: str
+    abTestArn: str
+    name: str
+    description: NotRequired[str]
+    status: str
+    executionStatus: str
+    gatewayArn: str
+    roleArn: str
+    variants: list[ABTestVariant]
+    evaluationConfig: ABTestEvaluationConfig
+    trafficAllocationConfig: NotRequired[TrafficAllocationConfig]
+    maxDurationDays: NotRequired[int]
+    currentRunId: NotRequired[str]
+    stopReason: NotRequired[str]
+    failureReason: NotRequired[str]
+    errorDetails: NotRequired[list[str]]
+    startedAt: NotRequired[str]
+    stoppedAt: NotRequired[str]
+    maxDurationExpiresAt: NotRequired[str]
+    createdAt: str
+    updatedAt: str
+    results: NotRequired[ABTestResults]
+
+
+class UpdateABTestResult(TypedDict):
+    abTestId: str
+    abTestArn: str
+    status: str
+    executionStatus: str
+    failureReason: NotRequired[str]
+    updatedAt: str
+
+
+class DeleteABTestResult(TypedDict):
+    success: bool
+    error: NotRequired[str]
+
+
+class ABTestSummary(TypedDict):
+    abTestId: str
+    abTestArn: str
+    name: str
+    description: NotRequired[str]
+    status: str
+    executionStatus: str
+    gatewayArn: NotRequired[str]
+    createdAt: str
+    updatedAt: str
+
+
+class ListABTestsResult(TypedDict):
+    abTests: list[ABTestSummary]
+    nextToken: NotRequired[str]
+
+
+def _dp_request(*, region: str, method: str, path: str, body: str | None = None) -> Any:
+    """Signed data-plane request (GetABTest on the data plane includes results/metrics)."""
+    endpoint = data_plane_endpoint(region)
+    response = signed_request(method, f"{endpoint}{path}", region=region, body=body)
+    if not response.ok:
+        message = f"ABTest API error ({response.status}): {response.text()}"
+        if response.status == 404:
+            raise JobNotFoundError(message, error_source="service")
+        raise RuntimeError(message)
+    if response.status == 204:
+        return {}
+    return response.json()
+
+
+def create_ab_test(
+    *,
+    region: str,
+    name: str,
+    gateway_arn: str,
+    role_arn: str,
+    variants: list[ABTestVariant],
+    evaluation_config: ABTestEvaluationConfig,
+    description: str | None = None,
+    gateway_filter: GatewayFilter | None = None,
+    enable_on_create: bool | None = None,
+) -> CreateABTestResult:
+    body: dict[str, Any] = {
+        "name": name,
+        "clientToken": str(uuid.uuid4()),
+        "gatewayArn": gateway_arn,
+        "roleArn": role_arn,
+        "variants": variants,
+        "evaluationConfig": evaluation_config,
+    }
+    if description:
+        body["description"] = description
+    if gateway_filter:
+        body["gatewayFilter"] = gateway_filter
+    if enable_on_create is not None:
+        body["enableOnCreate"] = enable_on_create
+    return _dp_request(region=region, method="POST", path="/ab-tests", body=to_json_string(body, indent=None))
+
+
+def get_ab_test(*, region: str, ab_test_id: str) -> GetABTestResult:
+    return _dp_request(region=region, method="GET", path=f"/ab-tests/{ab_test_id}")
+
+
+def update_ab_test(
+    *,
+    region: str,
+    ab_test_id: str,
+    name: str | None = None,
+    description: str | None = None,
+    variants: list[ABTestVariant] | None = None,
+    evaluation_config: ABTestEvaluationConfig | None = None,
+    execution_status: Literal["PAUSED", "RUNNING", "STOPPED"] | None = None,
+    role_arn: str | None = None,
+) -> UpdateABTestResult:
+    body = {
+        "clientToken": str(uuid.uuid4()),
+        **drop_none(
+            {
+                "name": name,
+                "description": description,
+                "variants": variants,
+                "evaluationConfig": evaluation_config,
+                "executionStatus": execution_status,
+                "roleArn": role_arn,
+            }
+        ),
+    }
+    return _dp_request(
+        region=region, method="PUT", path=f"/ab-tests/{ab_test_id}", body=to_json_string(body, indent=None)
+    )
+
+
+def delete_ab_test(*, region: str, ab_test_id: str) -> DeleteABTestResult:
+    try:
+        _dp_request(region=region, method="DELETE", path=f"/ab-tests/{ab_test_id}")
+        return {"success": True}
+    except Exception as exc:  # noqa: BLE001 - reported in the result, as upstream
+        return {"success": False, "error": str(exc)}
+
+
+def list_ab_tests(*, region: str, max_results: int | None = None, next_token: str | None = None) -> ListABTestsResult:
+    data = _dp_request(
+        region=region,
+        method="GET",
+        path=f"/ab-tests{query_string({'maxResults': max_results, 'nextToken': next_token})}",
+    )
+    return drop_none({"abTests": data.get("abTests") or [], "nextToken": data.get("nextToken")})  # type: ignore[return-value]

agentcore/aws/agentcore_batch_evaluation.py

@@ -0,0 +1,227 @@
+"""Batch evaluation operations (port of ``agentcore-batch-evaluation.ts``).
+
+Data-plane endpoints (service ``bedrock-agentcore``)::
+
+    POST   /evaluations/batch-evaluate                          StartBatchEvaluation
+    GET    /evaluations/batch-evaluate/{batchEvaluationId}      GetBatchEvaluation
+    GET    /evaluations/batch-evaluate                          ListBatchEvaluations
+    POST   /evaluations/batch-evaluate/{batchEvaluationId}/stop StopBatchEvaluation
+    DELETE /evaluations/batch-evaluate/{batchEvaluationId}      DeleteBatchEvaluation
+
+Upstream calls these with SigV4-signed ``fetch`` requests; the raw requests are kept.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, NotRequired, TypedDict
+
+from agentcore.aws._http import query_string, signed_request
+from agentcore.aws._util import drop_none
+from agentcore.aws.stage_endpoint import data_plane_endpoint
+from agentcore.lib.errors.types import JobNotFoundError
+from agentcore.lib.utils.json_format import to_json_string
+
+
+class SessionFilterConfig(TypedDict, total=False):
+    startTime: str
+    endTime: str
+
+
+class CloudWatchFilterConfig(TypedDict, total=False):
+    sessionIds: list[str]
+    timeRange: SessionFilterConfig
+
+
+class CloudWatchLogsSource(TypedDict):
+    serviceNames: list[str]
+    logGroupNames: list[str]
+    filterConfig: NotRequired[CloudWatchFilterConfig]
+
+
+class DataSourceConfig(TypedDict, total=False):
+    cloudWatchLogs: CloudWatchLogsSource
+    onlineEvaluationConfigSource: dict[str, Any]
+
+
+class Evaluator(TypedDict):
+    evaluatorId: str
+
+
+class InsightConfig(TypedDict):
+    insightId: str
+
+
+# Ground truth / session metadata are passed through verbatim:
+#   {"sessionMetadata": [{"sessionId", "testScenarioId"?, "groundTruth"?: {"inline": {...}}, "metadata"?}]}
+EvaluationMetadata = dict[str, Any]
+FailureAnalysisResult = dict[str, Any]
+EvaluationResults = dict[str, Any]
+OutputConfig = dict[str, Any]
+
+
+class StartBatchEvaluationResult(TypedDict):
+    batchEvaluationId: str
+    batchEvaluationArn: str
+    name: str
+    status: str
+    createdAt: NotRequired[str]
+
+
+class GetBatchEvaluationResult(TypedDict):
+    batchEvaluationId: str
+    batchEvaluationArn: str
+    name: str
+    status: str
+    createdAt: NotRequired[str]
+    updatedAt: NotRequired[str]
+    evaluators: NotRequired[list[Evaluator]]
+    dataSourceConfig: NotRequired[DataSourceConfig]
+    outputConfig: NotRequired[OutputConfig]
+    evaluationResults: NotRequired[EvaluationResults]
+    failureAnalysisResult: NotRequired[FailureAnalysisResult]
+    errorDetails: NotRequired[list[str]]
+    description: NotRequired[str]
+    kmsKeyArn: NotRequired[str]
+
+
+class BatchEvaluationSummary(TypedDict):
+    batchEvaluationId: str
+    batchEvaluationArn: str
+    name: str
+    status: str
+    createdAt: NotRequired[str]
+    description: NotRequired[str]
+    evaluators: NotRequired[list[Evaluator]]
+    evaluationResults: NotRequired[EvaluationResults]
+    errorDetails: NotRequired[list[str]]
+
+
+class ListBatchEvaluationsResult(TypedDict):
+    batchEvaluations: list[BatchEvaluationSummary]
+    nextToken: NotRequired[str]
+
+
+class StopBatchEvaluationResult(TypedDict):
+    batchEvaluationId: str
+    batchEvaluationArn: str
+    status: str
+    description: NotRequired[str]
+
+
+class DeleteBatchEvaluationResult(TypedDict):
+    batchEvaluationId: str
+    batchEvaluationArn: str
+    status: str
+
+
+def _signed_request(*, region: str, method: str, path: str, body: str | None = None) -> Any:
+    endpoint = data_plane_endpoint(region)
+    response = signed_request(method, f"{endpoint}{path}", region=region, body=body)
+    if not response.ok:
+        message = f"BatchEvaluation API error ({response.status}): {response.text()}"
+        if response.status == 404:
+            raise JobNotFoundError(message, error_source="service")
+        raise RuntimeError(message)
+    if response.status == 204:
+        return {}
+    return response.json()
+
+
+def start_batch_evaluation(
+    *,
+    region: str,
+    name: str,
+    data_source_config: DataSourceConfig,
+    evaluators: list[Evaluator] | None = None,
+    insights: list[InsightConfig] | None = None,
+    evaluation_metadata: EvaluationMetadata | None = None,
+    description: str | None = None,
+    client_token: str | None = None,
+    kms_key_arn: str | None = None,
+) -> StartBatchEvaluationResult:
+    """Start a batch evaluation (returns immediately with an ID to poll)."""
+    body: dict[str, Any] = {"batchEvaluationName": name, "dataSourceConfig": data_source_config}
+    if evaluators:
+        body["evaluators"] = evaluators
+    if insights:
+        body["insights"] = insights
+    if evaluation_metadata:
+        body["evaluationMetadata"] = evaluation_metadata
+    if description:
+        body["description"] = description
+    if client_token:
+        body["clientToken"] = client_token
+    if kms_key_arn:
+        body["kmsKeyArn"] = kms_key_arn
+
+    raw = _signed_request(
+        region=region, method="POST", path="/evaluations/batch-evaluate", body=to_json_string(body, indent=None)
+    )
+    return drop_none(  # type: ignore[return-value]
+        {
+            "batchEvaluationId": raw.get("batchEvaluationId") or "",
+            "batchEvaluationArn": raw.get("batchEvaluationArn") or "",
+            "name": raw.get("batchEvaluationName") or "",
+            "status": raw.get("status") or "",
+            "createdAt": raw.get("createdAt"),
+        }
+    )
+
+
+def get_batch_evaluation(*, region: str, batch_evaluation_id: str) -> GetBatchEvaluationResult:
+    raw = _signed_request(region=region, method="GET", path=f"/evaluations/batch-evaluate/{batch_evaluation_id}")
+    return drop_none(  # type: ignore[return-value]
+        {
+            "batchEvaluationId": raw.get("batchEvaluationId") or "",
+            "batchEvaluationArn": raw.get("batchEvaluationArn") or "",
+            "name": raw.get("batchEvaluationName") or "",
+            "status": raw.get("status") or "",
+            "createdAt": raw.get("createdAt"),
+            "updatedAt": raw.get("updatedAt"),
+            "evaluators": raw.get("evaluators"),
+            "dataSourceConfig": raw.get("dataSourceConfig"),
+            "outputConfig": raw.get("outputConfig"),
+            "evaluationResults": raw.get("evaluationResults"),
+            "failureAnalysisResult": raw.get("failureAnalysisResult"),
+            "errorDetails": raw.get("errorDetails"),
+            "description": raw.get("description"),
+            "kmsKeyArn": raw.get("kmsKeyArn"),
+        }
+    )
+
+
+def list_batch_evaluations(
+    *, region: str, max_results: int | None = None, next_token: str | None = None
+) -> ListBatchEvaluationsResult:
+    query = query_string({"maxResults": max_results, "nextToken": next_token})
+    data = _signed_request(region=region, method="GET", path=f"/evaluations/batch-evaluate{query}")
+    return drop_none(  # type: ignore[return-value]
+        {"batchEvaluations": data.get("batchEvaluations") or [], "nextToken": data.get("nextToken")}
+    )
+
+
+def stop_batch_evaluation(*, region: str, batch_evaluation_id: str) -> StopBatchEvaluationResult:
+    raw = _signed_request(region=region, method="POST", path=f"/evaluations/batch-evaluate/{batch_evaluation_id}/stop")
+    return drop_none(  # type: ignore[return-value]
+        {
+            "batchEvaluationId": raw.get("batchEvaluationId") or "",
+            "batchEvaluationArn": raw.get("batchEvaluationArn") or "",
+            "status": raw.get("status") or "",
+            "description": raw.get("description"),
+        }
+    )
+
+
+def delete_batch_evaluation(*, region: str, batch_evaluation_id: str) -> DeleteBatchEvaluationResult:
+    raw = _signed_request(region=region, method="DELETE", path=f"/evaluations/batch-evaluate/{batch_evaluation_id}")
+    return {
+        "batchEvaluationId": raw.get("batchEvaluationId") or "",
+        "batchEvaluationArn": raw.get("batchEvaluationArn") or "",
+        "status": raw.get("status") or "",
+    }
+
+
+def generate_client_token() -> str:
+    """Idempotency token."""
+    return str(uuid.uuid4())

agentcore/aws/agentcore_config_bundles.py

@@ -0,0 +1,220 @@
+"""Configuration bundle control-plane operations (port of ``agentcore-config-bundles.ts``).
+
+Upstream calls these with SigV4-signed ``fetch`` requests to the control plane; the raw requests
+are kept so paths, payloads and the passthrough of the service JSON are unchanged.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, NotRequired, TypedDict
+
+from agentcore.aws._http import query_string, signed_request
+from agentcore.aws._util import drop_none
+from agentcore.aws.stage_endpoint import control_plane_endpoint
+from agentcore.lib.utils.json_format import to_json_string
+
+
+class ComponentConfiguration(TypedDict):
+    configuration: dict[str, Any]
+
+
+ComponentConfigurationMap = dict[str, ComponentConfiguration]
+"""Component identifier (ARN) -> its configuration."""
+
+
+class CreatedBy(TypedDict):
+    name: str
+    arn: NotRequired[str]
+
+
+class VersionLineageMetadata(TypedDict, total=False):
+    parentVersionIds: list[str]
+    branchName: str
+    createdBy: CreatedBy
+    commitMessage: str
+
+
+class CreateConfigurationBundleResult(TypedDict):
+    bundleArn: str
+    bundleId: str
+    versionId: str
+    createdAt: str
+
+
+class GetConfigurationBundleResult(TypedDict):
+    bundleArn: str
+    bundleId: str
+    bundleName: str
+    description: NotRequired[str]
+    versionId: str
+    components: ComponentConfigurationMap
+    lineageMetadata: NotRequired[VersionLineageMetadata]
+    createdAt: str
+    updatedAt: str
+
+
+class UpdateConfigurationBundleResult(TypedDict):
+    bundleArn: str
+    bundleId: str
+    versionId: str
+    updatedAt: str
+
+
+class ConfigurationBundleSummary(TypedDict):
+    bundleArn: str
+    bundleId: str
+    bundleName: str
+    description: NotRequired[str]
+    createdAt: NotRequired[float]
+
+
+class ListConfigurationBundlesResult(TypedDict):
+    bundles: list[ConfigurationBundleSummary]
+    nextToken: NotRequired[str]
+
+
+class GetConfigurationBundleVersionResult(TypedDict):
+    bundleArn: str
+    bundleId: str
+    bundleName: str
+    description: NotRequired[str]
+    versionId: str
+    components: ComponentConfigurationMap
+    lineageMetadata: NotRequired[VersionLineageMetadata]
+    createdAt: str
+    versionCreatedAt: str
+
+
+class ListConfigurationBundleVersionsFilter(TypedDict, total=False):
+    branchName: str
+    latestPerBranch: bool
+    createdByName: str
+
+
+class ConfigurationBundleVersionSummary(TypedDict):
+    bundleArn: str
+    bundleId: str
+    versionId: str
+    lineageMetadata: NotRequired[VersionLineageMetadata]
+    versionCreatedAt: str
+
+
+class ListConfigurationBundleVersionsResult(TypedDict):
+    versions: list[ConfigurationBundleVersionSummary]
+    nextToken: NotRequired[str]
+
+
+def _signed_request(*, region: str, method: str, path: str, body: str | None = None) -> Any:
+    endpoint = control_plane_endpoint(region)
+    response = signed_request(method, f"{endpoint}{path}", region=region, body=body)
+    if not response.ok:
+        raise RuntimeError(f"ConfigurationBundle API error ({response.status}): {response.text()}")
+    if response.status == 204:
+        return {}
+    return response.json()
+
+
+def create_configuration_bundle(
+    *,
+    region: str,
+    bundle_name: str,
+    components: ComponentConfigurationMap,
+    description: str | None = None,
+    branch_name: str | None = None,
+    commit_message: str | None = None,
+    kms_key_arn: str | None = None,
+    created_by: CreatedBy | None = None,
+) -> CreateConfigurationBundleResult:
+    body: dict[str, Any] = {"bundleName": bundle_name, "clientToken": str(uuid.uuid4())}
+    if description:
+        body["description"] = description
+    body["components"] = components
+    if branch_name:
+        body["branchName"] = branch_name
+    if commit_message:
+        body["commitMessage"] = commit_message
+    if kms_key_arn:
+        body["kmsKeyArn"] = kms_key_arn
+    if created_by:
+        body["createdBy"] = created_by
+    return _signed_request(
+        region=region, method="POST", path="/configuration-bundles/create", body=to_json_string(body, indent=None)
+    )
+
+
+def get_configuration_bundle(
+    *, region: str, bundle_id: str, branch_name: str | None = None
+) -> GetConfigurationBundleResult:
+    path = f"/configuration-bundles/{bundle_id}{query_string({'branchName': branch_name})}"
+    return _signed_request(region=region, method="GET", path=path)
+
+
+def update_configuration_bundle(
+    *,
+    region: str,
+    bundle_id: str,
+    bundle_name: str | None = None,
+    description: str | None = None,
+    components: ComponentConfigurationMap | None = None,
+    parent_version_ids: list[str] | None = None,
+    branch_name: str | None = None,
+    commit_message: str | None = None,
+    created_by: CreatedBy | None = None,
+) -> UpdateConfigurationBundleResult:
+    body = {
+        "clientToken": str(uuid.uuid4()),
+        **drop_none(
+            {
+                "bundleName": bundle_name,
+                "description": description,
+                "components": components,
+                "parentVersionIds": parent_version_ids,
+                "branchName": branch_name,
+                "commitMessage": commit_message,
+                "createdBy": created_by,
+            }
+        ),
+    }
+    return _signed_request(
+        region=region,
+        method="PUT",
+        path=f"/configuration-bundles/{bundle_id}",
+        body=to_json_string(body, indent=None),
+    )
+
+
+def delete_configuration_bundle(*, region: str, bundle_id: str) -> None:
+    _signed_request(region=region, method="DELETE", path=f"/configuration-bundles/{bundle_id}")
+
+
+def list_configuration_bundles(
+    *, region: str, max_results: int | None = None, next_token: str | None = None
+) -> ListConfigurationBundlesResult:
+    query = query_string({"maxResults": max_results, "nextToken": next_token})
+    data = _signed_request(region=region, method="POST", path=f"/configuration-bundles{query}")
+    return drop_none({"bundles": data.get("bundles") or [], "nextToken": data.get("nextToken")})  # type: ignore[return-value]
+
+
+def get_configuration_bundle_version(
+    *, region: str, bundle_id: str, version_id: str
+) -> GetConfigurationBundleVersionResult:
+    return _signed_request(
+        region=region, method="GET", path=f"/configuration-bundles/{bundle_id}/versions/{version_id}"
+    )
+
+
+def list_configuration_bundle_versions(
+    *,
+    region: str,
+    bundle_id: str,
+    max_results: int | None = None,
+    next_token: str | None = None,
+    filter: ListConfigurationBundleVersionsFilter | None = None,
+) -> ListConfigurationBundleVersionsResult:
+    query = query_string({"maxResults": max_results, "nextToken": next_token})
+    body = to_json_string({"filter": filter}, indent=None) if filter else None
+    data = _signed_request(
+        region=region, method="POST", path=f"/configuration-bundles/{bundle_id}/versions{query}", body=body
+    )
+    return drop_none({"versions": data.get("versions") or [], "nextToken": data.get("nextToken")})  # type: ignore[return-value]