Soccer Analytics AI Agent

AI agent for soccer analytics using AWS Bedrock AgentCore Runtime. Provides pre and post-game analytics via web chat interface.

Table of Contents

• Prerequisites
• Quick Start
  • 1. Enable Bedrock Model Access
  • 2. Clone Repository
  • 3. Configure AWS SSO
  • 4. Deploy Infrastructure
  • 5. Upload Sample Schedule
  • 6. Create Test User
  • 7. Deploy AgentCore Runtime
  • 8. Deploy Streamlit Web UI
  • 9. Get Streamlit URL and Test
• Cost Estimate
• Complete Cleanup
• Architecture
• Troubleshooting
• Documentation
• Security
• Development
• License

Prerequisites

AWS Account Recommendation

⚠️ Important: We strongly recommend creating a dedicated AWS account under your organization for this application. This ensures:

• Isolated billing and cost tracking
• No impact on existing AWS resources
• Easy cleanup without affecting other workloads
• Clear cost attribution

Learn how to create an AWS account in an organization

Required Software

• Python 3.12+: python --version
• uv package manager: pip install uv
• AWS CLI: aws --version
• AWS CDK: npm install -g aws-cdk
• Docker: docker --version
• Git: git --version

Required AWS Access

• AWS SSO: Configured for secure authentication
• Bedrock Access: Claude Sonnet 4.5 model enabled in us-east-1
• IAM Permissions: Administrator access or permissions for IAM, S3, DynamoDB, Lambda, Cognito, Bedrock, ECR, CloudWatch, ECS

Quick Start

1. Enable Bedrock Model Access

Before deployment, enable Claude Sonnet 4.5 in AWS Bedrock:

1. Go to AWS Bedrock Console (us-east-1 region)
2. Navigate to Model access in the left sidebar
3. Click Manage model access
4. Find Anthropic → Claude Sonnet 4.5 and enable it
5. Click Save changes and wait for access to be granted (~2-5 minutes)

2. Clone Repository

git clone <repository-url>
cd the-beautiful-game

3. Configure AWS SSO

update the params as you see fit

# Configure AWS SSO (one-time setup)
aws configure sso

# Follow prompts:
# - SSO start URL (from your AWS administrator)
# - SSO region (typically us-east-1)
# - Account ID and role name
# - CLI default region: us-east-1
# - Output format: json
# - Profile name: soccer-analytics

# Login to AWS SSO
aws sso login --profile soccer-analytics

# Verify authentication
aws sts get-caller-identity --profile soccer-analytics

4. Deploy Infrastructure

# Install dependencies
uv pip install -e .

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy infrastructure
cdk deploy --all --outputs-file cdk-outputs.json

Deployment time: ~5-10 minutes

What gets created:

• DynamoDB tables (GameData, RateLimits)
• S3 bucket for PDF schedules
• Lambda function for PDF processing
• Cognito User Pool and Identity Pool
• IAM roles and policies

5. Upload Sample Schedule

# Get bucket name
BUCKET_NAME=$(cat cdk-outputs.json | grep -o '"PdfBucketName": "[^"]*"' | cut -d'"' -f4)

# Upload sample schedule
aws s3 cp data/samples/sample-schedule.pdf s3://$BUCKET_NAME/sample-schedule-$(date +%s).pdf

6. Create Test User

# Get User Pool ID from CDK outputs
USER_POOL_ID=$(cat cdk-outputs.json | grep -o '"UserPoolId": "[^"]*"' | cut -d'"' -f4)

# Create test user
./scripts/create_test_user.sh $USER_POOL_ID testuser TestPass123! test@example.com

7. Deploy AgentCore Runtime

cd agentcore
uv run python deploy_agent.py
cd ..

Deployment time: ~10-15 minutes (first time), ~5 minutes (subsequent)

What happens:

• Builds Docker image with AI agent
• Pushes to ECR
• Deploys to Bedrock AgentCore Runtime
• Configures IAM permissions for DynamoDB and Bedrock

8. Deploy Streamlit Web UI

uv run python streamlit_app/deploy_ecs.py

Deployment time: ~10-15 minutes

What gets created:

• ECS Fargate cluster and service
• Application Load Balancer
• Security groups and IAM roles

9. Get Streamlit URL and Test

# Get the public URL
./streamlit_app/get_ecs_url.sh

# Open the URL in your browser
# Login with: testuser / TestPass123!
# Try: "predict next LBFC game"

Cost Estimate

Monthly Costs (Running 24/7)

Service	Cost
Bedrock AgentCore Runtime	~$50-100
ECS Fargate (1 task, 1 vCPU, 2GB)	~$15-20
DynamoDB (on-demand, light usage)	~$5-10
S3 Storage (< 1GB)	~$0.50
CloudWatch Logs	~$2-5
Application Load Balancer	~$16-20
Total	~$90-155/month

Cost Optimization

Pause when not in use (recommended):

# Pause ECS service (stops UI, saves ~$35/month)
uv run python streamlit_app/deploy_ecs.py --pause

# Resume when needed
uv run python streamlit_app/deploy_ecs.py --resume

Paused costs: ~$55-120/month (AgentCore + DynamoDB + S3 + Logs)

Complete Cleanup

To delete all resources and stop all charges:

cd scripts
./cleanup_all.sh

This will delete (in order):

1. ECS cluster and services
2. AgentCore runtime and CodeBuild
3. CDK stack (Lambda, DynamoDB, S3, Cognito)
4. ECR repositories
5. CloudWatch log groups
6. Local configuration files

Verification:

# Verify all resources are deleted
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE | grep soccer-analytics
# Should return nothing

Architecture

• Backend: AWS Bedrock AgentCore Runtime with Strands framework
• Frontend: Streamlit web UI on ECS Fargate
• Data: S3 for PDFs, DynamoDB for structured game data
• Authentication: AWS Cognito User Pool + Identity Pool
• Infrastructure: AWS CDK (TypeScript)

Troubleshooting

For detailed troubleshooting, see:

• 📚 Deployment Guide
• 🐛 Troubleshooting Guide

Quick Fixes

CDK Deploy Fails:

aws sso login --profile soccer-analytics
cdk bootstrap --force

AgentCore Deploy Fails:

# Verify Bedrock access
aws bedrock list-foundation-models --region us-east-1 | grep claude-sonnet-4

Streamlit Login Fails:

# Verify user exists
aws cognito-idp list-users --user-pool-id $USER_POOL_ID

Check Logs:

# Lambda logs
aws logs tail /aws/lambda/soccer-analytics-pdf-processor --follow

# AgentCore logs
aws logs tail /aws/bedrock-agentcore/soccer_analytics_agent --follow

Documentation

📚 Complete documentation: docs/README.md

Quick Links

• 📦 Deployment Guide - Detailed deployment instructions
• 💰 Cost Control - Budget management and monitoring
• 🔒 Security - Security best practices
• 🐛 Troubleshooting - Common issues and solutions
• 🤖 AgentCore - AI agent development
• 🌐 Streamlit UI - Web interface details

Security

• AWS SSO authentication (no long-lived access keys)
• Temporary credentials via Cognito Identity Pool
• Encrypted data at rest and in transit
• IAM least privilege access

Development

# Run tests
uv run pytest -q

# Lint code
uv run ruff check

# Format code
uv run black .

# Type check
uv run mypy .

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 The Project Contributors