alphagbm-theme-research

AlphaGBM Theme Research

Group related tickers into named investment themes with an AI-generated summary and news keyword watchlist. Each theme is a lightweight basket you can track at the concept level.

When to use

• User wants to organize tickers by theme (AI infra, HK dividend, EV supply chain, biotech…)
• User asks to view a specific theme's holdings + latest summary
• User wants to add or remove tickers from a theme
• User wants the system to monitor news around a topic
• User mentions "主题" / "theme" / "basket" / "篮子" / "板块"

Prerequisites

• API Key: env ALPHAGBM_API_KEY (format agbm_xxxx…).
• Base URL: default https://alphagbm.zeabur.app. Override via ALPHAGBM_BASE_URL.
• Tier limits apply: Free tier is capped on themes — check_profile_limit mirrors the profile limit model. Check limits.max_themes via the dashboard endpoint.

API Endpoints

All endpoints require Authorization: Bearer $ALPHAGBM_API_KEY.

1. List themes

GET /api/research/themes

Response:

{
  "success": true,
  "themes": [
    {
      "id": 7,
      "theme_name": "AI Infrastructure",
      "description": "Picks & shovels for the AI capex cycle",
      "tickers": ["NVDA", "AVGO", "MSFT", "ORCL"],
      "news_keywords": ["AI capex", "data center", "hyperscaler"],
      "theme_summary": "Capex guidance up across 4 hyperscalers...",
      "last_updated_at": "2026-04-13T09:00:00Z"
    }
  ]
}

2. Get theme detail (aggregated)

GET /api/research/themes/<THEME_ID>

Returns the theme + aggregated data across its tickers (average price change, top movers, recent news matching keywords). 404 if not found or not owned.

3. Create theme

POST /api/research/themes
Content-Type: application/json

{
  "theme_name": "AI Infrastructure",
  "description": "Picks & shovels for AI capex",
  "tickers": ["NVDA", "AVGO", "MSFT"],
  "news_keywords": ["AI capex", "data center"]
}

4. Update theme (by id)

PUT /api/research/themes/<THEME_ID>
Content-Type: application/json

{"tickers": ["NVDA", "AVGO", "MSFT", "ORCL"], "news_keywords": [...]}

Partial update. Any of the fields from create are accepted.

5. Delete theme (by id)

DELETE /api/research/themes/<THEME_ID>

Hard-delete. Doesn't affect the underlying company profiles.

Response schema — theme

{
  id, theme_name, description,
  tickers,                  // array of ticker strings
  news_keywords,            // array of phrases for news matching
  theme_summary,            // AI-generated narrative (markdown)
  last_updated_at, created_at
}

Theme detail endpoint (GET /themes/<id>) additionally includes aggregated fields like top movers and recent matched news — the exact shape is service-side and stable for display, not for programmatic parsing.

Typical Workflow

1. User: "Create an AI infra theme with NVDA, AVGO, MSFT"
   → POST /api/research/themes
     {"theme_name": "AI Infrastructure", "tickers": ["NVDA","AVGO","MSFT"],
      "news_keywords": ["AI capex", "data center"]}
   → Confirm theme created; mention it'll start accumulating summary + news

2. User: "What themes do I have?"
   → GET /api/research/themes
   → Table: theme · ticker count · last updated · summary excerpt

3. User: "Add ORCL to my AI theme"
   → GET /api/research/themes (find id)
   → PUT /api/research/themes/<id> {"tickers": [... + "ORCL"]}

4. User: "What's happening in my HK dividend theme?"
   → GET /api/research/themes/<id>
   → Lead with theme_summary + aggregated movers + matched news

Output Formatting Tips

When presenting themes:

1. List view — theme name · ticker count · "updated Xd ago" · 1-sentence summary
2. Detail view — lead with theme_summary (AI narrative), then ticker grid with % change, then recent matched news
3. Keyword hygiene — if the user creates a theme with no news_keywords, prompt: "Want me to watch for any news phrases? E.g., 'AI capex', 'hyperscaler'"
4. Ticker overlap — when creating a new theme, check if tickers already exist in other themes; it's fine (tickers can be in multiple themes) but worth mentioning

Related Skills

• alphagbm-company-profile — Themes reference profiles; creating a theme with untracked tickers still works but they won't have profile data
• alphagbm-health-check — Flags orphan tickers that are in themes but no longer in any profile
• alphagbm-compare — Side-by-side comparison for tickers within a theme

---

Powered by AlphaGBM — Real-data options & research intelligence for traders and AI agents. 10K+ users.