trendsagi 0.1.0__py3-none-any.whl

trendsagi/__init__.py

@@ -0,0 +1,5 @@
+# File: trendsagi/__init__.py
+
+from .client import TrendsAGIClient # Assuming TrendsAGIClient is in trendsagi/client.py
+from . import exceptions            # Assuming exceptions are defined in trendsagi/exceptions.py
+                                    # Or: from .errors import exceptions if it's in trendsagi/errors.py

trendsagi/client.py

@@ -0,0 +1,337 @@
+import requests
+from typing import Optional, List, Dict, Any
+
+from . import models
+from . import exceptions
+
+class TrendsAGIClient:
+    """
+    The main client for interacting with the TrendsAGI API.
+    
+    :param api_key: Your TrendsAGI API key, generated from your profile page.
+    :param base_url: The base URL of the TrendsAGI API. Defaults to the production URL.
+                     Override this for development or testing against a local server.
+                     Example for local dev: base_url="http://localhost:8000"
+    """
+    def __init__(self, api_key: str, base_url: str = "https://api.trendsagi.com"):
+        if not api_key:
+            raise exceptions.AuthenticationError("API key is required.")
+        
+        self.base_url = base_url.rstrip('/')
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json"
+        })
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> Any:
+        """Internal helper for making API requests."""
+        url = f"{self.base_url}{endpoint}"
+        try:
+            response = self._session.request(method, url, **kwargs)
+            
+            if 200 <= response.status_code < 300:
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            
+            try:
+                error_detail = response.json().get('detail', response.text)
+            except requests.exceptions.JSONDecodeError:
+                error_detail = response.text
+                
+            if response.status_code == 401:
+                raise exceptions.AuthenticationError(error_detail)
+            if response.status_code == 404:
+                raise exceptions.NotFoundError(response.status_code, error_detail)
+            if response.status_code == 409:
+                raise exceptions.ConflictError(response.status_code, error_detail)
+            if response.status_code == 429:
+                raise exceptions.RateLimitError(response.status_code, error_detail)
+            
+            raise exceptions.APIError(response.status_code, error_detail)
+
+        except requests.exceptions.RequestException as e:
+            raise exceptions.TrendsAGIError(f"Network error communicating with API: {e}")
+
+    # --- Trends & Insights Methods ---
+
+    def get_trends(
+        self,
+        search: Optional[str] = None,
+        sort_by: str = 'volume',
+        order: str = 'desc',
+        limit: int = 20,
+        offset: int = 0,
+        period: str = '24h',
+        category: Optional[str] = None
+    ) -> models.TrendListResponse:
+        """
+        Retrieve a list of currently trending topics.
+        """
+        params = {k: v for k, v in locals().items() if v is not None and k != 'self'}
+        response_data = self._request('GET', '/api/trends', params=params)
+        return models.TrendListResponse.model_validate(response_data)
+        
+    def get_trend_details(self, trend_id: int) -> models.TrendDetail:
+        """
+        Retrieve detailed information for a single trend, including associated tweets.
+        """
+        response_data = self._request('GET', f'/api/trends/{trend_id}')
+        return models.TrendDetail.model_validate(response_data)
+
+    def get_trend_analytics(self, trend_id: int, period: str = '7d', start_date: Optional[str] = None, end_date: Optional[str] = None) -> models.TrendAnalytics:
+        """
+        Retrieve historical data points for a specific trend.
+        """
+        params = {"period": period, "start_date": start_date, "end_date": end_date}
+        params = {k: v for k, v in params.items() if v is not None}
+        response_data = self._request('GET', f'/api/trends/{trend_id}/analytics', params=params)
+        return models.TrendAnalytics.model_validate(response_data)
+
+    def search_insights(
+        self,
+        key_theme_contains: Optional[str] = None,
+        audience_keyword: Optional[str] = None,
+        angle_contains: Optional[str] = None,
+        sentiment_category: Optional[str] = None,
+        overall_topic_category_llm: Optional[str] = None,
+        trend_name_contains: Optional[str] = None,
+        limit: int = 20,
+        offset: int = 0,
+        sort_by: str = 'timestamp',
+        order: str = 'desc'
+    ) -> models.InsightSearchResponse:
+        """
+        Search for trends based on the content of their AI-generated insights.
+        """
+        params = {
+            "keyThemeContains": key_theme_contains, "audienceKeyword": audience_keyword,
+            "angleContains": angle_contains, "sentimentCategory": sentiment_category,
+            "overallTopicCategoryLlm": overall_topic_category_llm, "trendNameContains": trend_name_contains,
+            "limit": limit, "offset": offset, "sort_by": sort_by, "order": order
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        response_data = self._request('GET', '/api/insights/search', params=params)
+        return models.InsightSearchResponse.model_validate(response_data)
+        
+    def get_ai_insights(self, trend_id: int, force_refresh: bool = False) -> Optional[models.AIInsight]:
+        """
+        Get or generate AI-powered insights for a specific trend.
+        """
+        response_data = self._request('GET', f'/api/trends/{trend_id}/ai-insights', params={"force_refresh": force_refresh})
+        return models.AIInsight.model_validate(response_data) if response_data else None
+
+    # --- Custom Reports Methods ---
+
+    def generate_custom_report(self, report_request: Dict[str, Any]) -> models.CustomReport:
+        """
+        Generate a custom report based on specified dimensions, metrics, and filters.
+        """
+        response_data = self._request('POST', '/api/reports/custom', json=report_request)
+        return models.CustomReport.model_validate(response_data)
+        
+    # --- Intelligence Suite Methods ---
+
+    def get_recommendations(
+        self,
+        limit: int = 10, offset: int = 0, recommendation_type: Optional[str] = None,
+        source_trend_query: Optional[str] = None, priority: Optional[str] = None, status: str = 'new'
+    ) -> models.RecommendationListResponse:
+        """
+        Get actionable recommendations generated for the user.
+        """
+        params = {
+            "limit": limit, "offset": offset, "type": recommendation_type, 
+            "sourceTrendQ": source_trend_query, "priority": priority, "status": status
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        response_data = self._request('GET', '/api/intelligence/recommendations', params=params)
+        return models.RecommendationListResponse.model_validate(response_data)
+
+    def perform_recommendation_action(self, recommendation_id: int, action: Optional[str] = None, feedback: Optional[str] = None) -> models.Recommendation:
+        """
+        Update a recommendation's status or provide feedback.
+        """
+        if action and feedback:
+            raise ValueError("Only one of 'action' or 'feedback' can be provided at a time.")
+        if not action and not feedback:
+            raise ValueError("Either 'action' or 'feedback' must be provided.")
+
+        payload = {"action": action, "feedback": feedback}
+        payload = {k: v for k, v in payload.items() if v is not None}
+        response_data = self._request('POST', f'/api/intelligence/recommendations/{recommendation_id}/action', json=payload)
+        return models.Recommendation.model_validate(response_data)
+
+    def get_tracked_x_users(self, q: Optional[str] = None, min_followers: Optional[int] = None, sort_by: str = 'name_asc') -> models.MarketEntityListResponse:
+        """
+        Get a list of tracked X Users.
+        """
+        params = {"q": q, "min_followers": min_followers, "sort_by": sort_by}
+        params = {k: v for k, v in params.items() if v is not None}
+        response_data = self._request('GET', '/api/intelligence/market/x-users', params=params)
+        return models.MarketEntityListResponse.model_validate(response_data)
+
+    def get_tracked_x_user(self, entity_id: int) -> models.MarketEntity:
+        """
+        Retrieve a single tracked X User by their unique entity ID.
+        """
+        response_data = self._request('GET', f'/api/intelligence/market/x-users/{entity_id}')
+        return models.MarketEntity.model_validate(response_data)
+
+    def create_tracked_x_user(self, handle: str, name: Optional[str] = None, description: Optional[str] = None, notes: Optional[str] = None) -> models.MarketEntity:
+        """
+        Add a new X User to track.
+        """
+        payload = {"handle": handle, "name": name, "description": description, "notes": notes}
+        payload = {k: v for k, v in payload.items() if v is not None}
+        response_data = self._request('POST', '/api/intelligence/market/x-users', json=payload)
+        return models.MarketEntity.model_validate(response_data)
+        
+    def update_tracked_x_user(self, entity_id: int, updates: Dict[str, Any]) -> models.MarketEntity:
+        """
+        Update details of a tracked X User.
+        """
+        response_data = self._request('PUT', f'/api/intelligence/market/x-users/{entity_id}', json=updates)
+        return models.MarketEntity.model_validate(response_data)
+
+    def delete_tracked_x_user(self, entity_id: int) -> None:
+        """Stop tracking an X User."""
+        self._request('DELETE', f'/api/intelligence/market/x-users/{entity_id}')
+
+    def get_crisis_events(
+        self,
+        limit: int = 10, offset: int = 0, status: str = 'active', keyword: Optional[str] = None,
+        severity: Optional[str] = None, time_range: str = '24h',
+        start_date: Optional[str] = None, end_date: Optional[str] = None
+    ) -> models.CrisisEventListResponse:
+        """
+        Get crisis events detected for the user.
+        """
+        params = {
+            "limit": limit, "offset": offset, "status": status, "keyword": keyword, 
+            "severity": severity, "timeRange": time_range, "startDate": start_date, "endDate": end_date
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        response_data = self._request('GET', '/api/intelligence/crisis-events', params=params)
+        return models.CrisisEventListResponse.model_validate(response_data)
+
+    def get_crisis_event(self, event_id: int) -> models.CrisisEvent:
+        """
+        Retrieve a single crisis event by its unique ID.
+        """
+        response_data = self._request('GET', f'/api/intelligence/crisis-events/{event_id}')
+        return models.CrisisEvent.model_validate(response_data)
+
+    def perform_crisis_event_action(self, event_id: int, action: str) -> models.CrisisEvent:
+        """
+        Update the status of a crisis event (e.g., "acknowledge", "archive").
+        """
+        response_data = self._request('POST', f'/api/intelligence/crisis-events/{event_id}/action', json={"action": action})
+        return models.CrisisEvent.model_validate(response_data)
+
+    def perform_deep_analysis(self, query: str, force_refresh: bool = False) -> models.DeepAnalysis:
+        """
+        Perform deep AI analysis on a topic.
+        """
+        response_data = self._request('POST', '/api/intelligence/deep-analysis', json={"query": query, "force_refresh": force_refresh})
+        return models.DeepAnalysis.model_validate(response_data)
+        
+    # --- User & Account Management Methods (Non-sensitive) ---
+
+    def get_topic_interests(self) -> List[models.TopicInterest]:
+        """Retrieve the list of topic interests tracked by the user."""
+        response_data = self._request('GET', '/api/user/topic-interests')
+        return [models.TopicInterest.model_validate(item) for item in response_data]
+
+    def create_topic_interest(
+        self,
+        keyword: str, alert_condition_type: str,
+        volume_threshold_value: Optional[int] = None, percentage_growth_value: Optional[float] = None
+    ) -> models.TopicInterest:
+        """
+        Create a new topic interest.
+        """
+        payload = {
+            "keyword": keyword, "alert_condition_type": alert_condition_type,
+            "volume_threshold_value": volume_threshold_value, "percentage_growth_value": percentage_growth_value
+        }
+        payload = {k: v for k, v in payload.items() if v is not None}
+        response_data = self._request('POST', '/api/user/topic-interests', json=payload)
+        return models.TopicInterest.model_validate(response_data)
+        
+    def delete_topic_interest(self, interest_id: int) -> None:
+        """Delete a specific topic interest."""
+        self._request('DELETE', f'/api/user/topic-interests/{interest_id}')
+
+    def get_export_settings(self) -> List[models.ExportConfiguration]:
+        """Get all of the user's data export configurations."""
+        response_data = self._request('GET', '/api/user/export/settings')
+        return [models.ExportConfiguration.model_validate(item) for item in response_data]
+
+    def save_export_settings(
+        self,
+        destination: str, config: Dict[str, Any], schedule: str = "none",
+        schedule_time: Optional[str] = None, is_active: bool = False, config_id: Optional[int] = None
+    ) -> models.ExportConfiguration:
+        """
+        Create or update an export configuration.
+        """
+        payload = {
+            "id": config_id, "destination": destination, "config": config,
+            "schedule": schedule, "schedule_time": schedule_time, "is_active": is_active,
+        }
+        payload = {k: v for k, v in payload.items() if v is not None}
+        response_data = self._request('POST', '/api/user/export/settings', json=payload)
+        return models.ExportConfiguration.model_validate(response_data)
+
+    def delete_export_setting(self, config_id: int) -> None:
+        """Delete an export configuration."""
+        self._request('DELETE', f'/api/user/export/settings/{config_id}')
+
+    def get_export_history(self, limit: int = 15, offset: int = 0) -> models.ExportHistoryResponse:
+        """Get the user's export execution history."""
+        response_data = self._request('GET', '/api/user/export/history', params={"limit": limit, "offset": offset})
+        return models.ExportHistoryResponse.model_validate(response_data)
+
+    def run_export_now(self, config_id: int) -> models.ExportExecutionLog:
+        """Trigger an immediate export."""
+        response_data = self._request('POST', f'/api/user/export/configurations/{config_id}/run-now')
+        return models.ExportExecutionLog.model_validate(response_data)
+        
+    def get_dashboard_stats(self) -> models.DashboardStats:
+        """Get key statistics for the user's dashboard."""
+        response_data = self._request('GET', '/api/user/dashboard/stats')
+        return models.DashboardStats.model_validate(response_data)
+
+    def get_recent_notifications(self, limit: int = 10) -> models.NotificationListResponse:
+        """Get recent notifications for the user."""
+        response_data = self._request('GET', '/api/user/notifications/recent', params={"limit": limit})
+        return models.NotificationListResponse.model_validate(response_data)
+
+    def mark_notifications_read(self, ids: Optional[List[int]] = None) -> Dict[str, Any]:
+        """Mark notifications as read. If ids is None, marks all as read."""
+        payload = {"ids": ids if ids is not None else []}
+        return self._request('POST', '/api/user/notifications/mark-read', json=payload)
+
+    # --- Public Information & Status Methods ---
+    
+    def get_available_plans(self) -> List[models.SubscriptionPlan]:
+        """Retrieve a list of all publicly available subscription plans."""
+        response_data = self._request('GET', '/api/plans')
+        return [models.SubscriptionPlan.model_validate(plan) for plan in response_data]
+
+    def get_api_status(self) -> models.StatusPage:
+        """
+        Retrieve the current operational status of the API and its components.
+        """
+        response_data = self._request('GET', '/api/status')
+        return models.StatusPage.model_validate(response_data)
+        
+    def get_api_status_history(self) -> models.StatusHistoryResponse:
+        """
+        Retrieve the 90-day uptime history for all API components.
+        """
+        response_data = self._request('GET', '/api/status-history')
+        return models.StatusHistoryResponse.model_validate(response_data)

trendsagi/exceptions.py

@@ -0,0 +1,28 @@
+# File: trendsagi-client/trendsagi/exceptions.py
+
+class TrendsAGIError(Exception):
+    """Base exception for the TrendsAGI client library."""
+    pass
+
+class AuthenticationError(TrendsAGIError):
+    """Raised when authentication fails (e.g., invalid API key)."""
+    pass
+
+class APIError(TrendsAGIError):
+    """Raised for non-2xx API responses."""
+    def __init__(self, status_code, error_detail):
+        self.status_code = status_code
+        self.error_detail = error_detail
+        super().__init__(f"API request failed with status {status_code}: {error_detail}")
+
+class NotFoundError(APIError):
+    """Raised for 404 Not Found errors."""
+    pass
+
+class RateLimitError(APIError):
+    """Raised for 429 Too Many Requests errors."""
+    pass
+
+class ConflictError(APIError):
+    """Raised for 409 Conflict errors."""
+    pass

trendsagi/models.py

@@ -0,0 +1,281 @@
+# File: trendsagi-client/trendsagi/models.py
+
+from pydantic import BaseModel, Field, HttpUrl, EmailStr
+from typing import List, Optional, Any, Dict
+from datetime import datetime, date
+
+# --- Base & Helper Models ---
+class OrmBaseModel(BaseModel):
+    class Config:
+        from_attributes = True
+
+class PaginationMeta(OrmBaseModel):
+    total: int
+    limit: int
+    offset: int
+    period: Optional[str] = None
+    sort_by: Optional[str] = None
+    order: Optional[str] = None
+    search: Optional[str] = None
+    category: Optional[str] = None
+
+# --- Trends & Insights Models ---
+class TrendItem(OrmBaseModel):
+    id: int
+    name: str
+    volume: Optional[int] = None
+    timestamp: datetime
+    meta_description: Optional[str] = None
+    category: Optional[str] = None
+    growth: Optional[float] = None
+    previous_volume: Optional[int] = None
+    absolute_change: Optional[int] = None
+
+class TrendListResponse(OrmBaseModel):
+    trends: List[TrendItem]
+    meta: PaginationMeta
+    
+class TweetUser(OrmBaseModel):
+    id: int
+    user_id: int
+    screen_name: str
+    name: Optional[str] = None
+
+class Tweet(OrmBaseModel):
+    id: int
+    tweet_id: int
+    text: str
+    created_at: datetime
+    user: Optional[TweetUser] = None
+
+class TrendDetail(TrendItem):
+    tweets: List[Tweet] = Field(default_factory=list)
+
+class TrendDataPoint(OrmBaseModel):
+    date: datetime
+    volume: Optional[int] = None
+    growth_rate: Optional[float] = None
+
+class TrendAnalytics(OrmBaseModel):
+    trend_id: int
+    name: str
+    period: str
+    start_date: Optional[datetime] = None
+    end_date: Optional[datetime] = None
+    data: List[TrendDataPoint]
+
+class TrendSearchResultItem(OrmBaseModel):
+    id: int
+    name: str
+    category: Optional[str] = None
+    volume: Optional[int] = None
+    timestamp: Optional[datetime] = None
+    meta_description: Optional[str] = None
+
+class InsightSearchResponse(OrmBaseModel):
+    trends: List[TrendSearchResultItem]
+    meta: PaginationMeta
+
+class AIInsightContentBrief(OrmBaseModel):
+    target_audience_segments: List[str]
+    key_angles_for_content: List[str]
+    suggested_content_formats: List[str]
+    call_to_action_ideas: List[str]
+
+class AIInsightAdTargeting(OrmBaseModel):
+    primary_audience_keywords: List[str]
+    secondary_audience_keywords: List[str]
+    potential_demographics_summary: Optional[str]
+
+class AIInsight(OrmBaseModel):
+    trend_id: int
+    trend_name: str
+    sentiment_summary: Optional[str]
+    sentiment_category: Optional[str]
+    key_themes: List[str]
+    content_brief: Optional[AIInsightContentBrief]
+    ad_platform_targeting: Optional[AIInsightAdTargeting]
+    potential_risks_or_controversies: List[str]
+    overall_topic_category_llm: Optional[str]
+    generated_at: datetime
+    llm_model_used: str
+
+# --- Custom Report Models ---
+class ReportMeta(OrmBaseModel):
+    row_count: int
+    limit_applied: Optional[int] = None
+    time_period: str
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+
+class CustomReport(OrmBaseModel):
+    columns: List[str]
+    rows: List[Dict[str, Any]]
+    meta: ReportMeta
+
+# --- Intelligence Suite Models ---
+class Recommendation(OrmBaseModel):
+    id: int
+    user_id: int
+    type: str
+    title: str
+    details: str
+    source_trend_id: Optional[str] = None
+    source_trend_name: Optional[str] = None
+    priority: str
+    status: str
+    created_at: datetime
+    updated_at: datetime
+    user_feedback: Optional[str] = None
+
+class RecommendationListResponse(OrmBaseModel):
+    recommendations: List[Recommendation]
+    meta: PaginationMeta
+
+class MarketEntity(OrmBaseModel):
+    id: int
+    user_id: int
+    name: Optional[str] = None
+    handle: str
+    website: Optional[HttpUrl] = None
+    description: Optional[str] = None
+    notes: Optional[str] = None
+    followers_count: Optional[int] = None
+    overall_sentiment: Optional[str] = None
+    top_keywords: Optional[List[str]] = Field(default_factory=list, alias="top_keywords_json")
+    recent_topics: Optional[List[str]] = Field(default_factory=list, alias="recent_topics_json")
+    last_analyzed_at: Optional[datetime] = Field(None, alias="last_analyzed")
+    created_at: datetime
+    updated_at: datetime
+    
+    class Config:
+        populate_by_name = True
+
+class MarketEntityListResponse(OrmBaseModel):
+    items: List[MarketEntity]
+
+class CrisisEvent(OrmBaseModel):
+    id: int
+    user_id: int
+    title: str
+    summary: str
+    severity: str
+    status: str
+    detected_at: datetime
+    source_keywords: Optional[List[str]] = Field(None, alias="source_keywords_json")
+    impacted_entity: Optional[str] = None
+    trend_snapshot_link: Optional[HttpUrl] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        populate_by_name = True
+
+class CrisisEventListResponse(OrmBaseModel):
+    events: List[CrisisEvent]
+    meta: PaginationMeta
+
+class DeepAnalysisSentiment(OrmBaseModel):
+    overall_sentiment_category: str
+    positive_nuances: List[str]
+    negative_nuances: List[str]
+    neutral_aspects: List[str]
+
+class DeepAnalysisActionableInsights(OrmBaseModel):
+    marketing_pr: List[str]
+    product_development: List[str]
+    crm_strategy: List[str]
+    
+class DeepAnalysisRelatedTrend(OrmBaseModel):
+    id: str
+    name: str
+
+class DeepAnalysis(OrmBaseModel):
+    query_analyzed: str
+    generated_at: datetime
+    llm_model_used: str
+    overall_summary: str
+    key_findings: List[str]
+    sentiment_analysis: DeepAnalysisSentiment
+    causal_factors: List[str]
+    emerging_sub_topics: List[str]
+    future_outlook_and_predictions: List[str]
+    actionable_insights_for_roles: DeepAnalysisActionableInsights
+    related_trends: List[DeepAnalysisRelatedTrend]
+
+# --- User & Account Management Models ---
+class TopicInterest(OrmBaseModel):
+    id: int
+    user_id: int
+    keyword: str
+    alert_condition_type: str
+    volume_threshold_value: Optional[int] = None
+    percentage_growth_value: Optional[float] = None
+    created_at: datetime
+
+class ExportConfiguration(OrmBaseModel):
+    id: int
+    destination: str
+    config: Dict[str, Any]
+    schedule: str
+    schedule_time: Optional[str] = None
+    is_active: bool
+
+class ExportExecutionLog(OrmBaseModel):
+    id: int
+    execution_time: datetime
+    duration_seconds: Optional[float] = None
+    destination: str
+    status: str
+    message: Optional[str] = None
+    records_exported: Optional[int] = None
+    export_configuration_id: Optional[int] = None
+
+class ExportHistoryResponse(OrmBaseModel):
+    history: List[ExportExecutionLog]
+    meta: PaginationMeta
+
+class DashboardStats(OrmBaseModel):
+    active_trends: int
+    alerts_today: int
+    topic_interests: int
+    avg_growth: Optional[float] = None
+
+class Notification(OrmBaseModel):
+    id: int
+    title: str
+    message: str
+    notification_type: str
+    is_read: bool
+    created_at: datetime
+    read_at: Optional[datetime] = None
+    data: Optional[Dict[str, Any]] = None
+
+class NotificationListResponse(OrmBaseModel):
+    notifications: List[Notification]
+    unread_count: int
+
+# --- Public Information & Status Models ---
+class SubscriptionPlan(OrmBaseModel):
+    id: int
+    name: str
+    description: Optional[str] = None
+    price_monthly: Optional[float] = None
+    price_yearly: Optional[float] = None
+    is_custom: bool
+    features: Optional[Dict[str, Any]] = Field(default_factory=dict)
+
+class ComponentStatus(OrmBaseModel):
+    name: str
+    status: str
+    description: str
+
+class StatusPage(OrmBaseModel):
+    overall_status: str
+    last_updated: datetime
+    components: List[ComponentStatus]
+
+# NEW: Model for API Status History
+class StatusHistoryResponse(OrmBaseModel):
+    uptime_percentages: Dict[str, float]
+    daily_statuses: Dict[str, Dict[str, str]]

trendsagi-0.1.0.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: trendsagi
+Version: 0.1.0
+Summary: The official Python client for the TrendsAGI API.
+Author-email: TrendsAGI <contact@trendsagi.com>
+Project-URL: Homepage, https://github.com/TrendsAGI/TrendsAGI
+Project-URL: Bug Tracker, https://github.com/TrendsAGI/TrendsAGI/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+# TrendsAGI Official Python Client
+
+[![PyPI Version](https://img.shields.io/pypi/v/trendsagi.svg)](https://pypi.org/project/trendsagi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Versions](https://img.shields.io/pypi/pyversions/trendsagi.svg)](https://pypi.org/project/trendsagi/)
+
+The official Python client for the [TrendsAGI API](https://trendsagi.com), providing a simple and convenient way to access real-time trend data, AI-powered insights, and the full intelligence suite.
+
+This library is fully typed with Pydantic models for all API responses, giving you excellent editor support (like autocompletion and type checking) and data validation out of the box.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+  - [Authentication](#authentication)
+  - [Quickstart Example](#quickstart-example)
+- [Usage Examples](#usage-examples)
+  - [Get AI-Powered Insights for a Trend](#get-ai-powered-insights-for-a-trend)
+  - [Perform a Deep Analysis on a Topic](#perform-a-deep-analysis-on-a-topic)
+  - [Track an X (Twitter) User](#track-an-x-twitter-user)
+  - [Monitor for Crisis Events](#monitor-for-crisis-events)
+- [Handling Errors and Exceptions](#handling-errors-and-exceptions)
+- [Full API Documentation](#full-api-documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- Access real-time and historical trend data
+- Leverage powerful AI-driven insights, sentiment analysis, and content briefs for any trend
+- Perform deep, causal analysis on any topic or query
+- Utilize the Intelligence Suite for actionable recommendations, crisis monitoring, and market tracking
+- Manage topic interests, alerts, and data export configurations
+- Simple, intuitive methods mirroring the API structure
+- Robust error handling with custom exceptions
+- Data validation and rich type-hinting powered by Pydantic
+
+## Installation
+
+Install the library directly from PyPI:
+
+```bash
+pip install trendsagi
+```
+
+## Getting Started
+
+### Authentication
+
+First, you'll need a TrendsAGI account and an API key. You can sign up and generate a key from your dashboard.
+
+We strongly recommend storing your API key as an environment variable to avoid committing it to version control.
+
+```bash
+export TRENDSAGI_API_KEY="your_api_key_here"
+```
+
+### Quickstart Example
+
+This example demonstrates how to initialize the client and fetch the latest trending topics.
+
+```python
+import os
+import trendsagi
+from trendsagi import exceptions
+
+# It's recommended to load your API key from an environment variable
+API_KEY = os.environ.get("TRENDSAGI_API_KEY")
+
+if not API_KEY:
+    raise ValueError("Please set the TRENDSAGI_API_KEY environment variable.")
+
+# Initialize the client
+client = trendsagi.TrendsAGIClient(api_key=API_KEY)
+
+try:
+    # Get the top 5 trending topics from the last 24 hours
+    print("Fetching top 5 trending topics...")
+    response = client.get_trends(limit=5, period='24h')
+
+    print(f"\nFound {response.meta.total} total trends. Displaying the top {len(response.trends)}:")
+    for trend in response.trends:
+        print(f"- ID: {trend.id}, Name: '{trend.name}', Volume: {trend.volume}")
+
+except exceptions.AuthenticationError:
+    print("Authentication failed. Please check your API key.")
+except exceptions.APIError as e:
+    print(f"An API error occurred: Status {e.status_code}, Details: {e.error_detail}")
+except exceptions.TrendsAGIError as e:
+    print(f"A client-side error occurred: {e}")
+```
+
+## Usage Examples
+
+### Get AI-Powered Insights for a Trend
+
+Retrieve AI-generated insights for a specific trend, such as key themes, target audiences, and content ideas.
+
+```python
+# Assuming 'client' is an initialized TrendsAGIClient
+# and you have a trend_id from a call to get_trends()
+TREND_ID = 12345 
+
+try:
+    print(f"\nGetting AI insights for trend ID {TREND_ID}...")
+    ai_insight = client.get_ai_insights(trend_id=TREND_ID)
+    
+    if ai_insight:
+        print(f"  Sentiment: {ai_insight.sentiment_category}")
+        print("  Key Themes:")
+        for theme in ai_insight.key_themes[:3]:  # show first 3
+            print(f"    - {theme}")
+        print("  Suggested Content Angle:")
+        print(f"    - {ai_insight.content_brief.key_angles_for_content[0]}")
+        
+except exceptions.NotFoundError:
+    print(f"Trend with ID {TREND_ID} not found.")
+except exceptions.APIError as e:
+    print(f"An API error occurred: {e}")
+```
+
+### Perform a Deep Analysis on a Topic
+
+```python
+# Assuming 'client' is an initialized TrendsAGIClient
+try:
+    print("\nPerforming deep analysis on 'artificial intelligence'...")
+    analysis = client.perform_deep_analysis(
+        query="artificial intelligence",
+        analysis_type="comprehensive"
+    )
+    
+    print(f"Analysis completed. Key findings:")
+    print(f"- Market sentiment: {analysis.market_sentiment}")
+    print(f"- Growth trajectory: {analysis.growth_projection}")
+    print(f"- Key influencers: {', '.join(analysis.top_influencers[:3])}")
+    
+except exceptions.APIError as e:
+    print(f"An API error occurred: {e}")
+```
+
+### Track an X (Twitter) User
+
+Add a user to your tracked market entities in the Intelligence Suite.
+
+```python
+# Assuming 'client' is an initialized TrendsAGIClient
+try:
+    print("\nAdding a new X user to track...")
+    new_entity = client.create_tracked_x_user(
+        handle="OpenAI",
+        name="OpenAI",
+        notes="Key player in the AI industry."
+    )
+    print(f"Successfully started tracking '{new_entity.name}' (ID: {new_entity.id})")
+
+except exceptions.ConflictError:
+    print("This user is already being tracked.")
+except exceptions.APIError as e:
+    print(f"An API error occurred: {e}")
+```
+
+### Monitor for Crisis Events
+
+Retrieve any active crisis events detected by the system.
+
+```python
+# Assuming 'client' is an initialized TrendsAGIClient
+try:
+    print("\nChecking for active crisis events...")
+    crisis_response = client.get_crisis_events(status='active', limit=5)
+
+    if not crisis_response.events:
+        print("No active crisis events found.")
+    else:
+        for event in crisis_response.events:
+            print(f"- [SEVERITY: {event.severity}] {event.title}")
+            print(f"  Summary: {event.summary}\n")
+
+except exceptions.APIError as e:
+    print(f"An API error occurred: {e}")
+```
+
+## Handling Errors and Exceptions
+
+The library raises specific exceptions for different types of errors, all inheriting from `trendsagi.exceptions.TrendsAGIError`. This allows for granular error handling.
+
+- **`TrendsAGIError`**: The base exception for all library-specific errors
+- **`AuthenticationError`**: Raised on 401 errors for an invalid or missing API key
+- **`APIError`**: The base class for all non-2xx API responses
+- **`NotFoundError`**: Raised on 404 errors when a resource is not found
+- **`ConflictError`**: Raised on 409 errors, e.g., when trying to create a resource that already exists
+- **`RateLimitError`**: Raised on 429 errors when you have exceeded your API rate limit
+
+Example error handling:
+
+```python
+try:
+    response = client.get_trends()
+except exceptions.AuthenticationError:
+    print("Invalid API key. Please check your credentials.")
+except exceptions.RateLimitError as e:
+    print(f"Rate limit exceeded. Retry after: {e.retry_after} seconds")
+except exceptions.NotFoundError:
+    print("The requested resource was not found.")
+except exceptions.APIError as e:
+    print(f"API error: {e.status_code} - {e.error_detail}")
+except exceptions.TrendsAGIError as e:
+    print(f"Client error: {e}")
+```
+
+## Advanced Usage
+
+### Working with Pagination
+
+```python
+# Get all trends with pagination
+all_trends = []
+page = 1
+while True:
+    response = client.get_trends(page=page, limit=100)
+    all_trends.extend(response.trends)
+    
+    if page >= response.meta.total_pages:
+        break
+    page += 1
+
+print(f"Retrieved {len(all_trends)} total trends")
+```
+
+### Setting Up Alerts
+
+```python
+# Create a new trend alert
+alert = client.create_alert(
+    name="AI Technology Alert",
+    keywords=["artificial intelligence", "machine learning", "AI"],
+    threshold_volume=1000,
+    notification_method="email"
+)
+print(f"Created alert: {alert.name} (ID: {alert.id})")
+```
+
+### Export Data
+
+```python
+# Export trend data to CSV
+export_job = client.export_trends(
+    format="csv",
+    date_range="last_7_days",
+    filters={"category": "technology"}
+)
+print(f"Export job started: {export_job.job_id}")
+
+# Check export status
+status = client.get_export_status(export_job.job_id)
+if status.is_complete:
+    print(f"Export ready for download: {status.download_url}")
+```
+
+## Full API Documentation
+
+This library is a client for the TrendsAGI REST API. For complete details on all available API endpoints, parameters, data models, rate limits, and best practices, please refer to our official [API Documentation](https://trendsagi.com/api-docs).
+
+## Contributing
+
+Contributions are welcome! If you find a bug or have a feature request, please open an issue on our GitHub Issues page. If you'd like to contribute code, please fork the repository and open a pull request.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/trendsagi/TrendsAGI.git
+cd TrendsAGI
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linting
+flake8 trendsagi/
+mypy trendsagi/
+```
+
+## Support
+
+
+- **API Reference**: [https://trendsagi.com/api-docs](https://trendsagi.com/api-docs)
+- **Support Email**: contact@trendsagi.com
+- **GitHub Issues**: [https://github.com/TrendsAGI/TrendsAGI/issues](https://github.com/TrendsAGI/TrendsAGI/issues)
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**Built with ❤️ by the TrendsAGI Team**

trendsagi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+trendsagi/__init__.py,sha256=f1Pzinj-7c-LlZoxGhKA9RerL0NAZoV1nukGFTjXTo0,320
+trendsagi/client.py,sha256=PnG6y1ozBY1wR6Bri5dqt38VVGKL57NYk3eHym51Tt4,16502
+trendsagi/exceptions.py,sha256=t8hUNK8PxHltvgkuvxrnGOhOaNXj5k2Yuvy9GNhd1Io,829
+trendsagi/models.py,sha256=uRCKCl69SpqadTyo2QPGZ_rldkdE7UzDbvBJMpUZejc,7744
+trendsagi-0.1.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trendsagi-0.1.0.dist-info/METADATA,sha256=pzLt3bvAtad_yJJwwwHNb5Dt1Xrq1S1wGAxbPaGZ-p8,10825
+trendsagi-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+trendsagi-0.1.0.dist-info/top_level.txt,sha256=fzNg3zxSm70ICBiM_K5UF1XFq5XN0qUdcYub9U7it0g,10
+trendsagi-0.1.0.dist-info/RECORD,,

trendsagi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trendsagi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trendsagi