# Data Products Schema

This file is the machine-facing internal contract for the skill.
It is not the primary user-facing routing surface.

Use it to decide:

- which product to call
- which parameters are allowed
- which parameters are intentionally hidden
- what output shape to expect

Use [SKILL.md](../../SKILL.md) for high-level user intent routing first.
Use this file only after the intent has already been determined.

## Global Rules

### Market Scope

This skill only supports mainland China A-shares.

Out of scope:

- US stocks
- Hong Kong stocks
- cryptocurrencies
- futures
- forex
- any non-A-share asset

### Allowed Instrument Modes

Use exactly one:

- `instrument_name`
- `instrument_id + exchange_id`

Never mix both.
If the stock code is unknown, prefer `instrument_name`.
When using code mode, `exchange_id` must be `SSE` or `SZE`.

### Allowed Date Mode For Stock Products

Use:

- `target_date`
- optional `visual_days_len`

Do not use:

- `start_date`
- `end_date`

### Allowed Sector Inputs

For `resolve_sector` and `similar_sectors`, use:

- `query`

For `sector_constituents` and `sector_performance`, use exactly one:

- `sector_name`
- `sector_id`

Prefer direct `sector_name` first.
Treat `sector_id` as an internal identifier that should only be reused after the backend has already returned it.
Only call `resolve_sector` when the sector name is fuzzy, ambiguous, or direct sector lookup fails.
If the user gives a theme word such as `算力`, `机器人`, or `AI`, prefer `resolve_sector` before calling a sector detail product.

### Allowed Date Mode For News Products

Use:

- `target_date`
- optional `target_time`

### Hidden Parameters

These are intentionally hidden and should not be generated by the model:

- `start_date`
- `end_date`
- `is_realtime`
- `limit`
- `days`
- `periods`

### Product Families

- Stock data products:
  `instrument_profile`, `price_snapshot`, `bar_series`, `finance_context`, `finance_analysis_context`, `finance_report_status`, `finance_basic_indicators`, `finance_valuation_detail`, `finance_profit_forecast`, `finance_industry_rank`, `holder_context`, `chip_distribution`, `price_levels`, `instrument_concepts`, `money_flow`, `unusual_movement_context`
- Sector data products:
  `resolve_sector`, `similar_sectors`, `sector_constituents`, `sector_performance`
- News data products:
  `important_news`, `high_frequency_news`
- Analysis flow:
  `movement_analysis`

## Product Cards

### `instrument_profile`

Purpose:

- Resolve a stock name into `instrument_id + exchange_id`

Allowed input:

- `instrument_name`
  or
- `instrument_id + exchange_id`

Important notes:

- If the code is unknown, use `instrument_name`
- When using code mode, `exchange_id` must be `SSE` or `SZE`

Output keys:

- `instrument_id`
- `exchange_id`
- `instrument_name`

### `price_snapshot`

Purpose:

- Get current price status and target-date-to-latest performance summary

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `price_summary`

### `bar_series`

Purpose:

- Get a historical K-line window

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `bar_window`

### `finance_context`

Purpose:

- Get finance, valuation, and related report context

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `finance`

### `finance_analysis_context`

Purpose:

- Get the prompt-ready backend bundle for finance-report analysis

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `request`
- `finance_analysis_meta`
- `financial_data_text`

### `finance_report_status`

Purpose:

- Get a structured report-publication timeline and latest full-report availability

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `finance_report_status`

### `finance_basic_indicators`

Purpose:

- Get structured quarterly financial indicators, single-quarter slices, growth, and profit-model context

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `finance_basic_indicators`

### `finance_valuation_detail`

Purpose:

- Get detailed valuation percentiles, model-derived fair-value context, and valuation tips

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `finance_valuation_detail`

### `finance_profit_forecast`

Purpose:

- Get latest analyst forecast, coverage, and recent-report context for one stock

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `finance_profit_forecast`

### `finance_industry_rank`

Purpose:

- Get industry percentile context and composite scoring for one stock

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `finance_industry_rank`

### `holder_context`

Purpose:

- Get holder-change context

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `holders`

### `chip_distribution`

Purpose:

- Get chip-peak / chip-distribution data

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `chip_distribution`

Important notes:

- This is based on the `chip-peak` path
- Server-side default display window is approximately `120` bars unless overridden
- This payload is relatively heavy; prefer a lighter product unless chip distribution itself is the question

### `price_levels`

Purpose:

- Get key resistance-level signals

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `price_levels`

Important notes:

- This is based on the `chip-concentration` path
- Server-side default detection window is approximately `250` trading days unless overridden

### `instrument_concepts`

Purpose:

- Get concept-board tags for one stock

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `instrument_concepts`

### `money_flow`

Purpose:

- Get recent money-flow summary and recent records for one stock

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `money_flow`

### `unusual_movement_context`

Purpose:

- Get the deterministic no-image unusual-movement context bundle

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Output keys:

- `instrument`
- `request`
- `recent_trading_days_list`
- `recent_prices_list`
- `price_window_summary`
- `price_levels`
- `level_summary`
- `market_technical_status`
- `origin_input`
- `historical_reports`
- `unusual_movements`

Important notes:

- This is a heavy context bundle intended for movement-analysis preparation
- Do not use it when the user only needs one raw data product

### `resolve_sector`

Purpose:

- Resolve a sector / concept / theme query into one best match plus candidate list

Allowed input:

- `query`

Output keys:

- `query`
- `best_match`
- `matches`

Important notes:

- Use this only as a resolver fallback, not as the default first hop for every sector query
- The returned `sector_id` is an internal identifier for follow-up calls
- This is the preferred first hop for fuzzy theme words such as `算力`

### `similar_sectors`

Purpose:

- Resolve a fuzzy sector / concept / theme query into deterministic candidate sectors

Allowed input:

- `query`

Output keys:

- `query`
- `matches`

Important notes:

- Use this when the sector name is fuzzy or ambiguous
- The returned `sector_id` is an internal identifier for follow-up calls
- Prefer `resolve_sector` when you want one best match; use `similar_sectors` when you need multiple deterministic candidates

### `sector_constituents`

Purpose:

- Get the constituents of one resolved sector

Allowed input:

- `sector_name`
  or
- `sector_id`
- `target_date`

Important notes:

- Prefer `sector_name`
- Only use `sector_id` when it was already returned by a previous backend call

Optional input:

- `visual_days_len`

Output keys:

- `sector`
- `request`
- `summary`
- `constituents`

### `sector_performance`

Purpose:

- Get aggregated performance, valuation median, money-flow summary, and leader list for one resolved sector

Allowed input:

- `sector_name`
  or
- `sector_id`
- `target_date`

Important notes:

- Prefer `sector_name`
- Only use `sector_id` when it was already returned by a previous backend call

Optional input:

- `visual_days_len`

Output keys:

- `sector`
- `request`
- `summary`
- `returns`
- `leaders`

### `important_news`

Purpose:

- Get the important-news batch for a date

Allowed input:

- `target_date`

Output keys:

- `end_at_index`
- `data`

Important notes:

- Do not send stock instrument parameters
- Do not send `limit`

### `high_frequency_news`

Purpose:

- Get intraday high-frequency news for a date and optional cutoff time

Allowed input:

- `target_date`

Optional input:

- `target_time` in `HH:MM:SS`

Output keys:

- `target_date`
- `target_time`
- `cursor_datetime`
- `count`
- `data`

Important notes:

- The returned `data` keeps raw `datetime`
- This is the minute/second-granularity news product
- Do not send stock instrument parameters
- Do not send `limit`

### `movement_analysis`

Purpose:

- Build the final unusual-movement prompt package on top of `unusual_movement_context`

Allowed input:

- stock instrument mode
- `target_date`

Optional input:

- `visual_days_len`

Default behavior:

- local default `visual_days_len = 100` if omitted
- `is_realtime = true`
- historical reports are empty in v1
- chart image is not used in v1

Output keys:

- `flow`
- `instrument`
- `request`
- `price_summary`
- `price_levels`
- `level_summary`
- `origin_input`
- `unusual_movements`
- `trading_days`
- `prompt_package.system_prompt`
- `prompt_package.user_prompt`

Important notes:

- This is a flow, not a raw data product
- It internally uses fixed deterministic products
- Do not use it for simple data fetching; prefer the narrower raw-data products first