agentdata 0.3.26__py3-none-any.whl

agentdata/__init__.py

@@ -0,0 +1,33 @@
+"""AgentData SDK — two API families over domain data: corpus (hosted) + third-party realtime enrichment (local, keyless).
+
+Contract: docs/domains/api.md (cross-domain charter) + per-domain API docs. Zero third-party dependencies (stdlib-only, floor 3.10).
+
+    from agentdata import Client
+    c = Client()                                     # zero config: enrichment runs locally, usable immediately
+    c.healthcare.rxnav_rxcui_by_name(name="atorvastatin")               # flat panel command (the only surface since 0.3.0)
+    c.healthcare.fda_drug_shortages(search='openfda.manufacturer_name.exact:"Fresenius Kabi"')
+    c.company.gleif_lei_records(lei="5493001KJTIIGC8Y1R12")                  # company likewise (gleif parent face split in two)
+    c.company.gleif_direct_parent(lei="5493001KJTIIGC8Y1R12")
+    c.company.ted_notices_search(query="organisation-name-buyer=Siemens* AND organisation-country-buyer=DEU")
+    c.esg.eiti_payments(eiti_id="11111111-…")                        # esg likewise
+    c.esg.climatetrace_sources(owner_ids="E100000001492", year=2023)
+    c.legal.gb_ec_donations(query="Keystone")                       # legal likewise (UK EC donations/loans split in two + TNA case law)
+    c.legal.dgcomp_cases_search(name="Google", instrument="SA")
+    c.legal.lda_filings(client_name="Google LLC", limit=25)          #   page_size hard-clamped to 25 upstream
+    c.procurement.br_pncp_contracts(data_inicial="20260101", cnpj="…")  # procurement, seventh domain (founding pair + wb/NY trio + UNGM/NY OGS)
+    c.economy.wb_wdi_values(country="CHN", indicator="NY.GDP.MKTP.CD", date="2020:2023")  # economy, eighth domain (country denominators)
+    c2 = Client(base_url="https://…", api_key="mk_live_…")   # corpus family: hosted
+    c2.company.search(filters={"qtype": "专精特新小巨人"}, limit=100)
+
+CLI: eight domains executable (`agentdata healthcare fda_drug_shortages --search …`
+`agentdata company ted_notices_search --query 'organisation-name-buyer=Siemens*'`,
+`agentdata esg climatetrace_sources --owner-ids E…`, `agentdata procurement br_pncp_contracts --data-inicial 20260101`,
+`agentdata economy wb_wdi_values --country CHN --indicator NY.GDP.MKTP.CD`).
+Upstream parameter names verbatim + our defaults.
+"""
+from .client import Client
+from .errors import SdkError
+
+__version__ = "0.3.26"  # version bumps with each release; per-batch narratives live in the internal ledger (MAPPING.md) and MR descriptions (not exported)
+
+__all__ = ["Client", "SdkError", "__version__"]

agentdata/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentdata/cache.py

@@ -0,0 +1,115 @@
+"""agentdata.cache — per-user local query cache (SQLite; TTL declared per op, api.md section 9.3).
+
+Location ruling: defaults to the OS user cache directory
+  Windows  %LOCALAPPDATA%\\agentdata\\cache.db (falls back to ~/AppData/Local without LOCALAPPDATA)
+  POSIX    ~/.cache/agentdata/cache.db
+env AGENTDATA_CACHE_DIR overrides; an unwritable directory falls back to the system temp dir;
+if temp is unwritable too, an actionable error is raised (hinting --no-cache or
+AGENTDATA_CACHE_DIR). The SDK cache is independent of any internal datastore.
+
+TTL semantics: None=permanent (immutable keys: drug name -> RxCUI); a positive number=seconds
+(mutable records: GUDID 7 days). Expired entries are evicted lazily (an expired read counts
+as a miss).
+"""
+import json
+import os
+import pathlib
+import sqlite3
+import tempfile
+import time
+from datetime import datetime, timezone
+
+DDL = """
+CREATE TABLE IF NOT EXISTS thirdparty_cache (
+  provider   TEXT NOT NULL,
+  cache_key  TEXT NOT NULL,
+  payload    TEXT NOT NULL,
+  fetched_at INTEGER NOT NULL,   -- epoch ms
+  ttl_sec    INTEGER,            -- NULL = permanent
+  PRIMARY KEY (provider, cache_key)
+)
+"""
+
+
+def default_cache_dir() -> pathlib.Path:
+    env = os.environ.get("AGENTDATA_CACHE_DIR")
+    if env:
+        return pathlib.Path(env)
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA") or str(pathlib.Path.home() / "AppData" / "Local")
+        return pathlib.Path(base) / "agentdata"
+    return pathlib.Path.home() / ".cache" / "agentdata"
+
+
+def _open_or_none(dir_path: pathlib.Path):
+    """Open cache.db under dir_path; return None on failure (the caller falls back to the next candidate)."""
+    try:
+        dir_path.mkdir(parents=True, exist_ok=True)
+        p = dir_path / "cache.db"
+        conn = sqlite3.connect(str(p), timeout=5)
+        conn.execute("PRAGMA busy_timeout = 5000")
+        conn.execute(DDL)
+        conn.execute("INSERT OR REPLACE INTO thirdparty_cache (provider, cache_key, payload, fetched_at, ttl_sec) VALUES ('__probe','__probe','1',?,NULL)", (int(time.time() * 1000),))
+        conn.commit()
+        return conn
+    except OSError:
+        return None
+
+
+class Cache:
+    def __init__(self, cache_dir=None, enabled=True):
+        self.enabled = enabled and True
+        self._conn = None
+        if not enabled:
+            return
+        cands = [pathlib.Path(cache_dir) if cache_dir else default_cache_dir(),
+                 pathlib.Path(tempfile.gettempdir()) / "agentdata"]
+        last_err = None
+        for c in cands:
+            self._conn = _open_or_none(c)
+            if self._conn is not None:
+                return
+            last_err = c
+        raise RuntimeError(
+            f"Cache directory not writable (tried {cands}). Run with --no-cache, or point AGENTDATA_CACHE_DIR at a writable directory. (Last failed at {last_err})"
+        )
+
+    # —— hit -> {'payload': JSON as stored, 'fetched_at': epoch ms, 'fetched_at_iso': ISO8601Z}; miss/expired -> None ——
+    def get(self, provider: str, cache_key: str, ttl_sec):
+        if not self.enabled:
+            return None
+        row = self._conn.execute(
+            "SELECT payload, fetched_at, ttl_sec FROM thirdparty_cache WHERE provider=? AND cache_key=?",
+            (provider, cache_key),
+        ).fetchone()
+        if row is None:
+            return None
+        payload, fetched_at, row_ttl = row
+        if row_ttl is not None and time.time() * 1000 - fetched_at >= row_ttl * 1000:
+            return None
+        return {
+            "payload": json.loads(payload),
+            "fetched_at": fetched_at,
+            "fetched_at_iso": datetime.fromtimestamp(fetched_at / 1000, tz=timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        }
+
+    def set(self, provider: str, cache_key: str, payload, ttl_sec):
+        if not self.enabled:
+            return
+        self._conn.execute(
+            "INSERT OR REPLACE INTO thirdparty_cache (provider, cache_key, payload, fetched_at, ttl_sec) VALUES (?,?,?,?,?)",
+            (provider, cache_key, json.dumps(payload, ensure_ascii=False), int(time.time() * 1000), ttl_sec),
+        )
+        self._conn.commit()
+
+    def delete(self, provider: str, cache_key: str):
+        """Single-key delete: an occasional upstream "200 empty set" must not stand as cache authority
+        (EUDAMED primaryDi un-indexed face); the provider drops the entry as soon as it sees emptiness."""
+        if not self.enabled:
+            return
+        cur = self._conn.execute(
+            "DELETE FROM thirdparty_cache WHERE provider=? AND cache_key=?", (provider, cache_key)
+        )
+        self._conn.commit()
+        return cur.rowcount
+

agentdata/cli.py

@@ -0,0 +1,173 @@
+"""agentdata.cli — the dual command-line entry (console_scripts `agentdata` + `python -m agentdata`).
+
+Exit-code contract: 0 success / 1 upstream-availability family / 2 usage family (api.md section 9.4).
+enrichment works with zero config; the corpus family needs --base-url/--api-key (or env
+AGENTDATA_BASE_URL / AGENTDATA_API_KEY).
+"""
+import argparse
+import json
+import sys
+import uuid
+
+from . import __version__
+from .client import Client
+from .company import cli as company_cli
+from .economy import cli as economy_cli
+from .esg import cli as esg_cli
+from .healthcare import cli as healthcare_cli
+from .legal import cli as legal_cli
+from .procurement import cli as procurement_cli
+from .research import cli as research_cli
+from .security import cli as security_cli
+
+# 0.2.6 per-domain split: the domain command registrars (register(v, g)) live in each domain's cli.py;
+# the root keeps only the shared parts plus the search/read dispatch
+# 0.3.10 domain order = lexicographic (DOMAIN_ORDER is the source of truth — the build_parser loop, per-domain face order, and site navigation all follow it; the sort key is the English identifier)
+DOMAIN_ORDER = ("company", "economy", "esg", "healthcare", "legal", "procurement", "research", "security")
+_CLI = {"company": company_cli, "economy": economy_cli, "esg": esg_cli,
+        "healthcare": healthcare_cli, "legal": legal_cli, "procurement": procurement_cli,
+        "research": research_cli, "security": security_cli}
+from .errors import SdkError
+
+
+def _filter_arg(pairs):
+    """--filter 'k=v' / 'k=v1|v2' / 'k>=v' / 'k>v' / 'k<=v' / 'k<v' -> a DSL node."""
+    filters = {}
+    for raw in pairs or []:
+        for op_key, op in ((">=", "gte"), ("<=", "lte"), (">", "gt"), ("<", "lt")):
+            if op_key in raw:
+                k, _, v = raw.partition(op_key)
+                filters.setdefault(k, {"range": {}})["range"][op] = _cast(v)
+                break
+        else:
+            k, _, v = raw.partition("=")
+            if "|" in v:
+                filters[k] = {"any": v.split("|")}
+            else:
+                filters[k] = {"eq": _cast(v)}
+    return filters
+
+
+def _cast(v):
+    if v.lower() in ("true", "false"):
+        return v.lower() == "true"
+    try:
+        return int(v)
+    except ValueError:
+        return v
+
+
+def _leaf_globals():
+    """Global flags placed after a subcommand (the README example shape `agentdata company search … --api-key x`).
+    The dest gets a sub_ prefix + default=argparse.SUPPRESS: when argparse enters a subparser it opens
+    a separate namespace, parses there and writes the whole thing back into the parent namespace, so a
+    dest that carries a default overwrites the value the parent just parsed —
+    a global flag between the domain and the verb (`agentdata healthcare --no-cache epmc_search …`)
+    is therefore swallowed silently (reproduced by measurement on 2026-10-20). Under SUPPRESS a dest
+    that never appeared does not land in the namespace, so the parent's value survives; every read
+    uses getattr(…, default)."""
+    g = argparse.ArgumentParser(add_help=False)
+    g.add_argument("--base-url", dest="sub_base_url", default=argparse.SUPPRESS, help="Hosted API base URL (env AGENTDATA_BASE_URL)")
+    g.add_argument("--api-key", dest="sub_api_key", default=argparse.SUPPRESS, help="Bearer PAT (env AGENTDATA_API_KEY)")
+    g.add_argument("--cache-dir", dest="sub_cache_dir", default=argparse.SUPPRESS, help="Cache directory (env AGENTDATA_CACHE_DIR)")
+    g.add_argument("--no-cache", dest="sub_no_cache", action="store_true", default=argparse.SUPPRESS, help="Bypass the cache for this call")
+    g.add_argument("--execution", dest="sub_execution", default=argparse.SUPPRESS, choices=["local", "hosted", "auto"], help="Execution location (default auto: realtime queries run locally)")
+    return g
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="agentdata", description="AgentData SDK CLI (corpus queries via the hosted API + realtime queries executed locally)")
+    p.add_argument("--version", action="version", version=f"agentdata {__version__}")
+    p.add_argument("--base-url", default=None, help="Hosted API base URL (env AGENTDATA_BASE_URL)")
+    p.add_argument("--api-key", default=None, help="Bearer PAT (env AGENTDATA_API_KEY)")
+    p.add_argument("--cache-dir", default=None, help="Cache directory (env AGENTDATA_CACHE_DIR)")
+    p.add_argument("--no-cache", action="store_true", help="Bypass the cache for this call")
+    p.add_argument("--execution", default="auto", choices=["local", "hosted", "auto"])
+    sub = p.add_subparsers(dest="domain", required=True)
+    for domain in DOMAIN_ORDER:
+        d = sub.add_parser(domain, parents=[_leaf_globals()])
+        v = d.add_subparsers(dest="verb", required=True)
+        _CLI[domain].register(v, _leaf_globals)
+
+        s = v.add_parser("search", parents=[_leaf_globals()], help="Corpus search (hosted)",
+                         description="Corpus search (hosted, PAT required): filters/record_kind/level/pagination")
+        s.add_argument("--filter", action="append", default=[], metavar="K=V", help="Filter K=V (repeatable)")
+        s.add_argument("--record-kind", default=None, help="Record kind (closed set from the domain spec)")
+        s.add_argument("--facets", default=None, help="Comma-separated fields (facet counts)")
+        s.add_argument("--level", default="tier1", choices=["tier1", "tier2", "tier3"], help="T-layer depth (default tier1)")
+        s.add_argument("--limit", type=int, default=50, help="Page size (default 50, ≤1000)")
+        s.add_argument("--cursor", default=None, help="Pagination cursor (feed next_cursor from the response)")
+        s.add_argument("--mode", default=None, choices=["screen"], help="Special mode (screen: batch screening; requires --input)")
+        s.add_argument("--input", default=None, help="Input JSONL file for batch-screening mode (--mode screen)")
+
+        rd = v.add_parser("read", parents=[_leaf_globals()], help="Corpus record (hosted)",
+                          description="Corpus single-record read (hosted): id + T-layer depth")
+        rd.add_argument("--id", required=True, help="Subject id")
+        rd.add_argument("--level", default="tier1", choices=["tier1", "tier2", "tier3"], help="T-layer depth (default tier1)")
+    return p
+
+
+# 0.2.6 per-domain split: the source of truth for the flat dispatch table is each domain's cli.FLAT,
+# merged here (the search/read dispatch stays in this module's main)
+_FLAT_DISPATCH = {}
+for _m in _CLI.values():
+    _FLAT_DISPATCH.update(_m.FLAT)
+assert len(_FLAT_DISPATCH) == 117, f"flat dispatch {len(_FLAT_DISPATCH)} != 117 (117 faces; 0.3.2 esg +2 + 0.3.3 European registries +5 + 0.3.4 FR recherche +1 + 0.3.5 esg port-state +5 + 0.3.6 World Bank/NY +3 + 0.3.8 legal TNA caselaw +2 + 0.3.12 UNGM/NY OGS collection +2 + 0.3.14 CO RUES/KR hometax +2 + 0.3.16 legal co_sic +1 + healthcare gb_mhra +2 + 0.3.19 healthcare CA DPD/MDALL +4 + rasff/safety_gate +3 + 0.3.21 legal debarment rosters afdb/ca_sema/idb/wb +4 + 0.3.22 transport compliance euasl_datasets +1 + 0.3.23 economy domain (wb/eurostat/ecb/fred/who_xmart/un_comtrade/ilo_stat) +10 + 0.3.24 economy expansion (imf_sdmx/bis/unsd_sdg/wb_ids) +5; the csl_screening alias was removed in 0.3.0)"
+# 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 per-domain source of truth is each domain cli.py's COUNTRY (same face set as FLAT); the root only merges them; the success envelope carries a jurisdiction chapter (search/read are hosted mixed-jurisdiction corpus services — unstamped)
+_JURISDICTION = {f: cc for _m in _CLI.values() for f, cc in _m.COUNTRY.items()}
+assert set(_JURISDICTION) == set(_FLAT_DISPATCH), f"jurisdiction coverage {len(_JURISDICTION)} != dispatch faces {len(_FLAT_DISPATCH)}"
+def _merge_globals(a):
+    """Merge global flags: the ones placed after the subcommand (sub_*) win, the top level is the
+    fallback — both placements work (the README example shape). sub_* are all SUPPRESS: if one never
+    appeared the attribute does not exist, so every read falls back via getattr."""
+    a.base_url = getattr(a, "sub_base_url", None) or a.base_url
+    a.api_key = getattr(a, "sub_api_key", None) or a.api_key
+    a.cache_dir = getattr(a, "sub_cache_dir", None) or a.cache_dir
+    a.no_cache = a.no_cache or getattr(a, "sub_no_cache", False)
+    a.execution = getattr(a, "sub_execution", None) or a.execution
+    for k in ("sub_base_url", "sub_api_key", "sub_cache_dir", "sub_no_cache", "sub_execution"):
+        if hasattr(a, k):
+            delattr(a, k)
+    return a
+
+
+
+
+def main(argv=None) -> int:
+    # Force UTF-8 for piped/redirected output: on Chinese Windows the pipe defaults to CP936 and agents
+    # or redirected consumers would receive bad bytes; the interactive console is already UTF-8 under
+    # PEP 528, so reconfigure is imperceptible there.
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+    a = _merge_globals(build_parser().parse_args(argv))
+    try:
+        c = Client(a.base_url, a.api_key, cache_dir=a.cache_dir, no_cache=a.no_cache,
+                   execution=a.execution)
+        d = getattr(c, a.domain)
+        flat = _FLAT_DISPATCH.get(a.verb)
+        if flat is not None:
+            out = getattr(d, a.verb)(**flat(a))
+            out["jurisdiction"] = _JURISDICTION[a.verb]  # 0.3.10 jurisdiction chapter: downstream can route by country without digging through docs
+        elif a.verb == "search":
+            screen_inputs = None
+            if a.mode == "screen":
+                if not a.input:
+                    raise SdkError("usage_error", detail="--mode screen requires --input x.jsonl")
+                with open(a.input, encoding="utf-8") as f:
+                    screen_inputs = [json.loads(line) for line in f if line.strip()]
+            out = d.search(filters=_filter_arg(a.filter), record_kind=a.record_kind,
+                           facets=a.facets.split(",") if a.facets else None, level=a.level,
+                           limit=a.limit, cursor=a.cursor, mode=a.mode, screen_inputs=screen_inputs)
+        else:
+            out = d.read(a.id, level=a.level)
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+        return 0
+    except SdkError as e:
+        # api.md section 9.5: request_id runs through both the success and error states (mirroring the
+        # Node cli.mjs randomUUID emitted in both states)
+        print(json.dumps({"request_id": str(uuid.uuid4()), **e.to_dict()}, ensure_ascii=False, indent=2), file=sys.stderr)
+        return e.exit_code
+    except RuntimeError as e:  # actionable config errors such as an unwritable cache directory
+        print(f"Config error: {e}", file=sys.stderr)
+        return 2

agentdata/client.py

@@ -0,0 +1,158 @@
+"""agentdata.client — one object, both families share a shape: enrichment (local, zero config) + corpus (hosted, base_url+api_key).
+
+Contract: docs/domains/api.md (section 8 corpus / section 9 enrichment capability axis).
+- The quartet is mandatory: result / reason / evidence / source.
+- Enrichment rows carry source={provider, execution, from_cache, observed_at|fetched_at} (the cache is not a backend).
+- execution axis local|hosted|auto: auto->local (all current capabilities are keyless); requesting a keyless
+  capability as hosted -> capability_unavailable, never a silent rerouting (api.md section 9.2).
+- request_id: for local execution the SDK generates one (uuid4) and puts it on the envelope; for hosted corpus
+  the server-side request_id wins.
+"""
+import os
+import uuid
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .company.faces import CompanyFaces
+from .economy.faces import EconomyFaces
+from .esg.faces import EsgFaces
+from .healthcare.faces import HealthcareFaces
+from .legal.faces import LegalFaces
+from .procurement.faces import ProcurementFaces
+from .research.faces import ResearchFaces
+from .security.faces import SecurityFaces
+from .errors import SdkError
+from .cache import Cache
+from .transport import enrich_source, resolve_execution  # three helpers live in transport (0.3.0 verb-layer removal; _tty_tag now domain-internal)
+
+CONTRACT = "docs/domains/api.md"
+
+
+class Client:
+    def __init__(self, base_url=None, api_key=None, *, execution="auto", cache_dir=None,
+                 no_cache=False, timeout=20.0):
+        if execution not in ("local", "hosted", "auto"):
+            raise SdkError("usage_error", detail=f"execution must be local|hosted|auto, got '{execution}'")
+        self.default_execution = execution
+        self.no_cache = bool(no_cache)
+        self.timeout = timeout
+        self._cache = Cache(cache_dir, enabled=not no_cache)
+        self.base_url = (base_url or os.environ.get("AGENTDATA_BASE_URL") or "").rstrip("/") or None
+        self.api_key = api_key or os.environ.get("AGENTDATA_API_KEY") or None
+        self.healthcare = _Domain(self, "healthcare")
+        self.company = _Domain(self, "company")
+        self.esg = _Domain(self, "esg")
+        self.legal = _Domain(self, "legal")
+        self.procurement = _Domain(self, "procurement")  # 0.3.0: the seventh domain
+        self.research = _Domain(self, "research")
+        self.security = _Domain(self, "security")
+        self.economy = _Domain(self, "economy")  # 0.3.23: the eighth domain (country denominators)
+
+    def _request_id(self) -> str:
+        return str(uuid.uuid4())
+
+    # —— corpus family: hosted HTTP (Bearer PAT; the closed error-envelope set passes straight through) ——
+    def _corpus(self, domain: str, verb: str, payload: dict) -> dict:
+        if not self.base_url or not self.api_key:
+            raise SdkError("usage_error",
+                           detail="The corpus family uses hosted HTTP: Client(base_url=…, api_key=…) (enrichment works with zero config; ask us to issue you a PAT)")
+        url = f"{self.base_url}/v1/{domain}/{verb}"
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(url, data=data, method="POST", headers={
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        })
+        try:
+            with urllib.request.urlopen(req, timeout=max(self.timeout, 120)) as resp:
+                status, raw, headers = resp.status, resp.read(), resp.headers
+        except urllib.error.HTTPError as e:
+            status, raw, headers = e.code, e.read(), e.headers
+        except (urllib.error.URLError, OSError) as e:
+            raise SdkError("capability_unavailable", detail=f"Gateway unreachable: {e}") from e
+        try:
+            doc = json.loads(raw.decode("utf-8", "replace"))
+        except ValueError:
+            raise SdkError("capability_unavailable", status=status, detail=f"Gateway returned a non-JSON response (HTTP {status})")
+        if status >= 400:
+            err = doc.get("error") or {}
+            ra_hdr = headers.get("Retry-After") if headers else None
+            try:
+                ra = float(ra_hdr) if ra_hdr else None
+            except (TypeError, ValueError):
+                ra = None
+            raise SdkError(err.get("code", "internal"), status=status,
+                           detail=err.get("message") or f"HTTP {status}", retry_after=ra)
+        return doc
+
+
+class _Domain(HealthcareFaces, CompanyFaces, EsgFaces, LegalFaces, ProcurementFaces,
+              ResearchFaces, SecurityFaces, EconomyFaces):
+    """Domain namespace object — the flat faces are mixed in from each domain's faces; the corpus-family
+    search/read stay on the base class (hosted, api.md section 8 living contract). In 0.3.0 the verb layer
+    (resolve/evidence/trials/label/related/fulltext), the csl_screening frozen alias and the grants domain
+    alias were removed per the established contract."""
+    def __init__(self, client: Client, name: str):
+        self._c = client
+        self.name = name
+
+    # ---------- quartet envelope (shared by every domain's faces) ----------
+    # A single upstream request passes through; we may add defaults/validation/rate limiting/caching/
+    # error normalization/row shaping, but must never permanently hide a capability the upstream can
+    # express; a cap is allowed only for a hard protocol limit or local safety. Quartet envelope + the
+    # query echo quartet.
+
+    def _flat_env(self, *, tool, input, reason, result, evidence, provider_id, metas,
+                  query=None, deprecations=None):
+        ex = resolve_execution(self._c.default_execution)
+        metas = [m for m in metas if m]
+        out = {
+            "ok": True, "domain": self.name, "tool": tool,
+            "input": input,
+            "from_cache": bool(metas) and all(m.get("from_cache") for m in metas),
+            "reason": reason,
+            "result": result,
+            "evidence": evidence,
+            "source": enrich_source(provider_id, ex, *metas),
+            "request_id": self._c._request_id(),
+        }
+        if query is not None:
+            out["query"] = query
+        if deprecations:
+            out["deprecations"] = deprecations
+        return out
+
+    # ---------- corpus (hosted) ----------
+
+    def search(self, *, filters=None, record_kind=None, facets=None, level="tier1",
+               limit=50, cursor=None, mode=None, screen_inputs=None):
+        """Corpus search (hosted API). mode="screen" + screen_inputs is the batch-screening mode."""
+        payload = {"level": level, "limit": limit}
+        if filters:
+            payload["filters"] = filters
+        if record_kind:
+            payload["record_kind"] = record_kind
+        if facets:
+            payload["facets"] = facets if isinstance(facets, list) else [facets]
+        if cursor:
+            payload["cursor"] = cursor
+        if mode:
+            payload["mode"] = mode
+        if screen_inputs is not None:
+            payload["screen_inputs"] = screen_inputs
+        out = self._c._corpus(self.name, "search", payload)
+        out["request_id"] = out.get("request_id") or self._c._request_id()
+        return out
+
+    def read(self, id=None, *, target=None, level="tier1"):
+        """Corpus single-record read (hosted API): id (or target) + T-layer depth."""
+        payload = {"level": level}
+        if id is not None:
+            payload["id"] = id
+        elif target is not None:
+            payload["target"] = target
+        out = self._c._corpus(self.name, "read", payload)
+        out["request_id"] = out.get("request_id") or self._c._request_id()
+        return out

agentdata/company/__init__.py

@@ -0,0 +1,3 @@
+"""company domain package — provider adapters flat layout (one source per file) + faces/cli (0.2.6 per-domain reorg)."""
+from . import (cf, ch_zefix, co_rues, edgar_cik, edgar_fts, fdic_bankfind, fi_ytj,  # noqa: F401
+               fr_recherche, fts, gleif, kr_hometax, no_brreg, ror, ted, usaspending, vies)

agentdata/company/cf.py

@@ -0,0 +1,145 @@
+"""cf — UK Contracts Finder OCDS provider (UK below-threshold public procurement; keyless).
+
+2026-10-23 probing chain: bare path /api/1.0/ocdsReleasePackages 404s, host api.contractsfinder
+gives 000 — the real working face is
+www.contractsfinder.service.gov.uk/Published/Notices/OCDS/Search (verified 2026-10-20, re-verified
+alive 2026-10-23). Division of labor with FTS: FTS = WTO-line above-threshold, CF = below-threshold
+small contracts — the two faces complement each other.
+Parameter face: publishedFrom/publishedTo (bare dates are legal here — opposite of FTS's full
+timestamp requirement) + limit(≤100) + cursor + stages(tender|award, added in the 0.2.9 audit —
+symmetric with the FTS face);
+without a window releases are always empty — default falls back to a rolling "last 7 days" window.
+Identifier face: suppliers[].id is GB-COH-<Companies House number> (same key as the companies-house
+batch corpus line). TTL: 24h.
+"""
+import re
+from datetime import timedelta, datetime, timezone
+from urllib.parse import urlparse, parse_qs
+
+from ..errors import SdkError
+
+provider = {
+    "id": "cf",
+    "baseUrl": "https://www.contractsfinder.service.gov.uk",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "search": {"path": "/Published/Notices/OCDS/Search", "ttl": 24 * 3600, "timeoutMs": 30000},
+    },
+    "ttl": {"search": 24 * 3600},
+}
+
+_BARE_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def cf_from_upstream(data, name="", limit=10):
+    """Upstream payload → {rows, next_cursor, has_more} (pure function + client-side name filter, offline-testable; same shape as fts)."""
+    q = str(name or "").lower().strip()
+    hit = (lambda s: not q or q in str(s or "").lower())
+
+    def keep(rel):
+        if hit((rel or {}).get("buyer", {}).get("name")):
+            return True
+        return any(hit(sp.get("name")) for aw in (rel or {}).get("awards") or []
+                   for sp in (aw or {}).get("suppliers") or [])
+
+    rows = []
+    for rel in [x for x in (data or {}).get("releases") or [] if keep(x)][:limit]:
+        rows.append({
+            "ocid": rel.get("ocid"),
+            "date": rel.get("date"),
+            "tags": rel.get("tag") or [],
+            "buyer": (rel.get("buyer") or {}).get("name"),
+            "suppliers": sorted({sp.get("name") for aw in rel.get("awards") or []
+                                 for sp in aw.get("suppliers") or [] if sp.get("name")}),
+            "supplier_ids": sorted({sp.get("id") for aw in rel.get("awards") or []
+                                    for sp in aw.get("suppliers") or [] if sp.get("id")}),  # GB-COH-… (CH number) / GB-CFS-… (CF registry key), two forms
+            "award_values": [{"date": aw.get("date"), "amount": (aw.get("value") or {}).get("amount"),
+                              "currency": (aw.get("value") or {}).get("currency")}
+                             for aw in rel.get("awards") or [] if (aw.get("value") or {}).get("amount") is not None],
+            "tender_title": (rel.get("tender") or {}).get("title"),
+        })
+    nxt = (data or {}).get("links", {}).get("next")
+    cursor = (parse_qs(urlparse(nxt).query).get("cursor") or [None])[0] if nxt else None
+    return {"rows": rows, "next_cursor": cursor, "has_more": bool(nxt)}
+
+
+def company_uk_cf_tenders(name, *, limit=10, cursor=None, published_from=None, published_to=None,
+                          cache=None, no_cache=False):
+    """→ {rows, next_cursor, has_more, window, matched_on, _meta}; CF release rows (client-side contains match).
+    Always fetches the full 100-row page then filters and slices to limit; window default = rolling last 7 days (upstream is always empty without one)."""
+    from ..transport import call_provider
+
+    q = str(name or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="cf",
+                       detail="name is required (the OCDS face has no name-search param — client-side contains match)")
+    lim = min(max(1, int(limit) or 10), 100)
+    p = {"limit": 100}
+    if cursor:
+        p["cursor"] = str(cursor)
+
+    def iso(s):
+        s = str(s or "").strip()
+        return s if _BARE_DATE.match(s) else None
+
+    today = datetime.now(timezone.utc).date()
+
+    def d(n):
+        return (today + timedelta(days=n)).isoformat()
+
+    frm, to = iso(published_from), iso(published_to)
+    if not frm and not to:
+        frm, to = d(-7), d(0)      # both default: rolling 7-day window
+    elif not frm:
+        frm = d(-7)                # single end: the other end filled from the 7-day window
+    elif not to:
+        to = d(0)
+    p["publishedFrom"], p["publishedTo"] = frm, to
+    r = call_provider(provider, "search", p, cache=cache, no_cache=no_cache)
+    return {**cf_from_upstream(r["data"], q, lim),
+            "window": {"published_from": frm, "published_to": to},
+            "matched_on": "buyer|suppliers contains", "_meta": r}
+
+
+def search_raw(*, published_from=None, published_to=None, limit=100, cursor=None,
+               stages=None, cache=None, no_cache=False):
+    """→ {rows, next_cursor, has_more, window, params, _meta}; CF upstream-verbatim params (no name filter).
+    publishedFrom/publishedTo accept bare dates (opposite of FTS's full-timestamp requirement — evidence the two faces differ);
+    both-default = rolling 7-day window (**our default, not upstream's** — upstream is always empty without a window); limit 1-100.
+    stages (0.2.9 audit addition): tender|award passed through verbatim — invalid values get a self-describing upstream 400
+    (2026-10-28 probe: stages=BOGUS → code 3200 "BOGUS is not a valid OCDS stage", self-validating, so no local wall on this param);
+    absent = not sent → mixed feed (same-window baseline 100 rows = award 88 + tender 2 + planning 3; stages=tender gives 59 pure
+    tender/tenderAmendment rows, stages=award 100 pure award/awardUpdate rows — a real filter, not an echo)."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    lim = int(limit)
+    if not 1 <= lim <= 100:
+        raise SdkError("usage_error", provider="cf", detail="limit must be 1-100 (upstream page cap)")
+    params = {"limit": lim}
+    if cursor:
+        params["cursor"] = str(cursor)
+    if stages:
+        params["stages"] = str(stages).strip()
+
+    def iso(v):
+        s = str(v or "").strip()
+        return s if _BARE_DATE.match(s) else None
+
+    today = datetime.now(timezone.utc).date()
+
+    def d(n):
+        return (today + timedelta(days=n)).isoformat()
+
+    frm, to = iso(published_from), iso(published_to)
+    if not frm and not to:
+        frm, to = d(-7), d(0)   # our default: upstream is always empty without a window (probed), rolling 7-day fallback
+    elif not frm:
+        frm = d(-7)
+    elif not to:
+        to = d(0)
+    params["publishedFrom"], params["publishedTo"] = frm, to
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    return {**cf_from_upstream(r["data"], "", lim),
+            "window": {"published_from": frm, "published_to": to},
+            "params": params, "_meta": r}