> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Premium Finance Search Layer

> The targeted stock-news search layer that powers Premium Finance — how ticker queries are dispatched, ranked, and cached across upstream providers.

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](/docs/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.