a-share-runtime-data-access

# A-share Runtime Data Access Use this skill when the user asks for A-share local data retrieval, quote lookup, financial period lookup, valuation context building, technical indicator lookup, or schema inspection through the project's public runtime interfaces and local tools. ## Scope - Only handle A-share data in this workflow. - Do not switch to multi-market logic unless the user explicitly changes scope. - Prefer the project's public runtime interfaces over direct database access. ## First Read Before fetching data, read these documents in order: 1. `docs/design/runtime-interfaces/skill-runtime-overview.md` 2. `docs/design/runtime-interfaces/local-data-access-design.md` 3. `docs/design/runtime-interfaces/project-access-and-governance.md` If you need concrete function signatures or allowed collections, then read: 1. `core/skill_runtime/data_access.py` 2. `core/skill_runtime/project_access.py` 3. `core/skill_runtime/catalog.py` ## Runtime Rules - Prefer `core.skill_runtime.data_access` for business-semantic data access. - Use `core.skill_runtime.project_access` only when helper functions are insufficient or when inspecting schema / field coverage. - Do not create `MongoClient` or import `pymongo` directly. - Do not bypass `core.skill_runtime` by reading lower-level provider or database modules unless the user explicitly asks for code archaeology. - For technical analysis, prefer the project's local technical tools and materialized snapshots over ad hoc indicator calculation. ## Preferred Helpers For common A-share tasks, prefer these helpers first: 1. `get_stock_basic_info(symbol)` 2. `get_market_quotes(symbol)` 3. `get_latest_stock_price(symbol)` 4. `get_stock_daily_quotes(symbol, start_date, end_date)` 5. `get_stock_financial_periods(symbol)` 6. `get_stock_financial_data(symbol)` 7. `get_stock_valuation_context(symbol)` 8. `get_stock_news(symbol)` 9. `query_stock_collection(collection, ...)` 10. `inspect_stock_collection_schema(collection, ...)` For technical-analysis tasks, prefer these entry points first: 1. `core.tools.implementations.market.technical_factor_bundle_tool.get_technical_factor_bundle_tool` 2. `core.tools.implementations.market.technical_indicators.get_technical_indicators` Use the factor bundle first when the user needs structured MA20, RSI14, KDJ, or MACD values. Use `get_technical_indicators` only when the user wants a readable technical-analysis report rather than a structured factor payload. When checking freshness or explaining discrepancies, inspect these components in order: 1. `stock_technical_indicators` latest `trade_date` 2. `market_quotes` latest `trade_date` 3. `app/services/technical_indicator_materialization_service.py` 4. `app/main.py` technical indicator materialization job configuration ## How To Execute In Embedded Nanobot The embedded nanobot runtime does not expose `core.skill_runtime` as a first-class tool yet. When you need actual data, do this: 1. Read the design docs and target runtime module. 2. If the goal is only validation, inspection, or one-time probing, write a short temporary Python script under `temp/`. 3. Run the script with `C:\TradingAgentsCN\env\Scripts\python.exe` using the `exec` tool. 4. Summarize the returned data clearly for the user. Do not treat a `temp/*.py` script as the final artifact when the logic is clearly reusable. If the requested logic is parameterizable and should work for other stocks or other future runs, use the temp script only as a short validation probe and then promote the implementation into a reusable skill. For technical-analysis tasks in embedded nanobot, use this execution pattern: 1. If the user wants structured technical values, call `get_technical_factor_bundle_tool` from a temp script. 2. If the user wants a textual technical interpretation, call `get_technical_indicators` from a temp script. 3. If the tool result conflicts with price data, compare `stock_technical_indicators.trade_date` against `market_quotes.trade_date` before concluding there is a bug. For embedded runtime work, apply this boundary: 1. use temp scripts for fast verification and data access that the runtime does not yet expose directly 2. if the output is becoming a named reusable capability, convert it into a skill instead of leaving it in `temp/` 3. if the task is still exploratory and the reusable shape is not yet confirmed, say that explicitly ## Windows Execution Rule On Windows, do not rely on inline `python -c` snippets for runtime verification. Prefer writing a temporary `.py` file and then executing it. This avoids quoting and shell-expansion issues. ## Minimal Script Pattern ```python from pathlib import Path import sys repo = Path(r"C:\TradingAgentsCN") sys.path.insert(0, str(repo)) from core.skill_runtime.data_access import get_stock_basic_info data = get_stock_basic_info("600519") print(data) ``` ## Helper Selection Guide - If the user asks for one stock's snapshot, start with `get_stock_basic_info` or `get_stock_valuation_context`. - If the user asks for multi-period fundamentals, start with `get_stock_financial_periods`. - If the user asks for technical indicators, start with `get_technical_factor_bundle_tool`. - If the user asks for a prose-style technical reading, use `get_technical_indicators` after confirming the requested date range. - If the user asks for local collection availability or fields, start with `inspect_stock_collection_schema`. - If the user asks for a direct collection sample, use `query_stock_collection` only after confirming the collection is publicly exposed in `catalog.py`. ## Response Expectations - State which runtime interface you used. - If data is empty, state whether the helper returned no records or the collection/helper is not exposed. - When validation fails, report whether the problem is instruction gap, interface usage error, or missing underlying data.