FitnessCore

A serverless AI fitness coaching assistant delivered via Telegram — built on AWS AgentCore, MiniMax-M2.7, and a fully event-driven Lambda architecture.

FitnessCore lets users track daily nutrition and workouts through natural conversation. The agent understands free-form text, remembers what you told it in previous sessions, chains multiple tool calls to answer complex questions, and sends scheduled morning and evening reminders — all without any persistent servers.

Features

Feature	How it works
Natural language logging	"I just had 200g chicken and did a weightlifting session" → protein and workout logged in one message
Daily summary	`/today` or "how did I do today?" → formatted breakdown of all logged metrics
Weekly summary	`/week` → 7-day totals, averages, workout count, best deficit day
Calorie burndown	`/remaining` → progress bar, % complete, and days-to-goal estimate at current pace
Profile management	View and update current weight and target weight at any time
Conversational memory	Facts stated in one session ("I'm vegetarian") are recalled in future sessions automatically
Complex reasoning	"How close am I to my goal and what should I focus on this week?" → multi-tool chain, personalised answer
Scheduled reminders	Morning (8am UTC) motivation and evening (8pm UTC) log-completion check
Multi-user	All data scoped by Telegram `chat_id`; any number of users supported without rearchitecting

Architecture

Telegram Users
      │
      │ HTTPS Webhook
      ▼
┌─────────────────────────────────┐
│  API Gateway (HTTP API)         │
│  POST /webhook                  │
└────────────────┬────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│  Lambda: webhook-handler        │  Validates Telegram secret.
│  Python 3.12 · timeout 10s      │  Enqueues message to SQS.
└────────────────┬────────────────┘  Returns 200 in < 3s.
                 │
                 ▼
┌─────────────────────────────────┐
│  SQS: agent-queue               │  Standard queue.
│  DLQ after 3 failures           │  Visibility timeout 300s.
└────────────────┬────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│  Lambda: agent-invoker          │  SQS consumer.
│  Python 3.12 · timeout 120s     │  Runs onboarding wizard for new users.
└────────────────┬────────────────┘  Calls AgentCore for returning users.
                 │
                 ▼
┌──────────────────────────────────────────────────────────────────┐
│  AWS AgentCore Runtime                                            │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Per-session microVM · isolated per user_id                │  │
│  │                                                            │  │
│  │  1. Retrieve long-term memories (AgentCore Memory)         │  │
│  │  2. Build system prompt with user context                  │  │
│  │  3. Call MiniMax-M2.7 with tool definitions                │  │
│  │  4. AgentCore Gateway executes tool calls server-side      │  │
│  │  5. Feed results back → repeat until end_turn              │  │
│  │  6. Save conversation turn to AgentCore Memory             │  │
│  │  7. Return final text response                             │  │
│  └─────────────────┬──────────────────┬───────────────────────┘  │
│                    │                  │                            │
│   ┌────────────────▼───┐  ┌──────────▼─────────────────────────┐ │
│   │  AgentCore Memory  │  │  AgentCore Gateway (MCP)            │ │
│   │                    │  │                                     │ │
│   │  Short-term:       │  │  Tools (server-side execution):     │ │
│   │   session turns    │  │  • log_metric                       │ │
│   │                    │  │  • get_summary                      │ │
│   │  Long-term:        │  │  • get_or_update_profile            │ │
│   │   user facts       │  │  • get_progress                     │ │
│   │   preferences      │  │  • update_user_memory               │ │
│   │   patterns         │  │  • onboard_user                     │ │
│   └────────────────────┘  └─────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────────────┘
                           │ Response text
                           ▼
              Lambda: agent-invoker → Telegram sendMessage

EventBridge Scheduler
  ├── cron(0 8 * * ? *)   → Lambda: notification-dispatcher  [morning nudge]
  └── cron(0 20 * * ? *)  → Lambda: notification-dispatcher  [evening check-in]

Tech Stack

Layer	Technology	Notes
Frontend	Telegram Bot API	Webhook-based; no polling
API	AWS API Gateway (HTTP API)	Routes webhook POST to Lambda
Compute	AWS Lambda (Python 3.12)	ARM64, on-demand, per-function IAM roles
Agent runtime	AWS AgentCore Runtime	Per-session microVM; no persistent compute
Agent memory	AWS AgentCore Memory	Short-term (session turns) + long-term (semantic facts)
Tool server	AWS AgentCore Gateway (MCP)	Server-side tool execution via MCP protocol
LLM	MiniMax-M2.7	Anthropic-compatible endpoint; no extra translation layer
Database	Amazon DynamoDB (on-demand)	Two tables; always scoped by `user_id` partition key
Queue	Amazon SQS	Decouples webhook ack from agent processing
Scheduler	Amazon EventBridge Scheduler	Morning and evening cron triggers
Secrets	AWS SSM Parameter Store	All API keys stored as SecureString; fetched at runtime
IaC	AWS SAM	Single `template.yaml` defines all infrastructure
Observability	CloudWatch Logs + Alarms + X-Ray	Dashboard, 3 alarms, 30-day log retention

Project Structure

fitnesscore/
├── template.yaml                    ← AWS SAM — all infrastructure in one file
├── samconfig.toml.example           ← deployment config template (copy → samconfig.toml)
├── pytest.ini
│
├── src/
│   ├── webhook/                     ← Lambda: Telegram webhook receiver
│   │   ├── handler.py               ← validates secret, enqueues to SQS
│   │   └── requirements.txt
│   ├── agent-invoker/               ← Lambda: SQS consumer → AgentCore
│   │   ├── handler.py               ← onboarding wizard + AgentCore invocation
│   │   └── requirements.txt
│   ├── agent/                       ← AgentCore agent definition
│   │   ├── agent.py                 ← MiniMax client, memory, tool loop
│   │   ├── system_prompt.md         ← agent persona and instructions (single source of truth)
│   │   ├── Dockerfile               ← container image for ECR
│   │   └── requirements.txt
│   ├── tools/                       ← AgentCore Gateway tool implementations
│   │   ├── fitness_log.py           ← log_metric tool
│   │   ├── fitness_summary.py       ← get_summary tool
│   │   ├── fitness_profile.py       ← get_or_update_profile tool
│   │   ├── fitness_burndown.py      ← get_progress tool
│   │   ├── user_memory.py           ← update_user_memory tool
│   │   └── onboard_user.py          ← onboard_user tool
│   ├── tools-gateway/               ← Lambda: AgentCore Gateway dispatcher
│   │   └── handler.py
│   └── notifications/               ← Lambda: EventBridge-triggered reminders
│       └── dispatcher.py
│
├── tests/
│   ├── conftest.py                  ← shared fixtures (mocked DynamoDB, SSM)
│   ├── unit/                        ← 162 unit tests; moto mocks all AWS calls
│   └── integration/                 ← end-to-end tests against deployed stack
│       ├── integration_config.py.example   ← copy and fill in your values
│       ├── test_e2e.py              ← webhook → SQS → Lambda → DynamoDB pipeline
│       ├── test_agent.py            ← AgentCore memory and tool-chain tests
│       └── test_reasoning.py        ← multi-step reasoning scenarios
│
├── docs/
│   ├── ARCHITECTURE.md              ← detailed architecture and design decisions
│   ├── DATA_MODEL.md                ← DynamoDB schemas, validation rules, examples
│   └── RUNBOOK.md                   ← deploy, rollback, logs, secret rotation, troubleshooting
│
├── infra/
│   ├── iam.yaml                     ← IAM roles reference (least-privilege, per-Lambda)
│   ├── dynamodb.yaml                ← DynamoDB table definitions
│   └── ssm-params.sh                ← SSM parameter names reference (no values)
│
└── scripts/
    ├── setup-dev.sh                 ← install local dev dependencies
    ├── deploy.sh                    ← pytest → sam build → sam deploy pipeline
    └── seed-test-data.sh            ← seed DynamoDB with realistic test fixtures

Getting Started

Prerequisites

Python 3.12 — python3 --version
AWS CLI v2 — install guide
AWS SAM CLI ≥ 1.100 — install guide
Docker — required for SAM builds with Lambda container images
An AWS account with permissions to create Lambda, DynamoDB, SQS, API Gateway, IAM, SSM, EventBridge, and AgentCore resources
A Telegram bot token — create one via @BotFather
A MiniMax API key — from platform.minimaxi.com

1. Clone and set up local environment

git clone https://github.com/YOUR_USERNAME/fitnesscore.git
cd fitnesscore
bash scripts/setup-dev.sh
source .venv/bin/activate

2. Configure AWS credentials

aws configure --profile fitnesscore-dev
# Enter: Access Key ID, Secret Access Key, region (eu-west-1), output (json)

3. Store secrets in SSM Parameter Store

# Telegram bot token (from @BotFather)
aws ssm put-parameter \
  --name /fitnesscore/telegram/bot_token \
  --value "YOUR_BOT_TOKEN" \
  --type SecureString \
  --profile fitnesscore-dev --region eu-west-1

# Webhook secret (generate a random string)
aws ssm put-parameter \
  --name /fitnesscore/telegram/webhook_secret \
  --value "$(openssl rand -hex 32)" \
  --type SecureString \
  --profile fitnesscore-dev --region eu-west-1

# MiniMax API key
aws ssm put-parameter \
  --name /fitnesscore/minimax/api_key \
  --value "YOUR_MINIMAX_API_KEY" \
  --type SecureString \
  --profile fitnesscore-dev --region eu-west-1

4. Configure SAM deployment

cp samconfig.toml.example samconfig.toml
# Edit samconfig.toml: set your AWS profile name

5. Set up AgentCore

AgentCore Runtime, Memory, and Gateway must be provisioned before deployment. See docs/ARCHITECTURE.md for the full AgentCore setup steps, including:

Creating an AgentCore Runtime (container image from ECR)
Creating AgentCore Memory with a user preferences strategy
Creating an AgentCore Gateway and registering the 6 fitness tools
Storing the agent runtime ARN and memory IDs in SSM:

aws ssm put-parameter \
  --name /fitnesscore/agentcore/agent_id \
  --value "YOUR_AGENT_RUNTIME_ARN" \
  --type String \
  --profile fitnesscore-dev --region eu-west-1

6. Deploy

# Runs: pytest tests/unit → sam build → sam deploy
bash scripts/deploy.sh

On success, the webhook URL is printed in the CloudFormation outputs. Register it with Telegram:

WEBHOOK_SECRET=$(aws ssm get-parameter \
  --name /fitnesscore/telegram/webhook_secret \
  --with-decryption --query Parameter.Value --output text \
  --profile fitnesscore-dev --region eu-west-1)

BOT_TOKEN=$(aws ssm get-parameter \
  --name /fitnesscore/telegram/bot_token \
  --with-decryption --query Parameter.Value --output text \
  --profile fitnesscore-dev --region eu-west-1)

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"YOUR_WEBHOOK_URL_FROM_OUTPUTS\",
    \"secret_token\": \"${WEBHOOK_SECRET}\",
    \"allowed_updates\": [\"message\"]
  }"

7. Verify

Send /start to your bot in Telegram. You should be greeted by the onboarding wizard within a few seconds.

Running Tests

Unit tests (no AWS required)

pytest tests/unit -v
# 162 tests · moto mocks all DynamoDB and SSM calls

Integration tests (requires deployed stack)

# 1. Seed test data
bash scripts/seed-test-data.sh

# 2. Configure your test values
cp tests/integration/integration_config.py.example tests/integration/integration_config.py
# Edit integration_config.py with your ARNs and test user ID

# 3. Run
AWS_PROFILE=your-profile pytest tests/integration/test_e2e.py tests/integration/test_agent.py -v -s

Data Model

Two DynamoDB tables, both with on-demand billing and at-rest encryption:

fitnesscore-users — one record per registered user

Attribute	Type	Description
`user_id` (PK)	String	Telegram `chat_id`
`first_name`	String	Telegram first name
`current_weight`	Number	Current weight in kg
`target_weight`	Number	Goal weight in kg
`voice_enabled`	Boolean	Daily voice note opt-in
`video_enabled`	Boolean	Weekly video opt-in
`active`	Boolean	Include in notification fan-out
`registered_at`	String	ISO8601 UTC timestamp

fitnesscore-daily-logs — one record per user per calendar day

Attribute	Type	Description
`user_id` (PK)	String	Telegram `chat_id`
`date` (SK)	String	`YYYY-MM-DD`
`protein`	Number	Grams of protein (0–500)
`calories`	Number	Kcal intake (0–10,000)
`calories_burned`	Number	Kcal burned through exercise (0–5,000)
`deficit`	Number	Calorie deficit, can be negative (−5,000–5,000)
`weightlifting`	Boolean	Weightlifting session completed
`cycling`	Boolean	Cycling session completed

Full schemas, access patterns, and validation rules in docs/DATA_MODEL.md.

AgentCore Tools

Six tools registered with AgentCore Gateway. Each is a pure function — one DynamoDB operation or one calculation. The agent never sees user_id in tool schemas; it is always injected server-side.

Tool	What it does
`log_metric`	Write protein/calories/burn/deficit/workout to `fitnesscore-daily-logs`
`get_summary`	Read today's or this week's metrics from `fitnesscore-daily-logs`
`get_or_update_profile`	Read or write user profile in `fitnesscore-users`
`get_progress`	Calculate calorie burndown progress %, kcal remaining, days to goal
`update_user_memory`	Write a long-term user fact to AgentCore Memory
`onboard_user`	Create a new user record in `fitnesscore-users`

Security

No secrets in code — all API keys and tokens are fetched from SSM Parameter Store at runtime
Webhook validation — every request validated against X-Telegram-Bot-Api-Secret-Token using constant-time comparison
User isolation — every DynamoDB query includes user_id as the partition key; no cross-user data access is possible
AgentCore session isolation — one microVM per user session; memory is scoped per actor_id
Least-privilege IAM — each Lambda has a dedicated role with only the specific actions it needs on specific resources
Encryption at rest — DynamoDB and SQS both have server-side encryption enabled

Cost Estimate

Phase 1 runs comfortably within AWS free tier limits for Lambda and SQS. The main costs are AgentCore and MiniMax.

Scale	Monthly estimate
1 active user	~$4–7
10 active users	~$29–34
50 active users	~$90–110

Detailed breakdown in docs/ARCHITECTURE.md.

Documentation

Document	Contents
docs/ARCHITECTURE.md	Full system design, component responsibilities, memory strategy, IAM design, cost model, key decisions
docs/DATA_MODEL.md	DynamoDB schemas, attribute types, validation constraints, access patterns
docs/RUNBOOK.md	Deploy, rollback, log tailing, secret rotation, troubleshooting guide, known limitations

Observability

CloudWatch Dashboard: FitnessCore-Operations — Lambda invocations/errors/duration, SQS depth, DLQ count, DynamoDB capacity
CloudWatch Alarms: DLQ > 0 messages, webhook error rate > 5%, agent-invoker p99 latency > 90s → SNS topic
X-Ray tracing: Active tracing enabled on all Lambda functions
Log retention: 30 days on all Lambda log groups

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

FitnessCore

Features

Architecture

Tech Stack

Project Structure

Getting Started

Prerequisites

1. Clone and set up local environment

2. Configure AWS credentials

3. Store secrets in SSM Parameter Store

4. Configure SAM deployment

5. Set up AgentCore

6. Deploy

7. Verify

Running Tests

Unit tests (no AWS required)

Integration tests (requires deployed stack)

Data Model

AgentCore Tools

Security

Cost Estimate

Documentation

Observability

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
infra		infra
scripts		scripts
specs		specs
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
pytest.ini		pytest.ini
samconfig.toml.example		samconfig.toml.example
template.yaml		template.yaml

Folders and files

Latest commit

History

Repository files navigation

FitnessCore

Features

Architecture

Tech Stack

Project Structure

Getting Started

Prerequisites

1. Clone and set up local environment

2. Configure AWS credentials

3. Store secrets in SSM Parameter Store

4. Configure SAM deployment

5. Set up AgentCore

6. Deploy

7. Verify

Running Tests

Unit tests (no AWS required)

Integration tests (requires deployed stack)

Data Model

AgentCore Tools

Security

Cost Estimate

Documentation

Observability

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages