fd-open-data-protocol 0.1.0__py3-none-any.whl

fd_open_data_protocol/__init__.py

@@ -0,0 +1,8 @@
+"""fd-open-data-protocol: the open-data datasource protocol.
+
+A manifest contract a datasource exposes (datasource + functions + columns +
+concept hints + fetch reference) so that fd-open-data-mcp - or any consumer -
+can ingest it via ``register_datasource``. Ship one manifest file -> the
+datasource is added; no consumer-side wiring.
+"""
+__version__ = "0.1.0"

fd_open_data_protocol/loader.py

@@ -0,0 +1,69 @@
+"""Catalog loader: parse a manifest from YAML, JSON, a Python file/module, or a dict.
+
+``load_catalog(source)`` returns a validated ``DatasourceManifest``. This is
+the consumer entry point: a consumer (fd-open-data-mcp's ``register_datasource``,
+or any other) calls ``load_catalog`` then ingests.
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import json
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+
+from fd_open_data_protocol.schema import DatasourceManifest
+
+ManifestSource = Union[str, Path, dict, DatasourceManifest]
+
+
+def _manifest_from_catalog(catalog: Any) -> DatasourceManifest:
+    if isinstance(catalog, DatasourceManifest):
+        return catalog
+    if isinstance(catalog, dict):
+        return DatasourceManifest(**catalog)
+    raise ValueError(f"CATALOG is {type(catalog).__name__}, expected dict or DatasourceManifest")
+
+
+def load_catalog(source: ManifestSource) -> DatasourceManifest:
+    """Load + validate a ``DatasourceManifest`` from a path, module, dict, or manifest."""
+    if isinstance(source, DatasourceManifest):
+        return source
+    if isinstance(source, dict):
+        return DatasourceManifest(**source)
+    if isinstance(source, (str, Path)):
+        s = str(source)
+        p = Path(s)
+        if p.is_file():
+            suffix = p.suffix.lower()
+            if suffix in (".yaml", ".yml"):
+                data = yaml.safe_load(p.read_text())
+                if not isinstance(data, dict):
+                    raise ValueError(f"YAML manifest did not parse to a dict: {s}")
+                return DatasourceManifest(**data)
+            if suffix == ".json":
+                return DatasourceManifest(**json.loads(p.read_text()))
+            if suffix == ".py":
+                # exec the file, read CATALOG
+                spec = importlib.util.spec_from_file_location("_fd_odp_manifest", p)
+                if spec is None or spec.loader is None:
+                    raise ValueError(f"cannot create module spec for {s}")
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+                catalog = getattr(mod, "CATALOG", None)
+                if catalog is None:
+                    raise ValueError(f"{s} has no CATALOG attribute")
+                return _manifest_from_catalog(catalog)
+            raise ValueError(f"unsupported manifest file type: {suffix} ({s})")
+        # treat as a Python module path "pkg.mod" exposing CATALOG
+        try:
+            mod = importlib.import_module(s)
+        except ImportError as e:
+            raise ValueError(f"neither a file nor an importable module: {s}") from e
+        catalog = getattr(mod, "CATALOG", None)
+        if catalog is None:
+            raise ValueError(f"module {s} has no CATALOG attribute")
+        return _manifest_from_catalog(catalog)
+    raise TypeError(f"unsupported source type: {type(source).__name__}")

fd_open_data_protocol/provider.py

@@ -0,0 +1,49 @@
+"""The DataProvider interface (optional companion to a manifest).
+
+A manifest is the *declarative* catalog. A datasource that also ships fetch
+code implements ``DataProvider`` (or subclasses ``BaseDataProvider``) so the
+consumer can call ``run()``. The manifest's ``fetch`` field references the
+runner (a built-in name or a module path); the class is for providers that
+prefer to bundle catalog + code.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class DataProvider:
+    """Structural interface (duck-typed). A provider has ``name``,
+    ``registry()``, and ``run(command, params)``."""
+
+    name: str
+
+    def registry(self) -> dict:
+        raise NotImplementedError
+
+    def run(self, command: str, params: dict) -> Any:
+        raise NotImplementedError
+
+
+class BaseDataProvider:
+    """Base class with empty defaults for optional facets. Subclass and
+    override ``registry`` + ``run``; the rest are no-ops by default."""
+
+    name: str = ""
+
+    def registry(self) -> dict:
+        raise NotImplementedError
+
+    def run(self, command: str, params: dict) -> Any:
+        raise NotImplementedError
+
+    def introspect(self) -> list[dict]:
+        return []
+
+    def seed_entities(self, session: Any) -> dict:
+        return {}
+
+    def concept_rules(self) -> list:
+        return []
+
+    def build_params(self, fn: Any, identifier: str, date: str, binding: Any = None) -> dict:
+        return {}

fd_open_data_protocol/schema.py

@@ -0,0 +1,67 @@
+"""Pydantic schema for the datasource manifest (the protocol contract).
+
+A manifest declares a datasource's identity, functions, columns, concept
+hints, and fetch reference. Column-level ``frequency``/``datasource`` come from
+``enrich-concept-identity``; ``measure``/``entity_type`` are concept-level
+(via ``ConceptHint``).
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ParamSpec(BaseModel):
+    name: str
+    type: Optional[str] = None
+    required: bool = False
+    description: Optional[str] = None
+
+
+class ColumnSpec(BaseModel):
+    name: str
+    type: Optional[str] = None
+    description: Optional[str] = None
+    meaning: Optional[str] = None
+    semantic_type: Optional[str] = None
+    frequency: Optional[str] = None   # column-level cadence (defaults to the function's)
+    datasource: Optional[str] = None  # column-level source (defaults to the manifest's)
+
+
+class FunctionSpec(BaseModel):
+    command: str
+    category: Optional[str] = None
+    description: Optional[str] = None
+    parameters: list[ParamSpec] = Field(default_factory=list)
+    columns: list[ColumnSpec] = Field(default_factory=list)
+    frequency: Optional[str] = None
+    verified: bool = True
+
+
+class ConceptHint(BaseModel):
+    column: str
+    concept: str
+    entity_type: str
+    measure: Optional[str] = None
+    unit: Optional[str] = None
+    frequency: Optional[str] = None
+    confidence: float = 0.9
+
+
+class FetchRef(BaseModel):
+    runner: Optional[str] = None   # built-in runner name
+    module: Optional[str] = None   # "pkg.mod:func" import path
+
+
+class DatasourceManifest(BaseModel):
+    version: str = "1"
+    name: str
+    label: str
+    source_url: Optional[str] = None
+    scanner_mode: str = "upstream-curated"
+    requires: list[str] = Field(default_factory=list)
+    ranking_seed: list[float] = Field(default_factory=lambda: [0.5, 0.5])
+    functions: list[FunctionSpec]
+    concepts: list[ConceptHint] = Field(default_factory=list)
+    fetch: Optional[FetchRef] = None

fd_open_data_protocol-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: fd-open-data-protocol
+Version: 0.1.0
+Summary: The open-data datasource protocol: a manifest contract a datasource exposes to be ingested by fd-open-data-mcp (or any consumer).
+Author: FindDataOfficial
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# fd-open-data-protocol
+
+The **open-data datasource protocol**: a manifest contract a datasource exposes
+(datasource + functions + columns + concept hints + fetch reference) so that
+`fd-open-data-mcp` - or any consumer - can ingest it via `register_datasource`.
+
+**Ship one manifest file -> the datasource is added. No consumer-side wiring.**
+
+## The manifest
+
+A YAML/JSON file (or a Python module exposing `CATALOG`):
+
+```yaml
+version: "1"
+name: my-source
+label: My Source
+ranking_seed: [0.7, 0.7]            # [quality, accessibility] heuristic seed
+functions:
+  - command: get_data
+    frequency: daily
+    parameters: [{name: symbol, type: str, required: true}]
+    columns:
+      - {name: close, type: float, frequency: daily}
+concepts:                           # column -> concept hints (measure/entity_type here)
+  - {column: close, concept: price.close, entity_type: stock, unit: currency, frequency: daily}
+fetch:
+  runner: my-source                  # built-in runner name, OR module: "pkg.mod:run"
+```
+
+See `examples/example_stock.yaml` (declarative) and `examples/example_macro.py`
+(a `DataProvider` class with `run()`).
+
+## Load + validate
+
+```python
+from fd_open_data_protocol.loader import load_catalog
+manifest = load_catalog("examples/example_stock.yaml")
+print(manifest.name, len(manifest.functions))
+```
+
+`load_catalog` accepts a YAML/JSON file path, a `.py` file exposing `CATALOG`,
+a `"pkg.mod"` module path, or a dict.
+
+## Register with fd-open-data-mcp
+
+```bash
+fd-open-data-mcp register-datasource examples/example_stock.yaml
+```
+
+or the MCP tool `register_datasource(path)`.
+
+## Publish a datasource from another project
+
+In your datasource package's `pyproject.toml`:
+
+```toml
+[project.entry-points."fd_open_data_mcp.datasources"]
+my-source = "my_pkg.catalog:CATALOG"
+```
+
+`pip install my-pkg` -> fd-open-data-mcp auto-registers it on `import_catalog`.
+
+## Schema
+
+- **`DatasourceManifest`**: name, label, source_url, scanner_mode, ranking_seed, functions[], concepts[], fetch.
+- **`FunctionSpec`**: command, category, description, parameters[], columns[], frequency, verified.
+- **`ColumnSpec`**: name, type, description, meaning, semantic_type, `frequency` + `datasource` (column-level).
+- **`ConceptHint`**: column, concept, `entity_type`, `measure`, unit, frequency, confidence.
+- **`FetchRef`**: runner (built-in name) | module (`"pkg.mod:func"`).
+
+`measure` + `entity_type` are **concept-level** (disambiguate GDP-nominal vs
+GDP-PPP; stock close vs fund NAV). Column-level `frequency`/`datasource` support
+composite functions whose columns come from different sources at different cadences.
+
+## Template
+
+Copy `template/datasource.template.yaml` (declarative) or
+`template/provider_template.py` (a `BaseDataProvider` class with `run()`).

fd_open_data_protocol-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fd_open_data_protocol/__init__.py,sha256=lj15qAY5NVW7-1dfhfHRwMkNUTS0KFsthJmjsK9kz7c,362
+fd_open_data_protocol/loader.py,sha256=oBzhyNVLriyJoe_oGIOdv-tQatXpeNm-nG-g2WJfkmY,2928
+fd_open_data_protocol/provider.py,sha256=3BGCknL2-FYmpauGXssC_zq9-j3lLznl0SmJY29JmNE,1433
+fd_open_data_protocol/schema.py,sha256=FADg28wE9aozL1AVXDjCHCwajSmEievIrK9y-y2jTKM,2048
+fd_open_data_protocol-0.1.0.dist-info/METADATA,sha256=iGfuX45q5Uydr3ob0rw5eIyq30RM0xNx-A8S5Vyj9ls,3197
+fd_open_data_protocol-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+fd_open_data_protocol-0.1.0.dist-info/top_level.txt,sha256=FYtTIWYkMLzYyUoYKbxJQQU2yozvrWTntfDZ5jKmjvQ,22
+fd_open_data_protocol-0.1.0.dist-info/RECORD,,

fd_open_data_protocol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fd_open_data_protocol-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fd_open_data_protocol