📈 Topic Trend Aggregator

The Topic Trend Aggregator is the second-stage actor in the Content Blueprint AI pipeline. Its core function is to aggregate news articles from all upstream "News Intelligence" actors, use an LLM to identify and cluster emerging trends, and then enrich those trends with powerful, internally-calculated scores.

This actor calculates:

• Internal Trend Score: A unique score based on article Volume, Recency, and Source Diversity.
• Quick Sentiment: A fast, preliminary sentiment score (Positive, Negative, Neutral) for each trend.
• Entity Acceleration: Tracks how the mention frequency of key entities (like "BlackRock") is speeding up or slowing down over time.

This actor is stateful and resilient. It saves its progress automatically, allowing it to calculate acceleration and safely resume after a maintenance run.

🤖 Role in the "Content Blueprint AI" Pipeline

This actor is the central aggregation point and the second step in the pipeline:

1. News Intelligence Actors (14 actors, e.g., Health & Fitness Intelligence)
   • Job: 📰 Scrape raw articles.
2. Topic Trend Aggregator (This Actor)
   • Job: 🧠 Fetches articles, clusters them into trends, and calculates Impact Scores (Trend Score, Sentiment, Acceleration).
   • Output: A dataset of high-impact, scored trends.
3. Sentiment Compass
   • Job: 🔬 Receives the scored trends and performs a deep LLM analysis to find the content opportunity, angle, and risks.
4. Content Blueprint AI
   • Job: ✍️ Receives the final, enriched opportunity data and generates content briefs.

💰 Monetization

This actor is monetized using Apify's "Pay-per-event" model.

• Event Name: TREND_GENERATED
• What is charged: The actor charges one TREND_GENERATED event for each trend it successfully identifies and saves to the output dataset.

⚙️ Input Parameters

• 📥 Data Sources to Aggregate: A list of all the upstream News Intelligence actors to pull data from.
  • actorId: The Apify ID of the source actor (e.g., byseitz.agency/health-fitness-intelligence).
  • runId: (Optional) A specific runId to fetch from. If left blank, the actor will fetch the last successful run automatically.
• 📏 Max Articles per Source: The maximum number of articles to fetch from each data source (Default: 20).
• 📏 Maximum Clusters per Category: The maximum number of distinct trend clusters the LLM should extract per category (Default: 5).
• 🤖 LLM Model: The OpenAI model to use for analysis (Default: gpt-4o).
• 📦 LLM Article Batch Size: The number of articles to send to the LLM per category. The default is 500 (the maximum history) to ensure the highest quality analysis.
• 🧹 Fresh Start (Wipe Storage): If checked, the actor will wipe its internal memory (TREND_STATE) and its default output dataset before running. This is crucial for re-processing data.

📤 Output

The actor's output is a dataset of identified trends. Each item represents a single trend cluster and includes:

• cluster_topic: A concise name for the identified trend.
• internal_trend_score: The calculated score based on Volume, Recency, and Diversity.
• sentiment_score: A fast sentiment polarity score (-1.0 to 1.0).
• sentiment_label: "Positive", "Negative", or "Neutral".
• score_components: An object with the raw volume_score, recency_score, and diversity_score.
• articles_count: The number of articles in this cluster.
• articles: The specific array of article objects that make up this trend.
• mentioned_...: Arrays for people, organizations, etc. Each entity now includes trend_velocity_percent and trend_acceleration_percent.

🔄 How to Run a Full Pipeline Refresh

To clear all old data and re-process from the beginning:

1. Run News Actors: Run all 14 of your "News Intelligence" actors.
2. Run This Actor: Run the Topic Trend Aggregator with the 🧹 Fresh Start (Wipe Storage) box checked.
3. Run Compass: After the TTA finishes, run the Sentiment Compass actor, also with its 🧹 Fresh Start (Wipe Storage) box checked.