fd-open-data-protocol 0.3.1__tar.gz → 0.3.2__tar.gz

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fd-open-data-protocol
-Version: 0.3.1
+Version: 0.3.2
 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

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/__init__.py

@@ -5,4 +5,4 @@ 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.3.1"
+__version__ = "0.3.2"

fd_open_data_protocol-0.3.2/fd_open_data_protocol/openalex_provider.py

@@ -0,0 +1,213 @@
+"""OpenAlex 学术图谱数据源 provider（CC0，免费）。
+
+契约要点（对应 academic-graph-connector spec）：
+  - 礼貌调用：请求带含 mail 的 User-Agent（免费档 1000 credits/次级）
+  - 失败显式：配额/限流/不可达分别报错，**禁止返回空结果冒充无数据**
+  - 收录偏差：未收录如实标注，不断言「不存在引用」
+  - 引用图是增益，不替代既有 papers 检索
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .provider import BaseDataProvider
+
+API = "https://api.openalex.org"
+DEFAULT_MAILTO = os.environ.get("OPENALEX_MAILTO", "ops@finddata.dev")
+TIMEOUT = float(os.environ.get("OPENALEX_TIMEOUT", "25"))
+
+# 礼貌调用：OpenAlex 要求可识别的 User-Agent（含 mail），否则可能被限流
+UA = f"finddata-academic-connector/1.0 (mailto:{DEFAULT_MAILTO})"
+
+
+class OpenAlexUnavailable(RuntimeError):
+    """上游不可用/不可达——显式失败，不静默返回空。"""
+
+
+class OpenAlexQuotaExceeded(RuntimeError):
+    """配额/限流——显式失败，不冒充「无数据」。"""
+
+
+class OpenAlexProvider(BaseDataProvider):
+    name = "academic-openalex"
+
+    def registry(self) -> dict:
+        return {"manifest": "academic_openalex.yaml"}
+
+    def run(self, command: str, params: dict) -> Any:
+        handlers = {
+            "get_work": self.get_work,
+            "search_works": self.search_works,
+            "get_references": self.get_references,
+            "get_citations": self.get_citations,
+        }
+        if command not in handlers:
+            raise ValueError(f"unknown command {command!r}")
+        return handlers[command](params or {})
+
+    # ------------------------------------------------------------------ HTTP
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> tuple[dict, dict]:
+        """GET 并返回 (payload, quota_headers)。失败显式抛错。"""
+        url = f"{API}/{path}"
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        req = urllib.request.Request(
+            url, headers={"User-Agent": UA, "Accept": "application/json"}
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+                raw = json.loads(resp.read().decode("utf-8", "replace"))
+                headers = dict(resp.headers.items())
+        except urllib.error.HTTPError as exc:
+            # 429 或 5xx 都要区分清楚：前者是配额，后者是上游故障
+            if exc.code == 429:
+                raise OpenAlexQuotaExceeded(
+                    f"OpenAlex rate limit / quota exceeded (HTTP 429): {exc.read()[:200]!r}"
+                ) from exc
+            if 500 <= exc.code < 600:
+                raise OpenAlexUnavailable(
+                    f"OpenAlex upstream unavailable (HTTP {exc.code})"
+                ) from exc
+            raise OpenAlexUnavailable(
+                f"OpenAlex request failed (HTTP {exc.code}): {exc.read()[:200]!r}"
+            ) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise OpenAlexUnavailable(f"OpenAlex unreachable: {exc}") from exc
+        quota = {
+            k.lower(): v
+            for k, v in headers.items()
+            if k.lower().startswith("x-ratelimit") or k.lower() == "retry-after"
+        }
+        return raw, quota
+
+    def _resolve_work_id(self, params: dict) -> str:
+        """按 work_id 或 doi 定位作品。两者皆缺则报错（不猜）。"""
+        work_id = (params.get("work_id") or "").strip()
+        doi = (params.get("doi") or "").strip()
+        if not work_id and not doi:
+            raise ValueError("get_references/get_citations requires `work_id` or `doi`")
+        if work_id:
+            # 允许传完整 URL，统一取末段
+            return work_id.rstrip("/").split("/")[-1]
+        payload, _ = self._get(
+            "works",
+            {"filter": f"doi:{doi}", "select": "id", "per-page": "1"},
+        )
+        results = payload.get("results") or []
+        if not results:
+            raise ValueError(
+                f"work not found in OpenAlex for doi={doi!r} "
+                f"（未收录，不等于该作品不存在）"
+            )
+        return str(results[0]["id"]).rstrip("/").split("/")[-1]
+
+    # ------------------------------------------------------------- commands
+
+    def get_work(self, params: dict) -> dict:
+        doi = (params.get("doi") or "").strip()
+        if not doi:
+            raise ValueError("get_work requires `doi`")
+        payload, quota = self._get(
+            "works", {"filter": f"doi:{doi}", "per-page": "1"}
+        )
+        results = payload.get("results") or []
+        if not results:
+            # 未收录 ≠ 不存在：如实说明
+            raise ValueError(
+                f"work not found in OpenAlex for doi={doi!r} （未收录，不等于该作品不存在）"
+            )
+        w = results[0]
+        return {
+            "work_id": str(w.get("id", "")).rstrip("/").split("/")[-1],
+            "title": w.get("title"),
+            "year": w.get("publication_year"),
+            "venue": (w.get("primary_location") or {}).get("source", {}).get("display_name")
+            if isinstance(w.get("primary_location"), dict)
+            else None,
+            "cited_by_count": w.get("cited_by_count"),
+            "doi": w.get("doi"),
+            "source": "openalex",
+            "license": "CC0",
+            "quota": quota,
+        }
+
+    def search_works(self, params: dict) -> dict:
+        query = (params.get("query") or "").strip()
+        if not query:
+            raise ValueError("search_works requires `query`")
+        limit = int(params.get("limit") or 10)
+        payload, quota = self._get(
+            "works",
+            {
+                "search": query,
+                "per-page": str(min(limit, 200)),
+                "select": "id,title,publication_year,cited_by_count",
+            },
+        )
+        rows = []
+        for w in payload.get("results") or []:
+            rows.append(
+                {
+                    "work_id": str(w.get("id", "")).rstrip("/").split("/")[-1],
+                    "title": w.get("title"),
+                    "year": w.get("publication_year"),
+                    "cited_by_count": w.get("cited_by_count"),
+                }
+            )
+        return {
+            "total": (payload.get("meta") or {}).get("count"),
+            "results": rows,
+            "source": "openalex",
+            "license": "CC0",
+            "quota": quota,
+        }
+
+    def get_references(self, params: dict) -> dict:
+        work_id = self._resolve_work_id(params)
+        payload, quota = self._get(
+            f"works/{work_id}", {"select": "id,referenced_works_count,referenced_works"}
+        )
+        refs = payload.get("referenced_works") or []
+        return {
+            "work_id": work_id,
+            "reference_count": payload.get("referenced_works_count"),
+            "reference_ids": [str(r).rstrip("/").split("/")[-1] for r in refs],
+            "source": "openalex",
+            "license": "CC0",
+            "quota": quota,
+        }
+
+    def get_citations(self, params: dict) -> dict:
+        work_id = self._resolve_work_id(params)
+        limit = int(params.get("limit") or 10)
+        payload, quota = self._get(
+            "works",
+            {
+                "filter": f"cites:{work_id}",
+                "per-page": str(min(limit, 200)),
+                "select": "id,title,publication_year",
+            },
+        )
+        rows = []
+        for w in payload.get("results") or []:
+            rows.append(
+                {
+                    "citing_work_id": str(w.get("id", "")).rstrip("/").split("/")[-1],
+                    "title": w.get("title"),
+                    "year": w.get("publication_year"),
+                }
+            )
+        return {
+            "work_id": work_id,
+            "total_count": (payload.get("meta") or {}).get("count"),
+            "results": rows,
+            "source": "openalex",
+            "license": "CC0",
+            "quota": quota,
+        }

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/concepts.yaml

@@ -12,7 +12,7 @@
 # `variables:` block are declarative only (derivation links to them by code).
 #
 # Entries are never deleted — retirement is expressed with `superseded_by`.
-version: "2026.09"
+version: "2026.11"
 kind: concept
 entries:
   - id: GDP
@@ -228,3 +228,64 @@ entries:
     unit_type: none
     dimensions: []
     variables: []
+
+  - id: TradeFlow
+    label_en: Trade flow value
+    label_zh: 贸易流值
+    description: >-
+      Annual trade flow value (FOB, USD) for a China export commodity at
+      HS6 level, split by partner economy. The partner axis is expressed
+      encoded in the concept code (trade.export_flow.world/us/de/jp/uk,
+      one series per code per the dashboard plane contract); the import
+      side joins when an import batch lands. Source: UN Comtrade annual HS flows.
+    value_type: currency
+    unit_type: currency
+    dimensions: [world, us, de, jp, uk]
+    variables:
+      # 看板取数契约（data_plane.series 只按 code+source+entity 过滤）：
+      # 伙伴国轴编进 concept code，measure 统一 export——一序列一码。
+      - {code: trade.export_flow.world, entity_type: hs_code, measure: export, unit: usd, frequency: yearly}
+      - {code: trade.export_flow.us,    entity_type: hs_code, measure: export, unit: usd, frequency: yearly}
+      - {code: trade.export_flow.de,    entity_type: hs_code, measure: export, unit: usd, frequency: yearly}
+      - {code: trade.export_flow.jp,    entity_type: hs_code, measure: export, unit: usd, frequency: yearly}
+      - {code: trade.export_flow.uk,    entity_type: hs_code, measure: export, unit: usd, frequency: yearly}
+
+  - id: FxRate
+    label_en: FX reference rate
+    label_zh: 汇率参考价
+    description: >-
+      Reference/middle exchange rate for a currency pair, quoted in the
+      quote currency per one unit of base (EURCNY = CNY per 1 EUR).
+      Sources: ECB EXR monthly reference; PBOC middle rate when it lands.
+    value_type: number
+    unit_type: currency
+    dimensions: [reference]
+    variables:
+      - {code: fx.rate, entity_type: currency_pair, measure: reference, unit: cny, frequency: monthly}
+
+  - id: PolicyNotice
+    label_en: Policy notice count
+    label_zh: 政策通报数
+    description: >-
+      WTO TBT/SPS notifications raised per notifying member per month
+      (WTO ePing feed, deduplicated by member+title+date). For
+      cross-border exporters the heat answers "which markets are
+      raising barriers this month".
+    value_type: number
+    unit_type: count
+    dimensions: [tbt_sps]
+    variables:
+      - {code: policy.notice_count, entity_type: country, measure: tbt_sps, unit: count, frequency: monthly}
+
+  - id: PortCalls
+    label_en: Port calls
+    label_zh: 港口停靠数
+    description: >-
+      Daily number of vessel calls at a port (IMF PortWatch). Keyed by
+      the portwatch port id; the cross-border port batch registers the
+      Chinese hub ports only (never offshore-terminal feeds).
+    value_type: number
+    unit_type: count
+    dimensions: [daily_calls]
+    variables:
+      - {code: port.calls, entity_type: port, measure: daily_calls, unit: count, frequency: daily}

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/crosswalks/datacommons-worldbank.yaml

@@ -10,7 +10,7 @@
 #
 # URIs for the mapped Variables themselves are Phase 4; this release carries
 # only family URIs.
-version: "2026.09"
+version: "2026.11"
 kind: crosswalk
 mappings:
   # --- Population -------------------------------------------------------------

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/entity_types.yaml

@@ -7,7 +7,7 @@
 # URIs: https://schema.finddata.tech/entity-type/<id>
 #
 # Entries are never deleted — retirement is expressed with `superseded_by`.
-version: "2026.09"
+version: "2026.11"
 kind: entity-type
 entries:
   - id: country
@@ -97,3 +97,80 @@ entries:
     description: >-
       Human entities — fund managers, officers (logical-only; no taxonomy
       table). Aligns with schema.org Person and the Wikidata QID.
+  - id: paper
+    label_en: Paper
+    label_zh: 论文
+    description: >-
+      Scholarly works — journal articles, conference papers, preprints.
+      Keyed by DOI (10.1038/nature14539) or OpenAlex work id (W2919115771).
+      Aligns with schema.org ScholarlyArticle.
+  - id: author
+    label_en: Author
+    label_zh: 作者
+    description: >-
+      Persons credited as authors of scholarly works. Keyed by OpenAlex
+      author id; distinct from `person` (which carries no scholarly role).
+      Aligns with schema.org Person.
+  - id: institution
+    label_en: Institution
+    label_zh: 机构
+    description: >-
+      Research and academic institutions (universities, research institutes,
+      hospitals) as affiliation targets. Keyed by OpenAlex institution id;
+      aligns with schema.org EducationalOrganization. `organization` covers
+      generic bodies; this type is scoped to scholarly affiliation.
+  - id: venue
+    label_en: Venue
+    label_zh: 发表载体
+    description: >-
+      Publication venues — journals, conference proceedings, repositories.
+      Keyed by ISSN or OpenAlex source id. Aligns with schema.org
+      Periodical; distinct from `organization` (a venue is not a body).
+  - id: topic
+    label_en: Topic
+    label_zh: 主题
+    description: >-
+      Scholarly topics / fields of study (OpenAlex topics, concepts).
+      Keyed by OpenAlex topic id; describes what a work is about.
+  - id: customs_regime
+    label_en: Customs regime code
+    label_zh: 海关监管代码
+    description: >-
+      China customs supervision regime codes for cross-border e-commerce
+      (9610 retail export, 1210 bonded, 9710 B2B direct export, 9810
+      overseas-warehouse export). Keyed by the 4-digit regime code.
+  - id: platform
+    label_en: E-commerce platform
+    label_zh: 电商平台
+    description: >-
+      Cross-border e-commerce marketplace platforms (amazon, tiktok_shop,
+      temu, shein). Keyed by FindData shorthand; marketplace/store detail
+      lives in metadata. Merchant-authorized data is keyed here.
+  - id: hs_code
+    label_en: HS commodity code
+    label_zh: HS 商品编码
+    description: >-
+      Harmonized System commodity classifications keyed by 2/4/6-digit HS
+      code (854142). WCO nomenclature; China tariff lines extend to 8-10
+      digits on top of the HS6 base.
+  - id: currency_pair
+    label_en: Currency pair
+    label_zh: 货币对
+    description: >-
+      FX pairs keyed by base+quote ISO codes concatenated (EURCNY). Rate
+      concepts carry reference/middle rates per source; value unit is the
+      quote currency.
+  - id: port
+    label_en: Port
+    label_zh: 口岸
+    description: >-
+      Customs ports and logistics gateways keyed by UN/LOCODE or customs
+      port code. Reserved for the cross-border port batch (authoritative
+      port-code list pending; do not seed from offshore-terminal feeds).
+  - id: policy
+    label_en: Policy entry
+    label_zh: 政策条目
+    description: >-
+      Individual policy/instrument entries (customs announcements, tax
+      notices) keyed by issuing-body document id. Registered incrementally
+      as policy patrol output lands.

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/event_types.yaml

@@ -12,6 +12,6 @@
 # URIs: https://schema.finddata.tech/event-type/<id>
 #
 # Entries are never deleted — retirement is expressed with `superseded_by`.
-version: "2026.09"
+version: "2026.11"
 kind: event-type
 entries: []

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/qualifiers.yaml

@@ -8,7 +8,7 @@
 # URIs: https://schema.finddata.tech/qualifier/<id>
 #
 # Entries are never deleted — retirement is expressed with `superseded_by`.
-version: "2026.09"
+version: "2026.11"
 kind: qualifier
 entries:
   - id: nominal_current

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/relation_types.yaml

@@ -9,7 +9,7 @@
 # URIs: https://schema.finddata.tech/relation-type/<id>
 #
 # Entries are never deleted — retirement is expressed with `superseded_by`.
-version: "2026.09"
+version: "2026.11"
 kind: relation-type
 entries:
   - id: belongs_to
@@ -71,3 +71,48 @@ entries:
       The instrument was issued by the entity (stock/bond/fund -> company).
     source_types: [stock, bond, fund]
     target_types: [company, organization]
+  - id: cites
+    label_en: Cites
+    label_zh: 引用
+    description: >-
+      The source work cites the target work in its bibliography
+      (paper -> paper). Directional: source references target.
+    source_types: [paper]
+    target_types: [paper]
+  - id: cited_by
+    label_en: Cited By
+    label_zh: 被引
+    description: >-
+      Inverse of `cites` — the source work is cited by the target work
+      (paper -> paper). Retained explicitly because external scholarly
+      APIs expose both directions as distinct queries.
+    source_types: [paper]
+    target_types: [paper]
+  - id: authored_by
+    label_en: Authored By
+    label_zh: 作者为
+    description: >-
+      The work was authored by the person (paper -> author).
+    source_types: [paper]
+    target_types: [author]
+  - id: affiliated_with
+    label_en: Affiliated With
+    label_zh: 隶属于
+    description: >-
+      The author is affiliated with the institution (author -> institution).
+    source_types: [author]
+    target_types: [institution]
+  - id: published_in
+    label_en: Published In
+    label_zh: 发表于
+    description: >-
+      The work was published in the venue (paper -> venue).
+    source_types: [paper]
+    target_types: [venue]
+  - id: has_topic
+    label_en: Has Topic
+    label_zh: 主题为
+    description: >-
+      The work is classified under the topic (paper -> topic).
+    source_types: [paper]
+    target_types: [topic]

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol/vocabulary/units.yaml

@@ -8,7 +8,7 @@
 # URIs: https://schema.finddata.tech/unit/<id>
 #
 # Entries are never deleted — retirement is expressed with `superseded_by`.
-version: "2026.09"
+version: "2026.11"
 kind: unit
 entries:
   # --- Monetary ---------------------------------------------------------------
@@ -92,3 +92,10 @@ entries:
     label_zh: 年
     description: A duration measured in calendar years.
     un_cefact_code: ANN
+
+  - id: count
+    label_en: Count
+    label_zh: 计数
+    description: >-
+      Dimensionless tally of discrete events or items (notifications, port
+      calls). Used where the value is a number of things, not a measurement.

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fd-open-data-protocol
-Version: 0.3.1
+Version: 0.3.2
 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

{fd_open_data_protocol-0.3.1 → fd_open_data_protocol-0.3.2}/fd_open_data_protocol.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 fd_open_data_protocol/__init__.py
 fd_open_data_protocol/constants.py
 fd_open_data_protocol/loader.py
+fd_open_data_protocol/openalex_provider.py
 fd_open_data_protocol/provider.py
 fd_open_data_protocol/registry.py
 fd_open_data_protocol/registry_cli.py
@@ -23,6 +24,7 @@ fd_open_data_protocol/vocabulary/relation_types.yaml
 fd_open_data_protocol/vocabulary/units.yaml
 fd_open_data_protocol/vocabulary/crosswalks/datacommons-worldbank.yaml
 tests/test_loader.py
+tests/test_openalex_provider.py
 tests/test_registry_pipeline.py
 tests/test_registry_schema.py
 tests/test_schema_vocabulary.py

fd_open_data_protocol-0.3.2/tests/test_openalex_provider.py

@@ -0,0 +1,170 @@
+"""OpenAlex provider：离线测试（不访问网络）。
+
+覆盖契约要点：礼貌调用、四项命令、失败显式（配额/限流/不可达）、
+收录偏差如实标注、CC0 归属。
+"""
+from __future__ import annotations
+
+import urllib.error
+
+import pytest
+
+from fd_open_data_protocol import openalex_provider as oa
+
+
+class FakeResp:
+    def __init__(self, headers=None):
+        self.headers = headers or {}
+
+    def read(self):
+        return b"boom"
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def close(self):
+        return None
+
+    def items(self):
+        return list(self.headers.items())
+
+
+def test_polite_user_agent_carries_mailto():
+    assert "mailto:" in oa.UA
+    assert "@" in oa.UA.split("mailto:")[-1].strip(")")
+
+
+def test_quota_headers_recorded(monkeypatch):
+    payload = {
+        "results": [
+            {
+                "id": "https://openalex.org/W1",
+                "title": "T",
+                "publication_year": 2020,
+                "cited_by_count": 5,
+                "doi": "10.1/x",
+            }
+        ]
+    }
+
+    def fake_urlopen(req, timeout=None):
+        assert req.headers.get("User-agent") == oa.UA or req.get_header("User-agent") == oa.UA
+        return _json_resp(payload, {"x-ratelimit-limit": "1000"})
+
+    monkeypatch.setattr(oa.urllib.request, "urlopen", fake_urlopen)
+    out = oa.OpenAlexProvider().run("get_work", {"doi": "10.1/x"})
+    assert out["quota"]["x-ratelimit-limit"] == "1000"
+    assert out["source"] == "openalex" and out["license"] == "CC0"
+
+
+def _json_resp(payload, headers=None):
+    class R:
+        def __init__(self):
+            self.headers = _H(headers or {})
+
+        def read(self):
+            return __import__("json").dumps(payload).encode()
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+    class _H(dict):
+        def items(self):
+            return list(dict.items(self))
+
+    return R()
+
+
+def test_search_works_returns_total_and_rows(monkeypatch):
+    payload = {
+        "meta": {"count": 42},
+        "results": [
+            {"id": "https://openalex.org/Wa", "title": "A", "publication_year": 2017,
+             "cited_by_count": 7},
+            {"id": "https://openalex.org/Wb", "title": "B", "publication_year": 2019,
+             "cited_by_count": 9},
+        ],
+    }
+    monkeypatch.setattr(oa.urllib.request, "urlopen",
+                        lambda req, timeout=None: _json_resp(payload))
+    out = oa.OpenAlexProvider().run("search_works", {"query": "q", "limit": 2})
+    assert out["total"] == 42 and len(out["results"]) == 2
+    assert out["results"][0]["work_id"] == "Wa"
+
+
+def test_references_and_citations(monkeypatch):
+    p = oa.OpenAlexProvider()
+    monkeypatch.setattr(oa.urllib.request, "urlopen", lambda req, timeout=None: _json_resp(
+        {"id": "https://openalex.org/W1", "referenced_works_count": 2,
+         "referenced_works": ["https://openalex.org/Wx", "https://openalex.org/Wy"]}))
+    r = p.run("get_references", {"work_id": "W1"})
+    assert r["reference_count"] == 2 and r["reference_ids"] == ["Wx", "Wy"]
+
+    monkeypatch.setattr(oa.urllib.request, "urlopen", lambda req, timeout=None: _json_resp(
+        {"meta": {"count": 100},
+         "results": [{"id": "https://openalex.org/Wc", "title": "C", "publication_year": 2021}]}))
+    c = p.run("get_citations", {"work_id": "W1", "limit": 1})
+    assert c["total_count"] == 100 and c["results"][0]["citing_work_id"] == "Wc"
+
+
+def test_quota_error_is_explicit(monkeypatch):
+    def raise_429(req, timeout=None):
+        raise urllib.error.HTTPError("u", 429, "Too Many Requests", {}, FakeResp())
+
+    monkeypatch.setattr(oa.urllib.request, "urlopen", raise_429)
+    with pytest.raises(oa.OpenAlexQuotaExceeded):
+        oa.OpenAlexProvider().run("get_work", {"doi": "10.1/x"})
+
+
+def test_upstream_5xx_is_explicit(monkeypatch):
+    def raise_503(req, timeout=None):
+        raise urllib.error.HTTPError("u", 503, "Unavailable", {}, FakeResp())
+
+    monkeypatch.setattr(oa.urllib.request, "urlopen", raise_503)
+    with pytest.raises(oa.OpenAlexUnavailable):
+        oa.OpenAlexProvider().run("get_work", {"doi": "10.1/x"})
+
+
+def test_unreachable_is_explicit(monkeypatch):
+    def raise_urlerr(req, timeout=None):
+        raise urllib.error.URLError("dns fail")
+
+    monkeypatch.setattr(oa.urllib.request, "urlopen", raise_urlerr)
+    with pytest.raises(oa.OpenAlexUnavailable):
+        oa.OpenAlexProvider().run("get_work", {"doi": "10.1/x"})
+
+
+def test_not_found_states_not_indexed_not_nonexistent(monkeypatch):
+    """未收录必须如实说明——不断言「不存在」。"""
+    monkeypatch.setattr(oa.urllib.request, "urlopen",
+                        lambda req, timeout=None: _json_resp({"results": []}))
+    with pytest.raises(ValueError, match="未收录"):
+        oa.OpenAlexProvider().run("get_work", {"doi": "10.1/nope"})
+
+
+def test_missing_identifier_rejected():
+    p = oa.OpenAlexProvider()
+    with pytest.raises(ValueError):
+        p.run("get_references", {})
+    with pytest.raises(ValueError):
+        p.run("get_work", {})
+
+
+def test_manifest_validates_and_declares_relationships():
+    from fd_open_data_protocol.loader import load_catalog
+
+    m = load_catalog("adapters/academic_openalex.yaml")
+    cmds = {f.command for f in m.functions}
+    assert {"get_work", "search_works", "get_references", "get_citations"} <= cmds
+    rels = {(r.relation_type, r.source_entity_type, r.target_entity_type)
+            for r in (m.relationships or [])}
+    assert ("cites", "paper", "paper") in rels
+    assert ("cited_by", "paper", "paper") in rels
+    ents = {e.entity_type for e in (m.entities or [])}
+    assert {"paper", "author", "venue", "topic", "institution"} <= ents