Analysis ReferenceMarket Data Tools

Market Data Tools

Data provider tools wrap provider methods — yfinance for market data, SEC EDGAR for filings — for use in analysis pipelines and question-driven runs. They handle caching, validation, and error formatting automatically so the LLM always sees a consistent structured result.

Market data

get_market_quote

Current quote for an instrument: price, volume, market cap, P/E, 52-week range, and similar snapshot fields.

get_historical_market_data

Historical OHLCV data for a date range and interval. Returns a sorted list of MarketDataPoint objects. Used by regime detection tools and charting.

search_market_instruments

Search by symbol or display name. Returns matching instruments with exchange and type metadata. The same lookup as copinance market search.

get_options_chain

Options chain for an underlying: expiration dates, calls, puts, strike, last price, implied volatility, open interest, volume, and BSM Greeks when QuantLib is available. See Options & Greeks for how Greeks are computed.

Parameters: underlying_symbol (required); optional expiration_date (single YYYY-MM-DD), optional expiration_dates (array of YYYY-MM-DD)—when both are set they are merged and deduplicated. Omit both to use the provider default expiry. Optional option_side (call / put / all).

Response: One expiry returns the same chain object as before. Multiple expiries return multi_expiration: true, underlying_symbol, and expirations: an array of serialized chains (each filtered by option_side). The question-driven prompt includes a second example call with expiration_dates for agents.

get_options_positioning

Aggregate options surface / positioning metrics for an underlying in one JSON object: directional bias and probabilities, categorized signals (positioning, volatility, flow, gamma, structure), IV metrics (ATM IV, 25-delta skew, term-structure label), gamma regime, GEX profile, vanna / charm exposure summaries, mispricing vs BSM fair value, moneyness buckets, pin risk, max pain, implied move (ATM straddle / spot), and largest OI strikes. Implemented in copinance_os.data.analytics.options.positioning; results validate as OptionsPositioningResult (domain.models.options.positioning) with snake_case field names in tool output (model_dump(mode="json")).

Methodology is component-distributed:

  • Top-level methodology.specs is cross-cutting only (Greeks enrichment when present, aggregate bias, data quality).
  • signal_categories.<category>.methodology is colocated with that category’s signals.
  • Component objects such as iv_metrics, dollar_metrics, delta_exposure, vanna_exposure, charm_exposure, mispricing, moneyness_summary, pin_risk, and implied_move_detail include their own methodology.

No legacy compatibility response shape is emitted. Uncomputable components remain null/unavailable in output (no fallback synthesis).

Missing per-contract Greeks/OI/volume are treated as unavailable and skipped in aggregates; they are never coerced to synthetic zeroes.

If the selected positioning window has no contracts (for example, no usable expiry/contracts), the builder raises a domain ValidationError instead of returning a silent empty payload.

Narrative labels that accompany deterministic analysis surfaces are literacy-tiered through financial_literacy; clients should use stable numeric/enum fields for logic and treat text as presentation-level copy.

Parameters: symbol (required, underlying ticker); optional window: near (default) or mid — same horizon damping as the Library — Options positioning context helper.

Data: Fetches quote + full chain (get_options_chain with expiration_date=None) via the wired MarketDataProvider.

Fundamental data

get_equity_fundamentals

Comprehensive snapshot for an equity: financial ratios, income statement highlights, balance sheet summary, and key metrics from the configured fundamentals provider.

get_financial_statements

Income statement, balance sheet, or cash flow statement grid for a single symbol across annual or quarterly periods.

SEC / EDGAR tools

SEC tools are registered when a SEC-capable fundamentals provider is wired (see Configuration — SEC EDGAR). Without it, these tools are absent from the registry and question-driven runs will not attempt them.

get_sec_filings

Filing metadata for a symbol: form type, dates, accession number, CIK, filing URL. Use this to discover filings before fetching content.

get_sec_filing_content

Full body text or HTML for a specific filing (CIK + accession number). Large bodies are truncated; metadata indicates the cut point.

get_sec_company_edgar_profile

Entity metadata from EDGAR: name, CIK, SIC code, shares outstanding, public float. Useful for confirming the right issuer before other SEC lookups.

get_sec_company_facts_statement

Multi-period company facts for a single symbol (e.g. income, balance sheet, or cash flow across several annual or quarterly periods). Better suited to long history for one company than get_financial_statements.

get_sec_compare_financials_metrics

Standardized headline metrics (revenue, net income, etc.) across multiple tickers side-by-side.

get_sec_xbrl_statement_table

Primary financial statement table from the latest filing of a given form (e.g. 10-K) in XBRL-native presentation, with optional dimensional/segment rows.

get_sec_insider_form4

Recent Form 4 insider filings for an issuer: structured ownership summaries and capped transaction rows.

get_sec_13f_institutional_holdings

Latest 13F-HR portfolio for an institutional filer (manager CIK or ticker you specify): position tables and optional quarter-over-quarter comparison. Values are reported in thousands of dollars per SEC convention. Note: this returns one filer’s portfolio, not all institutions holding a given stock.

Using tools programmatically

Full question-driven registry (market + regime + macro + fundamentals + SEC when configured):

from copinance_os.core.pipeline.tools.discovery import collect_question_driven_tools
from copinance_os.domain.models.pipeline.tool_bundle_context import ToolBundleContext
from copinance_os.data.providers import YFinanceMarketProvider
 
ctx = ToolBundleContext(market_data_provider=YFinanceMarketProvider())
tools = collect_question_driven_tools(ctx)

Market + fundamentals preset (no regime or macro tools):

from copinance_os.core.pipeline.tools import build_data_provider_tool_registry
from copinance_os.data.providers import YFinanceMarketProvider
 
registry = build_data_provider_tool_registry(
    market_data_provider=YFinanceMarketProvider(),
    fundamental_data_provider=None,  # wire when you have fundamentals
)
tool = registry.get("get_market_quote")
result = await tool.execute(symbol="AAPL") if tool else None

Market tools only (no fundamentals):

from copinance_os.core.pipeline.tools.data_provider.registry import create_market_data_tools
from copinance_os.data.providers import YFinanceMarketProvider
 
tools = create_market_data_tools(YFinanceMarketProvider(), cache_manager=cache_manager)

See also

OverviewMacro & Market Regime