nlalpha-data 0.3.1

Data-access MCP server: provides market data access, coverage checks, quality evaluation, and trading calendar capabilities for strategy generation and backtesting, and publishes immutable data to other nlalpha services through the core DataArtifactStore.

Positioning

nlalpha-data runs as a standalone MCP server (SSE transport, port 8000) and serves as the data source of the nlalpha ecosystem:

• Publishes market data to DataArtifactStore through load_bars and returns a data_ref for nlalpha-backtest to read and run backtests.
• Provides data coverage checks and quality evaluation, helping strategy generation judge the usable data range.
• Provides trading calendar tools so strategy logic can reference trading-day information.

MCP tools

Tool	Description
list_data_providers	Lists all discovered data providers and the default provider.
check_data_coverage	Checks data coverage for the specified symbols, range, and interval.
get_data_quality	Returns a data quality evaluation (missing rate, outliers, and so on).
load_bars	Loads bar data, publishes it as an artifact, and returns a data_ref.
list_trading_calendars	Lists the supported trading calendars.
get_trading_days	Queries the trading-day sequence of the specified calendar.
is_trading_day	Determines whether a date is a trading day.
list_instruments	Lists instruments by asset class (stock/index/fund/future/cb/option).
get_trading_calendar	Reads the normalized exchange calendar (including session open/close and the previous trading day) from the selected data source.
get_daily_basic	Reads daily basic metrics for the specified instruments.
get_price_limits	Reads daily price-limit prices for the specified instruments.
get_suspensions	Reads daily suspension and resumption records for the specified instruments.
get_index_weights	Reads constituent weights of the specified index.
confess	Debugging: returns a summary of the service's own runtime configuration.

list_instruments, get_trading_calendar, get_daily_basic, get_price_limits, get_suspensions, and get_index_weights reuse the DataLoader provider selection rules, and source in their responses contains provider_id, the distribution package name, and the version. When the selected provider does not implement the corresponding method, the service returns an explicit data_error; it never silently switches sources or returns an empty result.

Provider selection and price-source evidence

load_bars, check_data_coverage, and get_data_quality share the same DataLoader and can name a source explicitly through provider_id. When none is given, they use NLALPHA_DATA_PROVIDER, or auto-select when exactly one provider is available; a request fails when several providers are available and no default is set. The service never switches sources automatically between providers. list_data_providers lists only available entries, while diagnose_providers reports providers that are installed but unavailable or failed to load. about surfaces each provider's manifest (including the capabilities summary), and confess(provider_id) returns the manifest plus optional sections of provider guidance.

price_adjustment can request unadjusted, forward, or backward. When a request explicitly requires an attribute, the selected provider must declare the same attribute for that symbol before loading; unknown or mismatched attributes fail the request explicitly and are never bypassed by switching sources. When no price attribute is requested, the source response still records unknown faithfully. Tushare supports unadjusted, forward, and backward for stock and ETF/fund daily bars, while continuous futures daily bars support only forward/backward; the adjustment baseline and anchor are defined by the selected provider's documentation, and the core layer defines no vendor-specific rules. Tushare provides daily bars for stocks, indices, and futures as well as ETF/funds, convertible bonds, and options (the latter three daily only); see its provider guidance for instrument identification, volume units, and adjustment declarations. The local file provider reports price attributes as unknown by default; the host can supply a JSON object through NLALPHA_LOCAL_PRICE_ADJUSTMENTS, for example {"600000.SH":"forward"}. That value is a host declaration, and the service never infers adjustment state from the price series.

source in responses is bound to the provider actually used for loading, and contains provider_id, the distribution package name, the version, price_adjustment, evidence, and cache_hit. Parquet metadata stores the same source contract under nlalpha.source.v1 with schema nlalpha.market.source.v1, and records the asset source per symbol. Cache directories are isolated by source fingerprint, and file names are generated from the exact query; writes use a temporary file in the same directory plus atomic replacement, with asynchronous reads and writes running on threads. A corrupted cache, or metadata that does not match the query or source, returns an explicit error and is never treated as a cache miss or silently overwritten.

DataArtifactStore and identity scope

load_bars publishes canonical Parquet bytes to the core DataArtifactStore and returns a data_ref along with the time contract. Each reference binds fixed content, schema, digest, size, creation and expiry times, and the request scope; repeated loads obtain a new reference and do not overwrite the old object. Storage access is held by the application instance created by create_app(), and lifespan starts and closes the store and the provider cache. /health indicates process liveness; /ready calls the health check of the selected backend after startup completes (Redis PING or S3 HeadBucket), and a failed check returns 503 not_ready.

The storage backend is selected explicitly by NLALPHA_ARTIFACT_BACKEND and defaults to redis; s3 uses an S3-compatible service, with MinIO optional. S3 does not depend on a Redis index. There is no default 10 MiB size limit; a payload is limited only when NLALPHA_ARTIFACT_MAX_BYTES is explicitly configured. Logical TTL is checked exactly per object; S3 bucket lifecycle physical cleanup runs asynchronously in whole days and is not guaranteed to delete in the same second as the logical expiry.

Setting	Default	Purpose
NLALPHA_ARTIFACT_BACKEND	redis	redis or s3
NLALPHA_ARTIFACT_REDIS_URL	redis://127.0.0.1:6379/0	Redis artifact backend
NLALPHA_ARTIFACT_TTL_SECONDS	86400	Logical TTL of a single reference
NLALPHA_ARTIFACT_MAX_BYTES	not set	Optional payload byte limit
NLALPHA_ARTIFACT_S3_BUCKET	required for S3	S3 bucket
NLALPHA_ARTIFACT_S3_ENDPOINT	not set	Optional S3/MinIO endpoint
NLALPHA_ARTIFACT_S3_ACCESS_KEY, NLALPHA_ARTIFACT_S3_SECRET_KEY	not set	Optional paired credentials
NLALPHA_ARTIFACT_S3_REGION	not set	Optional S3 region
NLALPHA_ARTIFACT_S3_RETENTION_DAYS	1	Bucket lifecycle retention in days; must cover the logical TTL

Before startup, S3 checks the bucket, that versioning is disabled, and the presence of a lifecycle rule covering the dedicated nlalpha/artifacts/v1/ prefix. Do not treat a lifecycle rule test as evidence that objects have actually been waited past expiry.

The identity scope is resolved by HostIdentityConfig into (environment, owner), and NLALPHA_ENV defaults to local and participates in isolation. NLALPHA_IDENTITY_MODE defaults to single-user: the owner is standalone, and requests that carry identity headers are rejected. Shared hosts should use trusted-host and configure NLALPHA_IDENTITY_USER_HEADER (default X-NLAlpha-User-ID); that header must be written and protected by an authenticated trusted gateway. NLAlpha only maps host identity and does not authenticate users itself.

DNS rebinding protection stays enabled. Allowed hosts are configured explicitly through create_app(allowed_hosts=...) or supplied by NLALPHA_ALLOWED_HOSTS; when unset, only localhost/loopback is allowed. The * wildcard host is not accepted.

Dependencies

Package	Relationship
nlalpha-core	DataArtifactStore (cross-service data handoff), telemetry (metrics/logs), platform (host identity mapping)
exchange-calendars	Underlying calendar library for the trading calendar tools (get_trading_days and others)
Data provider plugins	Discovered through entry points, such as local file, Parquet, and mock

Running

NLALPHA_ARTIFACT_BACKEND=redis \
NLALPHA_ARTIFACT_REDIS_URL=redis://127.0.0.1:6379/0 \
nlalpha-data

NLALPHA_HOST and NLALPHA_PORT default to 127.0.0.1 and 8000; python -m nlalpha_data.server is the equivalent module entry point.

Production or container deployments should explicitly select a network-reachable Redis or S3 endpoint and set the allowed hosts. S3 deployments also require bucket lifecycle rules to be configured in advance; MinIO is only an optional S3 implementation.

Source time contract

load_bars returns a time_contract summary alongside the data_ref. Canonical Parquet uses UTC open_time/close_time bounds at microsecond Bar precision and nlalpha.market.time.v1 metadata. Per-asset metadata retains original source timezones, source timestamp semantics, calendar IDs, and session-date availability. Consumers should use this declared contract rather than infer a zone or trading date from UTC values. Store/cache round trips preserve all Bar time fields; legacy caches fail with an actionable recreate/import error rather than being guessed or migrated destructively; Parquet files with naive timestamps or incomplete source contracts are rejected. Sub-microsecond Bar conversion is rejected.

The local provider accepts constructor time_contracts keyed by symbol or matching <symbol>.time.json sidecars (timezone, timestamp_semantics, optional calendar_id). Aware explicit bounds can be normalized without a source-zone guess. Naive timestamps need an explicit supported IANA timezone; a single timestamp column also needs open or close semantics and a valid interval. Date-only labels require a calendar ID and exact session bounds. Calendar lookup uses actual sessions and half-days for supported exchanges; unknown calendars fail. Futures need a symbol-specific accurate calendar supplied by the caller.

load_bars date filters are inclusive and prefer an actual session_date. If that label is absent, source_timestamp_semantics="open" selects the original open_time and close selects close_time; the selected instant is converted to its original source timezone or offset to obtain the local date. Filtering fails if neither a session label nor source timezone/offset is available, and never substitutes the UTC date.

Agent contract guidance

For Agent workflows, read the current data capability description before deciding which checks or data preparation are available. This README documents package behavior; the live capability description owns the callable contract. Report only coverage, quality, calendar, and time conclusions supported by the actual checks.

load_bars returns a data_ref, bar-count summary, and declared contracts; it does not return the bars or per-day observed session dates. A count cannot identify which sessions are missing. An exact missing-session count requires an authorized, currently callable artifact-reading capability that exposes the observed dates and an applicable instrument calendar; if either evidence source is unavailable, report the exact count as unknown.

The Arrow schema stores UTF-8 JSON time metadata under nlalpha.time_contract (schema: nlalpha.market.time.v1, canonical UTC bounds, precision, timezone database version, and per-asset source summaries). SQLite caches use exact integer nanosecond keys and separate open-time/metadata columns; legacy text-wallclock caches are rejected. A raw Bar may omit open time while stored internally, but a load_bars artifact must resolve both open and close bounds.

0.2.1 bar contract

Loaded bars and exported refs declare volume_unit and bar_contract. The data service places that metadata into new artifacts; its tool response includes both fields. New SQLite cache identity is bar_data_v2; Parquet uses the bar-contract-v2 namespace and schema metadata. Existing cache identities and refs are not overwritten or treated as the new contract. Reload old refs to obtain corrected unit metadata.

Focused verification

The parent-reviewed provider, Tushare, and backtest integration group passed 58 tests and 23 subtests, with 6 warnings, in 7.03 seconds. The run exercised the real local HTTP/Redis path with ordinary permissions. This is focused integration coverage, not a full workspace or release-gate result.

Canonical local provider guidance

Local CSV/Excel lookup, row and time metadata, host-declared price adjustment, availability, and cache identity are documented in local-provider.md. An available directory does not establish that the requested symbol has a file or data. The provider does not substitute another source. A future data.confess(provider_id="local") consumer reads this guide from the provider package; runtime integration remains pending.

Description and release metadata

The data service exposes about and provider-level confess descriptions from its cached provider manifests, declared methods, resources, and actual runtime distribution metadata. Descriptions follow nlalpha.description.v1; full and selected-section responses carry the same description_revision. Provider selection, source evidence, readiness, and artifact scope above describe runtime behavior; merely having an installed provider does not mean it is configured or available.

The 64 KiB limit applies to the artifact metadata protocol, not payload data. Payload limits are opt-in through NLALPHA_ARTIFACT_MAX_BYTES; with no configured limit there is no package-level 10 MiB cap. Concurrent materialization and deserialized object memory remain deployment budgeting responsibilities.

License

nlalpha-data is a community distribution under AGPL-3.0-or-later. This license scope does not include the platform integration, the adapter, private enhancement packages, or third-party dependencies.

Container images

The public Redis image installs the non-editable data-service wheel closure on Python 3.12 slim. The S3 image is a distinct build using ARTIFACT_BACKEND=s3; it adds the S3 client dependency while MinIO remains an external integration-test service. Platform integration images are assembled separately from the platform root and enhanced lock.