An open API service indexing awesome lists of open source software.

https://github.com/aws-samples/sample-badgers

Guidance on deploying a generative AI document analysis with Amazon Bedrock AgentCore. Auto-classifies, enhances, and aggregates multi-type documents using Gestalt-informed vision prompts. Custom analyzer creation wizard. Scripted CDK deployment. Gradio frontend included.
https://github.com/aws-samples/sample-badgers

agentcore agentcore-sdk agentic-ai agentic-workflow amazon-nova badgers cdk claude composable-prompts document-extraction document-intelligence document-vision full-text-extraction gestalt prompt-engineering strands-agent-sdk strands-agents vision-models

Last synced: about 19 hours ago
JSON representation

Guidance on deploying a generative AI document analysis with Amazon Bedrock AgentCore. Auto-classifies, enhances, and aggregates multi-type documents using Gestalt-informed vision prompts. Custom analyzer creation wizard. Scripted CDK deployment. Gradio frontend included.

Awesome Lists containing this project

README

          

> 🚧 **This repository is under active development.** Watch the repo, monitor branches and issues, and check the [Changelog](CHANGELOG.md) for the latest updates.

🧭 **Navigation:**

πŸ”΅ **Home** | [Vision LLM Theory](VISION_LLM_THEORY_README.md) | [Local Testing](local_testing/LOCAL_TESTING_README.md) | [Deployment UI](deployment/ui/DEPLOYMENT_UI_README.md) | [Deployment](deployment/DEPLOYMENT_README.md) | [CDK Stacks](deployment/stacks/STACKS_README.md) | [Runtime](deployment/runtime/RUNTIME_README.md) | [S3 Files](deployment/s3_files/S3_FILES_README.md) | [Lambda Analyzers](deployment/lambdas/LAMBDA_ANALYZERS.md) | [Prompting System](deployment/s3_files/prompts/PROMPTING_SYSTEM_README.md)

---

# 🦑 BADGERS

**Broad Agentic Document Generative Extraction & Recognition System**

BADGERS transforms document processing through vision-enabled AI and deep layout analysis. Unlike traditional text extraction tools, BADGERS understands document structure and meaning by recognizing visual hierarchies, reading patterns, and contextual relationships between elements.

## πŸ€” Why BADGERS?

Traditional document processing tools extract text but lose context. They can't distinguish a header from body text, understand table relationships, or recognize that a diagram explains the adjacent paragraph. BADGERS solves this by:

- πŸ—οΈ **Preserving semantic structure** - Maintains document hierarchy and element relationships
- πŸ‘οΈ **Understanding visual context** - Recognizes how layout conveys meaning
- πŸ“š **Processing diverse content** - Handles 21+ element types from handwriting to equations
- πŸ€– **Automating complex workflows** - Orchestrates multiple specialized analyzers via an AI agent

Use cases: research acceleration, compliance automation, content management, accessibility remediation.

## πŸ“Έ Screenshots

| Local Testing β€” Home | Local Testing β€” Chat |
| ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| ![Home Page](github-assets/badgers-local-testing-ui-home-page.png) | ![Chat Interface](github-assets/badgers-local-testing-ui-chat.png) |

| Deployment UI β€” Stacks | Deployment UI β€” Config Editor |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| ![Stack Information](github-assets/badgers-deploy-ui-stack-information.png) | ![Config Editor](github-assets/badgers-deploy-ui-config-editor.png) |

## βš™οΈ How It Works

```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ AgentCore Runtime β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
β”‚ β”‚ PDF Analysis Agent (Strands) β”‚ β”‚
β”‚ β”‚ - Claude Sonnet 4.5 with Extended Thinking β”‚ β”‚
β”‚ β”‚ - Session state management β”‚ β”‚
β”‚ β”‚ - MCP tool orchestration β”‚ β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ AgentCore Gateway β”‚
β”‚ - MCP Protocol (2025-03-26) β”‚
β”‚ - Cognito JWT Authentication β”‚
β”‚ - Semantic tool search β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ β”‚ β”‚
β–Ό β–Ό β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Lambda β”‚ β”‚ Lambda β”‚ β”‚ Lambda β”‚
β”‚ Analyzer β”‚ β”‚ Analyzer β”‚ β”‚ Analyzer β”‚
β”‚ (25 tools) β”‚ β”‚ β”‚ β”‚ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚ β”‚ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Bedrock β”‚
β”‚ Claude β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

1. πŸ“„ **User submits a document** with analysis instructions
2. 🧠 **Strands Agent** (running in AgentCore Runtime) interprets the request
3. πŸ”§ **Agent selects tools** from a library of specialized analyzers via MCP Gateway
4. ⚑ **Lambda analyzers** (standardized and domain-specific functions, including container-based) process document elements using Claude vision models
5. πŸ“Š **Results aggregate** with preserved structure and semantic relationships

## πŸ› οΈ Tech Stack

| Component | Technology |
| ------------------ | ------------------------------------------------------------------ |
| πŸ€– Agent Framework | [Strands Agents](https://github.com/strands-agents/strands-agents) |
| 🏠 Agent Hosting | Amazon Bedrock AgentCore Runtime |
| πŸšͺ Tool Gateway | Amazon Bedrock AgentCore Gateway (MCP Protocol) |
| 🧠 Foundation Model | Claude Sonnet 4.5 (via Amazon Bedrock) |
| ⚑ Compute | AWS Lambda (modular analyzer functions, including container-based) |
| πŸ“¦ Storage | Amazon S3 (configs, prompts, outputs) |
| πŸ” Auth | Amazon Cognito (OAuth 2.0 client credentials) |
| πŸ—οΈ IaC | AWS CDK (Python) |
| πŸ“ˆ Observability | CloudWatch Logs, X-Ray |
| πŸ“Š Cost Tracking | Bedrock Application Inference Profiles |

## πŸ”¬ Analyzers

| Analyzer | Purpose |
| ------------------------------------ | ------------------------------------------------------------------------------------------ |
| πŸ“Έ `pdf_to_images_converter` | Convert PDF pages to images |
| 🏷️ `classify_pdf_content` | Classify document content type |
| πŸ“ `full_text_analyzer` | Extract all text content |
| πŸ“Š `table_analyzer` | Extract and structure tables |
| πŸ“ˆ `charts_analyzer` | Analyze charts and graphs |
| πŸ”€ `diagram_analyzer` | Process diagrams and flowcharts |
| πŸ“ `layout_analyzer` | Document structure analysis |
| β™Ώ `accessibility_analyzer` | Generate accessibility metadata (part of remediation) |
| πŸ₯ `decision_tree_analyzer` | Medical/clinical document analysis |
| πŸ”¬ `scientific_analyzer` | Scientific paper analysis |
| ✍️ `handwriting_analyzer` | Handwritten text recognition |
| πŸ’» `code_block_analyzer` | Extract code snippets |
| πŸ—‚οΈ `metadata_generic_analyzer` | Generic metadata extraction |
| πŸ—‚οΈ `metadata_mads_analyzer` | MADS metadata format extraction |
| πŸ—‚οΈ `metadata_mods_analyzer` | MODS metadata format extraction |
| πŸ”‘ `keyword_topic_analyzer` | Extract keywords and topics |
| πŸ”§ `remediation_analyzer` | PDF accessibility remediation (container, content stream tagging + structure tree builder) |
| πŸ“„ `page_analyzer` | Single page content analysis |
| 🧱 `elements_analyzer` | Document element detection |
| 🧱 `robust_elements_analyzer` | Enhanced element detection with fallbacks |
| πŸ‘οΈ `general_visual_analysis_analyzer` | General-purpose visual content analysis |
| ✏️ `editorial_analyzer` | Editorial content and markup analysis |
| πŸ—ΊοΈ `war_map_analyzer` | Historical war map analysis |
| πŸŽ“ `edu_transcript_analyzer` | Educational transcript analysis |
| πŸ”— `correlation_analyzer` | Correlate multi-analyzer results per page |
| πŸ–ΌοΈ `image_enhancer` | Image enhancement and preprocessing |

## πŸš€ Deployment

### Prerequisites

- ☁️ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) configured with credentials
- πŸ“¦ [AWS CDK v2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) (`npm install -g aws-cdk`)
- 🐳 [Docker](https://docs.docker.com/get-started/get-docker/) (running)
- 🐍 [Python 3.12+](https://www.python.org/downloads/)
- ⚑ [uv](https://docs.astral.sh/uv/getting-started/installation/)

### Quick Start

```bash
cd deployment
./deploy_from_scratch.sh
```

This deploys 10 CloudFormation stacks:
1. πŸ“¦ S3 (config + output buckets)
2. πŸ” Cognito (OAuth authentication)
3. πŸ‘€ IAM (execution roles)
4. 🐳 ECR (container registry)
5. ⚑ Lambda (25 analyzer functions)
6. πŸšͺ Gateway (MCP endpoint)
7. 🧠 Memory (session persistence)
8. πŸ“Š Inference Profiles (cost tracking)
9. πŸƒ Runtime (Strands agent container)
10. 🧩 Custom Analyzers (optional, wizard-created)

### Manual Steps

See [deployment/DEPLOYMENT_README.md](deployment/DEPLOYMENT_README.md) for step-by-step instructions.

### Cleanup

```bash
cd deployment
./destroy.sh
```

## πŸ“ Project Structure

```
β”œβ”€β”€ deployment/
β”‚ β”œβ”€β”€ app.py # CDK app entry point
β”‚ β”œβ”€β”€ stacks/ # CDK stack definitions
β”‚ β”œβ”€β”€ lambdas/code/ # Analyzer Lambda functions
β”‚ β”œβ”€β”€ runtime/ # AgentCore Runtime container
β”‚ β”œβ”€β”€ s3_files/ # Prompts, schemas, manifests
β”‚ └── badgers-foundation/ # Shared analyzer framework
β”œβ”€β”€ local_testing/ # Local dev/testing UI (React + Express)
β”‚ β”œβ”€β”€ src/ # React components (chat, wizard, editor, pricing, etc.)
β”‚ └── server/ # Express API server
└── pyproject.toml
```

---

## πŸ” Technical Deep Dive

### πŸ“¦ Lambda Layers

BADGERS uses Lambda layers shared across analyzer functions:

**πŸ—οΈ Foundation Layer** (`layer.zip`)
- Built via `deployment/lambdas/build_foundation_layer.sh`
- Contains the analyzer framework (7 Python modules)
- Includes dependencies: boto3, botocore
- Includes core system prompts used by all analyzers

```
layer/python/
β”œβ”€β”€ foundation/
β”‚ β”œβ”€β”€ analyzer_foundation.py # 🎯 Main orchestration class
β”‚ β”œβ”€β”€ bedrock_client.py # πŸ”„ Bedrock API with retry/fallback
β”‚ β”œβ”€β”€ configuration_manager.py # βš™οΈ Config loading/validation
β”‚ β”œβ”€β”€ image_processor.py # πŸ–ΌοΈ Image optimization
β”‚ β”œβ”€β”€ message_chain_builder.py # πŸ’¬ Claude message formatting
β”‚ β”œβ”€β”€ prompt_loader.py # πŸ“œ Prompt file loading (local/S3)
β”‚ └── response_processor.py # πŸ“€ Response extraction
β”œβ”€β”€ config/
β”‚ └── config.py
└── prompts/core_system_prompts/
└── *.xml
```

**πŸ“„ Poppler Layer** (`poppler-qpdf-layer.zip`)
- PDF rendering library for `pdf_to_images_converter`
- Built via `deployment/lambdas/build_poppler_qdf_layer.sh`

### πŸ”¬ How an Analyzer Works

Each analyzer follows the same pattern using `AnalyzerFoundation`:

```python
# Lambda handler (simplified)
def lambda_handler(event, context):
# 1️⃣ Load config from S3 manifest
config = load_manifest_from_s3(bucket, "full_text_analyzer")

# 2️⃣ Initialize foundation with S3-aware prompt loader
analyzer = AnalyzerFoundation(...)

# 3️⃣ Run analysis pipeline
result = analyzer.analyze(image_data)

# 4️⃣ Save result to S3 and return
save_result_to_s3(result, session_id)
return {"result": result}
```

The `analyze()` method orchestrates:
1. πŸ–ΌοΈ **Image processing** - Resize/optimize for Claude's vision API
2. πŸ“œ **Prompt loading** - Combine wrapper + analyzer prompts from S3
3. πŸ’¬ **Message building** - Format for Bedrock Converse API
4. ⚑ **Dynamic token estimation** - Score image complexity and set token budget (when enabled)
5. πŸ€– **Model invocation** - Call Claude with retry/fallback logic
6. βœ… **Response processing** - Extract and validate result

### πŸ“œ Prompting System

Prompts are modular XML files composed at runtime:

```
s3://config-bucket/
β”œβ”€β”€ core_system_prompts/
β”‚ β”œβ”€β”€ prompt_system_wrapper.xml # 🎁 Main template with placeholders
β”‚ β”œβ”€β”€ core_rules/rules.xml # πŸ“ Shared rules for all analyzers
β”‚ └── error_handling/*.xml # ⚠️ Error response templates
β”œβ”€β”€ prompts/{analyzer_name}/
β”‚ β”œβ”€β”€ {analyzer}_job_role.xml # πŸ‘€ Role definition
β”‚ β”œβ”€β”€ {analyzer}_context.xml # 🌍 Domain context
β”‚ β”œβ”€β”€ {analyzer}_rules.xml # πŸ“ Analyzer-specific rules
β”‚ β”œβ”€β”€ {analyzer}_tasks.xml # βœ… Task instructions
β”‚ └── {analyzer}_format.xml # πŸ“‹ Output format spec
└── wrappers/
└── prompt_system_wrapper.xml
```

The `PromptLoader` composes the final system prompt:

```xml

{core_rules}
{composed_prompt}
{error_handler_general}
{error_handler_not_found}

```

Placeholders like `[[PIXEL_WIDTH]]` and `[[PIXEL_HEIGHT]]` are replaced with actual image dimensions at runtime.

### βš™οΈ Configuration System

Each analyzer has a manifest file in S3:

```json
// s3://config-bucket/manifests/full_text_analyzer.json
{
"tool": {
"name": "analyze_full_text_tool",
"description": "Extracts text content maintaining reading order...",
"inputSchema": {
"type": "object",
"properties": {
"image_path": { "type": "string" },
"session_id": { "type": "string" },
"audit_mode": { "type": "boolean" }
},
"required": ["image_path", "session_id"]
}
},
"analyzer": {
"name": "full_text_analyzer",
"enhancement_eligible": true,
"model_selections": {
"primary": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
"fallback_list": [
"us.anthropic.claude-haiku-4-5-20251001-v1:0",
"us.amazon.nova-premier-v1:0"
]
},
"max_retries": 3,
"prompt_files": [
"full_text_job_role.xml",
"full_text_context.xml",
"full_text_rules.xml",
"full_text_tasks_extraction.xml",
"full_text_format.xml"
],
"max_examples": 0,
"analysis_text": "full text content",
"expected_output_tokens": 6000,
"output_extension": "xml"
}
}
```

Key configuration features:
- πŸ”„ **Model fallback chain** - Primary model with ordered fallbacks
- πŸ” **Retry logic** - Configurable retry count per analyzer
- 🧩 **Prompt composition** - List of XML files to combine
- πŸ“‹ **Tool schema** - MCP-compatible input schema for Gateway
- πŸ–ΌοΈ **Enhancement eligible** - Flag indicating analyzer benefits from image preprocessing (used by `image_enhancer` tool)

Global settings (from environment or defaults):
```python
{
"max_tokens": 8000,
"temperature": 0.1,
"max_image_size": 20971520, # 20MB
"max_dimension": 2048,
"jpeg_quality": 85,
"throttle_delay": 1.0,
"aws_region": "us-west-2"
}
```

### ⚑ Dynamic Token Estimation

When enabled, BADGERS estimates the optimal `max_tokens` per image based on visual complexity, reducing cost on simple documents and avoiding truncation on dense ones. The scorer runs on the already-processed image bytes β€” no extra I/O.

Four metrics are combined into a complexity score: text pixel ratio, grayscale entropy, edge density, and color standard deviation. The score maps to a token budget (8K / 12K / 16K / 24K).

**Enabling:** Toggle "Dynamic Token Estimation" in the chat UI, or set the Lambda environment variable `DYNAMIC_TOKENS_ENABLED=true`.

**Tuning:** Add a `dynamic_tokens` block to an analyzer manifest to customize weights and thresholds:
```json
"dynamic_tokens": {
"weights": {
"text_ratio": 0.2,
"entropy": 0.3,
"edge_density": 0.3,
"color_std": 0.2
},
"thresholds": [
{"max_score": 0.20, "max_tokens": 8000},
{"max_score": 0.30, "max_tokens": 12000},
{"max_score": 0.45, "max_tokens": 16000},
{"max_score": 1.00, "max_tokens": 24000}
]
}
```

**Observability:** When active, logs report the estimated budget, actual token usage, and utilization percentage for calibration.

### πŸ“Š Inference Profiles for Cost Tracking

BADGERS uses Application Inference Profiles to enable cost allocation and usage monitoring. The system maps model IDs to profile ARNs at runtime:

```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Inference Profile Flow β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ β”‚
β”‚ 1. CDK deploys InferenceProfilesStack β”‚
β”‚ └─> Creates ApplicationInferenceProfile for each model β”‚
β”‚ β€’ badgers-claude-sonnet-{id} (US) β”‚
β”‚ β€’ badgers-claude-haiku-{id} (US) β”‚
β”‚ β€’ badgers-claude-opus-{id} (US) β”‚
β”‚ β€’ badgers-nova-premier-{id} (US) β”‚
β”‚ β”‚
β”‚ 2. Runtime receives profile ARNs as environment variables β”‚
β”‚ └─> CLAUDE_SONNET_PROFILE_ARN, CLAUDE_HAIKU_PROFILE_ARN, etc. β”‚
β”‚ β”‚
β”‚ 3. At invocation, bedrock_client.py maps model_id β†’ profile ARN β”‚
β”‚ └─> "us.anthropic.claude-sonnet-4-5-*" β†’ $CLAUDE_SONNET_PROFILE_ARN β”‚
β”‚ β”‚
β”‚ 4. Bedrock invoked with profile ARN (enables cost tracking) β”‚
β”‚ └─> Falls back to model ID if no profile configured β”‚
β”‚ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

Model ID to environment variable mapping:
| Model Pattern | Environment Variable |
| --------------------- | --------------------------- |
| `*claude-sonnet-4-5*` | `CLAUDE_SONNET_PROFILE_ARN` |
| `*claude-haiku-4-5*` | `CLAUDE_HAIKU_PROFILE_ARN` |
| `*claude-opus-4-6*` | `CLAUDE_OPUS_PROFILE_ARN` |
| `*nova-premier*` | `NOVA_PREMIER_PROFILE_ARN` |

### βž• Adding a New Analyzer

**Option 1: Use the Wizard (Recommended)**

```bash
cd local_testing
npm run dev
```

The Analyzer Creation Wizard is available as the πŸ§™ Create Analyzer tab in the [Local Testing UI](local_testing/LOCAL_TESTING_README.md).

**Option 2: Manual Creation**

1. πŸ“œ Create prompt files in `deployment/s3_files/prompts/{analyzer_name}/`
2. πŸ“‹ Create manifest in `deployment/s3_files/manifests/{analyzer_name}.json`
3. πŸ“ Create schema in `deployment/s3_files/schemas/{analyzer_name}.json`
4. ⚑ Create Lambda code in `deployment/lambdas/code/{analyzer_name}/lambda_handler.py`
5. πŸ“ Register in `deployment/stacks/lambda_stack.py`
6. πŸš€ Redeploy: `cdk deploy badgers-lambda badgers-gateway`

---

## πŸ”§ Troubleshooting

### Service Control Policy (SCP) Blocks Cross-Region Inference

If your AWS organization uses strict SCPs that deny cross-region Bedrock operations, you may see:

```
AccessDeniedException: ... is not authorized to perform: bedrock:InvokeModelWithResponseStream
on resource: arn:aws:bedrock:::foundation-model/anthropic.claude-* with an explicit deny
in a service control policy
```

BADGERS defaults to regional (`us.anthropic.*`) inference profiles which avoid cross-region routing. If you previously deployed with `global.anthropic.*` profiles, redeploy after pulling the latest code.

### Marketplace Subscription Error on First Invocation

After a fresh deployment, the first model invocation may fail with:

```
AccessDeniedException: Model access is denied due to IAM user or service role is not authorized
to perform the required AWS Marketplace actions (aws-marketplace:ViewSubscriptions,
aws-marketplace:Subscribe)
```

The IAM stack now includes `aws-marketplace:ViewSubscriptions` and `aws-marketplace:Subscribe` permissions. If you see this error on an older deployment, redeploy the IAM stack. As a workaround, manually invoke the model once in the Bedrock console playground to trigger the Marketplace subscription.

---

## Notices

Customers are responsible for making their own independent assessment of the information in this Guidance. This Guidance: (a) is for informational purposes only, (b) represents AWS current product offerings and practices, which are subject to change without notice, and (c) does not create any commitments or assurances from AWS and its affiliates, suppliers or licensors. AWS products or services are provided "as is" without warranties, representations, or conditions of any kind, whether express or implied. AWS responsibilities and liabilities to its customers are controlled by AWS agreements, and this Guidance is not part of, nor does it modify, any agreement between AWS and its customers.

---

## Authors
- Randall Potter

---

## πŸ“– Further Reading

### πŸ€– Amazon Bedrock & Foundation Models
- [Amazon Bedrock Developer Experience](https://aws.amazon.com/bedrock/developer-experience/) - Foundation model choice and customization
- [Anthropic's Claude in Amazon Bedrock](https://aws.amazon.com/bedrock/anthropic/) - Claude Opus 4.6, Sonnet 4.5, Haiku 4.5 hybrid reasoning models
- [Claude Sonnet 4.5 in Amazon Bedrock](https://aws.amazon.com/blogs/aws/introducing-claude-sonnet-4-5-in-amazon-bedrock-anthropics-most-intelligent-model-best-for-coding-and-complex-agents/) - Most intelligent model for coding and complex agents
- [Claude Opus 4.6 in Amazon Bedrock](https://aws.amazon.com/blogs/machine-learning/claude-opus-4-5-now-in-amazon-bedrock/) - Tool search, extended thinking, and agent capabilities
- [Amazon Nova Foundation Models](https://aws.amazon.com/blogs/aws/introducing-amazon-nova-frontier-intelligence-and-industry-leading-price-performance/) - Nova Micro, Lite, Pro, Premier - frontier intelligence
- [Using Amazon Nova in AI Agents](https://docs.aws.amazon.com/nova/latest/userguide/agents-use-nova.html) - Nova as foundation model for agents

### πŸš€ Amazon Bedrock AgentCore
- [Amazon Bedrock AgentCore Overview](https://aws.amazon.com/bedrock/agentcore/) - Build, deploy, and operate agents at scale
- [AgentCore Gateway Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building.html) - Set up unified tool connectivity
- [AgentCore Gateway Blog](https://aws.amazon.com/blogs/machine-learning/introducing-amazon-bedrock-agentcore-gateway-transforming-enterprise-ai-agent-tool-development/) - Transforming enterprise AI agent tool development
- [AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html) - Secure serverless hosting for AI agents

### ⚑ AWS Lambda
- [Lambda Layers Overview](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html) - Managing dependencies with layers
- [Python Lambda Layers](https://docs.aws.amazon.com/lambda/latest/dg/python-layers.html) - Working with layers for Python functions
- [Adding Layers to Functions](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) - Layer configuration and management

### πŸ” Amazon Cognito
- [OAuth 2.0 Grants](https://docs.aws.amazon.com/cognito/latest/developerguide/federation-endpoints-oauth-grants.html) - Authorization code, implicit, and client credentials
- [M2M Authorization](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html) - Scopes, resource servers, and machine-to-machine auth
- [M2M Security Best Practices](https://aws.amazon.com/blogs/security/how-to-monitor-optimize-and-secure-amazon-cognito-machine-to-machine-authorization/) - Monitor, optimize, and secure M2M authorization

### πŸ“ˆ Observability
- [CloudWatch + X-Ray Integration](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-cloudwatch.html) - Enhanced application monitoring
- [Cross-Account Tracing](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-crossaccount.html) - Distributed tracing across accounts
- [AWS Observability Best Practices](https://aws.amazon.com/blogs/publicsector/building-resilient-public-services-with-aws-observability-best-practices/) - Logs, metrics, and traces

### πŸ“¦ Amazon S3
- [S3 as Data Lake Storage](https://docs.aws.amazon.com/whitepapers/latest/building-data-lakes/amazon-s3-data-lake-storage-platform.html) - Central storage platform best practices
- [S3 Performance Optimization](https://aws.amazon.com/s3/whitepaper-best-practices-s3-performance/) - Design patterns for optimal performance

### πŸ’» Amazon Kiro IDE
- [Amazon Kiro Overview](https://aws.amazon.com/kiro/) - Agentic IDE for spec-driven development
- [Kiro with AWS Builder ID](https://docs.aws.amazon.com/signin/latest/userguide/builder_id-apps.html) - Sign in and get started with Kiro
- [Nova Act IDE Extension](https://aws.amazon.com/blogs/aws/accelerate-ai-agent-development-with-the-nova-act-ide-extension/) - Accelerate AI agent development in Kiro
- [Production-Ready AI Agents at Scale](https://aws.amazon.com/blogs/machine-learning/enabling-customers-to-deliver-production-ready-ai-agents-at-scale/) - Kiro as part of the agent development ecosystem