agentdata 0.3.26__py3-none-any.whl

agentdata/research/nsf.py

@@ -0,0 +1,68 @@
+"""nsf — NSF Awards API (US NSF funding search; keyless).
+
+No key needed (upstream states no keyless quota — self-imposed polite tier of 1 rps/burst 5).
+Double response shell: the payload sits inside {"response": {"award": [...]}} (probed
+2026-10-26); keyword full-text search × id award-number point lookup — upstream actually
+combines them with AND (measured 0.2.9), the local XOR is a sugar-split wall;
+rpp 1-200 (upstream API doc wall, row-count re-verified 2026-10-28);
+upstream sends no total — a full page signals more via has_more (len(rows)==rpp).
+"""
+provider = {
+    "id": "nsf",
+    "baseUrl": "https://api.nsf.gov",
+    "rate": {"rps": 1, "burst": 5},
+    "ops": {
+        "awards": {"path": "/services/v1/awards.json", "method": "GET", "idempotent": True},
+    },
+    "ttl": {"awards": 24 * 3600},
+}
+
+
+def _award_row(a):
+    return {
+        "id": a.get("id"), "title": a.get("title"), "agency": a.get("agency"),
+        "date": a.get("date"), "start_date": a.get("startDate"), "exp_date": a.get("expDate"),
+        "amount": a.get("amount"), "principal_investigator": a.get("pi"),
+        "institution": a.get("institution"), "organization": a.get("organization"),
+        "fund_program": a.get("fundProgramName"), "cfda": a.get("cfda"),
+        "abstract_text": a.get("abstractText"), "award_notice_url": a.get("awardNoticeUrl"),
+    }
+
+
+def awards_raw(keyword=None, *, id=None, rpp=25, offset=0, cache=None, no_cache=False):
+    """→ {total(=None, upstream sends no count), count, rows, has_more, params, _meta}; awards.json direct, verbatim name.
+    keyword XOR id (**a local wall, not upstream** — measured 2026-10-28 upstream combines with
+    AND: keyword=lithium&id=2624369→1 row, the intersection hit; sending both neither 400s nor
+    first-wins; the local XOR is a deliberate split between the full-text and point-lookup
+    channels); rpp 1-200 (upstream API doc; row-count re-verified 2026-10-28, rpp=200 truly
+    sends 200 rows); offset ≥0; an empty keyword semantically means browse-the-corpus (legal
+    upstream), no local wall here."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    kw = str(keyword or "").strip() or None
+    aid = str(id or "").strip() or None
+    if kw and aid:
+        raise SdkError("usage_error", provider="nsf",
+                       detail="pass only one of keyword (full-text search) or id (award-number "
+                              "point lookup) (local sugar-split wall — upstream actually combines "
+                              "them with AND into the intersection, probed 2026-10-28)")
+    if not kw and not aid:
+        raise SdkError("usage_error", provider="nsf",
+                       detail="nsf_awards requires at least one of keyword or id")
+    size = int(rpp)
+    if not 1 <= size <= 200:
+        raise SdkError("usage_error", provider="nsf",
+                       detail="rpp must be 1-200 (upstream API doc page-size cap)")
+    off = int(offset)
+    if off < 0:
+        raise SdkError("usage_error", provider="nsf", detail="offset must be ≥0")
+    params = {"rpp": size, "offset": off}
+    if kw:
+        params["keyword"] = kw
+    else:
+        params["id"] = aid
+    r = call_provider(provider, "awards", params, cache=cache, no_cache=no_cache)
+    rows = [_award_row(a) for a in ((r["data"] or {}).get("response") or {}).get("award") or []]
+    return {"total": None, "count": len(rows), "rows": rows,
+            "has_more": len(rows) == size, "params": params, "_meta": r}

agentdata/research/openalex.py

@@ -0,0 +1,145 @@
+"""openalex — OpenAlex API (global scholarly output and institution profiles; keyless).
+
+No key needed (official polite pool 10 rps, self-imposed polite tier of 5 rps). Two faces
+(probed 2026-10-26): works = paper rows (filter=institutions.ror: reaches the institution
+edge; rows link back through authorships[].institutions[].ror); institutions = institution
+candidates (search= is a fuzzy name search, same-name clones in different countries coexist —
+the candidate list is never auto-picked, pick the ROR explicitly and then query output on the
+works face, adversarial-review constraint 1).
+Three traps: per-page>200 is an explicit 400 (an honest wall, enforced locally); select must
+force-merge the core fields (stripping them drops the edges, adversarial-review constraint 2);
+the cursor (meta.next_cursor) encodes paging only, not the conditions — when continuing you
+must re-send the constraint parameters unchanged (adversarial-review constraint 3; this
+wrapper satisfies it naturally by requiring at least one constraint).
+"""
+provider = {
+    "id": "openalex",
+    "baseUrl": "https://api.openalex.org",
+    "rate": {"rps": 5, "burst": 5},  # quota semantics 5+5=10 ≤ the official 10 req/s (with burst 10 the 10+5=15 would exceed the cap, fixed on re-check in 0.2.5)
+    "ops": {
+        "works": {"path": "/works", "method": "GET", "idempotent": True},
+        "institutions": {"path": "/institutions", "method": "GET", "idempotent": True},
+    },
+    "ttl": {"works": 24 * 3600, "institutions": 24 * 3600},
+}
+
+_PER_PAGE_CAP = 200  # per-page>200 gets an explicit upstream 400 (probe 2026-10-26)
+_CORE_FIELDS = "id,doi,display_name,publication_year,type,cited_by_count,open_access,authorships"
+
+
+def _norm_ror(ror):
+    """ROR normalization: both the bare 15-char form (01xdqrp08) and the full URL
+    (https://ror.org/01xdqrp08) are accepted, both normalize to the full URL."""
+    v = str(ror or "").strip()
+    if not v:
+        return None
+    if v.startswith("https://ror.org/"):
+        return v
+    if v.startswith("ror.org/"):
+        return "https://" + v
+    return f"https://ror.org/{v}"
+
+
+def _work_row(w):
+    return {
+        "id": w.get("id"), "doi": w.get("doi"), "display_name": w.get("display_name"),
+        "publication_year": w.get("publication_year"), "type": w.get("type"),
+        "cited_by_count": w.get("cited_by_count"),
+        "open_access": w.get("open_access") or {},
+        "authorships": [{"position": a.get("author_position"),
+                         "author": (a.get("author") or {}).get("display_name"),
+                         "raw_author_name": a.get("raw_author_name"),
+                         "is_corresponding": a.get("is_corresponding"),
+                         "institutions": [{"ror": i.get("ror"), "display_name": i.get("display_name"),
+                                           "country_code": i.get("country_code")}
+                                          for i in a.get("institutions") or []],
+                         "countries": a.get("countries")}
+                        for a in w.get("authorships") or []],
+    }
+
+
+def works_raw(search=None, *, ror=None, doi=None, title_search=None,
+              per_page=25, cursor=None, select=None, cache=None, no_cache=False):
+    """→ {total, count, rows, next_cursor, params, _meta}; /works direct, verbatim name.
+    search full-text × ror (exact institutions.ror) × doi × title_search (title.search) — the
+    four constraints combine with AND into filter; at least one constraint (local wall: a
+    cursor is not a constraint, a bare whole-corpus scan is served by the bulk pipeline);
+    per_page 1-200 (explicit upstream 400 wall); cursor=meta.next_cursor to continue (it
+    encodes paging only, the constraint parameters must be re-sent unchanged); select is
+    force-merged with the core fields."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(search or "").strip() or None
+    r_v = _norm_ror(ror)
+    d_v = str(doi or "").strip() or None
+    t_v = str(title_search or "").strip() or None
+    if not (q or r_v or d_v or t_v):
+        raise SdkError("usage_error", provider="openalex",
+                       detail="openalex_works requires at least one of search/ror/doi/title_search"
+                              " (a cursor is not a constraint; local safety wall: a bare whole-corpus "
+                              "scan is served by the bulk pipeline)")
+    pp = int(per_page)
+    if not 1 <= pp <= _PER_PAGE_CAP:
+        raise SdkError("usage_error", provider="openalex",
+                       detail=f"per_page must be 1-{_PER_PAGE_CAP} (explicit upstream 400 wall, confirmed by probing 2026-10-26)")
+    filters = []
+    if r_v:
+        filters.append(f"institutions.ror:{r_v}")
+    if d_v:
+        filters.append(f"doi:{d_v}")
+    if t_v:
+        filters.append(f"title.search:{t_v}")
+    params = {"per-page": pp}
+    if q:
+        params["search"] = q
+    if filters:
+        params["filter"] = ",".join(filters)
+    cur = str(cursor or "").strip() or None
+    if cur:
+        params["cursor"] = cur
+    sel = {x.strip() for x in (select if isinstance(select, (list, tuple))
+                               else str(select or "").split(",")) if x and str(x).strip()}
+    params["select"] = ",".join(sorted(sel | set(_CORE_FIELDS.split(","))))
+    r = call_provider(provider, "works", params, cache=cache, no_cache=no_cache)
+    data = r["data"] or {}
+    meta = data.get("meta") or {}
+    rows = [_work_row(w) for w in data.get("results") or []]
+    return {"total": meta.get("count"), "count": len(rows), "rows": rows,
+            "next_cursor": meta.get("next_cursor"), "params": params, "_meta": r}
+
+
+def _institution_row(i):
+    return {
+        "id": i.get("id"), "ror": i.get("ror"), "display_name": i.get("display_name"),
+        "country_code": i.get("country_code"), "type": i.get("type"),
+        "works_count": i.get("works_count"), "cited_by_count": i.get("cited_by_count"),
+        "relevance_score": i.get("relevance_score"),
+        "homepage_url": i.get("homepage_url"),
+    }
+
+
+def institutions_raw(search, *, per_page=25, cache=None, no_cache=False):
+    """→ {total, count, rows, params, _meta}; /institutions?search= direct, verbatim name.
+    search required (local wall); per_page 1-200 (same wall as works).
+    Rows = institution candidate cards (ror/type/works_count); same-name clones in different
+    countries coexist (a pfizer probe returned 24 candidates incl. US/UK/FR) — the first one is
+    never auto-picked; pick the ROR explicitly and then query output via openalex_works
+    (adversarial-review constraint 1)."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(search or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="openalex", detail="openalex_institutions requires search (institution name)")
+    pp = int(per_page)
+    if not 1 <= pp <= _PER_PAGE_CAP:
+        raise SdkError("usage_error", provider="openalex",
+                       detail=f"per_page must be 1-{_PER_PAGE_CAP} (explicit upstream 400 wall)")
+    params = {"search": q, "per-page": pp}
+    r = call_provider(provider, "institutions", params, cache=cache, no_cache=no_cache)
+    data = r["data"] or {}
+    meta = data.get("meta") or {}
+    rows = [_institution_row(i) for i in data.get("results") or []]
+    return {"total": meta.get("count"), "count": len(rows), "rows": rows,
+            "params": params, "_meta": r}

agentdata/research/opencitations.py

@@ -0,0 +1,50 @@
+"""opencitations — OpenCitations COCI (open citation index; keyless).
+
+No key needed (migrated to the new host api.opencitations.net/index/v1/ — the old
+opencitations.org paths 301 here). citations face (probed 2026-10-26): GET /citations/{doi}
+(the DOI carries **no** doi: prefix; with it you get a 400 whose error body reports the
+correct format); **the limit parameter is silently ignored** (?limit=3 still returns all 217
+rows — one more case of an upstream silent clamp), so this face sets no limit and returns the
+full list plus a count.
+Row keys: oci/citing/cited/creation/timespan/journal_sc/author_sc.
+"""
+provider = {
+    "id": "opencitations",
+    "baseUrl": "https://api.opencitations.net",
+    "rate": {"rps": 1, "burst": 5},  # small academic-service tier (same as osv/nsf; COCI is single-shot with no paging, naturally low traffic)
+    "ops": {
+        "citations": {"path": "/index/v1/citations/{doi}", "method": "GET", "idempotent": True},
+    },
+    "ttl": {"citations": 24 * 3600},
+}
+
+
+def _norm_doi(doi):
+    """DOI normalization: strip the doi: prefix (upstream 400 wall — the error body itself
+    reports the prefix-less format)."""
+    v = str(doi or "").strip().lower()
+    if v.startswith("doi:"):
+        v = v[4:].strip()
+    if v.startswith("https://doi.org/"):
+        v = v[len("https://doi.org/"):]
+    if v.startswith("doi.org/"):
+        v = v[len("doi.org/"):]
+    return v or None
+
+
+def citations_raw(doi, *, cache=None, no_cache=False):
+    """→ {doi, count, rows, params, _meta}; /index/v1/citations/{doi} direct, verbatim name
+    (full list). doi required (doi: prefix/doi.org URL normalized away automatically); the
+    upstream limit parameter is silently ignored (probe: ?limit=3 still returned all 217
+    rows) — no fake pagination, the full list comes back."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    v = _norm_doi(doi)
+    if not v:
+        raise SdkError("usage_error", provider="opencitations",
+                       detail="opencitations_citations requires doi (the cited DOI; the doi: prefix is auto-stripped)")
+    params = {"doi": v}
+    r = call_provider(provider, "citations", params, cache=cache, no_cache=no_cache)
+    rows = r["data"] or []
+    return {"doi": v, "count": len(rows), "rows": rows, "params": params, "_meta": r}

agentdata/security/__init__.py

@@ -0,0 +1,3 @@
+"""security domain package — provider adapters laid flat (one source per file) + faces/cli (0.2.6 per-domain split).
+"""
+from . import cisa_kev, osv  # noqa: F401

agentdata/security/cisa_kev.py

@@ -0,0 +1,42 @@
+"""cisa_kev — CISA Known Exploited Vulnerabilities (KEV) Catalog provider (catalog of vulnerabilities
+exploited in the wild; keyless).
+
+Keyless static feed (~1.8MB single shot, probed 2026-10-26, count=1756). Upstream takes no query params —
+all cve/ransomware filtering is a **local post-filter** (echoed in input; upstream stays pure with empty params).
+The catalog updates at weekly cadence (the catalogVersion date stamp goes into reason).
+"""
+provider = {
+    "id": "cisa-kev",
+    "baseUrl": "https://www.cisa.gov",
+    "rate": {"rps": 0.25, "burst": 2},
+    "ops": {
+        "catalog": {"path": "/sites/default/files/feeds/known_exploited_vulnerabilities.json",
+                    "method": "GET", "idempotent": True},
+    },
+    "ttl": {"catalog": 24 * 3600},
+}
+
+
+def _row(v):
+    return {
+        "cve_id": v.get("cveID"), "vendor_project": v.get("vendorProject"),
+        "product": v.get("product"), "vulnerability_name": v.get("vulnerabilityName"),
+        "date_added": v.get("dateAdded"), "due_date": v.get("dueDate"),
+        "known_ransomware_campaign_use": v.get("knownRansomwareCampaignUse"),
+        "short_description": v.get("shortDescription"),
+        "required_action": v.get("requiredAction"), "notes": v.get("notes"),
+        "cwes": v.get("cwes") or [],
+    }
+
+
+def catalog_raw(*, cache=None, no_cache=False):
+    """→ {catalog_version, date_released, count_total, vulnerabilities, _meta}; the feed reshaped as-is.
+    No upstream params (static feed); the local post-filter happens at the face layer (the provider keeps the
+    zero-hidden-params discipline)."""
+    from ..transport import call_provider
+
+    r = call_provider(provider, "catalog", {}, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    vulns = [_row(v) for v in d.get("vulnerabilities") or []]
+    return {"catalog_version": d.get("catalogVersion"), "date_released": d.get("dateReleased"),
+            "count_total": d.get("count"), "vulnerabilities": vulns, "_meta": r}

agentdata/security/cli.py

@@ -0,0 +1,37 @@
+"""security cli — domain command registration (split per domain in 0.2.6, moved in from the root cli.py).
+
+register(v, g): registers the flat commands on the domain subparser (g = the root _leaf_globals factory,
+passed in to avoid a cli↔domain-cli cycle); FLAT = the flat dispatch table, merged by the root cli for main.
+"""
+import argparse
+
+def register(v, g):
+    f1 = v.add_parser("cisa_kev_catalog", parents=[g()],
+                      description="CISA Known Exploited Vulnerabilities catalog (realtime, local execution; static feed ~1.8MB; --cve and --ransomware are local post-filters, upstream stays empty-param pure; catalog updates weekly, catalogVersion echoed in reason)")
+    f1.add_argument("--cve", default=None, help="CVE id exact lookup (local filter, e.g. CVE-2021-44228)")
+    f1.add_argument("--ransomware", action="store_true",
+                    help="Only entries with known ransomware campaign use (local filter)")
+    f1.add_argument("--limit", type=int, default=50, help="Rows to return (default 50; full catalog ~1,756 rows — page instead of dumping)")
+
+    f2 = v.add_parser("osv_vulns", parents=[g()],
+                      description="Open-source package vulnerability query (realtime, local execution; OSV /v1/query POST; ecosystem is a closed set validated locally because upstream silently returns empty for unknown values; version omitted = all known vulns for the package)")
+    f2.add_argument("--package", required=True, help="Package name (e.g. lodash)")
+    f2.add_argument("--ecosystem", required=True,
+                    help="OSV ecosystem (npm/PyPI/Go/Maven/crates.io/RubyGems/NuGet/Packagist/Debian/Alpine/Linux/OSS-Fuzz/Hex/Pub/Conda/Android/GitHub Actions)")
+    f2.add_argument("--version", default=None, help="Package version (omit = all known vulns)")
+    f2.add_argument("--page-token", dest="page_token", default=None,
+                    help="Continuation token from a prior response's result.next_page_token (upstream paginates at >1000 vulns or >20s)")
+
+FLAT = {
+    "cisa_kev_catalog": lambda a: {"cve": a.cve, "ransomware": a.ransomware, "limit": a.limit},
+    "osv_vulns": lambda a: {"package": a.package, "ecosystem": a.ecosystem,
+                            "version": a.version, "page_token": a.page_token},
+}
+
+
+# 0.3.10 jurisdiction chapter: face -> jurisdiction (default = the issuing authority's jurisdiction;
+# institutions covering global phenomena = GLOBAL; vocabulary = ISO-3166 alpha-2 + EU + GLOBAL) — the root cli.py merges this into _JURISDICTION; the success envelope carries a jurisdiction chapter
+COUNTRY = {
+    "cisa_kev_catalog": "US",
+    "osv_vulns": "GLOBAL",
+}

agentdata/security/faces.py

@@ -0,0 +1,91 @@
+"""security faces — flat face-method mixin (split per domain in 0.2.6, moved in from client.py _Domain).
+
+Mixed into the root _Domain (assembled via MRO, see client.py); discipline: no __init__, depends only on the
+root internals (_flat_env/_c/_request…), method names globally unique across domains (a collision
+would shadow another domain's face).
+"""
+from ..errors import SdkError
+
+
+from .. import security  # domain-module path call (historical shape, kept for minimal disturbance)
+
+class SecurityFaces:
+    def _security_only(self, tool: str):
+        if self.name != "security":
+            raise SdkError("usage_error", detail=f"{tool} is a security-domain capability (not available on the {self.name} domain)")
+
+    def osv_vulns(self, *, package, ecosystem, version=None, page_token=None,
+                  execution=None, no_cache=None):
+        """security osv_vulns: open-source package vulnerability query (OSV /v1/query POST with verbatim
+        param names; ecosystem closed-set check — upstream silently returns empty for unknown values, so the
+        false-negative guard lives locally; version may be omitted = all known vulns;
+        paging: a next_page_token present in the response = more to fetch, pass page_token back verbatim to
+        continue — upstream paginates past >1000 vulns or >20s (probed 2026-10-28: Linux/Kernel 2719 rows
+        with a token)."""
+        self._security_only("osv_vulns")
+        r = security.osv.query_raw(package, ecosystem, version=version, page_token=page_token,
+                                    cache=self._c._cache,
+                                    no_cache=self._c.no_cache if no_cache is None else bool(no_cache))
+        result = {k: x for k, x in r.items() if k != "_meta"}
+        pk = r["params"]["package"]
+        ver = r["params"].get("version")
+        top = (result["vulns"] or [None])[0]
+        return self._flat_env(
+            tool="osv_vulns",
+            input={"package": pk["name"], "ecosystem": pk["ecosystem"],
+                   "version": ver, "page_token": r["params"].get("page_token")},
+            reason=(f"OSV: {pk['ecosystem']} package \"{pk['name']}\""
+                    + (f"@{ver} " if ver else "")
+                    + f" has {result['count']} known vulnerabilities"
+                    + (f", top concern {top['id']} ({top['summary'] or '—'})" if top else " (zero hits = no known vulnerabilities recorded for this version)")
+                    + (" (more available — pass result.next_page_token back as --page-token to continue)" if result.get("next_page_token") else "")),
+            result=result,
+            evidence=[{"quote": f"{v['id']} = {v['summary'] or '—'}"
+                                + (f" (alias {'/'.join(v['aliases'][:2])})" if v["aliases"] else ""),
+                       "url": v["advisory_url"] or f"https://osv.dev/vulnerability/{v['id']}"}
+                      for v in result["vulns"][:5]],
+            provider_id="osv", metas=[r["_meta"]],
+            query={"source": "raw", "upstream": r["params"]},
+        )
+
+    def cisa_kev_catalog(self, *, cve=None, ransomware=None, limit=50,
+                         execution=None, no_cache=None):
+        """security cisa_kev_catalog: the CISA catalog of vulnerabilities exploited in the wild (static feed
+        ~1.8MB; cve exact lookup / ransomware=True lists only known ransomware use — both are local
+        post-filters, upstream always stays pure with empty params; the catalog updates weekly, catalogVersion
+        goes into reason)."""
+        self._security_only("cisa_kev_catalog")
+        r = security.cisa_kev.catalog_raw(cache=self._c._cache,
+                                      no_cache=self._c.no_cache if no_cache is None else bool(no_cache))
+        all_rows = r["vulnerabilities"]
+        rows = all_rows
+        if ransomware:
+            rows = [v for v in rows if v["known_ransomware_campaign_use"] == "Known"]
+        cv = str(cve or "").strip().upper() or None
+        if cv:
+            rows = [v for v in rows if (v["cve_id"] or "").upper() == cv]
+        rows = rows[:max(1, int(limit))]
+        result = {"catalog_version": r["catalog_version"], "date_released": r["date_released"],
+                  "count_total": r["count_total"], "count": len(rows), "vulnerabilities": rows}
+        filters = []
+        if cv:
+            filters.append(f"CVE {cv}")
+        if ransomware:
+            filters.append("ransomware use on record")
+        return self._flat_env(
+            tool="cisa_kev_catalog",
+            input={"cve": cve, "ransomware": bool(ransomware), "limit": int(limit)},
+            reason=(f"CISA KEV catalog v{r['catalog_version']} (released {r['date_released'] or '—'}, "
+                    f"{r['count_total']} entries in total)"
+                    + (f", {len(rows)} entries matching {'+'.join(filters)}" if filters else f", returning the first {len(rows)} entries")
+                    + " — proven exploitation in the wild = the highest CVE priority tier"),
+            result=result,
+            evidence=[{"quote": f"{v['cve_id']} = {v['vendor_project'] or '—'} {v['product'] or '—'}: "
+                                f"{v['vulnerability_name'] or '—'}"
+                                + (" (ransomware use on record)" if v["known_ransomware_campaign_use"] == "Known" else ""),
+                       "url": f"https://nvd.nist.gov/vuln/detail/{v['cve_id']}"}
+                      for v in result["vulnerabilities"][:5]],
+            provider_id="cisa-kev", metas=[r["_meta"]],
+            query=({**({"source": "assembled", "assembled_from": {"cve": cv, "ransomware": bool(ransomware)}}),
+                    "upstream": {}} if (cv or ransomware) else {"source": "raw", "upstream": {}}),
+        )

agentdata/security/osv.py

@@ -0,0 +1,72 @@
+"""osv — OSV.dev API provider (open-source package vulnerability queries; keyless).
+
+Keyless (the api.osv.dev public query face, polite rate 1 rps). POST /v1/query:
+package{name,ecosystem}+version (version may be omitted = all known vulns for the package — upstream semantics);
+upstream returns an empty vulns[] for an unknown ecosystem (**a silent false negative**) — this face blocks that
+with a closed-set check locally (the OSV docs enumeration).
+The single-vuln detail face is GET /v1/vulns/{id} (keyless); no face stood up for it this round
+(the screening face already covers the use cases).
+"""
+provider = {
+    "id": "osv",
+    "baseUrl": "https://api.osv.dev",
+    "rate": {"rps": 1, "burst": 5},
+    "ops": {
+        "query": {"path": "/v1/query", "method": "POST", "idempotent": True},
+    },
+    "ttl": {"query": 24 * 3600},
+}
+
+# OSV docs ecosystem enumeration (normalized case-insensitively to the canonical form); upstream silently
+# returns empty for unknown values — the false-negative guard lives here
+ECOSYSTEMS = {
+    "npm": "npm", "pypi": "PyPI", "go": "Go", "maven": "Maven", "crates.io": "crates.io",
+    "rubygems": "RubyGems", "nuget": "NuGet", "packagist": "Packagist", "debian": "Debian",
+    "alpine": "Alpine", "linux": "Linux", "oss-fuzz": "OSS-Fuzz", "hex": "Hex",
+    "pub": "Pub", "conda": "Conda", "android": "Android", "github actions": "GitHub Actions",
+}
+
+
+def query_raw(package, ecosystem, *, version=None, page_token=None,
+              cache=None, no_cache=False):
+    """→ {count, vulns, next_page_token, params, _meta}; /v1/query POST with verbatim names.
+    ecosystem closed-set check (case-insensitive → canonical form); version may be omitted = all known vulns
+    (upstream semantics).
+    Paging: upstream paginates past >1000 vulns or >20s (official docs), the response carries next_page_token —
+    surfaced as-is + pass it back as page_token to continue until it goes absent; an occasional
+    "token-only, no rows" page must still be continued (per the docs).
+    Probed 2026-10-28: Linux/Kernel 2719 rows on the first page + a token present.
+    Recorded, not adopted (2026-10-28 audit): purl (an alternative to package{name,ecosystem}, the toolchain
+    form) and commit (another key for version lookups) — the screening name+ecosystem form already covers the
+    use cases, so no params were added."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    name = str(package or "").strip()
+    if not name:
+        raise SdkError("usage_error", provider="osv", detail="osv_vulns requires package (the package name)")
+    eco_canon = ECOSYSTEMS.get(str(ecosystem or "").strip().lower())
+    if not eco_canon:
+        raise SdkError("usage_error", provider="osv",
+                       detail=f"ecosystem \"{ecosystem}\" is not in the OSV enumeration ("
+                              + ", ".join(sorted(set(ECOSYSTEMS.values()))) +
+                              "; upstream silently returns empty for unknown values — the false-negative guard lives here; treat the OSV docs as authoritative for new values")
+    body = {"package": {"name": name, "ecosystem": eco_canon}}
+    if version not in (None, ""):
+        body["version"] = str(version).strip()
+    if page_token not in (None, ""):
+        body["page_token"] = str(page_token).strip()
+    r = call_provider(provider, "query", body, cache=cache, no_cache=no_cache)
+    vulns = (r["data"] or {}).get("vulns") or []
+    rows = [{
+        "id": v.get("id"),
+        "aliases": v.get("aliases") or [],
+        "summary": v.get("summary"),
+        "published": v.get("published"), "modified": v.get("modified"),
+        "severity": v.get("severity") or [],
+        "advisory_url": (f"https://github.com/advisories/{v['id']}"
+                         if str(v.get("id") or "").startswith("GHSA-") else None),
+    } for v in vulns]
+    return {"count": len(rows), "vulns": rows,
+            "next_page_token": (r["data"] or {}).get("next_page_token"),
+            "params": body, "_meta": r}