nlalpha-data 0.3.0__tar.gz → 0.4.0__tar.gz

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nlalpha-data
-Version: 0.3.0
+Version: 0.4.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
@@ -12,6 +12,7 @@ Requires-Python: <3.13,>=3.12
 Requires-Dist: aiofiles>=24.1
 Requires-Dist: aiosqlite>=0.19
 Requires-Dist: exchange-calendars>=4.13
+Requires-Dist: jsonschema<5,>=4.23
 Requires-Dist: mcp<2.0,>=1.0
 Requires-Dist: nlalpha-core[json-log,redis,telemetry]>=0.7.0
 Requires-Dist: pandas<3,>=2.3
@@ -22,7 +23,7 @@ Provides-Extra: s3
 Requires-Dist: nlalpha-core[s3]>=0.7.0; extra == 's3'
 Description-Content-Type: text/markdown
 
-# nlalpha-data 0.3.0
+# nlalpha-data 0.4.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`.
 
@@ -34,6 +35,10 @@ nlalpha-data runs as a standalone MCP server (SSE transport, port 8000) and serv
 - 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.
 
+## Provider SDK
+
+`nlalpha_data.provider` is the provider-neutral SDK used to implement and test data sources. It exposes `protocol` (the `DataProvider` contract), `manifest` (schema validation), `adjustment` (price-adjustment declarations), `bars` (time-contract bar construction; `build_bar` accepts `source_utc_offset_seconds` for exact source-offset evidence), `calendars` (exchange-calendar helpers, including the `TradingCalendar` re-export), `errors` (normalized provider errors), and `testing` (a synthetic provider plus contract assertions). It contains no source-specific rules.
+
 ## MCP tools
 
 | Tool | Description |
@@ -45,15 +50,23 @@ nlalpha-data runs as a standalone MCP server (SSE transport, port 8000) and serv
 | `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. |
+| `list_provider_tools` | Lists the tools one provider declares in its manifest. |
+| `invoke_provider_tool` | Validates and invokes one manifest-declared provider tool with bounded output. |
 | `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.
+## Breaking changes in 0.4.0
+
+The six provider-specific MCP tools `list_instruments`, `get_trading_calendar`, `get_daily_basic`, `get_price_limits`, `get_suspensions`, and `get_index_weights` were removed from the MCP tool surface. Their behavior now lives behind provider manifests: discover the tools with `list_provider_tools(provider_id)` and invoke them with `invoke_provider_tool(provider_id, tool_name, arguments)`. There is no compatibility alias — clients that called the old tool names must migrate to the gateway. A Tushare migration looks like:
+
+```python
+await data.invoke_provider_tool("tushare", "get_daily_basic", {"symbol": "600000.SH", "start": "20240101", "end": "20240331"})
+```
+
+## Provider tool gateway
+
+The data service exposes only manifest-declared provider tools through a generic gateway; it contains no vendor tool names and no method reflection. `list_provider_tools(provider_id)` returns the declared tools, descriptions, JSON Schemas, and provider identity. `invoke_provider_tool(provider_id, tool_name, arguments)` requires the tool to appear in that provider's manifest, validates `arguments` against the tool's `input_schema` with JSON Schema, then calls the provider's optional `invoke_tool`. Unknown tools and providers without the invocation capability return `unsupported_capability`; schema mismatches return `invalid_request`; timeouts and other invocation failures return `upstream_transient`. Provider errors already classified by the SDK propagate unchanged.
+
+The response is always `{rows, source, truncated, returned_rows, total_rows}`. Rows are serialized as UTF-8 JSON and bounded by `NLALPHA_PROVIDER_TOOL_MAX_BYTES` (default `1048576`); an oversized result returns the largest fitting row prefix with `truncated=true` instead of an unbounded payload. Invocation is bounded by `NLALPHA_PROVIDER_TOOL_TIMEOUT_SECONDS` (default `30`, finite and positive). Invalid values for either variable fail service startup. `source` contains `provider_id`, the distribution package name, and its version. The gateway never switches sources automatically and never registers provider-specific MCP tools, so the MCP tool surface stays stable as providers are added.
 
 ## Provider selection and price-source evidence
 
@@ -100,9 +113,11 @@ DNS rebinding protection stays enabled. Allowed hosts are configured explicitly
 ```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
+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

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/README.md

@@ -1,4 +1,4 @@
-# nlalpha-data 0.3.0
+# nlalpha-data 0.4.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`.
 
@@ -10,6 +10,10 @@ nlalpha-data runs as a standalone MCP server (SSE transport, port 8000) and serv
 - 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.
 
+## Provider SDK
+
+`nlalpha_data.provider` is the provider-neutral SDK used to implement and test data sources. It exposes `protocol` (the `DataProvider` contract), `manifest` (schema validation), `adjustment` (price-adjustment declarations), `bars` (time-contract bar construction; `build_bar` accepts `source_utc_offset_seconds` for exact source-offset evidence), `calendars` (exchange-calendar helpers, including the `TradingCalendar` re-export), `errors` (normalized provider errors), and `testing` (a synthetic provider plus contract assertions). It contains no source-specific rules.
+
 ## MCP tools
 
 | Tool | Description |
@@ -21,15 +25,23 @@ nlalpha-data runs as a standalone MCP server (SSE transport, port 8000) and serv
 | `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. |
+| `list_provider_tools` | Lists the tools one provider declares in its manifest. |
+| `invoke_provider_tool` | Validates and invokes one manifest-declared provider tool with bounded output. |
 | `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.
+## Breaking changes in 0.4.0
+
+The six provider-specific MCP tools `list_instruments`, `get_trading_calendar`, `get_daily_basic`, `get_price_limits`, `get_suspensions`, and `get_index_weights` were removed from the MCP tool surface. Their behavior now lives behind provider manifests: discover the tools with `list_provider_tools(provider_id)` and invoke them with `invoke_provider_tool(provider_id, tool_name, arguments)`. There is no compatibility alias — clients that called the old tool names must migrate to the gateway. A Tushare migration looks like:
+
+```python
+await data.invoke_provider_tool("tushare", "get_daily_basic", {"symbol": "600000.SH", "start": "20240101", "end": "20240331"})
+```
+
+## Provider tool gateway
+
+The data service exposes only manifest-declared provider tools through a generic gateway; it contains no vendor tool names and no method reflection. `list_provider_tools(provider_id)` returns the declared tools, descriptions, JSON Schemas, and provider identity. `invoke_provider_tool(provider_id, tool_name, arguments)` requires the tool to appear in that provider's manifest, validates `arguments` against the tool's `input_schema` with JSON Schema, then calls the provider's optional `invoke_tool`. Unknown tools and providers without the invocation capability return `unsupported_capability`; schema mismatches return `invalid_request`; timeouts and other invocation failures return `upstream_transient`. Provider errors already classified by the SDK propagate unchanged.
+
+The response is always `{rows, source, truncated, returned_rows, total_rows}`. Rows are serialized as UTF-8 JSON and bounded by `NLALPHA_PROVIDER_TOOL_MAX_BYTES` (default `1048576`); an oversized result returns the largest fitting row prefix with `truncated=true` instead of an unbounded payload. Invocation is bounded by `NLALPHA_PROVIDER_TOOL_TIMEOUT_SECONDS` (default `30`, finite and positive). Invalid values for either variable fail service startup. `source` contains `provider_id`, the distribution package name, and its version. The gateway never switches sources automatically and never registers provider-specific MCP tools, so the MCP tool surface stays stable as providers are added.
 
 ## Provider selection and price-source evidence
 
@@ -76,9 +88,11 @@ DNS rebinding protection stays enabled. Allowed hosts are configured explicitly
 ```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
+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

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/README.zh.md

@@ -1,4 +1,4 @@
-# nlalpha-data 0.3.0
+# nlalpha-data 0.4.0
 
 数据接入 MCP Server：为策略生成与回测提供行情数据接入、覆盖检查、质量评估与交易日历能力，并通过 core `DataArtifactStore` 向其他 nlalpha 服务交付不可变数据。
 
@@ -21,15 +21,23 @@ nlalpha-data 以独立 MCP Server（SSE transport，端口 8000）运行，作
 | `list_trading_calendars` | 列出支持的交易日历 |
 | `get_trading_days` | 查询指定日历的交易日序列 |
 | `is_trading_day` | 判断某日期是否为交易日 |
-| `list_instruments` | 按资产类别列出标的列表（stock/index/fund/future/cb/option） |
-| `get_trading_calendar` | 从所选数据源读取规范化交易所日历（含开闭市与前一交易日） |
-| `get_daily_basic` | 读取指定标的的每日基础指标 |
-| `get_price_limits` | 读取指定标的的每日涨跌停价格 |
-| `get_suspensions` | 读取指定标的的每日停复牌记录 |
-| `get_index_weights` | 读取指定指数的成分权重 |
+| `list_provider_tools` | 列出某个 provider 在 manifest 中声明的工具 |
+| `invoke_provider_tool` | 校验并调用一个 manifest 声明的 provider 工具，输出有界 |
 | `confess` | 调试用：返回服务自身的运行配置摘要 |
 
-`list_instruments`、`get_trading_calendar`、`get_daily_basic`、`get_price_limits`、`get_suspensions` 和 `get_index_weights` 复用 `DataLoader` 的 provider 选择规则，返回值中的 `source` 含 `provider_id`、发行包名与版本；所选 provider 未实现对应方法时返回明确的 `data_error`，不会静默换源或返回空结果。
+## 0.4.0 破坏性变更
+
+六个厂商专用 MCP 工具 `list_instruments`、`get_trading_calendar`、`get_daily_basic`、`get_price_limits`、`get_suspensions`、`get_index_weights` 已从 MCP 工具面移除，其能力改由 provider manifest 声明：先用 `list_provider_tools(provider_id)` 发现工具，再用 `invoke_provider_tool(provider_id, tool_name, arguments)` 调用。不提供兼容别名，仍调用旧工具名的客户端必须迁移到网关。Tushare 的迁移示例如下：
+
+```python
+await data.invoke_provider_tool("tushare", "get_daily_basic", {"symbol": "600000.SH", "start": "20240101", "end": "20240331"})
+```
+
+## Provider 工具网关
+
+data 服务通过通用网关只暴露 manifest 声明的 provider 工具，不包含任何厂商工具名，也不做方法反射。`list_provider_tools(provider_id)` 返回声明的工具、说明、JSON Schema 与 provider 身份。`invoke_provider_tool(provider_id, tool_name, arguments)` 要求工具出现在该 provider 的 manifest 中，先用 JSON Schema 校验 `arguments` 与工具的 `input_schema`，再调用 provider 可选的 `invoke_tool`。未知工具、以及未实现调用能力的 provider 返回 `unsupported_capability`；schema 不匹配返回 `invalid_request`；超时与其他调用失败返回 `upstream_transient`。SDK 已分类的 provider 错误原样传播。
+
+响应固定为 `{rows, source, truncated, returned_rows, total_rows}`。rows 以 UTF-8 JSON 序列化，并受 `NLALPHA_PROVIDER_TOOL_MAX_BYTES`（默认 `1048576`）约束；超限时返回能放入预算的最大行前缀并标记 `truncated=true`，绝不返回无界数据。调用受 `NLALPHA_PROVIDER_TOOL_TIMEOUT_SECONDS`（默认 `30`，必须有限且为正）约束。任一变量取值非法都会让服务启动失败。`source` 含 `provider_id`、发行包名与版本。网关不会自动换源，也不会动态注册厂商 MCP 工具，因此新增 provider 时 MCP 工具面保持稳定。
 
 ## Provider 选择与价格来源证据
 
@@ -76,9 +84,11 @@ DNS rebinding 防护保持开启。允许的 Host 通过 `create_app(allowed_hos
 ```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
+nlalpha-data
 ```
 
+`NLALPHA_HOST` 与 `NLALPHA_PORT` 默认 `127.0.0.1`/`8000`；等价的模块入口是 `python -m nlalpha_data.server`。
+
 生产或容器部署应显式选择网络可达的 Redis 或 S3 endpoint，并设置允许的 Host。S3 部署还需提前配置 bucket 生命周期规则；MinIO 只是可选的 S3 实现。
 
 ## Source time contract

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nlalpha-data"
-version = "0.3.0"
+version = "0.4.0"
 description = "Financial data infrastructure for nlalpha: providers, stores, and trading calendars"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -20,6 +20,7 @@ dependencies = [
     "pyarrow>=10.0",
     "mcp>=1.0,<2.0",
     "exchange-calendars>=4.13",
+    "jsonschema>=4.23,<5",
 ]
 
 [project.optional-dependencies]

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/src/nlalpha_data/__init__.py

@@ -1,6 +1,6 @@
 """Financial data providers, explicit loading, storage, and trading calendars."""
 
-from nlalpha_data.base import DataProvider
+from nlalpha_data.provider.protocol import DataProvider
 from nlalpha_data.store import BaseBarStore, BarOverview
 from nlalpha_data.calendar_base import TradingCalendar, WeekendOnlyCalendar
 from nlalpha_data.calendar import CNEquityCalendar, USEquityCalendar, FuturesCalendar

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/src/nlalpha_data/loader.py

@@ -8,7 +8,7 @@ from typing import Any
 
 from nlalpha.core.contracts.market import Bar
 from nlalpha.core.errors import DataError, InvalidRequestError, NlAlphaError, INVALID_REQUEST
-from nlalpha_data.base import DataProvider, validate_request_description
+from nlalpha_data.provider.protocol import DataProvider, validate_request_description
 from nlalpha_data.parquet_store import ParquetBarStore
 
 
@@ -153,56 +153,6 @@ class DataLoader:
             await store.save(bars, symbol=symbol, interval=interval, start=start, end=end)
         return LoadedBars(bars=bars, cache_hit=False, **source)
 
-    @staticmethod
-    def _source(record: DataProviderRecord) -> dict[str, Any]:
-        """Return the provider identity attached to pass-through reference data."""
-        return {"provider_id": record.provider_id, "package": record.package, "version": record.version}
-
-    def _provider_call(self, method_name: str) -> tuple[DataProviderRecord, Any]:
-        """Resolve one required provider method or expose its absence."""
-        record = self._select(None)
-        method = getattr(record.provider, method_name, None)
-        if not callable(method):
-            raise DataError(f"Selected data provider does not expose {method_name}.")
-        return record, method
-
-    async def list_instruments(self, asset: str, *, market: str | None = None,
-                               status: str | None = None) -> tuple[list[dict], dict[str, Any]]:
-        """List one asset class's instrument master with its source identity."""
-        record, method = self._provider_call("list_instruments")
-        rows = await method(asset, market=market, status=status)
-        return rows, self._source(record)
-
-    async def get_trading_calendar(self, exchange: str, start: str, end: str) -> tuple[list[dict], dict[str, Any]]:
-        """Return one exchange calendar with its source identity."""
-        record, method = self._provider_call("get_trading_calendar")
-        rows = await method(exchange, start, end)
-        return rows, self._source(record)
-
-    async def get_daily_basic(self, symbol: str, start: str, end: str) -> tuple[list[dict], dict[str, Any]]:
-        """Return daily fundamental metrics with their source identity."""
-        record, method = self._provider_call("get_daily_basic")
-        rows = await method(symbol, start, end)
-        return rows, self._source(record)
-
-    async def get_price_limits(self, symbol: str, start: str, end: str) -> tuple[list[dict], dict[str, Any]]:
-        """Return daily price limits with their source identity."""
-        record, method = self._provider_call("get_price_limits")
-        rows = await method(symbol, start, end)
-        return rows, self._source(record)
-
-    async def get_suspensions(self, symbol: str, start: str, end: str) -> tuple[list[dict], dict[str, Any]]:
-        """Return daily suspension rows with their source identity."""
-        record, method = self._provider_call("get_suspensions")
-        rows = await method(symbol, start, end)
-        return rows, self._source(record)
-
-    async def get_index_weights(self, index_code: str, start: str, end: str) -> tuple[list[dict], dict[str, Any]]:
-        """Return index constituent weights with their source identity."""
-        record, method = self._provider_call("get_index_weights")
-        rows = await method(index_code, start, end)
-        return rows, self._source(record)
-
     async def aclose(self) -> None:
         """Close all cache resources owned by this loader."""
         for store in self._stores.values():

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/src/nlalpha_data/local_provider.py

@@ -36,7 +36,7 @@ from nlalpha.core.contracts.market import Bar
 from nlalpha.core.errors import DataError
 from nlalpha.core.contracts.time import get_timezone, normalize_utc, timezone_metadata
 from nlalpha_data.calendar_base import exchange_calendar, session_bounds
-from nlalpha_data.base import _interval_delta
+from nlalpha_data.provider.protocol import _interval_delta
 from nlalpha_data.store import filter_bar_dates
 
 

{nlalpha_data-0.3.0 → nlalpha_data-0.4.0}/src/nlalpha_data/mock_provider.py

@@ -8,7 +8,7 @@ import math
 
 from nlalpha.core.contracts.market import Bar
 
-from nlalpha_data.base import _interval_delta
+from nlalpha_data.provider.protocol import _interval_delta
 
 
 class MockDataProvider:

nlalpha_data-0.4.0/src/nlalpha_data/provider/__init__.py

@@ -0,0 +1,63 @@
+"""Provider-neutral SDK contracts, manifests, adjustments, bars, calendars, and errors."""
+
+from nlalpha_data.provider.protocol import (
+    DataProvider,
+    ToolInvokingProvider,
+    _interval_delta,
+    validate_request_description,
+)
+from nlalpha_data.provider.manifest import MANIFEST_SCHEMA, validate_manifest
+from nlalpha_data.provider.adjustment import (
+    ADJUSTMENT_MODES,
+    AdjustmentSpec,
+    describe_adjustment,
+    validate_adjustment,
+)
+from nlalpha_data.provider.bars import build_bar, session_close, validate_bar_time
+from nlalpha_data.provider.calendars import (
+    CalendarResolver,
+    get_calendar,
+    session_bounds,
+    trading_days,
+)
+from nlalpha_data.provider.errors import (
+    CONTRACT_VIOLATION,
+    DATA_UNAVAILABLE,
+    INVALID_REQUEST,
+    RATE_LIMITED,
+    UNSUPPORTED_CAPABILITY,
+    UPSTREAM_TRANSIENT,
+    classify_http_status,
+    provider_error,
+)
+from nlalpha_data.provider.testing import SyntheticDataProvider, assert_provider_contract
+
+__all__ = [
+    "DataProvider",
+    "ToolInvokingProvider",
+    "validate_request_description",
+    "_interval_delta",
+    "MANIFEST_SCHEMA",
+    "validate_manifest",
+    "ADJUSTMENT_MODES",
+    "AdjustmentSpec",
+    "validate_adjustment",
+    "describe_adjustment",
+    "session_close",
+    "build_bar",
+    "validate_bar_time",
+    "get_calendar",
+    "session_bounds",
+    "trading_days",
+    "CalendarResolver",
+    "DATA_UNAVAILABLE",
+    "RATE_LIMITED",
+    "UPSTREAM_TRANSIENT",
+    "UNSUPPORTED_CAPABILITY",
+    "INVALID_REQUEST",
+    "CONTRACT_VIOLATION",
+    "provider_error",
+    "classify_http_status",
+    "SyntheticDataProvider",
+    "assert_provider_contract",
+]

nlalpha_data-0.4.0/src/nlalpha_data/provider/adjustment.py

@@ -0,0 +1,52 @@
+"""Describe provider price-adjustment declarations without vendor rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+ADJUSTMENT_MODES = ("unadjusted", "forward", "backward")
+_BASIS = ("price", "total_return")
+_ANCHORS = {"unadjusted": None, "forward": "end", "backward": "start"}
+
+
+@dataclass(frozen=True)
+class AdjustmentSpec:
+    """Declare a price-adjustment mode, its anchor, basis, and evidence."""
+
+    mode: str
+    anchor: str | None
+    basis: str
+    evidence: dict = field(default_factory=dict)
+
+
+def validate_adjustment(mode, *, anchor=None, basis="price", evidence=None) -> AdjustmentSpec:
+    """Validate an adjustment declaration and derive its canonical anchor."""
+    if not isinstance(mode, str) or mode not in ADJUSTMENT_MODES:
+        raise ValueError("adjustment mode must be one of: unadjusted, forward, backward")
+    expected_anchor = _ANCHORS[mode]
+    if anchor is not None and anchor != expected_anchor:
+        raise ValueError(
+            f"adjustment mode {mode!r} requires anchor {expected_anchor!r}"
+        )
+    if not isinstance(basis, str) or basis not in _BASIS:
+        raise ValueError("adjustment basis must be price or total_return")
+    if evidence is None:
+        evidence = {}
+    if not isinstance(evidence, dict):
+        raise ValueError("adjustment evidence must be an object")
+    return AdjustmentSpec(mode=mode, anchor=expected_anchor, basis=basis, evidence=dict(evidence))
+
+
+def describe_adjustment(spec: AdjustmentSpec) -> dict:
+    """Render an adjustment spec in the legacy source-declaration shape."""
+    if not isinstance(spec, AdjustmentSpec):
+        raise ValueError("describe_adjustment requires an AdjustmentSpec")
+    return {"price_adjustment": spec.mode, "evidence": dict(spec.evidence)}
+
+
+__all__ = [
+    "ADJUSTMENT_MODES",
+    "AdjustmentSpec",
+    "validate_adjustment",
+    "describe_adjustment",
+]

nlalpha_data-0.4.0/src/nlalpha_data/provider/bars.py

@@ -0,0 +1,83 @@
+"""Provider-neutral helpers for constructing and validating bars."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from dataclasses import replace
+
+from nlalpha.core.contracts.market import Bar
+from nlalpha.core.errors import DataError
+from nlalpha_data.calendar_base import session_bounds
+from nlalpha_data.provider.protocol import _interval_delta
+
+
+def session_close(calendar_id: str, session_date: date) -> datetime:
+    """Return the authoritative UTC close for one labeled session."""
+    return session_bounds(calendar_id, session_date)[1]
+
+
+def build_bar(
+    symbol: str,
+    interval: str,
+    *,
+    open: float,
+    high: float,
+    low: float,
+    close: float,
+    volume: float,
+    open_time: datetime | None = None,
+    close_time: datetime | None = None,
+    session_date: date | None = None,
+    source_timezone: str | None = None,
+    source_timestamp_semantics: str = "close",
+    calendar_id: str | None = None,
+    open_interest: float | None = None,
+    source_utc_offset_seconds: int | None = None,
+) -> Bar:
+    """Construct a Bar with an explicit, validated time contract."""
+    _interval_delta(interval)
+    if close_time is None:
+        if session_date is None or calendar_id is None:
+            raise DataError(
+                "close_time is required unless session_date and calendar_id resolve it.",
+                details={"time_contract": True, "field": "close_time"},
+            )
+        close_time = session_close(calendar_id, session_date)
+    if not isinstance(close_time, datetime):
+        raise DataError(
+            "close_time must be a datetime.",
+            details={"time_contract": True, "field": "close_time"},
+        )
+    return Bar(
+        symbol=symbol,
+        datetime=close_time,
+        open=open,
+        high=high,
+        low=low,
+        close=close,
+        volume=volume,
+        open_interest=open_interest,
+        open_time=open_time,
+        session_date=session_date,
+        source_timezone=source_timezone,
+        source_utc_offset_seconds=source_utc_offset_seconds,
+        source_timestamp_semantics=source_timestamp_semantics,
+        calendar_id=calendar_id,
+    )
+
+
+def validate_bar_time(bar: Bar) -> None:
+    """Re-run Bar time invariants and raise DataError on violation."""
+    if not isinstance(bar, Bar):
+        raise DataError(
+            "bar must be a Bar instance.",
+            details={"time_contract": True, "field": "bar"},
+        )
+    replace(bar)
+
+
+__all__ = [
+    "session_close",
+    "build_bar",
+    "validate_bar_time",
+]

nlalpha_data-0.4.0/src/nlalpha_data/provider/calendars.py

@@ -0,0 +1,67 @@
+"""Provider-neutral trading-calendar helpers and exchange mapping."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from nlalpha.core.errors import DataError
+from nlalpha_data.calendar_base import TradingCalendar
+from nlalpha_data.calendar_base import exchange_calendar, session_bounds as _session_bounds
+
+
+def get_calendar(calendar_id: str):
+    """Resolve an explicitly named exchange calendar."""
+    return exchange_calendar(calendar_id)
+
+
+def session_bounds(calendar_id: str, session_date: date) -> tuple[datetime, datetime]:
+    """Return the UTC open and close bounds of one labeled session."""
+    return _session_bounds(calendar_id, session_date)
+
+
+def trading_days(calendar_id: str, start, end) -> list[date]:
+    """Return the sessions between two inclusive date labels."""
+    from pandas import Timestamp
+
+    calendar = get_calendar(calendar_id)
+    try:
+        sessions = calendar.sessions_in_range(Timestamp(start), Timestamp(end))
+    except Exception as exc:
+        raise DataError(
+            f"Cannot resolve {calendar_id} sessions {start}..{end}: {exc}",
+            details={"time_contract": True},
+        ) from exc
+    return [session.date() for session in sessions]
+
+
+class CalendarResolver:
+    """Map exchange codes to calendar identifiers through an explicit table."""
+
+    def __init__(self, mapping: dict[str, str]):
+        if not isinstance(mapping, dict):
+            raise ValueError("calendar mapping must be an object")
+        for code, calendar_id in mapping.items():
+            if not isinstance(code, str) or not code or code != code.strip():
+                raise ValueError("calendar mapping keys must be non-empty trimmed strings")
+            if not isinstance(calendar_id, str) or not calendar_id or calendar_id != calendar_id.strip():
+                raise ValueError("calendar mapping values must be non-empty trimmed strings")
+        self._mapping = dict(mapping)
+
+    def resolve(self, exchange_code: str) -> str:
+        """Resolve one exchange code or fail with the unsupported exchange."""
+        calendar_id = self._mapping.get(exchange_code)
+        if calendar_id is None:
+            raise DataError(
+                f"Unsupported exchange code: {exchange_code!r}.",
+                details={"unsupported_exchange": exchange_code},
+            )
+        return calendar_id
+
+
+__all__ = [
+    "TradingCalendar",
+    "get_calendar",
+    "session_bounds",
+    "trading_days",
+    "CalendarResolver",
+]

nlalpha_data-0.4.0/src/nlalpha_data/provider/errors.py

@@ -0,0 +1,61 @@
+"""Provider error categories and normalized DataError construction."""
+
+from __future__ import annotations
+
+from nlalpha.core.errors import DataError
+
+DATA_UNAVAILABLE = "data_unavailable"
+RATE_LIMITED = "rate_limited"
+UPSTREAM_TRANSIENT = "upstream_transient"
+UNSUPPORTED_CAPABILITY = "unsupported_capability"
+INVALID_REQUEST = "invalid_request"
+CONTRACT_VIOLATION = "contract_violation"
+
+CATEGORIES = frozenset(
+    {
+        DATA_UNAVAILABLE,
+        RATE_LIMITED,
+        UPSTREAM_TRANSIENT,
+        UNSUPPORTED_CAPABILITY,
+        INVALID_REQUEST,
+        CONTRACT_VIOLATION,
+    }
+)
+_RETRYABLE = frozenset({RATE_LIMITED, UPSTREAM_TRANSIENT})
+
+
+def provider_error(category: str, message: str, *, details: dict | None = None,
+                   retryable: bool | None = None) -> DataError:
+    """Build a DataError tagged with a provider error category."""
+    if category not in CATEGORIES:
+        raise ValueError(f"unknown provider error category: {category!r}")
+    payload = dict(details or {})
+    payload["provider_error_category"] = category
+    if retryable is None:
+        retryable = category in _RETRYABLE
+    return DataError(message, details=payload, retryable=retryable)
+
+
+def classify_http_status(status: int) -> str:
+    """Map an HTTP status to a provider error category."""
+    if isinstance(status, bool) or not isinstance(status, int):
+        raise ValueError("HTTP status must be an integer")
+    if status == 429:
+        return RATE_LIMITED
+    if 500 <= status <= 599:
+        return UPSTREAM_TRANSIENT
+    if 400 <= status <= 499:
+        return INVALID_REQUEST
+    raise ValueError(f"unsupported HTTP status for provider classification: {status}")
+
+
+__all__ = [
+    "DATA_UNAVAILABLE",
+    "RATE_LIMITED",
+    "UPSTREAM_TRANSIENT",
+    "UNSUPPORTED_CAPABILITY",
+    "INVALID_REQUEST",
+    "CONTRACT_VIOLATION",
+    "provider_error",
+    "classify_http_status",
+]