AWS Bedrock Console App (Python)

A reusable, customizable, and extendable console application for interacting with Amazon Bedrock LLMs using AWS named profiles.

The app is designed for local development on both Windows and Linux, supports AWS SSO profiles, and can run from a self-managed .venv using the provided launcher scripts.

Quick Start

Installation from PyPI

pip install aws-console-app

Run immediately

# Using CLI arguments
aws-console-app --profile my-profile --region us-west-2 --model claude

# Or set environment variables
export AWS_PROFILE=my-profile
export AWS_REGION=us-west-2
aws-console-app

Docker

docker run -it -v "$HOME/.aws:/root/.aws" \
  -e AWS_PROFILE=my-profile \
  -e AWS_REGION=us-west-2 \
  aws-console-app:latest

Features

• Cross-platform runtime (Windows/Linux)
• Reads AWS profile/region from CLI or .env fallback
• Reads account/auth settings from your local .aws folder (config, credentials, sso/cache)
• AWS SSO-friendly authentication behavior:
  • Reuses cached token when valid
  • Triggers aws sso login --profile <profile> --no-browser --use-device-code when needed
• Bedrock chat support with model adapters:
  • Anthropic Claude
  • Amazon Titan Text
  • Amazon Nova
• List available Bedrock text models and embedding models for a region
• OOP architecture for easy extension
• Pytest unit tests with coverage gate
• CI workflows for tests, pip-audit, and Trivy FS scan
• Automated publishing workflows for TestPyPI and PyPI

Project Structure

aws_console_app/
|-- main.py
|-- run.bat
|-- run.sh
|-- requirements.txt
|-- requirements-dev.txt
|-- pyproject.toml
|-- src/
|   |-- auth/
|   |   |-- aws_auth.py
|   |   `-- token_manager.py
|   |-- bedrock/
|   |   |-- bedrock_client.py
|   |   |-- model_catalog.py
|   |   `-- models/
|   |       |-- base_model.py
|   |       |-- claude_model.py
|   |       |-- titan_model.py
|   |       `-- nova_model.py
|   |-- config/
|   |   `-- aws_config.py
|   |-- session/
|   |   `-- conversation.py
|   `-- ui/
|       `-- console_ui.py
|-- tests/
`-- .github/workflows/

Prerequisites

• Python 3.11+
• AWS CLI v2 configured
• Access to Amazon Bedrock in your AWS account/region
• For SSO profiles: profile configured with aws configure sso

Setup

Option A: Local Python (Windows/Linux/macOS)

Windows launcher

.\run.bat --help

Linux/macOS launcher

chmod +x run.sh
./run.sh --help

Launchers will:

1. Create .venv if missing
2. Install dependencies from requirements.txt on first run
3. Execute main.py using .venv Python

Option B: Docker Desktop

Yes, this app reads AWS settings and SSO cache from the home .aws directory.

Paths used by the app:

• ~/.aws/config
• ~/.aws/credentials
• ~/.aws/sso/cache

To run inside Docker while reusing your host AWS profile/session, mount your host .aws into /root/.aws in the container.

Build image

docker build -t aws-console-app:latest .

Run interactive chat with environment variables (Windows PowerShell)

docker run --rm -it `
  -v "$HOME/.aws:/root/.aws" `
  -e AWS_PROFILE=your-profile `
  -e AWS_REGION=us-west-2 `
  aws-console-app:latest

Run interactive chat with CLI args (Windows PowerShell)

docker run --rm -it `
  -v "$HOME/.aws:/root/.aws" `
  aws-console-app:latest `
  python main.py --profile your-profile --region us-west-2 --model claude

List models from container

docker run --rm -it `
  -v "$HOME/.aws:/root/.aws" `
  -e AWS_PROFILE=your-profile `
  -e AWS_REGION=us-west-2 `
  aws-console-app:latest `
  python main.py --list-models

Optional: pass .env from host

If you rely on .env profile/region fallback, mount it too:

docker run --rm -it `
  -v "$HOME/.aws:/root/.aws" `
  -v "${PWD}/.env:/app/.env" `
  aws-console-app:latest `
  python main.py

Notes:

• Keep the .aws mount read-write for SSO refresh flows.
• If SSO is expired, run aws sso login --profile your-profile on host first, or let the container perform device-code login interactively.

Docker Compose and helper scripts

The docker-compose.yml supports environment variables for AWS configuration:

# Build and start container with environment variables
export AWS_PROFILE=your-profile
export AWS_REGION=us-west-2
export CONTAINER_NAME=aws-console-app
export AWS_DIR=$HOME/.aws
docker compose -f docker-compose.yml up -d --build app

Helper scripts available:

• docker_build_image.bat / docker_build_image.sh - Build image
• docker_create_container.bat / docker_create_container.sh - Create/start container
• docker_run_app.bat / docker_run_app.sh - Run app commands in container
• docker_check_mount.bat / docker_check_mount.sh - Validate .aws mount

Build image with helper scripts

Windows:

.\docker_build_image.bat

Linux/macOS:

chmod +x docker_build_image.sh
./docker_build_image.sh

Create/start container with helper scripts

Windows:

.\docker_create_container.bat

Linux/macOS:

chmod +x docker_create_container.sh
./docker_create_container.sh

Run app inside container using helper scripts

Windows:

.\docker_run_app.bat --profile your-profile --region us-west-2 --model claude

Linux/macOS:

chmod +x docker_run_app.sh
./docker_run_app.sh --profile your-profile --region us-west-2 --model claude

Or directly via docker exec:

docker exec -it aws-console-app python main.py --profile your-profile --region us-west-2 --model claude

Quick mount validation (host <-> container)

Windows:

.\docker_check_mount.bat

Linux/macOS:

chmod +x docker_check_mount.sh
./docker_check_mount.sh

This validates bidirectional file visibility on the mounted .aws path.

Troubleshooting

Missing profile/region error

Error: Missing profile/region. Provide --profile and --region, or define PROFILE/REGION in the environment or .env.

Solution:

• Provide --profile and --region via CLI, OR
• Set AWS_PROFILE and AWS_REGION environment variables, OR
• Create .env file with profile/region configuration

Authentication failed

Error: Authentication failed: ...

Solution:

• Verify AWS CLI is installed: aws --version
• Check profile exists: aws configure list --profile your-profile
• For SSO profiles, ensure they're configured: aws configure sso --profile your-profile
• Run manual SSO login: aws sso login --profile your-profile

SSO token expired

Error: InvalidSignatureException or unauthorized errors mid-conversation

Solution:

• Run aws sso login --profile your-profile on the host
• The app will automatically detect the new token on next invocation
• Background monitor (60s interval) also checks and refreshes automatically

Docker mount issues

Error: .aws directory not accessible in container

Solution:

• Verify mount path: docker run ... -v "$HOME/.aws:/root/.aws" ...
• Check permissions: Run docker_check_mount.bat or ./docker_check_mount.sh
• On Windows, ensure Docker Desktop has file sharing enabled

Model not available in region

Error: Model not available in region

Solution:

• List available models for your region: python main.py --profile your-profile --region your-region --list-models
• Switch to a region where the model is available (e.g., us-west-2 for Claude)

License

This project is licensed under the MIT License. See LICENSE file for details.

Release Information

For release notes and version history, see CHANGELOG.md.

Latest releases are available on:

• PyPI: https://pypi.org/project/aws-console-app/
• TestPyPI: https://test.pypi.org/project/aws-console-app/

Switching GitHub Account Per Repo

Package Publishing

The repository now uses two separate GitHub Actions workflows for publishing:

• TestPyPI publishes on every branch push using a unique .dev<run_number> version so repeated uploads do not collide.
• PyPI publishes only when the pushed git tag matches both pyproject.toml and VERSION.

Required publishing setup:

• Configure GitHub Actions trusted publishing for the TestPyPI project.
• Configure GitHub Actions trusted publishing for the PyPI project.

Recommended release flow:

# 1. Update both version sources to the same release number
#    pyproject.toml -> project.version
#    VERSION -> same value

# 2. Commit and push your changes
git push

# 3. Create a release tag that matches the version
git tag v0.5.5
git push origin v0.5.5

Accepted release tag formats:

• vX.Y.Z
• X.Y.Z

If you use multiple GitHub accounts, use the helper scripts to switch the current repository identity without changing your global git config.

Windows:

.\set_git_account.bat shankonduru
.\set_git_account.bat shankondurucoforge shan.konduru@company.com https

Linux/macOS:

./set_git_account.sh shankonduru
./set_git_account.sh shankondurucoforge shan.konduru@company.com https

What these scripts update in the current repository:

• user.name
• user.email
• credential.username
• remote.origin.url (rewritten for the selected account)

Optional SSH mode:

.\set_git_account.bat shankonduru "" ssh

./set_git_account.sh shankonduru "" ssh

In SSH mode, ensure your ~/.ssh/config contains host aliases (github-shankonduru, github-shankondurucoforge) mapped to the correct keys.

Configuration

Environment Variables and Precedence

The app resolves AWS profile and region using this priority order:

1. CLI arguments (highest priority)

   • --profile <name>
   • --region <name>

2. Process environment variables

   • AWS_PROFILE, AWS_PROFILE_NAME (for profile)
   • AWS_REGION, AWS_DEFAULT_REGION (for region)

3. .env file (in project root, lowest priority)

   • PROFILE / AWS_PROFILE / AWS_PROFILE_NAME
   • REGION / AWS_REGION

Example: Use environment variables

export AWS_PROFILE=my-bedrock-profile
export AWS_REGION=us-west-2
python main.py  # Automatically picks up profile and region from env

Example: Use .env file

Create .env in the project root:

AWS_PROFILE=my-bedrock-profile
AWS_REGION=us-west-2

Then run:

python main.py

AWS Configuration Files

The app reads profile metadata from:

• ~/.aws/config - Profile definitions and regions
• ~/.aws/credentials - AWS access keys (for non-SSO profiles)
• ~/.aws/sso/cache - SSO token cache (checked for validity)

Available Configuration Keys

Profile resolution (.env)

Supported keys (checked in order):

• PROFILE
• AWS_PROFILE
• AWS_PROFILE_NAME

Region resolution (.env)

Supported keys (checked in order):

• REGION
• AWS_REGION

CLI Usage

python main.py [options]

Core options

• --profile <name> AWS named profile
• --region <region> AWS region (for example us-west-2)
• --model <claude|titan|nova> model family (default claude)
• --model-id <full-bedrock-model-id> explicit model id override
• --max-tokens <int> max generated tokens
• --temperature <float> generation temperature
• --system-prompt <text> custom system prompt
• --max-history <int> max chat turns kept in context
• --list-profiles list local AWS profiles and exit
• --list-models list available Bedrock text, embedding, and image models for region and exit

Examples

Chat (values from .env):

python main.py

Chat (explicit):

python main.py --profile my-profile --region us-west-2 --model claude

List available models/embeddings:

python main.py --profile my-profile --region us-west-2 --list-models

AWS SSO Behavior

For SSO-enabled profiles, the app checks token cache validity and only triggers login when needed.

Behavior summary:

1. If cached token is valid, continue without login
2. If not valid, run aws sso login --profile <profile> --no-browser --use-device-code
3. Build boto3 session and continue
4. If Bedrock call later fails due to expired auth, app re-authenticates and retries once

Linux-safe SSO flow (device code)

The app uses AWS CLI device authorization flags to avoid local browser dependency issues on Linux hosts, headless environments, and remote terminals:

• --no-browser
• --use-device-code

This means login is completed by opening the provided verification URL on any device and entering the shown code.

Flowchart

flowchart TD
  A[Start app] --> B[Resolve profile and region]
  B --> C[Read ~/.aws config and credentials]
  C --> D{SSO profile?}
  D -- No --> E[Build boto3 session]
  D -- Yes --> F{Valid cached SSO token?}
  F -- Yes --> E
  F -- No --> G[Run aws sso login --profile ... --no-browser --use-device-code]
  G --> H{Login command success?}
  H -- No --> I[Exit with auth error]
  H -- Yes --> J[Build boto3 session]
  E --> K[Invoke Bedrock]
  J --> K
  K --> L{Expired/Unauthorized/InvalidSignature?}
  L -- No --> M[Return model response]
  L -- Yes --> N[Re-authenticate once]
  N --> O[Retry Bedrock call once]
  O --> M

Sequence diagram: active token found

sequenceDiagram
  participant User
  participant App
  participant TokenCache as ~/.aws/sso/cache
  participant AWS as Bedrock Runtime

  User->>App: Start app
  App->>TokenCache: Check token validity (>5 min remaining)
  TokenCache-->>App: Valid token found
  App->>App: Build boto3 session
  App->>AWS: invoke_model(...)
  AWS-->>App: Response payload
  App-->>User: Answer

Sequence diagram: token missing or expired

sequenceDiagram
  participant User
  participant App
  participant TokenCache as ~/.aws/sso/cache
  participant CLI as aws sso login
  participant Device as Browser on any device
  participant AWS as Bedrock Runtime

  User->>App: Start app
  App->>TokenCache: Check token validity
  TokenCache-->>App: Missing/expired token
  App->>CLI: aws sso login --profile X --no-browser --use-device-code
  CLI-->>User: Show verification URL + device code
  User->>Device: Open URL and enter code
  Device-->>CLI: Authorization complete
  CLI-->>App: Exit code 0
  App->>App: Build boto3 session
  App->>AWS: invoke_model(...)
  AWS-->>App: Response payload
  App-->>User: Answer

Scenario mapping

1. User did not complete SSO login: The CLI command exits non-zero and the app exits with authentication error.

2. Active token is found: Login is skipped and the session is built immediately.

3. Active token is not found: Device-code login is triggered, then session is built on success.

4. Other situations: If Bedrock returns expired/unauthorized/signature errors during runtime, the app re-authenticates once and retries the call.

Extending with New Models

Implement a new adapter by subclassing BaseBedrockModel:

• model_id
• build_request_body(messages)
• parse_response(response_body)

Then register it in main.py model map.

Development

Install dev dependencies:

python -m pip install -r requirements.txt -r requirements-dev.txt

Run tests:

pytest

Run tests with coverage report:

pytest --cov=src --cov=main --cov-report=term-missing

Security and CI

Workflows include:

• Unit tests + 100% coverage gate
• pip-audit dependency vulnerability scan
• Trivy filesystem scan
• TestPyPI/PyPI publish workflow placeholders (currently disabled)

Notes

• Ensure your selected region has Bedrock access and models enabled.
• --list-models output depends on account permissions and regional availability.
• If using SSO, complete browser login when prompted on first auth refresh.