fix: add readme based on the structure

Author: swarna1101

README.md

@@ -1,118 +1,61 @@
-# Flare AI Social
+# 🤖 Flare AI Social
 
 A robust, extensible social media bot framework that monitors and automatically responds to mentions across multiple platforms using AI-powered responses.
 
-## Overview
+## 🚀 Key Features
 
-Flare AI Social is a Python-based system that connects AI capabilities with social media platforms. The bot monitors designated accounts for mentions, processes them using AI, and automatically responds with contextually appropriate replies.
+- **Multi-platform Support**: Monitor mentions and messages across Twitter/X and Telegram
+- **AI-powered Responses**: Generate contextually relevant replies using Google's Gemini AI
+- **Model Fine-tuning**: Support for custom-tuned models with example dataset
+- **Rate Limit Handling**: Built-in exponential backoff and retry mechanisms
+- **TEE Integration**: Secure execution in Trusted Execution Environment
 
-Currently supported platforms:
+## 🏗️ Project Structure
 
-- Twitter/X
-- Telegram
-
-## Features
-
-- **Multi-platform monitoring**: Monitor mentions/keywords across Twitter and messages in Telegram
-- **AI-powered responses**: Generate contextually relevant replies using Google's Gemini AI
-- **Rate limit handling**: Built-in exponential backoff and retry mechanisms
-- **Model customization**: Support for custom-tuned AI models
-
-## Architecture
-
-The system consists of three main components:
-
-1. **Bot Manager**: Coordinates all bots and handles initialization, monitoring, and shutdown
-2. **Platform-specific Bots**: Implementations for Twitter and Telegram
-3. **AI Provider**: Interface to the AI model (currently supports Google Gemini)
-
-## Prerequisites
-
-- Python 3.12+
-- Google Gemini API key
-- Twitter/X API credentials (API key, secret, access token, etc.)
-- RapidAPI key for Twitter search functionality
-- Telegram Bot API token (if using Telegram)
-
-## Installation
-
-```bash
-# Clone the repository
-git clone repo_url
-
-# Install dependencies uv sync --all-extras
-uv sync --all-extras
-
-# Create .env file
-cp .env.example .env
-# Edit .env with your API keys and configuration
 ```
-
-## Configuration
-
-Configure the bot by editing the `.env` file or setting environment variables:
-
-```
-# Google Gemini AI
-GEMINI_API_KEY=your_gemini_api_key
-TUNED_MODEL_NAME=pugo-hilion
-
-# Twitter/X Bot Settings
-ENABLE_TWITTER=true
-X_API_KEY=your_twitter_api_key
-X_API_KEY_SECRET=your_twitter_api_secret
-X_ACCESS_TOKEN=your_twitter_access_token
-X_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret
-RAPIDAPI_KEY=your_rapidapi_key
-RAPIDAPI_HOST=twitter241.p.rapidapi.com
-TWITTER_ACCOUNTS_TO_MONITOR=@YourAccount,@AnotherAccount,keyword
-TWITTER_POLLING_INTERVAL=60
-
-# Telegram Bot Settings
-ENABLE_TELEGRAM=true
-TELEGRAM_API_TOKEN=your_telegram_bot_token
-TELEGRAM_ALLOWED_USERS= # empty to allow all accounts to interact with the bot
-TELEGRAM_POLLING_INTERVAL=5
-
-# Fine-tuning Parameters
-TUNING_SOURCE_MODEL=models/gemini-1.5-flash-001-tuning
-TUNING_EPOCH_COUNT=100
-TUNING_BATCH_SIZE=4
-TUNING_LEARNING_RATE=0.001
+src/flare_ai_social/
+├── ai/                     # AI Provider implementations
+│   ├── base.py            # Base AI provider abstraction
+│   ├── gemini.py          # Google Gemini integration
+│   └── openrouter.py      # OpenRouter integration
+├── api/                    # API layer
+│   └── routes/            # API endpoint definitions
+├── attestation/           # TEE attestation implementation
+│   ├── vtpm_attestation.py # vTPM client
+│   └── vtpm_validation.py  # Token validation
+├── prompts/               # Prompt engineering templates
+│   └── templates.py       # Different prompt strategies
+├── telegram/              # Telegram bot implementation
+│   └── service.py         # Telegram service logic
+├── twitter/               # Twitter bot implementation
+│   └── service.py         # Twitter service logic
+├── bot_manager.py         # Bot orchestration
+├── main.py                # FastAPI application
+├── settings.py            # Configuration settings
+└── tune_model.py          # Model fine-tuning utilities
 ```
 
 ## 🏗️ Build & Run Instructions
 
-### Running the Social Media Bots
-
-Start the bots with UV:
+### Fine-tuning a Model
 
-```bash
-uv run start-bots
-```
-
-### Fine-tuning a Model Over a Dataset
-
-1. **Prepare the Environment File:**  
-   Rename `.env.example` to `.env` and update the variables accordingly.
-   Some parameters are specific to model fine-tuning:
+1. **Prepare Environment File**:  
+   Rename `.env.example` to `.env` and update these model fine-tuning parameters:
 
    | Parameter             | Description                                                                | Default                              |
       | --------------------- | -------------------------------------------------------------------------- | ------------------------------------ |
    | `tuned_model_name`    | Name of the newly tuned model.                                             | `pugo-hilion`                        |
    | `tuning_source_model` | Name of the foundational model to tune on.                                 | `models/gemini-1.5-flash-001-tuning` |
-   | `epoch_count`         | Number of tuning epochs to run. An epoch is a pass over the whole dataset. | `100`                                |
+   | `epoch_count`         | Number of tuning epochs to run. An epoch is a pass over the whole dataset. | `30`                                 |
    | `batch_size`          | Number of examples to use in each training batch.                          | `4`                                  |
    | `learning_rate`       | Step size multiplier for the gradient updates.                             | `0.001`                              |
 
-2. **Prepare a dataset:**
-   An example dataset is provided in `src/data/training_data.json`, which consists of tweet from
-   [Hugo Philion's X](https://x.com/HugoPhilion) account. You can use any publicly available dataset
-   for model fine-tuning.
-
-3. **Tune a new model**
-   Set the name of the new tuned model in `src/flare_ai_social/tune_model.py`, then:
+2. **Prepare Dataset**:
+   - Example dataset provided in `src/data/training_data.json`
+   - Based on Hugo Philion's X/Twitter feed
+   - Compatible with any public dataset
 
+3. **Tune Model**:
    ```bash
    uv run start-tuning
    ```
@@ -121,78 +64,114 @@ uv run start-bots
    After tuning in complete, a training loss PNG will be saved in the root folder corresponding to the new model.
    Ideally the loss should minimize to near 0 after several training epochs.
 
-5. **Test the new model**
-   Select the new tuned model and test it against a set of prompts:
+![pugo-hilion_mean_loss](https://github.com/user-attachments/assets/f6c4d82b-678a-4ae5-bfb7-39dc59e1103d)
+
+5. **Test Model**:
+   Select the new tuned model and compare it against a set of prompting techniques (zero-shot, few-shot and chain-of-thought):
 
    ```bash
-   uv run start-social
+   uv run start-compare
    ```
+   
+### Running Social Bots
 
-## Twitter/X Bot
-
-The Twitter bot:
+1. **Configure Platforms:**
+  - Set up Twitter/X API credentials 
+  - Configure Telegram bot token 
+  - Enable/disable platforms as needed
 
-1. Monitors mentions of specified accounts using the RapidAPI Twitter search endpoint
-2. Processes mentions to identify ones within the configured time window
-3. Generates AI responses for valid mentions
-4. Replies to mentions with the generated content
+2. **Start Bots:**
 
-### Rate Limits
+   ```bash
+   uv run start-bots
+   ```
+   
+### Build with Docker
 
-The Twitter component implements strategies to handle rate limits:
+After model training:
 
-- Exponential backoff for retries
-- Sequential (rather than concurrent) account monitoring
-- Configurable polling intervals
-- Comprehensive error handling
+1. **Build Image**:
+   ```bash
+   docker build -t flare-ai-social .
+   ```
 
-## Telegram Bot
+2. **Run Container**:
+   ```bash
+   docker run -p 80:80 -it --env-file .env flare-ai-social
+   ```
 
-The Telegram bot:
+3. **Access UI**: Navigate to `http://localhost:80`
 
-1. Listens for incoming messages
-2. Optionally filters messages based on allowed user IDs
-3. Processes messages through the AI provider
-4. Replies with generated responses
+## 🚀 Deploy on TEE
 
-## AI Provider
+Deploy on Confidential Space Instance (AMD SEV/Intel TDX) for hardware-backed security.
 
-The system uses Google's Gemini AI models with:
+### Prerequisites
 
-- Support for default models (gemini-1.5-flash)
-- Optional integration with custom-tuned models
-- Fallback mechanisms if tuned models are unavailable
-- Configurable system prompts for controlling AI behavior
+- GCP account with `verifiable-ai-hackathon` access
+- [Gemini API key](https://aistudio.google.com/app/apikey)
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed
 
-## Extending the System
+### Environment Setup
 
-### Adding New Social Platforms
+1. **Configure Environment**:
+   ```bash
+   # In .env file
+   TEE_IMAGE_REFERENCE=ghcr.io/flare-foundation/flare-ai-social:main
+   INSTANCE_NAME=<PROJECT_NAME-TEAM_NAME>
+   ```
 
-To add a new platform:
+2. **Load Variables**:
+   ```bash
+   source .env
+   ```
 
-1. Create a new class that implements the platform's API
-2. Follow the pattern established by `TwitterBot` and `TelegramBot`
-3. Add the new bot to `BotManager`
+### Deployment
 
-### Using Different AI Models
+Deploy to Confidential Space (AMD SEV):
 
-The system uses a provider pattern for AI integration:
+```bash
+gcloud compute instances create $INSTANCE_NAME \
+  --project=verifiable-ai-hackathon \
+  --zone=us-central1-c \
+  --machine-type=n2d-standard-2 \
+  --network-interface=network-tier=PREMIUM,nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=default \
+  --metadata=tee-image-reference=$TEE_IMAGE_REFERENCE,\
+tee-container-log-redirect=true,\
+tee-env-GEMINI_API_KEY=$GEMINI_API_KEY,\
+tee-env-GEMINI_MODEL=$GEMINI_MODEL,\
+tee-env-WEB3_PROVIDER_URL=$WEB3_PROVIDER_URL,\
+tee-env-SIMULATE_ATTESTATION=false \
+  --maintenance-policy=MIGRATE \
+  --provisioning-model=STANDARD \
+  --service-account=confidential-sa@verifiable-ai-hackathon.iam.gserviceaccount.com \
+  --scopes=https://www.googleapis.com/auth/cloud-platform \
+  --min-cpu-platform="AMD Milan" \
+  --tags=flare-ai,http-server,https-server \
+  --create-disk=auto-delete=yes,\
+boot=yes,\
+device-name=$INSTANCE_NAME,\
+image=projects/confidential-space-images/global/images/confidential-space-debug-250100,\
+mode=rw,\
+size=11,\
+type=pd-standard \
+  --shielded-secure-boot \
+  --shielded-vtpm \
+  --shielded-integrity-monitoring \
+  --reservation-affinity=any \
+  --confidential-compute-type=SEV
+```
 
-1. Create a new class that implements the `BaseAIProvider` interface
-2. Implement the `generate` method to interface with your AI service
-3. Configure the `BotManager` to use your provider
+### Post-deployment
 
-## Troubleshooting
+Monitor startup in [GCP Console](https://console.cloud.google.com/welcome?project=verifiable-ai-hackathon) under **Serial port 1**. When you see:
 
-### Twitter Rate Limits
+```plaintext
+INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
+```
 
-- Increase `TWITTER_POLLING_INTERVAL` to reduce API calls
-- Reduce the number of monitored accounts
-- Upgrade your RapidAPI plan for higher limits
+Access the UI via the instance's external IP.
 
-### Connection Timeouts
+## 💡 Example Use Cases & Next Steps
 
-- Check network connectivity
-- Verify API credentials
-- Ensure clock synchronization for OAuth
-- Monitor Twitter API status
+TODO: Add example use cases and next steps for the project.