data/github/personal_ai_agent/architecture.md

Architecture — Personal AI Digital Twin

System Overview

A FastAPI backend serving a glassmorphic chat UI, backed by a tool-calling AI agent that runs on Groq's inference API. The agent is stateful per session (in-memory), speaks in Arun's voice from injected context files, and pushes live notifications to a Telegram bot for every new session and message.

Components

Entry Point (app.py)

FastAPI application setup. Mounts the static UI at /static, serves index.html at the root, includes the API router, and binds to the PORT environment variable for Render compatibility.

API Router (api.py)

• Single POST /chat endpoint
• Manages per-session conversation history in SESSIONS dict (keyed by session_id)
• Triggers a Telegram push notification on new session start
• Forwards every user message and AI response to Telegram in real time
• Delegates all AI logic to the Me agent class

Agent Core (services/me_agent.py — the Me class)

The most important module. Responsibilities:

• Context loading: Reads me/summary.txt at startup to build Arun's persona context
• System prompt assembly: Injects persona context + behavioral rules into every LLM request
• Tool-calling agentic loop: Runs up to 3 iterations per user message — if the model calls a tool, it executes it and feeds results back into the conversation before generating the final response
• Multi-model fallback: Tries 4 Groq models in sequence — any model failure (rate limit, timeout) automatically falls through to the next
• Artifact cleanup: Strips <function=...> tags that Llama 3 occasionally leaks into output

Tools (services/tools.py)

• save_lead: Saves lead contact info locally when the agent detects hiring/collaboration interest
• save_unknown_questions: Logs questions the agent couldn't answer for Arun to review later
• push: Sends Telegram notifications via HTTP to Arun's bot

Identity Data (me/summary.txt)

Plain-text file containing Arun's professional background — injected directly into the system prompt on every request. This is the source of truth for the agent's persona.

Data Flow

User message (browser)
        ↓
POST /chat (FastAPI)
        ↓
Session history lookup → append user message
        ↓
Me.chat() → build messages [system prompt + history]
        ↓
Groq LLM call (model fallback chain if rate limited)
        ↓
If tool_calls → execute tools → re-invoke LLM (up to 3x)
        ↓
Final response → push to Telegram → return to browser

Deployment

• Host: Render (free tier)
• Port: Dynamic via PORT env var
• Config: .env for GROQ_API_KEY and Telegram bot token