trustrender 0.2.0__tar.gz → 0.3.0__tar.gz

trustrender-0.3.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: trustrender
+Version: 0.3.0
+Summary: Validate and normalize Stripe, Shopify, and custom billing data for Factur-X/ZUGFeRD
+License-Expression: MIT
+Project-URL: Homepage, https://trustrender.dev
+Project-URL: Documentation, https://trustrender.dev
+Project-URL: Source, https://github.com/verityengine/trustrender
+Project-URL: Issues, https://github.com/verityengine/trustrender/issues
+Project-URL: Changelog, https://github.com/verityengine/trustrender/releases
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: drafthorse>=2024.0
+Provides-Extra: render
+Requires-Dist: typst>=0.14; extra == "render"
+Requires-Dist: jinja2>=3.1; extra == "render"
+Requires-Dist: pypdf>=4.0; extra == "render"
+Provides-Extra: serve
+Requires-Dist: starlette>=0.40; extra == "serve"
+Requires-Dist: uvicorn>=0.30; extra == "serve"
+Provides-Extra: zugferd
+Requires-Dist: factur-x>=3.0; extra == "zugferd"
+Provides-Extra: all
+Requires-Dist: trustrender[render,serve,zugferd]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: factur-x>=3.0; extra == "dev"
+Requires-Dist: trustrender[all]; extra == "dev"
+Dynamic: license-file
+
+# TrustRender
+
+Validate and normalize billing data from Stripe, Shopify, and custom systems before Factur-X/ZUGFeRD embedding.
+
+If you're bridging a non-compliant billing platform into EU e-invoicing, libraries like [factur-x](https://github.com/akretion/factur-x) and [drafthorse](https://github.com/pretix/python-drafthorse) assume your data is already correct. TrustRender catches arithmetic mismatches, field misalignment, missing required fields, and structural problems before compliant XML gets embedded.
+
+```
+pip install trustrender
+trustrender validate invoice.json
+```
+
+## What it does
+
+Takes invoice JSON from Stripe, Shopify, custom billing APIs, or legacy exports and tells you whether it's safe to embed as Factur-X/ZUGFeRD.
+
+```
+$ trustrender validate quickbooks_invoice.json
+
+Invoice:   INV-2026-5541
+From:      Summit Analytics Co.
+To:        Horizon Financial
+Items:     2
+Total:     $10,524.50
+
+Normalizations (25):
+  DocNumber → invoice_number        CompanyName → sender.name
+  TxnDate → invoice_date            customer.Name → recipient.name
+  Line → items                      SubTotal → subtotal
+  ... and 19 more
+
+PASS — invoice data is valid
+
+Safe to embed in Factur-X/ZUGFeRD PDF.
+```
+
+Bad data gets blocked:
+
+```
+$ trustrender validate ocr_extracted_invoice.json
+
+BLOCKED — 2 problem(s)
+
+  items[1] total is wrong
+    You entered $459.00 but math says $450.00
+    Fix the line total or the price/quantity.
+
+  Subtotal is wrong
+    Lines add up to $12,459.00 but you listed $12,450.00
+
+This invoice cannot be processed until the problems above are fixed.
+```
+
+## Install
+
+```
+pip install trustrender
+```
+
+Core install requires only `drafthorse`. No Typst, no browser, no heavy deps.
+
+Optional extras:
+```
+pip install "trustrender[zugferd]"    # XSD/Schematron validation
+pip install "trustrender[render]"     # PDF rendering via Typst
+pip install "trustrender[all]"        # everything
+```
+
+Requires Python 3.11+.
+
+## Python API
+
+```python
+from trustrender import validate_invoice
+
+result = validate_invoice({
+    "invoiceNo": "INV-001",
+    "vendor": {"companyName": "Acme Corp"},
+    "customer": {"Name": "Client Inc"},
+    "LineItems": [{"desc": "Widget", "qty": 2, "unitPrice": 50, "amount": 100}],
+    "SubTotal": 100,
+    "tax": 8.50,
+    "TotalAmt": 108.50,
+}, zugferd=True)
+
+if result["render_ready"] and result.get("zugferd_ready"):
+    # safe to call factur-x / drafthorse
+    print("All checks passed")
+else:
+    for error in result["errors"]:
+        print(f"BLOCKED: {error['message']}")
+```
+
+`validate_invoice()` returns:
+- `status`: "ready" | "ready_with_warnings" | "blocked"
+- `render_ready`: bool
+- `canonical`: normalized invoice dict (all fields in canonical names)
+- `errors`: list of blocking issues with rule_id, path, expected/actual
+- `warnings`: advisory issues
+- `normalizations`: field-level provenance (what was renamed, coerced, computed)
+- `zugferd_ready`: bool (if `zugferd=True`)
+
+## What it normalizes
+
+90+ vendor field aliases across QuickBooks, Xero, Stripe, and generic CSV/ERP formats:
+
+| Source field | Canonical field |
+|---|---|
+| `DocNumber`, `invoiceNo`, `inv_no`, `ref` | `invoice_number` |
+| `CompanyName`, `account_name`, `bill_from_name` | `sender.name` |
+| `customer`, `billTo`, `Contact` | `recipient` |
+| `Line`, `LineItems`, `entries`, `products` | `items` |
+| `UnitPrice`, `cost`, `rate`, `unitCost` | `unit_price` |
+| `Amount`, `LineAmount`, `line_total` | `line_total` |
+| `SubTotal`, `net_total`, `sub_total` | `subtotal` |
+| `TotalAmt`, `grand_total`, `amount_due` | `total` |
+
+Plus: type coercion (`"$1,234.56"` → `1234.56`), date parsing (`"April 10, 2026"` → `2026-04-10`), computed defaults (missing `line_total` = `qty × price`), near-match typo detection (`invioce_number` → suggests `invoice_number`).
+
+## What it checks
+
+7 deterministic semantic checks, all arithmetic:
+
+| Check | What it catches |
+|---|---|
+| `identity.invoice_number` | Missing or empty invoice number |
+| `identity.sender_name` | Missing vendor/sender name |
+| `identity.recipient_name` | Missing recipient/buyer name |
+| `items.non_empty` | No line items |
+| `arithmetic.line_total` | line_total ≠ qty × unit_price |
+| `arithmetic.subtotal` | subtotal ≠ sum of line_totals |
+| `arithmetic.total` | total ≠ subtotal + tax_amount |
+
+No AI. No heuristics. Every check is deterministic and objectively verifiable.
+
+## CLI
+
+```
+trustrender validate <data.json> [--zugferd] [--format text|json]
+trustrender ingest <data.json> [-o canonical.json]
+trustrender render <template> <data.json> -o <output.pdf> [--zugferd en16931]
+trustrender preflight <template> <data.json> [--zugferd en16931]
+trustrender serve --templates <dir> [--port 8190]
+trustrender doctor [--smoke]
+```
+
+## Integration with factur-x / drafthorse
+
+TrustRender validates and normalizes. You generate and embed with the library of your choice.
+
+```python
+from trustrender import validate_invoice
+
+# Step 1: Validate with TrustRender
+result = validate_invoice(messy_data, zugferd=True)
+if not result["render_ready"] or not result["zugferd_ready"]:
+    raise ValueError(f"Invoice blocked: {result['errors']}")
+
+# Step 2: Use the canonical payload with drafthorse or factur-x
+canonical = result["canonical"]
+# ... your existing ZUGFeRD generation code here
+```
+
+## EN 16931 e-invoicing (narrow scope)
+
+Catches many document-level and ZUGFeRD/EN 16931 readiness issues before embedding. Currently supports:
+
+- **Domestic German B2B invoices** with standard VAT, EUR, SEPA payment
+- Single or mixed VAT rates (7% + 19%)
+- Invoice type 380 and credit note 381
+- PDF/A-3b with embedded CII XML (requires `trustrender[render]`)
+
+Not supported (fails loudly): reverse charge, cross-border, allowances/charges, non-EUR currencies.
+
+See [docs/einvoice-scope.md](docs/einvoice-scope.md) for the full scope matrix.
+
+## Optional: PDF rendering
+
+If you also want TrustRender to generate PDFs (not just validate):
+
+```
+pip install "trustrender[render]"
+trustrender render invoice.j2.typ data.json -o invoice.pdf --zugferd en16931
+```
+
+Rendering uses Typst — no browser, no Chromium. Fast and deterministic.
+
+## What this is not
+
+- Not a full AP automation platform
+- Not an e-invoice compliance certification
+- Not an AI-powered data fixer (all corrections are deterministic)
+- Not a replacement for factur-x or drafthorse — it's the validation layer you run before them
+
+## Development
+
+```
+pip install -e ".[dev]"
+trustrender doctor --smoke
+pytest
+```
+
+## License
+
+MIT

trustrender-0.3.0/README.md

@@ -0,0 +1,204 @@
+# TrustRender
+
+Validate and normalize billing data from Stripe, Shopify, and custom systems before Factur-X/ZUGFeRD embedding.
+
+If you're bridging a non-compliant billing platform into EU e-invoicing, libraries like [factur-x](https://github.com/akretion/factur-x) and [drafthorse](https://github.com/pretix/python-drafthorse) assume your data is already correct. TrustRender catches arithmetic mismatches, field misalignment, missing required fields, and structural problems before compliant XML gets embedded.
+
+```
+pip install trustrender
+trustrender validate invoice.json
+```
+
+## What it does
+
+Takes invoice JSON from Stripe, Shopify, custom billing APIs, or legacy exports and tells you whether it's safe to embed as Factur-X/ZUGFeRD.
+
+```
+$ trustrender validate quickbooks_invoice.json
+
+Invoice:   INV-2026-5541
+From:      Summit Analytics Co.
+To:        Horizon Financial
+Items:     2
+Total:     $10,524.50
+
+Normalizations (25):
+  DocNumber → invoice_number        CompanyName → sender.name
+  TxnDate → invoice_date            customer.Name → recipient.name
+  Line → items                      SubTotal → subtotal
+  ... and 19 more
+
+PASS — invoice data is valid
+
+Safe to embed in Factur-X/ZUGFeRD PDF.
+```
+
+Bad data gets blocked:
+
+```
+$ trustrender validate ocr_extracted_invoice.json
+
+BLOCKED — 2 problem(s)
+
+  items[1] total is wrong
+    You entered $459.00 but math says $450.00
+    Fix the line total or the price/quantity.
+
+  Subtotal is wrong
+    Lines add up to $12,459.00 but you listed $12,450.00
+
+This invoice cannot be processed until the problems above are fixed.
+```
+
+## Install
+
+```
+pip install trustrender
+```
+
+Core install requires only `drafthorse`. No Typst, no browser, no heavy deps.
+
+Optional extras:
+```
+pip install "trustrender[zugferd]"    # XSD/Schematron validation
+pip install "trustrender[render]"     # PDF rendering via Typst
+pip install "trustrender[all]"        # everything
+```
+
+Requires Python 3.11+.
+
+## Python API
+
+```python
+from trustrender import validate_invoice
+
+result = validate_invoice({
+    "invoiceNo": "INV-001",
+    "vendor": {"companyName": "Acme Corp"},
+    "customer": {"Name": "Client Inc"},
+    "LineItems": [{"desc": "Widget", "qty": 2, "unitPrice": 50, "amount": 100}],
+    "SubTotal": 100,
+    "tax": 8.50,
+    "TotalAmt": 108.50,
+}, zugferd=True)
+
+if result["render_ready"] and result.get("zugferd_ready"):
+    # safe to call factur-x / drafthorse
+    print("All checks passed")
+else:
+    for error in result["errors"]:
+        print(f"BLOCKED: {error['message']}")
+```
+
+`validate_invoice()` returns:
+- `status`: "ready" | "ready_with_warnings" | "blocked"
+- `render_ready`: bool
+- `canonical`: normalized invoice dict (all fields in canonical names)
+- `errors`: list of blocking issues with rule_id, path, expected/actual
+- `warnings`: advisory issues
+- `normalizations`: field-level provenance (what was renamed, coerced, computed)
+- `zugferd_ready`: bool (if `zugferd=True`)
+
+## What it normalizes
+
+90+ vendor field aliases across QuickBooks, Xero, Stripe, and generic CSV/ERP formats:
+
+| Source field | Canonical field |
+|---|---|
+| `DocNumber`, `invoiceNo`, `inv_no`, `ref` | `invoice_number` |
+| `CompanyName`, `account_name`, `bill_from_name` | `sender.name` |
+| `customer`, `billTo`, `Contact` | `recipient` |
+| `Line`, `LineItems`, `entries`, `products` | `items` |
+| `UnitPrice`, `cost`, `rate`, `unitCost` | `unit_price` |
+| `Amount`, `LineAmount`, `line_total` | `line_total` |
+| `SubTotal`, `net_total`, `sub_total` | `subtotal` |
+| `TotalAmt`, `grand_total`, `amount_due` | `total` |
+
+Plus: type coercion (`"$1,234.56"` → `1234.56`), date parsing (`"April 10, 2026"` → `2026-04-10`), computed defaults (missing `line_total` = `qty × price`), near-match typo detection (`invioce_number` → suggests `invoice_number`).
+
+## What it checks
+
+7 deterministic semantic checks, all arithmetic:
+
+| Check | What it catches |
+|---|---|
+| `identity.invoice_number` | Missing or empty invoice number |
+| `identity.sender_name` | Missing vendor/sender name |
+| `identity.recipient_name` | Missing recipient/buyer name |
+| `items.non_empty` | No line items |
+| `arithmetic.line_total` | line_total ≠ qty × unit_price |
+| `arithmetic.subtotal` | subtotal ≠ sum of line_totals |
+| `arithmetic.total` | total ≠ subtotal + tax_amount |
+
+No AI. No heuristics. Every check is deterministic and objectively verifiable.
+
+## CLI
+
+```
+trustrender validate <data.json> [--zugferd] [--format text|json]
+trustrender ingest <data.json> [-o canonical.json]
+trustrender render <template> <data.json> -o <output.pdf> [--zugferd en16931]
+trustrender preflight <template> <data.json> [--zugferd en16931]
+trustrender serve --templates <dir> [--port 8190]
+trustrender doctor [--smoke]
+```
+
+## Integration with factur-x / drafthorse
+
+TrustRender validates and normalizes. You generate and embed with the library of your choice.
+
+```python
+from trustrender import validate_invoice
+
+# Step 1: Validate with TrustRender
+result = validate_invoice(messy_data, zugferd=True)
+if not result["render_ready"] or not result["zugferd_ready"]:
+    raise ValueError(f"Invoice blocked: {result['errors']}")
+
+# Step 2: Use the canonical payload with drafthorse or factur-x
+canonical = result["canonical"]
+# ... your existing ZUGFeRD generation code here
+```
+
+## EN 16931 e-invoicing (narrow scope)
+
+Catches many document-level and ZUGFeRD/EN 16931 readiness issues before embedding. Currently supports:
+
+- **Domestic German B2B invoices** with standard VAT, EUR, SEPA payment
+- Single or mixed VAT rates (7% + 19%)
+- Invoice type 380 and credit note 381
+- PDF/A-3b with embedded CII XML (requires `trustrender[render]`)
+
+Not supported (fails loudly): reverse charge, cross-border, allowances/charges, non-EUR currencies.
+
+See [docs/einvoice-scope.md](docs/einvoice-scope.md) for the full scope matrix.
+
+## Optional: PDF rendering
+
+If you also want TrustRender to generate PDFs (not just validate):
+
+```
+pip install "trustrender[render]"
+trustrender render invoice.j2.typ data.json -o invoice.pdf --zugferd en16931
+```
+
+Rendering uses Typst — no browser, no Chromium. Fast and deterministic.
+
+## What this is not
+
+- Not a full AP automation platform
+- Not an e-invoice compliance certification
+- Not an AI-powered data fixer (all corrections are deterministic)
+- Not a replacement for factur-x or drafthorse — it's the validation layer you run before them
+
+## Development
+
+```
+pip install -e ".[dev]"
+trustrender doctor --smoke
+pytest
+```
+
+## License
+
+MIT

{trustrender-0.2.0 → trustrender-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trustrender"
-version = "0.2.0"
-description = "Fast, code-first PDF generation from structured data. No browser, no Chromium."
+version = "0.3.0"
+description = "Validate and normalize Stripe, Shopify, and custom billing data for Factur-X/ZUGFeRD"
 license = "MIT"
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -15,17 +15,14 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Topic :: Office/Business :: Financial",
-    "Topic :: Text Processing :: Markup",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
 ]
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "typst>=0.14",
-    "jinja2>=3.1",
-    "starlette>=0.40",
-    "uvicorn>=0.30",
     "drafthorse>=2024.0",
-    "pypdf>=4.0",
 ]
 
 [project.urls]
@@ -39,14 +36,27 @@ Changelog = "https://github.com/verityengine/trustrender/releases"
 trustrender = "trustrender.cli:main"
 
 [project.optional-dependencies]
+render = [
+    "typst>=0.14",
+    "jinja2>=3.1",
+    "pypdf>=4.0",
+]
+serve = [
+    "starlette>=0.40",
+    "uvicorn>=0.30",
+]
+zugferd = [
+    "factur-x>=3.0",
+]
+all = [
+    "trustrender[render,serve,zugferd]",
+]
 dev = [
     "pytest>=8.0",
     "ruff>=0.4",
     "httpx>=0.27",
     "factur-x>=3.0",
-]
-zugferd = [
-    "factur-x>=3.0",
+    "trustrender[all]",
 ]
 
 [tool.setuptools.packages.find]

{trustrender-0.2.0 → trustrender-0.3.0}/src/trustrender/__init__.py

@@ -1,4 +1,13 @@
-"""TrustRender: fast, code-first PDF generation from structured data."""
+"""TrustRender — validate and normalize messy invoice data for Factur-X/ZUGFeRD compliance.
+
+Core API (always available, no rendering deps required):
+    validate_invoice(data, zugferd=False) → structured validation result
+    ingest_invoice(data) → IngestionReport with canonical payload + provenance
+
+Rendering API (requires `pip install trustrender[render]`):
+    render(template, data, ...) → PDF bytes
+    audit(template, data, ...) → AuditResult with fingerprint + drift detection
+"""
 
 from __future__ import annotations
 
@@ -7,8 +16,16 @@ import os
 from dataclasses import dataclass
 from pathlib import Path
 
-from .engine import CompileBackend, compile_typst, compile_typst_file
 from .errors import ErrorCode, TrustRenderError
+from .invoice_ingest import IngestionReport, ingest_invoice
+
+# Rendering imports — optional, guarded
+try:
+    from .engine import CompileBackend, compile_typst, compile_typst_file
+    from .templates import render_template
+    _HAS_RENDER = True
+except ImportError:
+    _HAS_RENDER = False
 
 
 @dataclass
@@ -18,18 +35,83 @@ class RenderResult:
     pdf_bytes: bytes
     trace_id: str | None = None
 
-# Re-export for public API
-from .errors import ErrorCode as ErrorCode  # noqa: F811
-from .templates import render_template
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
+    # Core API (always available)
+    "validate_invoice", "ingest_invoice", "IngestionReport",
+    # Rendering API (requires [render] extras)
     "render", "audit", "AuditResult",
-    "TrustRenderError", "ErrorCode", "__version__", "bundled_font_dir",
+    # Errors
+    "TrustRenderError", "ErrorCode",
+    # Meta
+    "__version__", "bundled_font_dir",
 ]
 
 
+# ── Core API: validation (always available) ──────────────────────────
+
+def validate_invoice(data: dict, *, zugferd: bool = False) -> dict:
+    """Validate and normalize messy invoice data. Returns structured result.
+
+    This is the primary API for using TrustRender as a validation layer
+    before Factur-X/ZUGFeRD embedding. No rendering deps required.
+
+    Args:
+        data: Messy invoice data as a dict (any vendor format — QuickBooks,
+              Xero, Stripe, CSV, OCR output, etc.).
+        zugferd: If True, also run ZUGFeRD EN 16931 readiness checks
+                 on the canonical output.
+
+    Returns:
+        Dict with keys:
+          - status: "ready" | "ready_with_warnings" | "blocked"
+          - render_ready: bool
+          - canonical: normalized invoice dict
+          - errors: list of blocking issues
+          - warnings: list of advisory issues
+          - normalizations: list of field changes with provenance
+          - computed_fields: list of auto-computed fields
+          - unknown_fields: list of unrecognized fields with classification
+          - zugferd_ready: bool (only if zugferd=True)
+          - zugferd_errors: list (only if zugferd=True)
+
+    Example::
+
+        from trustrender import validate_invoice
+
+        result = validate_invoice({
+            "invoiceNo": "INV-001",
+            "vendor": {"companyName": "Acme Corp"},
+            "customer": {"Name": "Client Inc"},
+            "LineItems": [{"desc": "Widget", "qty": 2, "unitPrice": 50, "amount": 100}],
+            "SubTotal": 100, "tax": 8.50, "TotalAmt": 108.50,
+        }, zugferd=True)
+
+        if result["render_ready"] and result.get("zugferd_ready"):
+            print("Safe to embed — all checks passed")
+        else:
+            for error in result["errors"]:
+                print(f"BLOCKED: {error['message']}")
+    """
+    report = ingest_invoice(data)
+    result = report.to_dict()
+
+    if zugferd and report.render_ready:
+        from .zugferd import validate_zugferd_invoice_data
+        zug_errors = validate_zugferd_invoice_data(report.canonical)
+        result["zugferd_errors"] = [
+            {"path": e.path, "message": e.message} for e in zug_errors
+        ]
+        result["zugferd_ready"] = len(zug_errors) == 0
+    elif zugferd:
+        result["zugferd_errors"] = []
+        result["zugferd_ready"] = False  # can't be zugferd-ready if base validation failed
+
+    return result
+
+
 # Resolved once at import time — deterministic across local, test, and container.
 # Check multiple locations: env var, installed package, dev layout.
 def _find_bundled_fonts() -> Path | None:
@@ -85,6 +167,17 @@ def _build_font_paths(
     return result or None
 
 
+def _require_render():
+    """Raise a clear error if rendering dependencies are not installed."""
+    if not _HAS_RENDER:
+        raise TrustRenderError(
+            "Rendering requires additional dependencies. "
+            "Install with: pip install trustrender[render]",
+            code=ErrorCode.BACKEND_ERROR,
+            stage="import",
+        )
+
+
 def _render_document_pipeline(
     template_path: Path,
     data: dict,
@@ -94,7 +187,7 @@ def _render_document_pipeline(
     validate: bool = True,
     zugferd: str | None = None,
     provenance: bool = False,
-    backend: CompileBackend | None = None,
+    backend: "CompileBackend | None" = None,
     timeout: float | None = None,
     display_name: str | None = None,
 ) -> RenderResult:
@@ -117,6 +210,8 @@ def _render_document_pipeline(
     If ``TRUSTRENDER_HISTORY`` is set, a stage-by-stage RenderTrace is
     recorded to the trace store after each render (success or failure).
     """
+    _require_render()
+
     import hashlib
     import time
 
@@ -574,9 +669,12 @@ def _resolve_data(data: dict | str | os.PathLike) -> dict:
     path = Path(data) if not isinstance(data, str) else None
     if path is None:
         # Could be a JSON string or a file path string
-        candidate = Path(data)
-        if candidate.exists() and candidate.suffix == ".json":
-            path = candidate
+        try:
+            candidate = Path(data)
+            if candidate.exists() and candidate.suffix == ".json":
+                path = candidate
+        except OSError:
+            pass  # String too long to be a path — treat as JSON below
 
     if path is not None and path.exists():
         with open(path) as f: