{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "grounded-summary-01",
   "metadata": {},
   "source": [
    "# Source-Grounded Business Summaries · real-time and batch example\n",
    "\n",
    "**Available on [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-fpr4ku72wwntg), version 0.1.0.** AWS confirms Public product visibility and a Released offer. The release package completed actual AWS validation against the exact image; the full seller real-time, batch and cleanup rehearsal passed. Subscribe in your account before deploying. No model output is fabricated or saved in this notebook.\n",
    "\n",
    "Subscribe, choose **Continue to configuration**, select `us-east-1`, and copy the model-package ARN into the `GROUNDED_SUMMARY_MODEL_PACKAGE_ARN` environment variable. No seller package ARN is supplied as a default. The notebook checks the completed Marketplace container and exact qualified image digest; your active subscription supplies access. A buyer-account subscription transaction has not been rehearsed by the seller.\n",
    "\n",
    "**Default Run All is offline.** Review the notebook, then change `RUN_DEMO = False` to `True` to enable AWS setup, real-time deployment, invocation and cleanup. Batch is separately disabled until you set `RUN_BATCH = True`. Keep `RUN_DEMO` enabled while cleaning up.\n",
    "\n",
    "Run in your own SageMaker notebook role session in `us-east-1`, with `boto3` installed. The notebook infers that execution role and creates a uniquely named private encrypted evidence bucket. Outside a role session, set `SAGEMAKER_EXECUTION_ROLE_ARN`; optionally use an existing private bucket with `SAGEMAKER_DEMO_BUCKET`. Existing buckets are checked and never reconfigured. The execution role must trust SageMaker and allow the purchased package plus the private input/output prefix. Your caller needs permission to create, describe, invoke and delete the demo SageMaker resources, pass that role, read the role identity, and create/configure the fresh S3 evidence bucket. If bucket setup fails, inspect the printed bucket name in S3. Evidence storage remains billable after compute cleanup. Request capacity for one `ml.g6e.4xlarge` endpoint and, optionally, one `ml.g6e.2xlarge` Batch Transform instance.\n",
    "\n",
    "**AWS infrastructure charges are separate from software charges and any software trial.** This example creates one GPU endpoint until you delete it; batch compute also incurs charges while running. Execute the cleanup cells, even after a failure. All example text is fictional. Review every model result: literal source evidence does not establish semantic support."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-02",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import os\n",
    "import re\n",
    "import time\n",
    "import uuid\n",
    "\n",
    "import boto3\n",
    "from botocore.exceptions import ClientError, WaiterError\n",
    "\n",
    "# Opt in only after reviewing costs, permissions and cleanup. Default Run All is offline.\n",
    "RUN_DEMO = False\n",
    "RUN_BATCH = False\n",
    "APPROVED_IMAGE_DIGEST = \"sha256:6d38d9384206b0b77181db4f47167dde5bd23fe9e4c7ff86075dfcc2b468c917\"\n",
    "REGION = \"us-east-1\"\n",
    "\n",
    "\n",
    "def validate_package_arn(arn):\n",
    "    if not re.fullmatch(r\"arn:aws:sagemaker:us-east-1:\\d{12}:model-package/[A-Za-z0-9-]+\", arn):\n",
    "        raise ValueError(\"Set GROUNDED_SUMMARY_MODEL_PACKAGE_ARN to your subscribed us-east-1 package ARN.\")\n",
    "\n",
    "\n",
    "def validate_package(package):\n",
    "    if package.get(\"ModelPackageStatus\") != \"Completed\":\n",
    "        raise RuntimeError(\"The subscribed package is not Completed.\")\n",
    "    containers = package.get(\"InferenceSpecification\", {}).get(\"Containers\", [])\n",
    "    if len(containers) != 1 or not containers[0].get(\"ProductId\"):\n",
    "        raise RuntimeError(\"Expected one AWS Marketplace container; verify your subscription and package ARN.\")\n",
    "    image_digest = containers[0].get(\"ImageDigest\") or containers[0].get(\"Image\", \"\").partition(\"@\")[2]\n",
    "    if image_digest != APPROVED_IMAGE_DIGEST:\n",
    "        raise RuntimeError(\"Package image differs from the release-approved digest.\")\n",
    "\n",
    "\n",
    "configured_arn = os.environ.get(\"GROUNDED_SUMMARY_MODEL_PACKAGE_ARN\", \"\").strip()\n",
    "if RUN_DEMO:\n",
    "    # Validate configuration before constructing any client or creating resources.\n",
    "    if not re.fullmatch(r\"sha256:[0-9a-f]{64}\", APPROVED_IMAGE_DIGEST):\n",
    "        raise RuntimeError(\"Unreleased candidate: no certified image digest is approved.\")\n",
    "    validate_package_arn(configured_arn)\n",
    "    if any(\n",
    "        globals().get(key, False)\n",
    "        for key in (\n",
    "            \"model_created\",\n",
    "            \"config_created\",\n",
    "            \"endpoint_created\",\n",
    "            \"transform_created\",\n",
    "        )\n",
    "    ):\n",
    "        raise RuntimeError(\"Clean up the existing demo before rerunning setup; its resource names are preserved.\")\n",
    "    session = boto3.Session(region_name=REGION)\n",
    "    sm = session.client(\"sagemaker\")\n",
    "    validate_package(sm.describe_model_package(ModelPackageName=configured_arn))\n",
    "    runtime = session.client(\"sagemaker-runtime\")\n",
    "    s3 = session.client(\"s3\")\n",
    "    identity = session.client(\"sts\").get_caller_identity()\n",
    "    account_id = identity[\"Account\"]\n",
    "\n",
    "if RUN_DEMO:\n",
    "    run_name = \"ss-summary-demo-\" + time.strftime(\"%Y%m%d-%H%M%S\", time.gmtime()) + \"-\" + uuid.uuid4().hex[:6]\n",
    "    prefix = f\"grounded-summary-demo/{run_name}\"\n",
    "\n",
    "\n",
    "def prepare_demo_access(session, identity, region):\n",
    "    \"\"\"Use the notebook role and a fresh private bucket unless explicitly configured.\"\"\"\n",
    "    account = identity[\"Account\"]\n",
    "    role = os.environ.get(\"SAGEMAKER_EXECUTION_ROLE_ARN\", \"\").strip()\n",
    "    if not role:\n",
    "        assumed = identity[\"Arn\"].partition(\":assumed-role/\")[2]\n",
    "        if \"/\" not in assumed:\n",
    "            raise RuntimeError(\"Run in a SageMaker role session or configure SAGEMAKER_EXECUTION_ROLE_ARN.\")\n",
    "        role_name = assumed.rsplit(\"/\", 1)[0].rsplit(\"/\", 1)[-1]\n",
    "        role = session.client(\"iam\").get_role(RoleName=role_name)[\"Role\"][\"Arn\"]\n",
    "    if not role.startswith(f\"arn:aws:iam::{account}:role/\"):\n",
    "        raise RuntimeError(\"The SageMaker execution role must belong to your AWS account.\")\n",
    "    storage = session.client(\"s3\")\n",
    "    bucket_name = os.environ.get(\"SAGEMAKER_DEMO_BUCKET\", \"\").strip()\n",
    "    if bucket_name:\n",
    "        storage.head_bucket(Bucket=bucket_name, ExpectedBucketOwner=account)\n",
    "        blocks = storage.get_public_access_block(\n",
    "            Bucket=bucket_name,\n",
    "            ExpectedBucketOwner=account,\n",
    "        )[\"PublicAccessBlockConfiguration\"]\n",
    "        keys = (\"BlockPublicAcls\", \"IgnorePublicAcls\", \"BlockPublicPolicy\", \"RestrictPublicBuckets\")\n",
    "        if not all(blocks.get(k) is True for k in keys):\n",
    "            raise RuntimeError(\"The configured evidence bucket must block public access; it was not modified.\")\n",
    "    else:\n",
    "        bucket_name = f\"sagemaker-summary-demo-{account}-{region}-{uuid.uuid4().hex[:8]}\"\n",
    "        params = {\"Bucket\": bucket_name}\n",
    "        if region != \"us-east-1\":\n",
    "            params[\"CreateBucketConfiguration\"] = {\"LocationConstraint\": region}\n",
    "        storage.create_bucket(**params)\n",
    "        print(f\"Created private evidence bucket {bucket_name}; it is retained with the demo inputs/outputs.\")\n",
    "        # Only alter the fresh uniquely named bucket after successful creation.\n",
    "        storage.put_public_access_block(\n",
    "            Bucket=bucket_name,\n",
    "            ExpectedBucketOwner=account,\n",
    "            PublicAccessBlockConfiguration={\n",
    "                \"BlockPublicAcls\": True,\n",
    "                \"IgnorePublicAcls\": True,\n",
    "                \"BlockPublicPolicy\": True,\n",
    "                \"RestrictPublicBuckets\": True,\n",
    "            },\n",
    "        )\n",
    "        storage.put_bucket_encryption(\n",
    "            Bucket=bucket_name,\n",
    "            ExpectedBucketOwner=account,\n",
    "            ServerSideEncryptionConfiguration={\n",
    "                \"Rules\": [{\"ApplyServerSideEncryptionByDefault\": {\"SSEAlgorithm\": \"AES256\"}}],\n",
    "            },\n",
    "        )\n",
    "    return role, bucket_name\n",
    "\n",
    "\n",
    "if RUN_DEMO:\n",
    "    role_arn, bucket = prepare_demo_access(session, identity, REGION)\n",
    "    tags = [{\"Key\": \"SoftwareSushiDemoRun\", \"Value\": run_name}]\n",
    "    model_created = False\n",
    "    config_created = False\n",
    "    endpoint_created = False\n",
    "    transform_created = False"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "grounded-summary-03",
   "metadata": {},
   "source": [
    "## Bounded multilingual requests\n",
    "\n",
    "Use one structured request per invocation, or one request per line in a line-split batch. Limits: 1–64 unique segments; 2,000 characters per segment; 16,000 combined ID-plus-text characters; 96 KiB body; 3,072 actual input tokens; 1,024 output tokens. Oversized inputs are rejected without truncation. Owner is an explicitly named person only, and deadline is an explicit valid ISO date only; otherwise null. This service accepts text, not audio, images, or PDFs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-04",
   "metadata": {},
   "outputs": [],
   "source": [
    "examples = {\n",
    "    \"en\": \"Maya Chen will send the signed transition plan by 2027-06-18.\",\n",
    "    \"es\": \"Lucía Mena enviará el cronograma firmado antes del 2027-06-18.\",\n",
    "    \"pt\": \"João Luís enviará o cronograma assinado até 2027-06-18.\",\n",
    "}\n",
    "requests = [{\"language\": language, \"segments\": [{\"id\": \"s1\", \"text\": text}]} for language, text in examples.items()]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "grounded-summary-05",
   "metadata": {},
   "source": [
    "## Create one temporary real-time endpoint\n",
    "\n",
    "Run this cell only when ready to test. Wait for `InService`, then invoke immediately and delete the endpoint using the next cleanup cell. If creation or waiting fails, run cleanup before retrying. Keep this notebook open until cleanup finishes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-06",
   "metadata": {},
   "outputs": [],
   "source": [
    "if RUN_DEMO:\n",
    "    sm.create_model(\n",
    "        ModelName=run_name,\n",
    "        ExecutionRoleArn=role_arn,\n",
    "        PrimaryContainer={\"ModelPackageName\": configured_arn},\n",
    "        EnableNetworkIsolation=True,\n",
    "        Tags=tags,\n",
    "    )\n",
    "    model_created = True\n",
    "    sm.create_endpoint_config(\n",
    "        EndpointConfigName=run_name,\n",
    "        ProductionVariants=[\n",
    "            {\n",
    "                \"VariantName\": \"AllTraffic\",\n",
    "                \"ModelName\": run_name,\n",
    "                \"InstanceType\": \"ml.g6e.4xlarge\",\n",
    "                \"InitialInstanceCount\": 1,\n",
    "                \"InitialVariantWeight\": 1,\n",
    "                \"ContainerStartupHealthCheckTimeoutInSeconds\": 600,\n",
    "                \"ModelDataDownloadTimeoutInSeconds\": 1200,\n",
    "            }\n",
    "        ],\n",
    "        Tags=tags,\n",
    "    )\n",
    "    config_created = True\n",
    "    sm.create_endpoint(EndpointName=run_name, EndpointConfigName=run_name, Tags=tags)\n",
    "    endpoint_created = True\n",
    "    sm.get_waiter(\"endpoint_in_service\").wait(\n",
    "        EndpointName=run_name,\n",
    "        WaiterConfig={\"Delay\": 30, \"MaxAttempts\": 80},\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-07",
   "metadata": {},
   "outputs": [],
   "source": [
    "if RUN_DEMO:\n",
    "    for request in requests:\n",
    "        response = runtime.invoke_endpoint(\n",
    "            EndpointName=run_name,\n",
    "            ContentType=\"application/json\",\n",
    "            Accept=\"application/json\",\n",
    "            Body=json.dumps(request, ensure_ascii=False).encode(\"utf-8\"),\n",
    "        )\n",
    "        try:\n",
    "            result = json.loads(response[\"Body\"].read())\n",
    "        finally:\n",
    "            response[\"Body\"].close()\n",
    "        assert result[\"model\"] == \"grounded-summary\" and result[\"version\"] == \"0.1.0\"\n",
    "        assert result[\"review_required\"] is True\n",
    "        source = {s[\"id\"]: s[\"text\"] for s in request[\"segments\"]}\n",
    "        for item in result[\"summary\"] + result[\"actions\"]:\n",
    "            evidence = item[\"evidence\"]\n",
    "            text = source[evidence[\"segment_id\"]]\n",
    "            assert evidence[\"quote\"] == text and evidence[\"start\"] == 0 and evidence[\"end\"] == len(text)\n",
    "        print(json.dumps(result, ensure_ascii=False, indent=2))\n",
    "    # Exact citation location is checked above; semantic support still requires review."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-08",
   "metadata": {},
   "outputs": [],
   "source": [
    "if RUN_DEMO:\n",
    "    # Stop endpoint charges before the optional batch example. Retain the model for batch.\n",
    "    if endpoint_created:\n",
    "        sm.delete_endpoint(EndpointName=run_name)\n",
    "        sm.get_waiter(\"endpoint_deleted\").wait(\n",
    "            EndpointName=run_name,\n",
    "            WaiterConfig={\"Delay\": 15, \"MaxAttempts\": 80},\n",
    "        )\n",
    "        endpoint_created = False\n",
    "    if config_created:\n",
    "        sm.delete_endpoint_config(EndpointConfigName=run_name)\n",
    "        config_created = False"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "grounded-summary-09",
   "metadata": {},
   "source": [
    "## Optional line-split Batch Transform\n",
    "\n",
    "Set `RUN_BATCH = True` before setup to enable this cell. It needs the separate GPU batch quota. It uploads three fictional requests to your private bucket using server-side encryption. Batch compute stops when the job completes. Input/output objects are retained in your bucket for inspection; remove only this run's prefix later if appropriate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-10",
   "metadata": {},
   "outputs": [],
   "source": [
    "if RUN_DEMO and RUN_BATCH:\n",
    "    input_key = f\"{prefix}/input/examples.jsonl\"\n",
    "    s3.put_object(\n",
    "        Bucket=bucket,\n",
    "        Key=input_key,\n",
    "        ExpectedBucketOwner=account_id,\n",
    "        Body=(\"\\n\".join(json.dumps(r, ensure_ascii=False) for r in requests) + \"\\n\").encode(\"utf-8\"),\n",
    "        ContentType=\"application/jsonlines\",\n",
    "        ServerSideEncryption=\"AES256\",\n",
    "    )\n",
    "    sm.create_transform_job(\n",
    "        TransformJobName=run_name,\n",
    "        ModelName=run_name,\n",
    "        BatchStrategy=\"SingleRecord\",\n",
    "        MaxConcurrentTransforms=1,\n",
    "        MaxPayloadInMB=1,\n",
    "        TransformInput={\n",
    "            \"DataSource\": {\"S3DataSource\": {\"S3DataType\": \"S3Prefix\", \"S3Uri\": f\"s3://{bucket}/{input_key}\"}},\n",
    "            \"ContentType\": \"application/jsonlines\",\n",
    "            \"SplitType\": \"Line\",\n",
    "        },\n",
    "        TransformOutput={\n",
    "            \"S3OutputPath\": f\"s3://{bucket}/{prefix}/output/\",\n",
    "            \"Accept\": \"application/jsonlines\",\n",
    "            \"AssembleWith\": \"Line\",\n",
    "        },\n",
    "        TransformResources={\"InstanceType\": \"ml.g6e.2xlarge\", \"InstanceCount\": 1},\n",
    "        Tags=tags,\n",
    "    )\n",
    "    transform_created = True\n",
    "    sm.get_waiter(\"transform_job_completed_or_stopped\").wait(\n",
    "        TransformJobName=run_name,\n",
    "        WaiterConfig={\"Delay\": 30, \"MaxAttempts\": 120},\n",
    "    )\n",
    "    job = sm.describe_transform_job(TransformJobName=run_name)\n",
    "    if job[\"TransformJobStatus\"] != \"Completed\":\n",
    "        raise RuntimeError(\"Batch did not complete; inspect the job and run cleanup.\")\n",
    "    output = s3.get_object(\n",
    "        Bucket=bucket,\n",
    "        Key=f\"{prefix}/output/examples.jsonl.out\",\n",
    "        ExpectedBucketOwner=account_id,\n",
    "    )\n",
    "    try:\n",
    "        for line in output[\"Body\"].read().decode(\"utf-8\").splitlines():\n",
    "            print(json.dumps(json.loads(line), ensure_ascii=False, indent=2))\n",
    "    finally:\n",
    "        output[\"Body\"].close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "grounded-summary-11",
   "metadata": {},
   "source": [
    "## Cleanup after success or failure\n",
    "\n",
    "Run this cell even if an earlier operation failed. It acts only on this unique demo run. It stops an unfinished batch job, deletes any remaining endpoint/configuration, and removes the demo model after compute stops. It preserves S3 input/output evidence. Check the AWS console if a cleanup call fails; closing the notebook does not stop an endpoint."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "grounded-summary-12",
   "metadata": {},
   "outputs": [],
   "source": [
    "if RUN_DEMO:\n",
    "    cleanup_errors = []\n",
    "    batch_active = False\n",
    "    if transform_created:\n",
    "        try:\n",
    "            job = sm.describe_transform_job(TransformJobName=run_name)\n",
    "            status = job[\"TransformJobStatus\"]\n",
    "            batch_active = status in (\"InProgress\", \"Stopping\")\n",
    "            if status == \"InProgress\":\n",
    "                sm.stop_transform_job(TransformJobName=run_name)\n",
    "            if batch_active:\n",
    "                sm.get_waiter(\"transform_job_completed_or_stopped\").wait(\n",
    "                    TransformJobName=run_name,\n",
    "                    WaiterConfig={\"Delay\": 15, \"MaxAttempts\": 80},\n",
    "                )\n",
    "                batch_active = False\n",
    "            transform_created = False\n",
    "        except (ClientError, WaiterError) as exc:\n",
    "            cleanup_errors.append(exc)\n",
    "    # Endpoint cleanup still runs if a batch operation failed.\n",
    "    if endpoint_created:\n",
    "        try:\n",
    "            state = sm.describe_endpoint(EndpointName=run_name)[\"EndpointStatus\"]\n",
    "            if state != \"Deleting\":\n",
    "                sm.delete_endpoint(EndpointName=run_name)\n",
    "            sm.get_waiter(\"endpoint_deleted\").wait(\n",
    "                EndpointName=run_name,\n",
    "                WaiterConfig={\"Delay\": 15, \"MaxAttempts\": 80},\n",
    "            )\n",
    "            endpoint_created = False\n",
    "        except (ClientError, WaiterError) as exc:\n",
    "            cleanup_errors.append(exc)\n",
    "    if config_created and not endpoint_created:\n",
    "        try:\n",
    "            sm.delete_endpoint_config(EndpointConfigName=run_name)\n",
    "            config_created = False\n",
    "        except ClientError as exc:\n",
    "            cleanup_errors.append(exc)\n",
    "    if model_created and not endpoint_created and not batch_active:\n",
    "        try:\n",
    "            sm.delete_model(ModelName=run_name)\n",
    "            model_created = False\n",
    "        except ClientError as exc:\n",
    "            cleanup_errors.append(exc)\n",
    "    if cleanup_errors:\n",
    "        raise RuntimeError(\n",
    "            \"Some cleanup calls failed; inspect this demo run in AWS before closing.\"\n",
    "        ) from cleanup_errors[0]\n",
    "    print(f\"Demo compute removed. Private evidence remains at s3://{bucket}/{prefix}/\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
