You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+111-6
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,117 @@
1
-
## My Project
1
+
#Conversation With Your Architecture Demo
2
2
3
-
TODO: Fill this README out!
3
+
This project demonstrates how to chat with your architecture using Amazon Bedrock's Converse API, tool use, and a knowledge base. Implemented in Python, the demo allows users to analyze architecture diagrams, evaluate effectiveness, get recommendations, and make informed decisions about their system architecture.
4
4
5
-
Be sure to:
5
+
The application interacts with a foundation model on Amazon Bedrock to provide information based on an architecture diagram and user input. It utilizes three custom tools to gather information:
6
6
7
-
* Change the title in this README
8
-
* Edit your repository description on GitHub
7
+
1. Audit Info Tool: Provides audit information about a system based on the system name inferred from the architecture diagram file name.
8
+
2. Joy Count Tool: Provides joy count data about a system.
9
+
3. Best Practices Tool: Provides a company's best practices information, including best practices around how much joy the application is generating.
10
+
11
+
This demo is based on the [Amazon Bedrock Tool Use Demo](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/bedrock-runtime/cross-model-scenarios/tool_use_demo) and parts of [Amazon Bedrock: Enhance HR Support with Function Calling & Knowledge Bases blog post](https://community.aws/content/2izvh9HlmMvgYyRMoOUbkR0bNPV/enhancing-hr-support-with-function-calling-and-knowledge-bases-in-amazon-bedrock).
12
+
13
+
## ⚠️ Warning
14
+
15
+
Running this app may result in charges to your AWS account.
16
+
17
+
## Repository Structure
18
+
19
+
-`architecture_chat_demo.py`: Main entry point for the demo application.
20
+
-`audit_info_tool.py`: Implementation of the Audit Info Tool.
21
+
-`best_practices_tool.py`: Implementation of the Best Practices Tool.
22
+
-`joy_count_tool.py`: Implementation of the Joy Count Tool.
23
+
-`demo/`: Directory containing sample data files.
24
+
-`audit-info.json`: Sample audit information for the Fluffy Puppy Joy Generator system.
25
+
-`best-practices-data.md`: Sample best practices data for the organization
26
+
-`joy-count.json`: Sample joy count data for the Fluffy Puppy Joy Generator system.
27
+
-`fluffy-puppy-joy-generator.png`: Sample architecture diagram image for the Fluffy Puppy Joy Generator system.
28
+
-`fluffy-puppy-joy-generator.drawio`: Sample architecture diagram Draw.io format for the Fluffy Puppy Joy Generator system.
29
+
-`util/`: Directory containing utility functions.
30
+
-`demo_print_utils.py`: Utility functions for printing demo-related messages.
31
+
-`README.md`: This file, containing project documentation.
32
+
33
+
## Usage Instructions
34
+
35
+
### Prerequisites
36
+
37
+
To run this demo, you'll need a few bits set up first:
38
+
39
+
- An AWS account. You can create your account [here](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
40
+
- Request access to an AI model (we'll use Claude Sonnet) on Amazon Bedrock before you can use it. Learn about model access [here](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html).
41
+
-[Python 3.6.0 or later](https://www.python.org/) setup and configured on your system.
42
+
- A [python virtual environment setup](https://docs.python.org/3/library/venv.html) with packages installed via [requirements.txt](requirements.txt).
43
+
44
+
### Setup
45
+
46
+
Set up your custom environmeng variables by creating a `.env` file in the project root directory with the following content:
47
+
48
+
```
49
+
AWS_REGION=<your-aws-region>
50
+
KNOWLEDGE_BASE_ID=<your-knowledge-base-id>
51
+
```
52
+
53
+
### Run the app
54
+
55
+
To run the app, run the following command in your virtual environment:
56
+
57
+
```bash
58
+
python architecture_chat_demo.py
59
+
```
60
+
61
+
2. When prompted, enter `fluffy-puppy-joy-generator.png` when prompted for a diagram to chat with (or check out the next section to use your own).
62
+
63
+
3. Then enter one of the example queries to interact with the diagram or ask your questions about the architecture.
64
+
65
+
4. To exit the demo, type `x` and press Enter.
66
+
67
+
### Bring your own diagram
68
+
69
+
Want to chat with your own diagram? Drop an image file (jpg, jpeg, or png) into the `demo` folder and rerun the app. When prompted, enter the full name (excluding the path) of that diagram to chat with.
70
+
71
+
### Sample queries
72
+
73
+
Below are some sample queries you could use to chat with an architecture diagram in this app:
74
+
75
+
- List the AWS Services used in the architecture diagram by official AWS name and excluding any sub-titles.
76
+
- What are the recommended strategies for unit testing this architecture?
77
+
- How well does this architecture adhere to the AWS Well Architected Framework?
78
+
- What improvements should be made to the resiliency of this architecture?
79
+
- Convert the data flow from this architecture into a Mermaid formatted sequence diagram.
80
+
- What are the quotas or limits in this architecture?
81
+
82
+
### Bonus: Generate the infrastructure code
83
+
84
+
Depending on the type of diagram you're chatting with, you could also enter the following query to generate the infrastructure code:
85
+
86
+
```plaintext
87
+
Can you generate the Terraform code to provision this architecture?
88
+
```
89
+
90
+
## Data Flow
91
+
92
+
1. User Input: The user provides input through the command-line interface.
93
+
2. Architecture Chat Demo: The main `ArchitectureChatDemo` class processes the user input and manages the conversation flow.
94
+
3. Amazon Bedrock: The user's input is sent to Amazon Bedrock's Converse API along with the system prompt and tool configurations.
95
+
4. Tool Invocation: Based on the model's response, the appropriate tool (Audit Info, Joy Count, or Best Practices) is invoked.
96
+
5. Tool Processing: The invoked tool fetches data from its respective source (JSON files or knowledge base).
97
+
6. Response Generation: The tool's output is sent back to Amazon Bedrock for further processing and response generation.
98
+
7. User Output: The final response is displayed to the user through the command-line interface.
99
+
100
+
See [sequence diagram](sequencediagram.mmd).
101
+
102
+
## Troubleshooting
103
+
104
+
- If you encounter authentication errors, ensure your AWS credentials are correctly set up in your environment or AWS credentials file.
105
+
- If the demo fails to start, check that all required environment variables are set in the `.env` file.
106
+
- For issues with tool invocations, verify that the JSON files in the `demo/` directory are present and correctly formatted.
107
+
108
+
To enable debug mode, set the `logging` level to `DEBUG` in the `architecture_chat_demo.py` file:
0 commit comments