# Reddit Insights Python SDK

Official Python SDK for the Reddit Insights API. Analyze Reddit conversations with AI-powered semantic search.

## Installation

```bash
pip install reddit-insights
```

## Quick Start

```python
from reddit_insights import RedditInsightsClient

# Initialize the client
client = RedditInsightsClient(api_key="YOUR_API_KEY")

# Semantic search
results = client.semantic_search(
    query="What do young people complain about banking apps?",
    limit=20
)
print(results)

# Vector search with date filters
results = client.vector_search(
    query="electric vehicle charging",
    start_date="2025-01-01",
    end_date="2025-01-31",
    limit=30
)

# Get trending topics
trends = client.get_trends(
    start_date="2025-01-01",
    end_date="2025-01-31",
    limit=20
)
```

## Sonar Management (FREE Endpoints)

Sonars allow you to monitor Reddit conversations and receive alerts.

```python
# List all sonars
sonars = client.list_sonars()

# Create a new sonar
sonar = client.create_sonar(
    name="Product Feedback Monitor",
    query="What do users think about our product?",
    description="Track product feedback",
    schedule="daily",
    triggers={
        "keywords": ["bug", "issue", "problem"],
        "sentiment": "negative",
        "minNewPosts": 5
    },
    notify_email=True
)

# Get sonar execution history
executions = client.get_sonar_executions(
    sonar_id="sonar_123",
    limit=50
)

# Get detailed execution results
detail = client.get_execution_detail(execution_id="exec_789")
```

## API Reference

### RedditInsightsClient

#### Constructor

```python
RedditInsightsClient(
    api_key: str,
    base_url: str = "https://reddit-insights.com",
    timeout: int = 30
)
```

#### Methods

| Method | Description | Quota |
|--------|-------------|-------|
| `semantic_search(query, limit)` | AI-powered semantic search | Uses quota |
| `vector_search(query, limit, start_date, end_date)` | Vector similarity search | Uses quota |
| `get_trends(start_date, end_date, limit)` | Get trending topics | Uses quota |
| `list_sonars()` | List all sonars | FREE |
| `create_sonar(...)` | Create a new sonar | FREE |
| `get_sonar_executions(sonar_id, limit, offset)` | Get execution history | FREE |
| `get_execution_detail(execution_id)` | Get execution details | FREE |

## Error Handling

```python
from reddit_insights import (
    RedditInsightsClient,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    APIError
)

client = RedditInsightsClient(api_key="YOUR_API_KEY")

try:
    results = client.semantic_search(query="test query")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except APIError as e:
    print(f"API error: {e.message}")
```

## Rate Limits

| Tier | Limit |
|------|-------|
| Free | 100 requests/hour |
| Pro | 10,000 requests/month |
| Enterprise | Unlimited |

## License

MIT License

## Support

For support, please visit https://reddit-insights.com or contact support@reddit-insights.com.

