---
title: "Premium Finance Search Layer"
description: "This document covers the extra targeted stock-news search layer used by premium finance."
---
This document covers the **extra** targeted stock-news search layer used by premium finance.

It is separate from the core premium-finance architecture on purpose.

Core premium finance can still function without this layer. The search layer exists to improve stock-news discovery quality for targeted ticker analysis, especially where feed-only coverage is weak.

See the core system document in [PREMIUM_FINANCE.md](/premium-finance).

---

## Why This Exists

World Monitor is mostly feed-first:

- curated RSS feeds
- digest aggregation
- Google News RSS fallbacks

The source repo being migrated from uses a broader search-provider layer for stock-specific news lookup. That produces better targeted coverage for:

- single-symbol premium analysis
- less prominent tickers
- recent company-specific developments not well represented in the feed inventory

This layer closes that gap without replacing the project's broader feed architecture.

---

## Provider Order

The current provider chain is:

1. `Tavily`
2. `Brave`
3. `SerpAPI`
4. Google News RSS fallback

`Bocha` was intentionally not added because the current premium-finance direction is not China-focused.

---

## Implementation

Primary implementation:

- [stock-news-search.ts](https://github.com/koala73/worldmonitor/blob/main/server/worldmonitor/market/v1/stock-news-search.ts)

Integration point:

- [analyze-stock.ts](https://github.com/koala73/worldmonitor/blob/main/server/worldmonitor/market/v1/analyze-stock.ts)

The helper:

- builds a normalized stock-news query
- tries providers in priority order
- rotates across configured keys
- tracks temporary provider/key failures in memory
- normalizes provider responses into `StockAnalysisHeadline`
- caches search results in Redis
- falls back to Google News RSS when provider-backed search is unavailable

---

## Query Strategy

The current query shape intentionally mirrors the stock-news style from the source repo for foreign equities:

`<Company Name> <SYMBOL> stock latest news`

Examples:

- `Apple AAPL stock latest news`
- `Microsoft MSFT stock latest news`

Search freshness is dynamic:

- Monday: 3 days
- Saturday/Sunday: 2 days
- Tuesday-Friday: 1 day

That mirrors the idea that weekend gaps need a wider lookback than midweek trading days.

---

## Runtime Secrets

The search layer uses runtime-managed secret keys so it fits the same desktop/web secret model as the rest of the project.

Configured keys:

- `TAVILY_API_KEYS`
- `BRAVE_API_KEYS`
- `SERPAPI_API_KEYS`

These are wired through:

- [runtime-config.ts](https://github.com/koala73/worldmonitor/blob/main/src/services/runtime-config.ts)
- [settings-constants.ts](https://github.com/koala73/worldmonitor/blob/main/src/services/settings-constants.ts)
- [main.rs](https://github.com/koala73/worldmonitor/blob/main/src-tauri/src/main.rs)
- [local-api-server.mjs](https://github.com/koala73/worldmonitor/blob/main/src-tauri/sidecar/local-api-server.mjs)

The values are multi-key strings, split on commas or newlines.

---

## Caching

Search results are cached in Redis under a query-derived key. The cache key includes:

- symbol
- dynamic day window
- result limit
- hashed query

This avoids repeated provider calls when multiple users request the same premium stock analysis.

The cache is intentionally short-lived because search-backed finance news gets stale quickly.

---

## Fallback Behavior

If `Tavily` fails, the system tries `Brave`.

If `Brave` fails, the system tries `SerpAPI`.

If provider-backed search is unavailable, empty, or unconfigured, the system falls back to Google News RSS.

That means:

- premium stock analysis does not hard-depend on paid search providers
- provider keys improve coverage, not feature availability

---

## Why This Is A Separate Layer

This layer is not the stock-analysis engine itself.

It should be treated as:

- targeted news enrichment
- a coverage-quality upgrade
- a provider-backed precision lookup layer

It should **not** be treated as:

- the canonical market/news ingestion architecture
- a replacement for feed digest aggregation
- the source of truth for premium finance persistence

That separation matters because it keeps the premium finance feature understandable:

- core finance product logic stays stable
- search-backed enrichment can evolve independently

---

## Known Boundaries

The current implementation does not yet expose a standalone public stock-news search RPC.

Right now it is an internal backend helper used by premium stock analysis. That is deliberate:

- it keeps the surface area small
- it avoids adding a premature UI/API product surface
- it allows provider behavior to evolve before being frozen into a dedicated external contract

If needed later, this helper can be promoted into a first-class market RPC.
