111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
|
# VoxPop AI Analysis Service
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
1. Clone the repository
|
||
|
|
2. Install dependencies:
|
||
|
|
```bash
|
||
|
|
pip install -r requirements.txt
|
||
|
|
```
|
||
|
|
3. Run the service:
|
||
|
|
```bash
|
||
|
|
python -m app.main
|
||
|
|
```
|
||
|
|
4. Access the API documentation at http://localhost:8000/docs
|
||
|
|
|
||
|
|
### Docker Deployment
|
||
|
|
|
||
|
|
1. Build the Docker image:
|
||
|
|
```bash
|
||
|
|
docker build -t voxpop-analysis .
|
||
|
|
```
|
||
|
|
2. Run the container:
|
||
|
|
```bash
|
||
|
|
docker run -p 8000:8000 voxpop-analysis
|
||
|
|
```
|
||
|
|
|
||
|
|
## How It Works
|
||
|
|
|
||
|
|
### Data Flow
|
||
|
|
|
||
|
|
1. **Fetch**: Retrieve perspectives from IPFS (currently mocked)
|
||
|
|
2. **Analyze**:
|
||
|
|
- Perform sentiment analysis on each perspective
|
||
|
|
- Generate embeddings and cluster similar perspectives
|
||
|
|
- Extract key topics from each cluster
|
||
|
|
3. **Generate**: Create structured insights with confidence scores
|
||
|
|
4. **Store**: Save insights to disk for historical analysis
|
||
|
|
5. **Serve**: Provide API endpoints for accessing analysis results
|
||
|
|
|
||
|
|
### Example Analysis Output
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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:
|
||
|
|
|
||
|
|
1. VoxPop's perspective submission service stores user submissions in IPFS
|
||
|
|
2. This analysis service fetches perspectives from IPFS
|
||
|
|
3. AI analysis generates insights that are made available through the API
|
||
|
|
4. The VoxPop frontend displays these insights to users and moderators
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
[MIT License](LICENSE)
|