API reference¶

Data client¶

class fincore.data.DataClient(market='US')¶

Client for market data discovery, historical fetches, and simple streams.

Parameters:: market (str | Iterable[str])

fetch_bars(symbol, start, end, *, interval='1d', source=None)¶

Fetch OHLCV bars for a stock or ETF over a date/time range.

Parameters:

symbol (str) – Symbol or fuzzy instrument name.
start (str) – Inclusive start date.
end (str) – Inclusive end date.
interval (str) – Yahoo Finance interval such as "1m", "5m", "1h", or "1d".
source (YahooFinanceSource | None) – Optional Yahoo Finance source descriptor.

Returns:

Normalized daily bar dictionaries.

Return type:

list[dict[str, Any]]

fetch_bond_yields(series_id, start=None, end=None, source=None)¶

Fetch a public Treasury yield time series from FRED.

Parameters:

series_id (str) – FRED series ID or fuzzy bond maturity/name query.
start (str | None) – Optional inclusive start date.
end (str | None) – Optional inclusive end date.
source (FredBondSource | None) – Optional FRED source descriptor.

Returns:

Normalized observation dictionaries.

Return type:

list[dict[str, Any]]

list_bonds()¶

Return supported public bond yield series.

Returns:: Bond/yield series dictionaries.
Return type:: list[dict[str, Any]]

list_etfs()¶

Return available ETF symbols.

Returns:: ETF instrument dictionaries.
Return type:: list[dict[str, Any]]

list_instruments(asset_types=None, markets=None)¶

Return available market instruments from free source directories.

Stocks and ETFs are sourced from Nasdaq Trader, ASX, and NSE directories. Bonds are represented as FRED Treasury yield series.

Parameters:

asset_types (Iterable[AssetType] | None) – Optional asset classes to include.
markets (str | Iterable[str] | None) – Optional market override. Defaults to the client context.

Returns:

Matching instrument dictionaries.

Return type:

list[dict[str, Any]]

list_stocks()¶

Return available stock symbols.

Returns:: Stock instrument dictionaries.
Return type:: list[dict[str, Any]]

refresh_instruments()¶

Refresh and return the locally cached source instrument directory.

Returns:: Fresh instrument directory.
Return type:: list[dict[str, Any]]

async replay_bars(symbol, start, end, *, interval='1d', interval_seconds=0.0)¶

Replay historical bars as an async stream.

Parameters:

symbol (str) – Symbol or fuzzy instrument name.
start (str) – Inclusive start date.
end (str) – Inclusive end date.
interval (str) – Yahoo Finance interval.
interval_seconds (float) – Optional delay between replayed events.

Yields:

Stream event envelopes.

Return type:

AsyncIterator[dict[str, Any]]

resolve_instrument(query, *, asset_types=None, markets=None, min_score=0.65)¶

Resolve a symbol or fuzzy company/fund name to one instrument.

Parameters:

query (str) – Symbol, company name, ETF name, or bond maturity query.
asset_types (Iterable[AssetType] | None) – Optional asset classes to search.
markets (str | Iterable[str] | None) – Optional market override. Defaults to the client context.
min_score (float) – Minimum fuzzy score required for automatic resolution.

Returns:

Best instrument match with alternatives.

Return type:

dict[str, Any]

Raises:

ValueError – If no confident match is found.

resolve_symbol(query, *, asset_types=None, markets=None, min_score=0.65)¶

Resolve a human query to the canonical source symbol.

Parameters:

query (str) – Symbol, name, or maturity query.
asset_types (Iterable[AssetType] | None) – Optional asset classes to search.
markets (str | Iterable[str] | None) – Optional market override. Defaults to the client context.
min_score (float) – Minimum fuzzy score required for automatic resolution.

Returns:

Canonical source symbol.

Return type:

str

search_instruments(query, *, asset_types=None, markets=None, limit=10)¶

Return the closest symbol/name matches for a human query.

Parameters:

query (str) – Symbol, company name, ETF name, or bond maturity query.
asset_types (Iterable[AssetType] | None) – Optional asset classes to search.
markets (str | Iterable[str] | None) – Optional market override. Defaults to the client context.
limit (int) – Maximum number of matches to return.

Returns:

Matched instruments enriched with score and reason.

Return type:

list[dict[str, Any]]

Raises:

ValueError – If limit is not positive.

async stream_bars(symbols, *, interval='1m', lookback='1d', poll_seconds=30.0)¶

Poll latest delayed bars and expose unseen bars as an async stream.

Free sources generally do not provide reliable real-time stock streams. This method intentionally models current data as polling of delayed bars over a recent lookback range.

Parameters:

symbols (Iterable[str]) – Symbols or fuzzy instrument names to poll.
interval (str) – Yahoo Finance interval.
lookback (str) – Recent range to request each poll, such as "1d" or "6h".
poll_seconds (float) – Delay between polling rounds.

Yields:

Stream event envelopes.

Return type:

AsyncIterator[dict[str, Any]]

Raises:

ValueError – If poll_seconds is not positive.

async stream_current_bars(symbols, *, interval='1m', lookback='1d', poll_seconds=30.0)¶

Poll latest delayed bars and expose unseen bars as an async stream.

Free sources generally do not provide reliable real-time stock streams. This method intentionally models current data as polling of delayed bars over a recent lookback range.

Parameters:

symbols (Iterable[str]) – Symbols or fuzzy instrument names to poll.
interval (str) – Yahoo Finance interval.
lookback (str) – Recent range to request each poll, such as "1d" or "6h".
poll_seconds (float) – Delay between polling rounds.

Yields:

Stream event envelopes.

Return type:

AsyncIterator[dict[str, Any]]

Raises:

ValueError – If poll_seconds is not positive.

Market constants¶

fincore.data.SUPPORTED_MARKETS = {'AU', 'IN', 'US'}¶: Build an unordered collection of unique elements.

fincore.data.SUPPORTED_INTERVALS = {'15m', '1d', '1h', '1m', '1mo', '1wk', '2m', '30m', '3mo', '5d', '5m', '60m', '90m'}¶: Build an unordered collection of unique elements.

Sources¶

class fincore.data.YahooFinanceSource(name='yahoo')¶

Free delayed daily market data source for US stocks and ETFs.

Variables:: name (str) – Source adapter name.
Parameters:: name (str)

class fincore.data.FredBondSource(name='fred')¶

Free public FRED CSV source for US Treasury yield series.

Variables:: name (str) – Source adapter name.
Parameters:: name (str)

Utilities¶

Utility helpers for date normalization and instrument fuzzy matching.

fincore.data.utils.coerce_date(value)¶

Normalize common date inputs into ISO YYYY-MM-DD text.

Parameters:: value (Any) – Date-like value supplied by the Python user.
Returns:: ISO date string in YYYY-MM-DD format.
Return type:: str
Raises:: ValueError – If the value cannot be interpreted as a date.

fincore.data.utils.coerce_datetime(value, *, end_of_day=False)¶

Normalize common date/datetime inputs into UTC datetimes.

Parameters:

value (Any) – Date-like or datetime-like value.
end_of_day (bool) – Whether date-only inputs should map to 23:59:59.

Returns:

Timezone-aware UTC datetime.

Return type:

datetime

Raises:

ValueError – If the value cannot be interpreted as a date or datetime.

fincore.data.utils.coerce_yahoo_period(start, end, interval)¶

Normalize a user range into Yahoo period timestamps and interval.

Parameters:

start (Any) – Inclusive range start.
end (Any) – Inclusive range end.
interval (str) – User interval.

Returns:

period1, period2, and normalized interval.

Return type:

tuple[int, int, str]

Raises:

ValueError – If the range or interval is invalid.

fincore.data.utils.lookback_start(lookback, *, end=None)¶

Calculate a UTC start datetime from a compact lookback expression.

Parameters:

lookback (str) – Expression such as "1d", "6h", or "30m".
end (datetime | None) – Optional UTC end datetime. Defaults to now.

Returns:

Start datetime.

Return type:

datetime

fincore.data.utils.normalize_interval(interval)¶

Normalize a user interval into Yahoo Finance’s chart interval values.

Parameters:: interval (str) – User interval such as "5m", "1hour", or "day".
Returns:: Yahoo-compatible interval.
Return type:: str
Raises:: ValueError – If the interval is unsupported.

fincore.data.utils.normalize_market(market)¶

Normalize a market/country context.

Parameters:: market (str) – Market code or country-like value such as "US" or "Australia".
Returns:: Canonical market code.
Return type:: str
Raises:: ValueError – If the market is unsupported.

fincore.data.utils.normalize_markets(markets)¶

Normalize one or more market contexts.

Parameters:: markets (Any) – Single market, iterable of markets, or "all".
Returns:: Canonical market code set.
Return type:: set[str]

fincore.data.utils.normalize_search_text(value)¶

Normalize a symbol or instrument name for fuzzy matching.

Parameters:: value (str) – Raw user query or instrument field.
Returns:: Lowercase token string with noisy finance/legal words removed.
Return type:: str

fincore.data.utils.score_instrument(query, instrument)¶

Score an instrument against a normalized human query.

Parameters:

query (str) – Normalized user query from normalize_search_text().
instrument (dict[str, Any]) – Instrument dictionary returned by the Rust core.

Returns:

Match score and reason.

Return type:

tuple[float, str]

fincore.data.utils.validate_interval_range(start, end, interval)¶

Validate Yahoo’s approximate retention limits for intraday intervals.

Parameters:

start (datetime) – UTC start datetime.
end (datetime) – UTC end datetime.
interval (str) – Normalized Yahoo interval.

Returns:

None.

Return type:

None

Raises:

ValueError – If the requested range is too large for the interval.

Events¶

Normalized stream event envelopes for downstream sinks.

fincore.data.events.bar_event(bar, *, stream_type)¶

Wrap a normalized bar row in a stream event envelope.

Parameters:

bar (dict[str, Any]) – Normalized bar dictionary returned by the Rust core.
stream_type (str) – Stream producer type, such as "historical_replay".

Returns:

Timescale/Kafka-friendly event envelope.

Return type:

dict[str, Any]

fincore.data.events.bond_yield_event(observation, *, stream_type)¶

Wrap a normalized bond-yield observation in a stream event envelope.

Parameters:

observation (dict[str, Any]) – Normalized observation dictionary returned by the Rust core.
stream_type (str) – Stream producer type.

Returns:

Timescale/Kafka-friendly event envelope.

Return type:

dict[str, Any]

Kafka¶

Optional Kafka sink for fincore data streams.

class fincore.data.kafka.KafkaSink(bootstrap_servers, topic, **producer_kwargs)¶

Publish normalized fincore stream events to Kafka.

aiokafka is imported lazily so Kafka remains an optional dependency.

Parameters:

bootstrap_servers (str) – Kafka bootstrap server string.
topic (str) – Kafka topic to publish to.
producer_kwargs (Any) – Additional keyword arguments passed to AIOKafkaProducer.

async publish_event(event)¶

Publish one event envelope to Kafka.

Parameters:: event (dict[str, Any]) – Event envelope.
Returns:: None.
Return type:: None
Raises:: RuntimeError – If aiokafka is not installed.

async publish_stream(events)¶

Publish every event from an async stream to Kafka.

Parameters:: events (AsyncIterable[dict[str, Any]]) – Async iterable of event envelopes.
Returns:: Number of published events.
Return type:: int
Raises:: RuntimeError – If aiokafka is not installed.

Analytics¶

class fincore.analytics.MetricEngine(metrics=None, *, max_window=None, field_map=None)¶

Compute normalized metric events from bars or bar stream events.

Parameters:

metrics (Iterable[str | dict[str, Any] | MetricSpec] | None)
max_window (int | None)
field_map (Mapping[str, str] | None)

compute(records, metrics=None, *, field_map=None)¶

Compute metric events for a finite batch of records.

Parameters:

records (Iterable[Mapping[str, Any]]) – Bar rows, stream envelopes, or external source mappings.
metrics (Iterable[str | dict[str, Any] | MetricSpec] | None) – Optional metric override.
field_map (Mapping[str, str] | None) – Optional external-source field map override.

Returns:

Normalized metric events.

Return type:

list[dict[str, Any]]

async run(records, metrics=None)¶

Yield metric events from an async stream of market records.

Parameters:

records (Any) – Async iterable of bar rows or stream envelopes.
metrics (Iterable[str | dict[str, Any] | MetricSpec] | None) – Optional metric override.

Yields:

Metric event dictionaries.

Return type:

AsyncIterator[dict[str, Any]]

update(record, metrics=None, *, field_map=None)¶

Update streaming state with one record and emit newly available metrics.

Parameters:

record (Mapping[str, Any]) – Bar row or bar stream envelope.
metrics (Iterable[str | dict[str, Any] | MetricSpec] | None) – Optional metric override.
field_map (Mapping[str, str] | None) – Optional external-source field map override.

Returns:

New metric events for this update.

Return type:

list[dict[str, Any]]

class fincore.analytics.MetricSpec(name, window=1, input_field='close', output_name=None)¶

Describe one metric calculation.

Parameters:

name (str) – Registered metric name, such as "return.simple".
window (int) – Rolling window size in bars.
input_field (str) – Numeric input field. "close" is currently supported by the Rust core.
output_name (str | None) – Optional emitted metric name override.

classmethod from_value(value)¶

Normalize a user metric value into a MetricSpec.

Parameters:: value (str | dict[str, Any] | MetricSpec) – Metric name, spec dictionary, or existing MetricSpec.
Returns:: Normalized metric specification.
Return type:: MetricSpec

to_rust()¶

Return the dictionary shape consumed by the Rust core.

Returns:: Rust-compatible metric spec dictionary.
Return type:: dict[str, Any]

fincore.analytics.normalize_bar(record, *, field_map=None)¶

Normalize a bar row, stream event, or DB-style mapping for analytics.

Parameters:

record (Mapping[str, Any]) – Bar dictionary, stream envelope, or external source row.
field_map (Mapping[str, str] | None) – Optional mapping from normalized names to source names.

Returns:

Normalized bar dictionary for the Rust metric core.

Return type:

dict[str, Any]

Raises:

ValueError – If required fields are missing.