An AI-powered service that analyzes user perspectives from VoxPop's decentralized platform, extracting insights through sentiment analysis and clustering.

Features

🔄 Data Fetching: Retrieves perspectives from IPFS (mocked for now)
🧠 AI Processing:
- Sentiment analysis (positive, negative, neutral)
- Embedding generation and clustering
- Topic extraction from clusters
💡 Insight Generation: Creates structured insights with confidence scores
⏱️ Scheduled Analysis: Automatically runs analysis hourly
📊 Visualization: Generates interactive visualizations of perspective clusters
🐳 Containerized: Docker-ready for easy deployment

API Endpoints

GET /analyze: Analyze perspectives and generate insights
GET /insights: Get consolidated insights from recent analyses
GET /status: Check service status and job information
POST /run-now: Trigger an immediate analysis run

Getting Started

Prerequisites

Python 3.8+
Docker (optional, for containerized deployment)

Local Development

Clone the repository
Install dependencies:
```
pip install -r requirements.txt
```
Run the service:
```
python -m app.main
```
Access the API documentation at http://localhost:8000/docs

Docker Deployment

Build the Docker image:
```
docker build -t voxpop-analysis .
```

Run the container:

docker run -p 8000:8000 voxpop-analysis

How It Works

Data Flow

Fetch: Retrieve perspectives from IPFS (currently mocked)
Analyze:
- Perform sentiment analysis on each perspective
- Generate embeddings and cluster similar perspectives
- Extract key topics from each cluster
Generate: Create structured insights with confidence scores
Store: Save insights to disk for historical analysis
Serve: Provide API endpoints for accessing analysis results

Example Analysis Output

{
  "perspectives": [...],
  "clusters": [0, 1, 0, 2, 1, ...],
  "insights": [
    {
      "summary": "Cluster 1: Perspectives about parks, funding, community, 75% positive",
      "confidence": 0.4
    },
    {
      "summary": "Cluster 2: Perspectives about transportation, infrastructure, traffic, 60% negative",
      "confidence": 0.35
    },
    {
      "summary": "Cluster 3: Perspectives about housing, development, affordable, 50% neutral/mixed",
      "confidence": 0.25
    }
  ],
  "visualization": {...}
}

Configuration

The service uses sensible defaults but can be configured through environment variables:

LOG_LEVEL: Logging level (default: INFO)
ANALYSIS_INTERVAL: Minutes between analysis runs (default: 60)
INSIGHTS_DIR: Directory to store insights (default: insights)

Integration with VoxPop

This service is designed to work as part of the VoxPop decentralized platform:

VoxPop's perspective submission service stores user submissions in IPFS
This analysis service fetches perspectives from IPFS
AI analysis generates insights that are made available through the API
The VoxPop frontend displays these insights to users and moderators

License

MIT License