Skip to content

event-trigger-guide.md

Latest commit

 

History

History
168 lines (128 loc) · 5.15 KB

event-trigger-guide.md

File metadata and controls

168 lines (128 loc) · 5.15 KB
Raw

Event Trigger API Guide

Overview

The /api/events/trigger endpoint allows you to manually trigger market events that will run the full analysis pipeline and generate personalized newsletters and content drafts.

Endpoint

POST /api/events/trigger

Query Parameters

Parameter Type Default Description
user_id string "demo-user" User ID for personalization. Use "all" to generate newsletters for all users in the database.
persona string "buffett" Investment persona: buffett, trump, burry, or all

Request Body

{
  "ticker": "NVDA",
  "event_type": "price_drop",
  "change_pct": 11.1,
  "timeframe": "2h",
  "threshold": -10.0,
  "price_at_trigger": 145.32
}

Body Parameters

Field Type Required Description
ticker string Yes Stock ticker symbol (e.g., "NVDA", "AAPL")
event_type string Yes Type of event: price_drop, price_spike, or volume_surge
change_pct float Yes Percentage change that triggered the event
timeframe string No Time window for the event (default: "2h")
threshold float No Threshold value (auto-calculated if not provided)
price_at_trigger float No Stock price at trigger time

Response

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Behavior

Newsletter Generation

The newsletter generation behavior depends on the user_id parameter:

1. Specific User ID (Default)

Generates newsletter only for the specified user.

curl -X POST "http://localhost:8000/api/events/trigger?user_id=demo-user&persona=buffett" \
    -H "Content-Type: application/json" \
    -d '{
      "ticker": "NVDA",
      "event_type": "price_drop",
      "change_pct": 11.1,
      "timeframe": "2h"
    }'

Result: Newsletter created for demo-user only.

2. Custom User ID

Generates newsletter only for that specific user.

curl -X POST "http://localhost:8000/api/events/trigger?user_id=28ccec92-6473-4af6-9e24-6d1f9768700b&persona=buffett" \
    -H "Content-Type: application/json" \
    -d '{
      "ticker": "NVDA",
      "event_type": "price_drop",
      "change_pct": 11.1,
      "timeframe": "2h"
    }'

Result: Newsletter created for user 28ccec92-6473-4af6-9e24-6d1f9768700b only.

3. All Users

Generates newsletters for all users in the database.

curl -X POST "http://localhost:8000/api/events/trigger?user_id=all&persona=buffett" \
    -H "Content-Type: application/json" \
    -d '{
      "ticker": "NVDA",
      "event_type": "price_drop",
      "change_pct": 11.1,
      "timeframe": "2h"
    }'

Result: Newsletters created for every user in the users table.

What Happens Behind the Scenes

  1. Market Event Creation: A record is created in the market_events table with status detected
  2. Status Update: Event status changes to processing
  3. Analysis Pipeline: The LangGraph analysis pipeline runs with 4 nodes:
    • Anomaly Detection: Validates the market event
    • News Correlation: Fetches and correlates relevant news
    • Behavioral Coaching: Generates personalized coaching advice
    • Content Generation: Creates social media content drafts
  4. Content Drafts: Platform-specific content saved to content_drafts table
  5. Newsletter Generation: Personalized newsletters saved to user_newsletters table (based on user_id parameter)
  6. Status Update: Event status changes to completed (or failed if error occurs)

WebSocket Events

The pipeline broadcasts real-time progress via WebSocket at ws://localhost:8000/ws:

  • analysis_started: Pipeline begins
  • node_started: Individual node begins processing
  • node_completed: Individual node finishes
  • analysis_complete: Full pipeline completes

Database Tables Updated

  • market_events: Event record and status
  • content_drafts: Social media content (Twitter, LinkedIn, etc.)
  • user_newsletters: Personalized newsletter entries

Notes

  • Newsletters are only generated if is_anomaly is true in the analysis result
  • The force_anomaly flag is set to true for manual triggers to ensure the pipeline runs
  • Content drafts are always saved, regardless of anomaly detection
  • The analysis is personalized based on the user_id parameter (affects coaching advice)
  • The pipeline runs asynchronously in the background

Error Handling

If the pipeline fails:

  • Event status is set to failed
  • Error details are stored in market_events.metadata.error
  • Check server logs for detailed stack traces

Querying Results

Get Event Details

curl "http://localhost:8000/api/events/{event_id}"

Returns event details plus linked content drafts and newsletters.

List All Events

curl "http://localhost:8000/api/events?limit=20&status=completed"

Query parameters:

  • status: Filter by status (detected, processing, completed, failed)
  • ticker: Filter by ticker symbol
  • limit: Max results (default: 20, max: 50)