Merge pull request #245 from mrgiba/main

feat: Contract Compliance Analysis V2

Author: krokoko

README.md

@@ -16,7 +16,7 @@ This repo provides samples to demonstrate how to build your own Generative AI so
 |[Amazon Bedrock Agents](samples/bedrock-agent/)| This sample provides a sample application which deploys an Amazon Bedrock Agent and Knowledge Base backed by an OpenSearch Serverless Collection and documents in S3. It demonstrates how to use the [Amazon Bedrock CDK construct](https://github.com/awslabs/generative-ai-cdk-constructs/tree/main/src/cdk-lib/bedrock). |Backend|TypeScript|
 |[Python Samples](samples/python-samples/)| This project showcases the utilization of the 'generative-ai-cdk-constructs' package from the Python Package Index (PyPI).| Backend | Python|
 |[.NET Samples](samples/dotnet-samples/)| This project showcases the utilization of the 'Cdklabs.GenerativeAiCdkConstructs' package from nuget library.| Backend | .NET|
-|[Contract Compliance Analysis](samples/contract-compliance-analysis/)| This project automates the analysis of contracts by splitting them into clauses, determining clause types, evaluating compliance against a customer's legal guidelines, and assessing overall contract risk based on the number of compliant clauses. This is achieved through a workflow that leverages Large Language Models via Amazon Bedrock. | Backend + Frontend | Python for Backend, TypeScript (React) for Frontend |
+|[Contract Compliance Analysis](samples/contract-compliance-analysis/)|  This prototype can potentially help you make your contract compliance process more efficient, leveraging Generative Artificial Intelligence (GenAI) to evaluate contract clauses against predefined guidelines and to provide feedback on adherence to standards applicable to you, based on your instructions. This is achieved through workflows that leverages Large Language Models via Amazon Bedrock. | Backend + Frontend | Python for Backend, TypeScript (React) for Frontend |
 |[Multimodal RAG solution](samples/multimodal-rag)| This project showcases Amazon Bedrock multimodal features using [Amazon Bedrock Data Automation](https://aws.amazon.com/bedrock/bda/) (BDA) combined with Amazon Bedrock Knowledge Bases for a RAG-based chatbot. | Backend + Frontend | Python for Backend, TypeScript (React) for Frontend |
 |[RFP Answers with GenAI](samples/rfp-answer-generation/)| This project provides guidance on how you can use Knowledge Bases for Amazon Bedrock with custom transformations to create draft answers for Request for Proposal (RFP) documents, streamlining the answer of new potential contracts. This is achieved through a workflow that leverages Large Language Models via Amazon Bedrock. | Backend + Frontend | Python for Backend, TypeScript (React) for Frontend |
 | [Code Expert](samples/code-expert/)                                                          | This project addresses the scalability limitations of manual code reviews by leveraging artificial intelligence to perform expert code reviews automatically. It leverages the [Bedrock Batch Step Functions CDK construct](https://github.com/awslabs/generative-ai-cdk-constructs/blob/main/src/patterns/gen-ai/aws-bedrock-batch-stepfn/README.md). | Backend            | Python for Backend and Demo, TypeScript for CDK     |

samples/contract-compliance-analysis/.gitignore

@@ -1 +1,5 @@
-history
+history
+**/**/history*
+**/**/.DS_Store
+.kiro
+.amazonq

samples/contract-compliance-analysis/AmazonQ.md

@@ -0,0 +1,32 @@
+# Contract Compliance Analysis - Setup Guide
+
+This guide covers the key steps to deploy and run the Contract Compliance Analysis prototype.
+
+## Follow READMEs in order (please read each one in full)
+1. `backend/README.md` - Deploy backend stack and load guidelines
+2. `frontend/README.md` - Configure and run frontend
+
+## What to check before starting the deployment
+- Check if there is AWS profile configure
+- Check the AWS account number and ask user to confirm it's the expected one
+- Get AWS default account region and ask user to confirm it's the expected one
+
+## General deployment/configuration recommendations
+- Follow README instructions in sequence. Make sure not to miss instructions.
+- For running `cdk deploy`, `cdk bootstrap` or any other command that will log much content, run the command redirecting the log to a temporary folder
+- It's recommended to run cdk deploy having '--require-approval=never' flag, otherwise cdk deploy will prompt for typing (y/n) but the user will not see, since it's running behind q chat / execute_bash
+- Legislation Check is an optional feature, but feel free to ask user if they want the feature to be configured - but alert about the costs (OpenSearch)
+- For frontend, rather than running the command to start the web application, just tell the user what the command is
+
+## Additional Steps for MainBackendStack stack
+
+### 1. Enable Bedrock Model Access
+Follow the "Enable Bedrock Model Access (Prerequisite)" section in `backend/README.md` before deploying the stack.
+
+### 2. Get Stack Outputs for Frontend
+```bash
+aws cloudformation describe-stacks --stack-name MainBackendStack --query "Stacks[0].Outputs"
+```
+
+### 3. Create Cognito User
+Follow the "Add users to Cognito User Pool" section in `backend/README.md`

samples/contract-compliance-analysis/README.md

@@ -2,86 +2,153 @@
 
 ## Overview
 
-This is a project to automate the compliance analysis of contracts, leveraging Generative Artificial Intelligence (GenAI) to evaluate contract clauses against predefined guidelines and provide feedback on their adherence to the required standards.
+This prototype can potentially help you make your contract compliance process more efficient, leveraging Generative Artificial Intelligence (GenAI) to evaluate contract clauses against predefined guidelines and to provide feedback on adherence to standards applicable to you, based on your instructions.
+
+This prototype is powered by Large Language Models (LLMs) available on Amazon Bedrock, capable of understanding common legal terms and concepts. The LLMs are used to perform advanced natural language tasks like classifying contractual clauses and evaluating whether a particular clauses aligns with predefined guidelines.
+
+**NOTE: Contract Compliance Analysis prototype does not provide legal advice, nor does it serve as a substitute for professional advice. Legal matters may be complex and fact-specific, so you should make your own assessment and consider seeking the advice of a licensed legal profession for any legal matters you encounter.**
+
+## Folder Structure
+
+This sample application codebase is organized into these key folders:
+
+```
+samples/contract-compliance-analysis
+│
+├── backend                                        # Backend
+├── frontend                                       # Frontend
+```
+
+## Getting started
+
+> **Warning**
+> This sample allows you to interact with models from third party providers. Your use of the third-party generative AI (GAI) models is governed by the terms provided to you by the third-party GAI model providers when you acquired your license to use them (for example, their terms of service, license agreement, acceptable use policy, and privacy policy).
+
+> You are responsible for ensuring that your use of the third-party GAI models comply with the terms governing them, and any laws, rules, regulations, policies, or standards that apply to you.
+
+> You are also responsible for making your own independent assessment of the third-party GAI models that you use, including their outputs and how third-party GAI model providers use any data that might be transmitted to them based on your deployment configuration. AWS does not make any representations, warranties, or guarantees regarding the third-party GAI models, which are "Third-Party Content" under your agreement with AWS. This sample is offered to you as "AWS Content" under your agreement with AWS.
+
+To deploy this project, follow the instructions available in the README files located at the **backend** and **frontend** folders, in that sequence.
+
+## Key Features
+
+- **Automated Contract Analysis**: Validates, processes, classifies, and evaluates contract clauses against your guidelines with risk assessment
+- **Multi-Language AI Analysis**: Generate analysis reports in English, Spanish, or Portuguese based on user selection
+- **Multi-Contract Type Support**: Define and manage multiple contract types (service agreements, employment contracts, etc.) with type-specific guidelines
+- **Web Application**: User interface for managing contract types, guidelines, and viewing analysis results
+- **AI-Generated Evaluation Questions**: Automatically create compliance questions from guideline definitions
+- **Contract Import**: Bootstrap new contract types by extracting guidelines from reference contracts
+- **Configurable Risk Thresholds**: Customize risk classification criteria per contract type
+- **Flexible Model Selection**: Configure different foundation models for specific tasks via parameter store
+- **Optional Legislation Compliance**: AI agent with knowledge base integration for verifying clauses against legal documents
 
-The project is powered by Large Language Models (LLM) available on Amazon Bedrock, capable of understanding legal terminology and concepts. LLMs are used to perform advanced natural language tasks, such as clause classification and compliance evaluation according to predefined guidelines.
 
 ## Architecture
 
-The core of this solution is the contract analysis workflow, which leverages Large Language Models to perform advanced natural language tasks to evaluate clauses against predefined guidelines. 
-Different storage components are used for the input, intermediate steps, analysis output, and the guidelines information. Additionally, there are components for the user interface, comprising web application hosting, authentication, and integration services.
+This prototype leverages AWS managed services and Large Language Models to automate contract compliance analysis. The architecture consists of multiple workflows that work together to validate contracts against your guidelines and optionally verify compliance with legislation.
+
+### High-Level Architecture
+
+The system includes serverless workflows for contract processing, a web interface for managing contract types and viewing results, authentication via Amazon Cognito, and storage for contracts, guidelines, and analysis results:
 
 ![High Level Architecture](./images/high-level-architecture.png)
 
-Zooming in to the contract analysis workflow:
+### Guidelines Compliance Workflow
+
+The core workflow processes uploaded contracts through multiple stages: validation, preprocessing (clause extraction), classification (identifying clause types using LLMs), evaluation (checking compliance against guidelines), and risk assessment (calculating overall contract risk):
+
+![Guidelines Compliance Architecture](./images/guidelines-compliance-architecture.png)
 
-![High Level Architecture](./images/contract-analysis-architecture.png)
+### Legislation Compliance Workflow (Optional)
+
+When enabled, this workflow uses an AI agent with access to a knowledge base of legislation documents to verify that contract clauses comply with applicable laws and regulations:
+
+![Legislation Compliance Architecture](./images/legislation-compliance-architecture.png)
+
+### Contract Import Workflow
+
+This workflow uses LLMs to automatically extract contract type information and guidelines from reference contracts, enabling rapid onboarding of new contract types without manual guideline creation:
+
+![Contract Import Architecture](./images/contract-import-architecture.png)
 
 ## Cost Analysis and Pricing
 
-This solution demonstrates significant cost savings by using Amazon Nova models compared to traditional Claude models. The following analysis is based on processing the **sample contract included with this solution** using the default guidelines.
+This section analyzes the primary cost drivers for this prototype and demonstrates significant cost savings by using Amazon Nova models compared to Claude models.
+
+### Primary Cost Drivers
+
+**1. Amazon Bedrock** - LLM inference costs for contract processing. Varies based on contract size, guidelines complexity, selected model, and usage volume.
 
-### Model Cost Comparison
+**2. Amazon OpenSearch Serverless (Optional)** - Required only if legislation compliance is deployed. **Minimum cost: ~$350/month** (2 OCUs at ~$0.24/OCU-hour), continuous even when idle.
+
+**3. Other AWS Services** - Step Functions, DynamoDB, Lambda, S3, and API Gateway use pay-per-use pricing. Typically much smaller than Bedrock and OpenSearch costs.
+
+### Bedrock Model Cost Comparison
+
+> **Note**: The following cost estimates are based on actual processing of the **sample contract included with this prototype** using the default guidelines. Your actual costs may vary depending on contract size, guidelines complexity, and usage patterns.
 
 The following analysis shows token usage and costs for processing the included sample contract. Some of the scenarios have [Amazon Bedrock prompt caching](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) enabled.
 
 #### Claude 3.5 Haiku and Amazon Nova Lite
 | Model | Input Tokens | Output Tokens | Cache Read Tokens | Cache Write Tokens | **Total Cost** |
 |-------|-------------|---------------|-------------------|-------------------|---------------|
-| **Claude 3.5 Haiku** | 98,166<br>$0.08 | 40,570<br>$0.16 | 570,255<br>$0.05 | 16,293<br>$0.02 | **$0.30** |
-| **Amazon Nova Lite** | 89,140<br>$0.07 | 45,733<br>$0.11 | 534,275<br>$0.11 | 15,265<br>$0.00 | **$0.02** |
-| | | | | **Savings:** | **🟢 92%** |
+| **Claude 3.5 Haiku** | 96,627<br>$0.08 | 38,273<br>$0.15 | 556,512<br>$0.04 | 16,368<br>$0.02 | **$0.29** |
+| **Amazon Nova Lite** | 88,024<br>$0.01 | 35,208<br>$0.01 | 567,691<br>$0.01 | 15,343<br>$0.00 | **$0.02** |
+| | | | | **Savings:** | **🟢 93%** |
 
 #### Claude 3.5 Sonnet v2 and Amazon Nova Pro (without prompt caching)
 | Model | Input Tokens | Output Tokens | **Total Cost** |
 |-------|-------------|---------------|---------------|
-| **Claude 3.5 Sonnet v2** | 684,737<br>$2.05 | 65,927<br>$0.99 | **$3.04** |
-| **Amazon Nova Pro** | 625,677<br>$0.50 | 33,493<br>$0.11 | **$0.61** |
-| | | **Savings:** | **🟢 80%** |
+| **Claude 3.5 Sonnet v2** | 706,407<br>$4.24 | 58,021<br>$1.74 | **$5.98** |
+| **Amazon Nova Pro** | 577,291<br>$0.46 | 30,384<br>$0.10 | **$0.56** |
+| | | **Savings:** | **🟢 91%** |
 
 #### Claude 3.7 Sonnet and Amazon Nova Premier
 | Model | Input Tokens | Output Tokens | Cache Read Tokens | Cache Write Tokens | **Total Cost** |
 |-------|-------------|---------------|-------------------|-------------------|---------------|
-| **Claude 3.7 Sonnet** | 98,189<br>$0.29 | 65,927<br>$0.99 | 586,548<br>$0.18 | 16,293<br>$0.06 | **$1.52** |
-| **Amazon Nova Premier** | 92,706<br>$0.23 | 53,539<br>$0.69 | 541,100<br>$0.34 | 15,460<br>$0.00 | **$1.26** |
-| | | | | **Savings:** | **🟢 17%** |
+| **Claude 3.7 Sonnet** | 94,944<br>$0.28 | 80,574<br>$1.21 | 572,880<br>$0.17 | 16,368<br>$0.01 | **$1.67** |
+| **Amazon Nova Premier** | 91,076<br>$0.23 | 49,836<br>$0.62 | 529,550<br>$0.33 | 15,575<br>$0.00 | **$1.18** |
+| | | | | **Savings:** | **🟢 29%** |
 
+### Pricing Reference
 
-### Cost Factors
+For the most up-to-date pricing information, refer to the [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) page.
 
-Actual costs depend on several factors:
-- **Guidelines complexity**: More detailed guidelines require more tokens
-- **Contract size**: Larger contracts consume more input tokens
-- **Selected LLM**: Different models have different pricing structures
 
-### Pricing Reference
+## Documentation
 
-For the most up-to-date pricing information, refer to the [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) page.
+For comprehensive information including architecture, security, deployment, and operations, see the [Technical Documentation](./documentation/technical-documentation.adoc).
 
-> **Note**: The cost analysis above is based on processing the sample contract included with this solution using the default guidelines. Your actual costs may vary depending on your specific contract sizes, guidelines complexity, and usage patterns.
+## Optional: Use Amazon Q Developer CLI Assistant to setup project
 
-## Folder Structure
+For additional setup assistance, you can optionally use Amazon Q Developer CLI, an AI assistant that can help guide you through the deployment process, troubleshoot issues, and answer questions about AWS services.
 
-This sample application codebase is organized into these key folders:
+> **Security Note**: Amazon Q CLI can read files and execute AWS CLI commands. Review all suggested commands before execution, especially those that create, modify, or delete AWS resources. Use in development environments only.
 
-```
-samples/contract-compliance-analysis
-│
-├── backend                                        # Backend
-├── frontend                                       # Frontend
-```
+### Installation
 
-## Getting started
+Install Amazon Q Developer CLI by following the instructions at: https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html
 
-> **Warning**
-> This sample allows you to interact with models from third party providers. Your use of the third-party generative AI (GAI) models is governed by the terms provided to you by the third-party GAI model providers when you acquired your license to use them (for example, their terms of service, license agreement, acceptable use policy, and privacy policy).
+### Usage
 
-> You are responsible for ensuring that your use of the third-party GAI models comply with the terms governing them, and any laws, rules, regulations, policies, or standards that apply to you.
+1. Start the interactive assistant from the project root directory:
+   ```bash
+   q chat
+   ```
 
-> You are also responsible for making your own independent assessment of the third-party GAI models that you use, including their outputs and how third-party GAI model providers use any data that might be transmitted to them based on your deployment configuration. AWS does not make any representations, warranties, or guarantees regarding the third-party GAI models, which are “Third-Party Content” under your agreement with AWS. This sample is offered to you as “AWS Content” under your agreement with AWS.
+2. Ask for help with setup, for example:
+   - "Help me set up this contract compliance analysis project"
+   - "What are the steps to deploy this application?"   
 
-To deploy this project, follow the instructions available in the README files located at the **backend** and **frontend** folders, in that sequence.
+The assistant will have access to this project's documentation and could help with:
+- Step-by-step deployment guidance
+- AWS CLI commands and troubleshooting
+- Stack output retrieval and frontend configuration
+- Cognito user creation
+
+**Important**: Always review and understand commands before executing them. Q CLI will ask for confirmation before making changes to your system or AWS resources.
 
+Type `/quit` to exit the assistant. For more Q CLI options, run `q --help`.
 
 # Content Security Legal Disclaimer
 The sample code; software libraries; command line tools; proofs of concept; templates; or other related technology (including any of the foregoing that are provided by our personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.