gdelt 0.1.0

//! Skill manifest and CLAUDE.md content generation.

use serde::{Deserialize, Serialize};

/// Skill manifest containing metadata
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SkillManifest {
    pub name: String,
    pub version: String,
    pub description: String,
    pub commands: Vec<String>,
}

impl Default for SkillManifest {
    fn default() -> Self {
        Self {
            name: "gdelt".to_string(),
            version: env!("CARGO_PKG_VERSION").to_string(),
            description: "GDELT Project CLI for global event data analysis".to_string(),
            commands: vec![
                "gdelt doc search".to_string(),
                "gdelt events query".to_string(),
                "gdelt gkg query".to_string(),
                "gdelt analytics trends".to_string(),
                "gdelt analytics sentiment".to_string(),
            ],
        }
    }
}

impl SkillManifest {
    /// Generate the CLAUDE.md skill content
    pub fn generate_claude_md(&self) -> String {
        format!(
            r#"# GDELT CLI Skill

Query and analyze global event data from the GDELT Project.

## Overview

The GDELT CLI provides access to:
- **DOC API**: Search news articles and documents worldwide
- **GEO API**: Geographic event data and mapping
- **TV API**: Television news coverage analysis
- **Local Database**: Query cached events, GKG, and mentions data
- **Analytics**: Trend analysis, sentiment, entity extraction, and reports

## Commands

### News Article Search (DOC API)

Search for news articles by keyword, country, language, or topic:

```bash
# Search recent news
gdelt doc search "climate change" --timespan 7d

# Filter by country and language
gdelt doc search "election" --country US --lang en

# Get timeline data
gdelt doc timeline "artificial intelligence" --timespan 30d
```

### Events Database Queries

Query the local events database for historical analysis:

```bash
# Query events by actor
gdelt events query --actor USA --start 2024-01-01

# Query by event type (CAMEO codes)
gdelt events query --event-code "14*" --country US

# Lookup specific event
gdelt events lookup 123456789
```

### GKG (Global Knowledge Graph) Queries

Extract entities, themes, and sentiment from news:

```bash
# Query by theme
gdelt gkg query --theme CLIMATE

# Get top persons mentioned
gdelt gkg persons --min-count 10 --limit 50

# Query organizations
gdelt gkg organizations --pattern "United Nations"
```

### Analytics

Run analytical queries on local data:

```bash
# Trend analysis
gdelt analytics trends "Russia" "Ukraine" --timespan 30d --detect-anomalies

# Sentiment over time
gdelt analytics sentiment "technology" --dimension time --timespan 7d

# Compare topics
gdelt analytics compare "renewable energy" "fossil fuels" --timespan 30d

# Generate reports
gdelt analytics report daily --topics "AI" "climate"
```

### Data Management

Download and manage local GDELT data:

```bash
# Download historical events
gdelt data download events --start 2024-01-01 --end 2024-01-31

# Sync to latest data
gdelt data sync

# Show download status
gdelt data status --detailed
```

### Database Operations

Manage the local DuckDB database:

```bash
# Show statistics
gdelt db stats --detailed

# Run custom SQL
gdelt db query "SELECT COUNT(*) FROM events WHERE quad_class = 4"

# Export data
gdelt db export events --output events.parquet --format parquet
```

## CAMEO Event Codes Reference

Common event categories:
- **01-09**: Verbal cooperation (statements, consultations, aid)
- **10-14**: Verbal conflict (demands, threats, protests)
- **15-20**: Material conflict (force, assault, violence)

```bash
# List all codes
gdelt events codes list

# Search codes
gdelt events codes search "protest"
```

## Output Formats

All commands support multiple output formats:

```bash
# JSON output
gdelt doc search "query" --json

# CSV output
gdelt events query --csv

# Table output (default for TTY)
gdelt db stats --table

# JSONL streaming
gdelt events query --jsonl
```

## Tips for Effective Queries

1. **Use specific timeframes**: GDELT data is large; always specify date ranges
2. **Combine filters**: Use actor, country, and event codes together for precise results
3. **Check local data first**: Queries against local database are much faster
4. **Use analytics for insights**: Built-in analytics provide summary statistics

## Version

GDELT CLI version: {}
"#,
            self.version
        )
    }
}