aws-solutions-library-samples · HatmanStack · Sep 8, 2025 · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.py text eol=lf
+*.sh text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
diff --git a/docs/agent-analysis.md b/docs/agent-analysis.md
@@ -37,18 +37,15 @@ https://github.com/user-attachments/assets/e2dea2c5-5eb1-42f6-9af5-469afd2135a7
 
 ## Architecture
 
-The architecture of the Agent Analysis feature is shown below. The Web UI and AppSync API components are the same as used by the rest of the IDP system (with new AppSync endpoints added). Note the inclusion of Amazon Athena and the AgentCore Code Interpreter is specific to the Analytics Agent, but the Agent Request Handler and Processor lambdas along with jobs table are used for all agents, including [MCP agents](./custom-MCP-agent.md).
-
-![Architecture Diagram](../images/IDP-AnalyticsAgent.drawio.png)
-
 ### Multi-Agent System
 
 The Agent Analysis feature uses a multi-agent architecture with:
 
 1. **Orchestrator Agent**: Routes queries to appropriate specialized agents based on query content and agent capabilities
 2. **Analytics Agent**: Handles data analysis, SQL generation, and visualization creation
-3. **External MCP Agents**: Custom agents connected via Model Context Protocol servers
-
+3. **Dummy Agent**: Provides simple calculations and development testing capabilities
+4. **External MCP Agents**: Custom agents connected via Model Context Protocol servers
+5. **Extensible Framework**: Easy addition of new specialized agents for specific use cases
 
 ### Agent Workflow
 

diff --git a/docs/custom-MCP-agent.md b/docs/custom-MCP-agent.md
@@ -20,9 +20,23 @@ The External MCP Agent allows you to:
 - **Real-time Integration**: Tools are available immediately through the IDP web interface
 
 ## Architecture
-An example architecture demonstrating the authentication flow and connections between the MCP Client (running in the IDP application) and an external MCP Server (deployed outside of the IDP application) can be seen below. The `get_client_address` and `send_verification_email` APIs drawn are just for demonstration purposes.
 
-![Architecture Diagram](../images/IDP-external-mcp-example.drawio.png)
+```
+┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
+│   IDP Solution      │    │   Your AWS Account   │    │   Your MCP Server   │
+│                     │    │                      │    │                     │
+│ ┌─────────────────┐ │    │ ┌──────────────────┐ │    │ ┌─────────────────┐ │
+│ │ External MCP    │ │    │ │ AWS Cognito      │ │    │ │ Custom Tools    │ │
+│ │ Agent           │◄┼────┼─┤ User Pool        │◄┼────┼─┤ - Calculator    │ │
+│ │                 │ │    │ │                  │ │    │ │ - Weather API   │ │
+│ └─────────────────┘ │    │ └──────────────────┘ │    │ │ - Database      │ │
+│                     │    │                      │    │ │ - Custom Logic  │ │
+│ ┌─────────────────┐ │    │                      │    │ └─────────────────┘ │
+│ │ AWS Secrets     │ │    │                      │    │                     │
+│ │ Manager         │ │    │                      │    │                     │
+│ └─────────────────┘ │    │                      │    │                     │
+└─────────────────────┘    └──────────────────────┘    └─────────────────────┘
+```
 
 ## Prerequisites
 

diff --git a/docs/govcloud-deployment.md b/docs/govcloud-deployment.md
@@ -42,7 +42,7 @@ You need to have the following packages installed on your computer:
 3. [sam (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
 4. python 3.11 or later
 5. A local Docker daemon
-6. Python packages for publish.py: `pip install boto3 rich PyYAML botocore setuptools`
+6. Python packages for publish.py: `pip install boto3 typer rich botocore setuptools`
 
 ### Step 1: Generate GovCloud Template
 
@@ -65,7 +65,7 @@ aws cloudformation deploy \
   --template-file .aws-sam/idp-govcloud.yaml \
   --stack-name my-idp-govcloud-stack \
   --region us-gov-west-1 \
-  --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
+  --capabilities CAPABILITY_IAM \
   --parameter-overrides \
     IDPPattern="Pattern2 - Packet processing with Textract and Bedrock"
 ```

diff --git a/docs/pattern-1.md b/docs/pattern-1.md
@@ -196,11 +196,49 @@ payload = {
 
 Pattern-1 supports Human-in-the-Loop (HITL) review capabilities using Amazon SageMaker Augmented AI (A2I). This feature allows human reviewers to validate and correct extracted information when the system's confidence falls below a specified threshold.
 
-**Pattern-1 Specific Configuration:**
+#### HITL Workflow
+1. **Automatic Triggering**: 
+   - HITL is triggered when the feature is enabled in your configuration
+   - Extraction confidence score falls below your configured confidence threshold
+   - The system creates a human review task in SageMaker A2I
+
+2. **Review Process**:
+   - Reviewers access the SageMaker A2I Review Portal (URL available in CloudFormation output `SageMakerA2IReviewPortalURL`)
+   - Login credentials are the same as those used for the GenAI IDP portal (if you want to use your own Private work team, you can provide your existing private workforce work team arn as a input parameter for `Pattern1 - Existing Private Workforce ARN`)
+   - Extracted key-value pairs are presented for validation and correction
+   - Reviewers validate correct extractions or make necessary corrections
+   - After review, corrections are submitted with the "Submit" button
+
+3. **Result Integration**:
+   - Corrected key-value pairs automatically update the source results
+   - The document processing workflow continues with the human-verified data
+
+<img src="../../images/hitl_a2i_workflow.png" alt="HITL Flow diagram" width="800">
+
+#### Configuration
 - `EnableHITL`: Boolean parameter to enable/disable the HITL feature
-- `Pattern1 - Existing Private Workforce ARN`: Optional parameter to use existing private workforce
+- **Confidence Threshold**: Configured through the Web UI Portal Configuration tab under "Assessment & HITL Configuration" section. This numeric value (0.0-1.0) determines when human review is triggered based on extraction confidence scores.
 
-For comprehensive HITL documentation including workflow details, configuration steps, best practices, and troubleshooting, see the [Human-in-the-Loop Review Guide](./human-review.md). 
+#### Configuring Confidence Threshold
+To set the confidence threshold for HITL triggering:
+
+1. **Access the Web UI**: Open the Web UI URL from your CloudFormation stack outputs
+2. **Navigate to Configuration**: Click on the "Configuration" tab in the navigation menu
+3. **Find Assessment & HITL Section**: Scroll to the "Assessment & HITL Configuration" section
+4. **Set Confidence Threshold**: 
+   - Enter a value between 0.0-1.0 (e.g., 0.8 for 80% confidence threshold)
+   - Fields with confidence scores below this threshold will trigger HITL review
+5. **Save Configuration**: Click "Save" to apply the changes
+
+The confidence threshold is stored as a configuration parameter and automatically applied to new document processing without requiring stack redeployment.
+
+#### Best Practices
+- Regularly check the Review Portal for pending tasks to avoid processing delays
+- Establish consistent correction guidelines if multiple reviewers are involved
+
+#### Known Limitations
+  - Current version of SageMaker A2I cannot provide direct hyperlink to respective document tasks. When reviewer clicks on review document URL and start working, review portal will start displating all review tasks. Reviewer cannot pick specific task and start working. 
+  - Updating SageMaker A2I Template and workflow performs deletion on A2I flow definition, A2I custom template and recreate the resources via lambda function. Update A2I resources through Python SDK is not allowed. 
 
 ## Best Practices
 1. **BDA Project Configuration**:

diff --git a/docs/pattern-2.md b/docs/pattern-2.md
@@ -16,7 +16,6 @@ This pattern implements an intelligent document processing workflow that uses Am
     - [Classification Function](#classification-function)
     - [Extraction Function](#extraction-function)
     - [ProcessResults Function](#processresults-function)
-  - [Human-in-the-Loop (HITL)](#human-in-the-loop-hitl)
   - [Monitoring and Metrics](#monitoring-and-metrics)
     - [Performance Metrics](#performance-metrics)
     - [Error Tracking](#error-tracking)
@@ -177,17 +176,6 @@ Each step includes comprehensive retry logic for handling transient errors:
   }
   ```
 
-### Human-in-the-Loop (HITL)
-
-Pattern-2 supports Human-in-the-Loop (HITL) review capabilities using Amazon SageMaker Augmented AI (A2I). This feature allows human reviewers to validate and correct extracted information when the system's confidence falls below a specified threshold.
-
-**Pattern-2 Specific Configuration:**
-- `EnableHITL`: Boolean parameter to enable/disable the HITL feature
-- `IsPattern2HITLEnabled`: Boolean parameter specific to Pattern-2 HITL enablement
-- `Pattern2 - Existing Private Workforce ARN`: Optional parameter to use existing private workforce
-
-For comprehensive HITL documentation including workflow details, configuration steps, best practices, and troubleshooting, see the [Human-in-the-Loop Review Guide](./human-review.md).
-
 ### Monitoring and Metrics
 
 The pattern includes a comprehensive CloudWatch dashboard with:

diff --git a/docs/setup-development-env-WSL.md b/docs/setup-development-env-WSL.md
@@ -0,0 +1,126 @@
+# Development Environment Setup Guide on Windows using WSL
+
+## Introduction  
+This guide establishes a WSL-based development environment on Windows, specifically designed for the GenAI IDP accelerator.
+
+**Purpose**: Provides a Linux development environment directly on Windows without virtualization overhead, combining native Windows tools with a complete Linux development stack.
+
+**When to use this guide**:
+- You're developing on Windows and need Linux compatibility
+- You want to avoid Docker Desktop or VM overhead
+- You need consistent behavior with the project's Linux-based AWS infrastructure
+- You prefer integrated Windows/Linux development workflows
+
+**What you'll achieve**: A seamless development setup where you can use Windows tools (VS Code, browsers, file explorers) while running the GenAI IDP accelerator in a native Linux environment.
+
+## Prerequisites
+
+**Official Microsoft WSL Installation Guide**: https://docs.microsoft.com/en-us/windows/wsl/install
+
+## Step 1: Enable WSL on Windows
+
+### 1.1 Install WSL with Ubuntu
+1. Open PowerShell as Administrator
+2. Run the installation command:
+```bash
+wsl --install -d Ubuntu 
+```  
+3. Complete Ubuntu setup with username/password 
+4. You will enter into linux shell directly, then go to your WSL home directory using ``` cd ~ ```
+
+## Step 2: Clone Repository and Run Setup Script
+
+### 2.1  Clone Repository
+```
+git clone https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws
+```
+```
+cd accelerated-intelligent-document-processing-on-aws
+```
+
+### 2.2 Run Automated Setup Script
+```
+./scripts/wsl_setup.sh
+```
+This script automatically installs:
+- Git, Python 3, pip, and build tools
+- Node.js 18
+- AWS CLI v2
+- AWS SAM CLI
+- Python dependencies
+
+After running the setup script, go to your WSL home directory using ```cd ~```
+
+## Step 3: Complete Manual Setup
+
+### 3.1 Create Python Virtual Environment
+```
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### 3.2 Install Python Dependencies
+```bash
+pip install setuptools wheel boto3 rich PyYAML botocore ruff pytest typer
+```
+### 3.3 Configure AWS CLI
+```bash
+aws configure
+```
+Enter your AWS credentials when prompted. Refer to: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html
+
+## Step 4: Test the Setup
+
+### 4.1 Verify All Tools
+```bash
+# Check versions
+python3 --version (Example: Python 3.12.3)
+aws --version (Example: aws-cli/2.28.26)
+sam --version (Example: SAM CLI, version 1.143.0)
+node --version (Example: v18.20.8)
+npm --version (Example: 10.8.2)
+```
+### 4.2 Test Build Process
+```
+cd accelerated-intelligent-document-processing-on-aws
+```
+```
+# Test publish script help
+python3 publish.py --help
+
+# Test build (replace with your S3 bucket name)
+python3 publish.py your-bucket-name build-test us-east-1
+```
+
+### 4.3 Troubleshooting Build Issues
+If the build fails, use the `--verbose` flag:
+```bash
+python3 publish.py your-bucket-name build-test us-east-1 --verbose
+```
+
+The verbose flag shows:
+- Exact SAM build commands being executed
+- Complete error output from failed builds
+- Python version compatibility issues
+- Missing dependencies or configuration problems
+
+## Step 5: Install Visual Studio Code on Local Machine for using WSL as a terminal
+### Visit the official website: Go to [https://code.visualstudio.com/](https://code.visualstudio.com/)
+Download: Click the "Download for Windows" button 
+- This will download the User Installer (recommended for most users) 
+- File name will be something like VSCodeUserSetup-x64-1.x.x.exe  
+
+Install:   
+   - Run the downloaded installer  
+   - Choose installation location (default is recommended)  
+
+Launch: Click "Launch Visual Studio Code" when installation completes
+
+### Install VSCode Extensions
+Install **WSL** extension
+
+### Open Project in WSL
+From WSL terminal, navigate to project and open in VSCode
+```
+cd accelerated-intelligent-document-processing-on-aws
+```
diff --git a/docs/web-ui.md b/docs/web-ui.md
@@ -104,11 +104,6 @@ The "Chat with Document" feature is available at the bottom of the Document Deta
 
 Your chat history will be saved as you continue your chat but if you leave the document details screen, your chat history is erased. This feature uses prompt caching for the document contents for repeated chat requests for each document.
 
-See the feature in action in this video:  
-
-https://github.com/user-attachments/assets/50607084-96d6-4833-85a6-3dc0e72b28ac
-
-
 ### How to Use
 
 1. Navigate to a document's detail page and scroll to the bottom
@@ -158,12 +153,12 @@ To run the web UI locally for development:
 1. Navigate to the `/ui` directory
 2. Create a `.env` file using the `WebUITestEnvFile` output from the CloudFormation stack:
 ```
-REACT_APP_USER_POOL_ID=<value>
-REACT_APP_USER_POOL_CLIENT_ID=<value>
-REACT_APP_IDENTITY_POOL_ID=<value>
-REACT_APP_APPSYNC_GRAPHQL_URL=<value>
-REACT_APP_AWS_REGION=<value>
-REACT_APP_SETTINGS_PARAMETER=<value>
+VITE_USER_POOL_ID=<value>
+VITE_USER_POOL_CLIENT_ID=<value>
+VITE_IDENTITY_POOL_ID=<value>
+VITE_APPSYNC_GRAPHQL_URL=<value>
+VITE_AWS_REGION=<value>
+VITE_SETTINGS_PARAMETER=<value>
 ```
 3. Install dependencies: `npm install`
 4. Start the development server: `npm run start`