README.md

metadata

title: WesternFront API
emoji: 🌐
colorFrom: indigo
colorTo: blue
sdk: docker
sdk_version: 0.95.2
app_file: app.py
pinned: false

WesternFront: India-Pakistan Conflict Tracker API

A FastAPI application that leverages unofficial Twitter access via Twikit and Google's Gemini AI to monitor and analyze India-Pakistan tensions in real-time.

Overview

WesternFront is an AI-powered conflict tracker that:

1. Collects tweets from reliable news sources covering India-Pakistan relations without using official Twitter API
2. Analyzes these tweets using Google's Gemini AI to assess the current conflict situation
3. Provides RESTful endpoints to access the analysis
4. Updates analysis periodically and on-demand

Core Components

Twitter Data Collection

• Uses Twikit for unofficial Twitter access
• Fetches tweets from a predefined list of reliable sources
• Implements caching to avoid unnecessary requests

AI Analysis with Gemini

• Analyzes collected tweets to assess India-Pakistan tensions
• Generates comprehensive reports including:
  • Current situation summary
  • Key developments in the last 24-48 hours
  • Information reliability assessment
  • Regional stability implications
  • Tension level classification (Low/Medium/High/Critical)

FastAPI Server

• Endpoint for on-demand analysis updates
• Endpoint to get latest analysis
• Background task system for periodic updates
• Health check endpoint
• Source list and keyword management

Getting Started

Prerequisites

• Python 3.9+
• Docker (optional)

Environment Setup

1. Clone the repository
2. Copy .env.example to .env and fill in the required values:

   # Twitter Credentials
   TWITTER_USERNAME=your_twitter_username
   TWITTER_PASSWORD=your_twitter_password
   TWITTER_EMAIL=your_twitter_email
   
   # Google Gemini API Key
   GEMINI_API_KEY=your_gemini_api_key
   
   # Application Settings
   UPDATE_INTERVAL_MINUTES=60
   CACHE_EXPIRY_MINUTES=120
   LOG_LEVEL=INFO
   

Installation

Local Development

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn app:app --reload

Docker Deployment

# Build the Docker image
docker build -t westernfront .

# Run the container
docker run -p 8000:8000 --env-file .env westernfront

API Endpoints

Root Endpoint

• GET /: Basic API information

Health Check

• GET /health: Check the health of the API and its components

Analysis

• GET /analysis: Get the latest conflict analysis
• POST /analysis/update: Trigger an analysis update
  • Request Body: { "force": boolean } (optional, defaults to false)

News Sources

• GET /sources: Get the current list of news sources
• POST /sources: Update the list of news sources
  • Request Body: Array of NewsSource objects

Keywords

• GET /keywords: Get the current search keywords
• POST /keywords: Update the search keywords
  • Request Body: Array of strings

Tension Levels

• GET /tension-levels: Get the available tension levels

Data Models

News Source

{
  "name": "BBC News",
  "twitter_handle": "BBCWorld",
  "country": "UK",
  "reliability_score": 0.9,
  "is_active": true
}

Conflict Analysis

{
  "analysis_id": "uuid",
  "generated_at": "2023-05-01T12:00:00Z",
  "situation_summary": "...",
  "key_developments": [
    {
      "title": "Development 1",
      "description": "...",
      "sources": ["@BBCWorld", "@Reuters"],
      "timestamp": "2023-05-01T10:30:00Z"
    }
  ],
  "reliability_assessment": "...",
  "regional_implications": "...",
  "tension_level": "Medium",
  "source_tweets": [],
  "update_triggered_by": "scheduled"
}

Implementation Notes

• The application uses asyncio for handling concurrent requests
• Implements in-memory caching (can be extended to Redis)
• Rate limiting and throttling for Twitter scraping to avoid blocking
• Proper error handling and logging via loguru
• Secure credential management via environment variables

Future Enhancements

• Redis integration for more robust caching
• User authentication for API access
• Email/notification alerts for critical tension levels
• Historical data storage and trend analysis
• Additional data sources beyond Twitter

License

MIT License

Disclaimer

This application is designed for educational and research purposes. The analysis provided should not be used as the sole source for critical decision-making related to regional conflicts.