nlalpha-data 0.3.0__py3-none-any.whl

nlalpha_data/store.py

@@ -0,0 +1,316 @@
+"""Bar data storage abstraction layer.
+
+BaseBarStore provides a unified interface for persisting and retrieving
+Bar data, regardless of the underlying storage backend (parquet, SQLite,
+PostgreSQL, ClickHouse, etc.).
+
+The storage layer is part of the core infrastructure, while specific
+backends can be plugged in via assembly profile or environment variables.
+
+Example:
+    store = ParquetBarStore(cache_dir="workspace/cache")
+    await store.save(bars)
+    bars = await store.load("AAPL", "1d", "2023-01-01", "2023-12-31")
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+import json
+from hashlib import sha256
+import math
+import re
+from numbers import Real
+
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.contracts.market_source import (
+    BAR_CONTRACT, BAR_CONTRACT_KEY, BAR_CONTRACT_VERSION, SOURCE_KEY, read_source_contract,
+)
+from nlalpha.core.contracts.time import get_timezone, normalize_utc, timezone_metadata
+from nlalpha.core.errors import DataError
+
+BAR_CACHE_SCHEMA_VERSION = BAR_CONTRACT_VERSION
+BAR_CACHE_NAMESPACE = f"bar-contract-v{BAR_CACHE_SCHEMA_VERSION}"
+
+
+@dataclass
+class BarOverview:
+    """Overview of bar data stored in a specific store.
+
+    Mirrors vnpy's BarOverview concept but uses our internal naming.
+    """
+
+    symbol: str
+    interval: str
+    count: int = 0
+    start: datetime | None = None
+    end: datetime | None = None
+
+
+class BaseBarStore(ABC):
+    """Abstract bar data storage backend.
+
+    All storage implementations (Parquet, SQLite, PostgreSQL, etc.)
+    must inherit from this class and implement the abstract methods.
+
+    Design principles:
+    - save() is idempotent-ish: writing the same bars twice should not
+      corrupt data (backend-specific deduplication recommended).
+    - load() must return bars sorted ascending by datetime.
+    - load() filters by the exact [start, end] date range.
+    """
+
+    @abstractmethod
+    async def save(
+        self,
+        bars: list[Bar],
+        symbol: str = "",
+        interval: str = "",
+        start: str = "",
+        end: str = "",
+    ) -> int:
+        """Persist a list of Bar objects.
+
+        Args:
+            bars: List of Bar instances to save.
+            symbol: Instrument code (used as storage key).
+            interval: Bar interval (used as storage key).
+            start: Requested start date (used as storage key).
+            end: Requested end date (used as storage key).
+
+        Returns:
+            Number of bars actually persisted (after deduplication).
+        """
+        ...
+
+    @abstractmethod
+    async def load(
+        self,
+        symbol: str,
+        interval: str,
+        start: str,
+        end: str,
+    ) -> list[Bar]:
+        """Load bars for a given symbol, interval, and date range.
+
+        Args:
+            symbol: Instrument code, e.g. "AAPL", "000300.SH"
+            interval: Bar interval, e.g. "1d", "1m"
+            start: Start date, "YYYY-MM-DD"
+            end: End date, "YYYY-MM-DD"
+
+        Returns:
+            Bars sorted ascending by datetime. Empty list if no data.
+        """
+        ...
+
+    @abstractmethod
+    async def delete(self, symbol: str, interval: str) -> int:
+        """Delete all bars for a given symbol + interval.
+
+        Returns:
+            Number of bars deleted.
+        """
+        ...
+
+    @abstractmethod
+    async def get_overview(self) -> list[BarOverview]:
+        """Return an overview of all stored bar series.
+
+        Returns:
+            List of BarOverview, one per (symbol, interval) pair.
+        """
+        ...
+
+    def is_available(self) -> bool:
+        """Check if the storage backend is ready.
+
+        Defaults to True. Subclasses may override to check DB connectivity,
+        disk space, permissions, etc.
+        """
+        return True
+
+
+# ---------------------------------------------------------------------------
+# Shared parquet helpers (used by ParquetBarStore and available for reuse)
+# ---------------------------------------------------------------------------
+
+QUERY_KEY = b"nlalpha.query.v1"
+
+
+def _cache_path(symbol: str, interval: str, start: str, end: str, cache_dir: str | Path) -> Path:
+    """Hash the exact query into a collision-resistant safe filename."""
+    query = json.dumps([symbol, interval, start, end], separators=(",", ":"), ensure_ascii=False)
+    return Path(cache_dir) / f"{sha256(query.encode()).hexdigest()}.parquet"
+
+
+def _bars_to_df(bars: list[Bar]):
+    """Return the canonical UTC bar frame with original source metadata."""
+    return _bars_to_table(bars).to_pandas()
+
+
+def _df_to_bars(df, fallback_symbol: str = "") -> list[Bar]:
+    """Restore canonical bars without losing source metadata or precision."""
+    import pandas as pd
+    missing = set(_BAR_COLUMNS) - set(df.columns)
+    if missing:
+        raise DataError(
+            f"Legacy or incomplete bar cache lacks {sorted(missing)}; recreate it or import with an explicit source time contract.",
+            details={"time_contract": True},
+        )
+    bars: list[Bar] = []
+    for row in df.to_dict("records"):
+        def optional(name):
+            value = row[name]
+            return None if pd.isna(value) else value
+        session = optional("session_date")
+        if isinstance(session, datetime):
+            session = session.date()
+        elif isinstance(session, str):
+            session = date.fromisoformat(session)
+        for name in ("source_timezone", "calendar_id"):
+            value = optional(name)
+            if value is not None and (not isinstance(value, str) or not value or value != value.strip()):
+                raise DataError(f"Invalid canonical source metadata {name}.", details={"time_contract": True})
+        semantics = row["source_timestamp_semantics"]
+        if not isinstance(semantics, str) or semantics not in {"open", "close", "trading_date"}:
+            raise DataError("Invalid canonical source timestamp semantics.", details={"time_contract": True})
+        offset = optional("source_utc_offset_seconds")
+        if offset is not None and (isinstance(offset, bool) or not isinstance(offset, Real) or not math.isfinite(offset) or offset != int(offset)):
+            raise DataError("Source UTC offset must be exact integer seconds.", details={"time_contract": True})
+        bars.append(Bar(
+            symbol=row["symbol"] or fallback_symbol,
+            datetime=_canonical_datetime(row["close_time"]),
+            open_time=_canonical_datetime(optional("open_time")) if optional("open_time") is not None else None,
+            open=float(row["open"]), high=float(row["high"]), low=float(row["low"]),
+            close=float(row["close"]), volume=float(row["volume"]),
+            open_interest=float(optional("open_interest")) if optional("open_interest") is not None else None,
+            session_date=session,
+            source_timezone=optional("source_timezone"),
+            source_utc_offset_seconds=int(offset) if offset is not None else None,
+            source_timestamp_semantics=semantics,
+            calendar_id=optional("calendar_id"),
+        ))
+    bars.sort(key=lambda b: b.datetime)
+    return bars
+
+
+_BAR_COLUMNS = (
+    "symbol", "open_time", "close_time", "open", "high", "low", "close", "volume",
+    "open_interest", "session_date", "source_timezone", "source_utc_offset_seconds",
+    "source_timestamp_semantics", "calendar_id",
+)
+TIME_CONTRACT_KEY = b"nlalpha.time_contract"
+
+
+def _canonical_datetime(value) -> datetime:
+    """Require an aware timestamp representable by the Bar transport."""
+    if getattr(value, "nanosecond", 0):
+        raise DataError("Bar transport cannot truncate sub-microsecond timestamps.", details={"time_contract": True})
+    if hasattr(value, "to_pydatetime"):
+        value = value.to_pydatetime()
+    elif isinstance(value, str):
+        fractional = re.search(r"[T ]\d{2}:\d{2}:\d{2}\.(\d+)", value)
+        if fractional and any(character != "0" for character in fractional.group(1)[6:]):
+            raise DataError("Bar transport cannot truncate sub-microsecond timestamps.", details={"time_contract": True})
+        value = datetime.fromisoformat(value)
+    return normalize_utc(value)
+
+
+def bar_time_contract(bars: list[Bar]) -> dict:
+    """Summarize declared source semantics for canonical UTC bar transport."""
+    from importlib.metadata import version
+    assets = {}
+    for bar in bars:
+        item = assets.setdefault(bar.symbol, {"source_timezones": set(), "source_timestamp_semantics": set(), "calendar_ids": set(), "session_date_available": True})
+        if bar.source_timezone is not None:
+            item["source_timezones"].add(bar.source_timezone)
+        item["source_timestamp_semantics"].add(bar.source_timestamp_semantics)
+        if bar.calendar_id is not None:
+            item["calendar_ids"].add(bar.calendar_id)
+        item["session_date_available"] &= bar.session_date is not None
+    for item in assets.values():
+        for name in ("source_timezones", "source_timestamp_semantics", "calendar_ids"):
+            item[name] = sorted(item[name])
+    return {
+        "schema": "nlalpha.market.time.v1", "timezone": "UTC",
+        "timestamp_semantics": "bounds", "timestamp_precision": "us", "assets": assets,
+        "timezone_database": {"tzdata_version": timezone_metadata("UTC")["tzdata_version"]},
+        "calendar_library_version": version("exchange-calendars"),
+    }
+
+
+def _bars_to_table(bars: list[Bar], *, require_bounds: bool = False):
+    """Serialize exact UTC microseconds and attach a source time contract."""
+    import pyarrow as pa
+    if require_bounds and any(bar.open_time is None for bar in bars):
+        raise DataError("Bar delivery requires resolved open_time and close_time; declare source endpoint semantics or session calendar.", details={"time_contract": True})
+    types = {
+        "symbol": pa.string(), "open_time": pa.timestamp("us", tz="UTC"),
+        "close_time": pa.timestamp("us", tz="UTC"), "open": pa.float64(),
+        "high": pa.float64(), "low": pa.float64(), "close": pa.float64(),
+        "volume": pa.float64(), "open_interest": pa.float64(), "session_date": pa.date32(),
+        "source_timezone": pa.string(), "source_utc_offset_seconds": pa.int32(),
+        "source_timestamp_semantics": pa.string(), "calendar_id": pa.string(),
+    }
+    arrays = {}
+    for name in _BAR_COLUMNS:
+        attribute = "datetime" if name == "close_time" else name
+        values = [getattr(bar, attribute) for bar in bars]
+        if name in {"open_time", "close_time"}:
+            values = [normalize_utc(value) if value is not None else None for value in values]
+        arrays[name] = pa.array(values, type=types[name])
+    table = pa.table(arrays)
+    return table.replace_schema_metadata({TIME_CONTRACT_KEY: json.dumps(bar_time_contract(bars), sort_keys=True).encode("utf-8")})
+
+
+def _table_to_bars(table, fallback_symbol: str = "") -> list[Bar]:
+    """Validate a canonical cache envelope before reconstructing bars."""
+    raw = (table.schema.metadata or {}).get(TIME_CONTRACT_KEY)
+    if raw is None:
+        raise DataError("Legacy bar cache has no nlalpha.time_contract; recreate it or import with an explicit source time contract.", details={"time_contract": True})
+    try:
+        contract = json.loads(raw)
+    except (ValueError, TypeError) as exc:
+        raise DataError("Malformed bar cache time contract.", details={"time_contract": True}) from exc
+    for name in ("open_time", "close_time"):
+        field = table.schema.field(name) if name in table.column_names else None
+        if field is None or not hasattr(field.type, "tz") or field.type.tz != "UTC" or field.type.unit != "us":
+            raise DataError(f"Canonical cache {name} must be an aware UTC microsecond timestamp.", details={"time_contract": True})
+    try:
+        bars = _df_to_bars(table.to_pandas(), fallback_symbol)
+    except Exception as exc:
+        if isinstance(exc, DataError) and exc.details.get("time_contract"):
+            raise
+        raise DataError(f"Invalid canonical bar cache: {exc}", details={"time_contract": True}) from exc
+    if contract != bar_time_contract(bars):
+        raise DataError("Bar cache time envelope contradicts its source metadata.", details={"time_contract": True})
+    return bars
+
+
+def bar_source_date(bar: Bar) -> date:
+    """Resolve the session label or the original timestamp's source civil date."""
+    if bar.session_date is not None:
+        return bar.session_date
+    if bar.source_timestamp_semantics == "open":
+        if bar.open_time is None:
+            raise DataError("Open timestamp semantics requires open_time for source-date filtering.", details={"time_contract": True})
+        instant = bar.open_time
+    else:
+        instant = bar.datetime
+    if bar.source_timezone is not None:
+        source_zone = get_timezone(bar.source_timezone)
+    elif bar.source_utc_offset_seconds is not None:
+        source_zone = timezone(timedelta(seconds=bar.source_utc_offset_seconds))
+    else:
+        raise DataError("Date filtering requires a session label or original source timezone/offset.", details={"time_contract": True})
+    return instant.astimezone(source_zone).date()
+
+
+def filter_bar_dates(bars: list[Bar], start: str, end: str) -> list[Bar]:
+    """Filter inclusive dates using each bar's original source semantics."""
+    begin, finish = date.fromisoformat(start), date.fromisoformat(end)
+    if begin > finish:
+        raise DataError("Requested start date is after end date.")
+    return [bar for bar in bars if begin <= bar_source_date(bar) <= finish]

nlalpha_data-0.3.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: nlalpha-data
+Version: 0.3.0
+Summary: Financial data infrastructure for nlalpha: providers, stores, and trading calendars
+Project-URL: Homepage, https://github.com/ruimarj/nlalpha-data
+Project-URL: Repository, https://github.com/ruimarj/nlalpha-data
+Project-URL: Issues, https://github.com/ruimarj/nlalpha-data/issues
+Project-URL: Changelog, https://github.com/ruimarj/nlalpha-data/releases
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: <3.13,>=3.12
+Requires-Dist: aiofiles>=24.1
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: exchange-calendars>=4.13
+Requires-Dist: mcp<2.0,>=1.0
+Requires-Dist: nlalpha-core[json-log,redis,telemetry]>=0.7.0
+Requires-Dist: pandas<3,>=2.3
+Requires-Dist: pyarrow>=10.0
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: s3
+Requires-Dist: nlalpha-core[s3]>=0.7.0; extra == 's3'
+Description-Content-Type: text/markdown
+
+# nlalpha-data 0.3.0
+
+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
+
+```bash
+NLALPHA_ARTIFACT_BACKEND=redis \
+NLALPHA_ARTIFACT_REDIS_URL=redis://127.0.0.1:6379/0 \
+uvicorn nlalpha_data.server:app --host 127.0.0.1 --port 8000
+```
+
+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`](src/nlalpha_data/knowledge/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.

nlalpha_data-0.3.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+nlalpha_data/__init__.py,sha256=tXqAWCWoz5e7I5HVb_79Iw1Ag8fIM4tQUjjATYiT8lE,1071
+nlalpha_data/bars_aligner.py,sha256=eWk_6BnkqmgSDjxR-yvASw4EI9qTZVDiEM-3Grb4Mmk,2832
+nlalpha_data/base.py,sha256=xkhEGGkvO_TaJpSc1SxhmvDViapBwFNKq31sY8PANhY,3284
+nlalpha_data/calendar_base.py,sha256=undkziW1qDq__0_PUvt8GQSWrXsoVtZiMQqrPmpNRbw,7241
+nlalpha_data/calendar_tools.py,sha256=8PE5C4oeqJ9YZBR9z-T_ryyf0789YHV7SKvgMrxpv1g,5314
+nlalpha_data/discovery.py,sha256=7afazHho14w8I0285ntQeyOwOhsci2xLwmiYE5TB44o,6929
+nlalpha_data/loader.py,sha256=27B2g7PIHVhkopIxjuKUiNr_GLacvWC_eedlfnLy1FM,10869
+nlalpha_data/local_provider.py,sha256=Kc6MwEf3Vff2Tr9YZTTF9xJKzIYyG5EhU__EcUMlu1o,19885
+nlalpha_data/mock_provider.py,sha256=-Yl32zhVKagB0NVz0hyJ0R776LkonY3TFZMe7hnlm_I,5868
+nlalpha_data/parquet_store.py,sha256=Pp1gzWvxgB3R6oFQ0kdgvgvp7e1O9ns_U7Zby807118,6577
+nlalpha_data/server.py,sha256=c_n-uTKbYXknhiCUa45hh79bxwummz8DizEJ3GkHtIY,20093
+nlalpha_data/sqlite_store.py,sha256=7Wms-WlPLRl4acqeZpXrN9vMPnKhuFPlvM9EH4OFBn8,8480
+nlalpha_data/store.py,sha256=4uBHuCo9p788md2KWaMP24bufqXGno7ylIoeWztj0JU,13643
+nlalpha_data/calendar/__init__.py,sha256=ENn5QWGvh8VtU-xjtSe99n7Di4oaDHJzX9U_--Zavw4,437
+nlalpha_data/calendar/cn_equity.py,sha256=LfEK4Tk4y-SxtdkcSqkt2RUycId9Rlvj8SfZZWZi0p0,1143
+nlalpha_data/calendar/futures.py,sha256=slK8Q2-jHQp5DBT9g3Je_M8KFXjD0x4nbc9FvAvjnyU,1557
+nlalpha_data/calendar/us_equity.py,sha256=0sYfoGO_iWRyga7DhIeOPATsmIi3mCC7o8__1xk-6KQ,856
+nlalpha_data/knowledge/loading.md,sha256=2iFlRwHH8-o_f23s62hj_M0A-FoyQz3ZX7tVoldBwlE,4017
+nlalpha_data/knowledge/local-provider.md,sha256=3kFFtlQrZva2NKUVIjYmlPLeEJ-X2SmW4ROfy0vModk,2696
+nlalpha_data-0.3.0.dist-info/METADATA,sha256=B64bHQRu2nCxo2EkgVdyg9MD1nZX86qkmVBr0lZrdlE,15888
+nlalpha_data-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+nlalpha_data-0.3.0.dist-info/entry_points.txt,sha256=hW4qBROeaBiWA-A-xuH1ZUnPBBzEYO44Qw0kCE26q7I,58
+nlalpha_data-0.3.0.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+nlalpha_data-0.3.0.dist-info/RECORD,,

nlalpha_data-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nlalpha_data-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nlalpha-data = nlalpha_data.server:main