schemafit 0.1.0__py3-none-any.whl

schemafit/__init__.py

@@ -0,0 +1,16 @@
+"""schemafit — provider-aware structured-output / JSON-Schema CI linter.
+
+Statically lint a JSON Schema / tool definition / response_format against each
+LLM provider's documented constraint surface (OpenAI, Anthropic, Gemini) and
+fail CI *before* the schema 400s in production on provider X.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .linter import PROVIDERS, has_errors, lint, lint_multi
+from .model import Finding
+from .repair import repair
+
+__all__ = ["PROVIDERS", "Finding", "__version__", "has_errors", "lint", "lint_multi", "repair"]

schemafit/__main__.py

@@ -0,0 +1,10 @@
+"""Enable ``python -m schemafit``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

schemafit/cli.py

@@ -0,0 +1,187 @@
+"""schemafit command-line interface.
+
+Commands:
+  lint <schema.json> --provider openai[,anthropic,gemini]   # exit 1 on violations
+  repair <schema.json> --provider <p> [--out fixed.json]
+  providers
+  demo                                                       # hermetic proof
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__, report
+from .linter import PROVIDERS, has_errors, lint, lint_multi
+from .repair import repair
+
+# A schema that is valid for OpenAI but deliberately trips Anthropic (rejected
+# validation keywords) and Gemini (anyOf). Used by `demo` for a hermetic proof.
+DEMO_BAD_SCHEMA: dict = {
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "name": {"type": "string", "minLength": 1, "maxLength": 50},
+        "email": {"type": "string", "format": "email"},
+        "age": {"type": "integer", "minimum": 0, "maximum": 120},
+        "status": {"anyOf": [{"type": "string"}, {"type": "null"}]},
+    },
+    "required": ["name", "email", "age", "status"],
+}
+
+
+def _load_schema(path: str) -> object:
+    if path == "-":
+        return json.load(sys.stdin)
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _parse_providers(spec: str) -> list[str]:
+    provs = [p.strip() for p in spec.split(",") if p.strip()]
+    if not provs:
+        raise SystemExit("error: --provider requires at least one provider")
+    for p in provs:
+        if p not in PROVIDERS:
+            raise SystemExit(f"error: unknown provider {p!r} (choose from {', '.join(PROVIDERS)})")
+    return provs
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    providers = _parse_providers(args.provider)
+    all_results: dict[str, dict] = {}
+    overall_fail = False
+    for path in args.schemas:
+        try:
+            schema = _load_schema(path)
+            results = lint_multi(schema, providers)
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"error: cannot read schema {path!r}: {exc}", file=sys.stderr)
+            return 2
+        except RecursionError:
+            print(f"error: schema {path!r} is too deeply nested to lint safely", file=sys.stderr)
+            return 2
+        all_results[path] = results
+        if args.strict:
+            failed = any(findings for findings in results.values())
+        else:
+            failed = any(has_errors(findings) for findings in results.values())
+        overall_fail = overall_fail or failed
+        if args.format != "json":
+            if len(args.schemas) > 1:
+                print(f"== {path} ==")
+            print(report.format_human(results))
+    if args.format == "json":
+        print(report.format_json_multi(all_results))
+    return 1 if overall_fail else 0
+
+
+def cmd_repair(args: argparse.Namespace) -> int:
+    if args.provider not in PROVIDERS:
+        raise SystemExit(f"error: unknown provider {args.provider!r}")
+    try:
+        schema = _load_schema(args.schema)
+        fixed, rep = repair(schema, args.provider)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: cannot read schema {args.schema!r}: {exc}", file=sys.stderr)
+        return 2
+    except RecursionError:
+        print(
+            f"error: schema {args.schema!r} is too deeply nested to repair safely",
+            file=sys.stderr,
+        )
+        return 2
+    rendered = json.dumps(fixed, indent=2, sort_keys=True)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            fh.write(rendered + "\n")
+        print(f"wrote {args.out}", file=sys.stderr)
+    else:
+        print(rendered)
+    print(
+        f"repair: auto_fixed={len(rep['auto_fixed'])} "
+        f"lossy={len(rep['lossy'])} manual_required={len(rep['manual_required'])}",
+        file=sys.stderr,
+    )
+    for tag in rep["manual_required"]:
+        print(f"  MANUAL {tag}", file=sys.stderr)
+    return 0
+
+
+def cmd_providers(_args: argparse.Namespace) -> int:
+    for p in PROVIDERS:
+        print(p)
+    return 0
+
+
+def cmd_demo(_args: argparse.Namespace) -> int:
+    """Hermetic end-to-end proof of the spine: lint -> repair -> matrix."""
+    print("== schemafit demo ==")
+    before = lint(DEMO_BAD_SCHEMA, "anthropic")
+    n_before = sum(1 for f in before if f.severity == "error")
+    exit_before = 1 if has_errors(before) else 0
+    print(f"PROVIDER=anthropic INPUT=demo-bad VIOLATIONS={n_before} EXIT={exit_before}")
+    if before:
+        print(
+            f"VIOLATION_PATH={before[0].json_pointer} "
+            f"(keyword: {before[0].keyword} -> rejected by anthropic)"
+        )
+
+    fixed, rep = repair(DEMO_BAD_SCHEMA, "anthropic")
+    after = lint(fixed, "anthropic")
+    n_after = sum(1 for f in after if f.severity == "error")
+    exit_after = 1 if has_errors(after) else 0
+    print(
+        f"--- after `schemafit repair --provider anthropic` --- "
+        f"VIOLATIONS={n_after} EXIT={exit_after} auto_fixed={len(rep['auto_fixed'])}"
+    )
+
+    matrix = lint_multi(DEMO_BAD_SCHEMA, list(PROVIDERS))
+    rendered = " ".join(
+        f"{p}={'FAIL' if has_errors(matrix[p]) else 'PASS'}" for p in PROVIDERS
+    )
+    print(f"MULTI: {rendered}")
+    gem_warns = sum(1 for f in matrix["gemini"] if f.severity == "warning")
+    print(f"NOTE: gemini portability warnings={gem_warns} (version-sensitive, non-failing)")
+
+    ok = has_errors(before) and not has_errors(after)
+    print("PROOF_OK" if ok else "PROOF_FAILED")
+    return 0 if ok else 3
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="schemafit",
+        description="Provider-aware structured-output / JSON-Schema CI linter.",
+    )
+    parser.add_argument("--version", action="version", version=f"schemafit {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_lint = sub.add_parser("lint", help="lint one or more schemas against one or more providers")
+    p_lint.add_argument("schemas", nargs="+", help="schema JSON file(s) ('-' = stdin)")
+    p_lint.add_argument("--provider", required=True, help="comma list: openai,anthropic,gemini")
+    p_lint.add_argument("--format", choices=("human", "json"), default="human")
+    p_lint.add_argument("--strict", action="store_true", help="also fail (exit 1) on warnings")
+    p_lint.set_defaults(func=cmd_lint)
+
+    p_rep = sub.add_parser("repair", help="emit a best-effort provider-valid variant")
+    p_rep.add_argument("schema", help="path to a JSON schema file, or '-' for stdin")
+    p_rep.add_argument("--provider", required=True, help="one of: openai|anthropic|gemini")
+    p_rep.add_argument("--out", help="write fixed schema here (default: stdout)")
+    p_rep.set_defaults(func=cmd_repair)
+
+    p_prov = sub.add_parser("providers", help="list supported providers")
+    p_prov.set_defaults(func=cmd_providers)
+
+    p_demo = sub.add_parser("demo", help="run a hermetic end-to-end proof")
+    p_demo.set_defaults(func=cmd_demo)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)

schemafit/linter.py

@@ -0,0 +1,125 @@
+"""The lint engine: apply a provider's declarative rule pack to a schema."""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+
+from .model import Finding
+from .walk import walk
+
+PROVIDERS: tuple[str, ...] = ("openai", "anthropic", "gemini")
+
+_RULE_CACHE: dict[str, dict] = {}
+
+
+def load_rule_pack(provider: str) -> dict:
+    """Load a provider's JSON rule pack from packaged data (cached)."""
+    if provider not in PROVIDERS:
+        raise ValueError(f"unknown provider: {provider!r} (choose from {', '.join(PROVIDERS)})")
+    if provider not in _RULE_CACHE:
+        text = files("schemafit").joinpath("rules", f"{provider}.json").read_text(encoding="utf-8")
+        _RULE_CACHE[provider] = json.loads(text)
+    return _RULE_CACHE[provider]
+
+
+def _is_object_schema(node: dict) -> bool:
+    t = node.get("type")
+    if t == "object":
+        return True
+    if isinstance(t, list) and "object" in t:
+        return True
+    # Untyped schema: a 'properties' key implies an object. But if an explicit
+    # non-object type is declared, a stray 'properties' key does NOT make it one
+    # (e.g. {"type": "array", "properties": {...}} is an array, not an object).
+    if t is None:
+        return "properties" in node
+    return False
+
+
+def _join(pointer: str, token: str) -> str:
+    return f"{pointer}/{token}"
+
+
+def apply_rule(
+    rule: dict, provider: str, nodes: list[tuple[str, dict, frozenset[str]]]
+) -> list[Finding]:
+    """Apply one rule across every walked node, returning findings."""
+    kind = rule["kind"]
+    out: list[Finding] = []
+
+    def mk(node_ptr: str, json_ptr: str, keyword: str) -> Finding:
+        return Finding(
+            provider=provider,
+            rule_id=rule["id"],
+            kind=kind,
+            node_pointer=node_ptr,
+            json_pointer=json_ptr,
+            keyword=keyword,
+            reason=rule.get("reason", ""),
+            severity=rule.get("severity", "error"),
+            doc_url=rule.get("doc_url", ""),
+            auto_repair=rule.get("auto_repair", "manual"),
+        )
+
+    if kind == "forbidden_keyword":
+        kw = rule["keyword"]
+        for ptr, node, _ctx in nodes:
+            if kw in node:
+                out.append(mk(ptr, _join(ptr, kw), kw))
+
+    elif kind == "forbidden_keyword_in_context":
+        kw = rule["keyword"]
+        need = rule["context"]
+        for ptr, node, ctx in nodes:
+            if need in ctx and kw in node:
+                out.append(mk(ptr, _join(ptr, kw), kw))
+
+    elif kind == "object_requires":
+        kw = rule["keyword"]
+        val = rule["value"]
+        for ptr, node, _ctx in nodes:
+            if _is_object_schema(node) and node.get(kw) != val:
+                # If the keyword is absent, point at the offending object node
+                # (a "<ptr>/<kw>" pointer would not resolve in the source).
+                json_ptr = _join(ptr, kw) if kw in node else ptr
+                out.append(mk(ptr, json_ptr, kw))
+
+    elif kind == "object_all_properties_required":
+        for ptr, node, _ctx in nodes:
+            props = node.get("properties")
+            if _is_object_schema(node) and isinstance(props, dict):
+                required = set(node.get("required", []) or [])
+                for name in props:
+                    if name not in required:
+                        # Point at the property that should be required (resolves).
+                        out.append(mk(ptr, _join(_join(ptr, "properties"), name), name))
+
+    elif kind == "forbidden_additional_properties_schema":
+        for ptr, node, _ctx in nodes:
+            if isinstance(node.get("additionalProperties"), dict):
+                out.append(mk(ptr, _join(ptr, "additionalProperties"), "additionalProperties"))
+
+    else:  # defensive: unknown rule kind in a pack
+        raise ValueError(f"unknown rule kind: {kind!r} (rule {rule.get('id')!r})")
+
+    return out
+
+
+def lint(schema: object, provider: str) -> list[Finding]:
+    """Lint ``schema`` against one provider; return sorted findings."""
+    pack = load_rule_pack(provider)
+    nodes = list(walk(schema))
+    findings: list[Finding] = []
+    for rule in pack.get("rules", []):
+        findings.extend(apply_rule(rule, provider, nodes))
+    findings.sort(key=lambda f: (f.json_pointer, f.rule_id, f.keyword))
+    return findings
+
+
+def lint_multi(schema: object, providers: list[str]) -> dict[str, list[Finding]]:
+    return {p: lint(schema, p) for p in providers}
+
+
+def has_errors(findings: list[Finding]) -> bool:
+    return any(f.severity == "error" for f in findings)

schemafit/model.py

@@ -0,0 +1,37 @@
+"""Data model for lint findings."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single provider-compatibility violation in a schema.
+
+    Attributes:
+        provider: the provider the rule belongs to (openai|anthropic|gemini).
+        rule_id: stable identifier of the rule that fired.
+        kind: the rule kind (drives auto-repair dispatch).
+        node_pointer: JSON Pointer to the subschema the rule applies to.
+        json_pointer: JSON Pointer to the precise offending location (keyword).
+        keyword: the JSON-Schema keyword / property name involved.
+        reason: human-readable explanation.
+        severity: "error" (fails CI) or "warning".
+        doc_url: primary-source link documenting the constraint.
+    """
+
+    provider: str
+    rule_id: str
+    kind: str
+    node_pointer: str
+    json_pointer: str
+    keyword: str
+    reason: str
+    severity: str = "error"
+    doc_url: str = ""
+    auto_repair: str = "manual"  # strip | set_false | fill_required | manual
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

schemafit/repair.py

@@ -0,0 +1,63 @@
+"""Best-effort, conservative auto-repair toward a provider-valid schema.
+
+Repair is deliberately limited to transforms that are *safe* or whose lossiness
+is reported. It never silently changes meaning without flagging it. Transforms
+it cannot perform safely are returned as ``manual_required`` rather than guessed.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from .linter import lint
+from .walk import resolve_pointer
+
+
+def repair(schema: object, provider: str) -> tuple[Any, dict]:
+    """Return ``(fixed_schema, report)``.
+
+    report = {auto_fixed: [...], lossy: [...], manual_required: [...]}
+    Each entry is a short ``"<rule_id> @ <pointer>"`` string.
+    """
+    fixed = copy.deepcopy(schema)
+    report: dict[str, list[str]] = {"auto_fixed": [], "lossy": [], "manual_required": []}
+
+    # Re-lint the working copy; apply fixes by each rule's declared strategy.
+    for finding in lint(fixed, provider):
+        if finding.severity != "error":
+            continue  # warnings don't fail CI; leave them for the author
+        node = resolve_pointer(fixed, finding.node_pointer)
+        if not isinstance(node, dict):
+            # The node was removed/overwritten by an earlier fix in this pass —
+            # already handled; do not emit a dangling tag.
+            continue
+        tag = f"{finding.rule_id} @ {finding.json_pointer}"
+
+        strategy = finding.auto_repair
+        if strategy == "strip":
+            # Dropping a validation constraint is provider-valid but lossy.
+            if finding.keyword in node:
+                del node[finding.keyword]
+                report["auto_fixed"].append(tag)
+                report["lossy"].append(tag)
+        elif strategy == "set_false":
+            # Overwriting a subschema (open-map) with False discards a constraint.
+            if isinstance(node.get(finding.keyword), dict):
+                report["lossy"].append(tag)
+            node[finding.keyword] = False
+            report["auto_fixed"].append(tag)
+        elif strategy == "fill_required":
+            props = node.get("properties")
+            if isinstance(props, dict):
+                node["required"] = sorted(set(node.get("required", []) or []) | set(props))
+                report["auto_fixed"].append(tag)
+                report["lossy"].append(tag)  # optional fields made required
+            else:
+                report["manual_required"].append(tag)
+        else:
+            # "manual": structural rewrites (anyOf/oneOf removal, dict->object)
+            # are unsafe to guess — surface for a human.
+            report["manual_required"].append(tag)
+
+    return fixed, report

schemafit/report.py

@@ -0,0 +1,48 @@
+"""Human and JSON reporters for lint results."""
+
+from __future__ import annotations
+
+import json
+
+from .model import Finding
+
+
+def _status(findings: list[Finding]) -> str:
+    return "FAIL" if any(f.severity == "error" for f in findings) else "PASS"
+
+
+def format_human(results: dict[str, list[Finding]]) -> str:
+    lines: list[str] = []
+    for provider, findings in results.items():
+        errs = [f for f in findings if f.severity == "error"]
+        warns = [f for f in findings if f.severity != "error"]
+        lines.append(
+            f"[{provider}] {_status(findings)} — {len(errs)} error(s), {len(warns)} warning(s)"
+        )
+        for f in findings:
+            lines.append(f"  {f.severity.upper():<7} {f.json_pointer}  ({f.rule_id})")
+            lines.append(f"          {f.reason}")
+            if f.doc_url:
+                lines.append(f"          ref: {f.doc_url}")
+    if not lines:
+        lines.append("(no providers selected)")
+    return "\n".join(lines)
+
+
+def _results_payload(results: dict[str, list[Finding]]) -> dict:
+    return {
+        provider: {
+            "status": _status(findings),
+            "findings": [f.to_dict() for f in findings],
+        }
+        for provider, findings in results.items()
+    }
+
+
+def format_json(results: dict[str, list[Finding]]) -> str:
+    return json.dumps(_results_payload(results), indent=2, sort_keys=True)
+
+
+def format_json_multi(all_results: dict[str, dict[str, list[Finding]]]) -> str:
+    payload = {path: _results_payload(results) for path, results in all_results.items()}
+    return json.dumps(payload, indent=2, sort_keys=True)

schemafit/rules/anthropic.json

@@ -0,0 +1,19 @@
+{
+  "provider": "anthropic",
+  "doc": "JSON-Schema validation keywords Anthropic rejects on the STRICT structured-output path (400 Bad Request), keyword set confirmed verbatim in vercel/ai#13355. SCOPE: these target the structured-output / response_format surface (where the AI SDK had to strip them to avoid a 400); general Messages-API tool input_schema is more permissive and may accept (ignore) some of these. Run this pack against schemas you send on the structured-output path.",
+  "rules": [
+    {"id": "anthropic-no-minLength", "kind": "forbidden_keyword", "keyword": "minLength", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'minLength' validation keyword in structured-output/tool schemas (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-maxLength", "kind": "forbidden_keyword", "keyword": "maxLength", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'maxLength' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-pattern", "kind": "forbidden_keyword", "keyword": "pattern", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'pattern' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-format", "kind": "forbidden_keyword", "keyword": "format", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'format' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-minimum", "kind": "forbidden_keyword", "keyword": "minimum", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'minimum' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-maximum", "kind": "forbidden_keyword", "keyword": "maximum", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'maximum' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-exclusiveMinimum", "kind": "forbidden_keyword", "keyword": "exclusiveMinimum", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'exclusiveMinimum' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-exclusiveMaximum", "kind": "forbidden_keyword", "keyword": "exclusiveMaximum", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'exclusiveMaximum' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-minItems", "kind": "forbidden_keyword", "keyword": "minItems", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'minItems' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-maxItems", "kind": "forbidden_keyword", "keyword": "maxItems", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'maxItems' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-uniqueItems", "kind": "forbidden_keyword", "keyword": "uniqueItems", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'uniqueItems' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-minProperties", "kind": "forbidden_keyword", "keyword": "minProperties", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'minProperties' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"},
+    {"id": "anthropic-no-maxProperties", "kind": "forbidden_keyword", "keyword": "maxProperties", "severity": "error", "auto_repair": "strip", "reason": "Anthropic rejects the 'maxProperties' validation keyword (400 Bad Request).", "doc_url": "https://github.com/vercel/ai/issues/13355"}
+  ]
+}

schemafit/rules/gemini.json

@@ -0,0 +1,41 @@
+{
+  "provider": "gemini",
+  "doc": "Gemini response_schema portability cautions. NOTE: Gemini's structured-output schema support has evolved fast — Gemini 2.5 added anyOf (Jan 2026) and the API added additionalProperties (Nov 2025); older models (<=2.0) and older python-genai SDK versions rejected them. These are therefore emitted as WARNINGS (version-sensitive portability cautions), not hard errors — use --strict to fail CI on them.",
+  "rules": [
+    {
+      "id": "gemini-anyof-version-sensitive",
+      "kind": "forbidden_keyword",
+      "keyword": "anyOf",
+      "severity": "warning",
+      "auto_repair": "manual",
+      "reason": "'anyOf' is supported by current Gemini 2.5 (Jan 2026) but raises 'AnyOf is not supported' on older Gemini models / older python-genai. Portability caution for older targets.",
+      "doc_url": "https://github.com/googleapis/python-genai/issues/460"
+    },
+    {
+      "id": "gemini-oneof-unsupported",
+      "kind": "forbidden_keyword",
+      "keyword": "oneOf",
+      "severity": "warning",
+      "auto_repair": "manual",
+      "reason": "Gemini's response schema models alternatives via 'anyOf', not 'oneOf'; 'oneOf' is not a documented response_schema keyword. Prefer anyOf.",
+      "doc_url": "https://ai.google.dev/gemini-api/docs/structured-output"
+    },
+    {
+      "id": "gemini-open-dict-version-sensitive",
+      "kind": "forbidden_additional_properties_schema",
+      "severity": "warning",
+      "auto_repair": "manual",
+      "reason": "Open-ended dict/map types (additionalProperties as a schema): the Gemini API added additionalProperties support (Nov 2025), but older python-genai rejects it client-side. Portability caution for older SDK versions.",
+      "doc_url": "https://github.com/googleapis/python-genai/issues/1815"
+    },
+    {
+      "id": "gemini-ref-recursion-risk",
+      "kind": "forbidden_keyword",
+      "keyword": "$ref",
+      "severity": "warning",
+      "auto_repair": "manual",
+      "reason": "Gemini may fail on '$ref' / self-referencing schemas (maximum recursion errors); inline or flatten the reference.",
+      "doc_url": "https://github.com/googleapis/python-genai/issues/460"
+    }
+  ]
+}

schemafit/rules/openai.json

@@ -0,0 +1,43 @@
+{
+  "provider": "openai",
+  "doc": "OpenAI strict structured-outputs / response_format constraints",
+  "rules": [
+    {
+      "id": "openai-additional-properties-false",
+      "kind": "object_requires",
+      "keyword": "additionalProperties",
+      "value": false,
+      "severity": "error",
+      "auto_repair": "set_false",
+      "reason": "OpenAI strict structured outputs require every object schema to set additionalProperties:false.",
+      "doc_url": "https://platform.openai.com/docs/guides/structured-outputs"
+    },
+    {
+      "id": "openai-all-properties-required",
+      "kind": "object_all_properties_required",
+      "severity": "error",
+      "auto_repair": "fill_required",
+      "reason": "OpenAI strict structured outputs require every defined property to appear in 'required' (model optionality via a nullable union instead).",
+      "doc_url": "https://platform.openai.com/docs/guides/structured-outputs"
+    },
+    {
+      "id": "openai-no-default",
+      "kind": "forbidden_keyword",
+      "keyword": "default",
+      "severity": "error",
+      "auto_repair": "strip",
+      "reason": "OpenAI structured outputs reject 'default' within a property definition.",
+      "doc_url": "https://github.com/openai/openai-agents-python/issues/474"
+    },
+    {
+      "id": "openai-no-oneof-in-array-items",
+      "kind": "forbidden_keyword_in_context",
+      "keyword": "oneOf",
+      "context": "array_items",
+      "severity": "error",
+      "auto_repair": "manual",
+      "reason": "OpenAI rejects 'oneOf' within the items definition of an array property (use anyOf).",
+      "doc_url": "https://github.com/openai/openai-agents-python/issues/474"
+    }
+  ]
+}

schemafit/walk.py

@@ -0,0 +1,120 @@
+"""Deterministic JSON-Schema traversal with JSON-Pointer tracking.
+
+Yields every *object-form* subschema node, with a precise JSON Pointer and an
+*edge context* (how this node relates to its parent, e.g. it is an array's
+``items`` schema). The context describes only the immediate parent edge and is
+intentionally NOT inherited, so a rule like "oneOf is forbidden inside array
+items" matches the items schema itself and not arbitrarily deep descendants.
+
+Boolean subschemas (the JSON-Schema ``true``/``false`` forms) are not yielded:
+they carry no keywords for the rule engine to inspect. Provider rules that care
+about the open-map form check the parent node's keyword value directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+# subschema maps: {name -> schema}
+_CHILD_MAP_KEYS = ("properties", "patternProperties", "$defs", "definitions", "dependentSchemas")
+# single subschema values
+_CHILD_SCHEMA_KEYS = (
+    "items",
+    "additionalItems",
+    "additionalProperties",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+    "contains",
+    "contentSchema",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+)
+# lists of subschemas
+_CHILD_LIST_KEYS = ("allOf", "anyOf", "oneOf", "prefixItems")
+
+
+def _escape(token: str) -> str:
+    """Escape a JSON Pointer reference token (RFC 6901)."""
+    return token.replace("~", "~0").replace("/", "~1")
+
+
+def _unescape(token: str) -> str:
+    return token.replace("~1", "/").replace("~0", "~")
+
+
+def walk(
+    schema: object,
+    pointer: str = "#",
+    context: frozenset[str] = frozenset(),
+) -> Iterator[tuple[str, dict, frozenset[str]]]:
+    """Yield ``(json_pointer, node, edge_context)`` for every subschema dict."""
+    if not isinstance(schema, dict):
+        return
+    yield pointer, schema, context
+
+    for key in _CHILD_MAP_KEYS:
+        sub = schema.get(key)
+        if isinstance(sub, dict):
+            child_ctx = frozenset({"property"}) if key == "properties" else frozenset()
+            for name, child in sub.items():
+                yield from walk(child, f"{pointer}/{key}/{_escape(str(name))}", child_ctx)
+
+    for key in _CHILD_SCHEMA_KEYS:
+        sub = schema.get(key)
+        if isinstance(sub, dict):
+            if key in ("items", "additionalItems", "unevaluatedItems"):
+                child_ctx = frozenset({"array_items"})
+            elif key in ("additionalProperties", "unevaluatedProperties"):
+                child_ctx = frozenset({"additional_properties"})
+            else:
+                child_ctx = frozenset()
+            yield from walk(sub, f"{pointer}/{key}", child_ctx)
+        elif key == "items" and isinstance(sub, list):
+            # tuple validation: items as an array of schemas
+            for i, child in enumerate(sub):
+                yield from walk(child, f"{pointer}/items/{i}", frozenset({"array_items"}))
+
+    for key in _CHILD_LIST_KEYS:
+        sub = schema.get(key)
+        if isinstance(sub, list):
+            for i, child in enumerate(sub):
+                child_ctx = (
+                    frozenset({"array_items"})
+                    if key == "prefixItems"
+                    else frozenset({f"{key}_member"})
+                )
+                yield from walk(child, f"{pointer}/{key}/{i}", child_ctx)
+
+    # draft-07 "dependencies": map of name -> (schema | list[str]). Only dict
+    # values are subschemas; array values are property-name lists, so skip them.
+    deps = schema.get("dependencies")
+    if isinstance(deps, dict):
+        for name, child in deps.items():
+            if isinstance(child, dict):
+                yield from walk(child, f"{pointer}/dependencies/{_escape(str(name))}", frozenset())
+
+
+def resolve_pointer(root: object, pointer: str) -> object | None:
+    """Resolve a JSON Pointer (``#`` / ``#/a/b/0``) to its node, or None."""
+    if pointer in ("#", ""):
+        return root
+    if not pointer.startswith("#/"):
+        return None
+    node: object = root
+    for raw in pointer[2:].split("/"):
+        token = _unescape(raw)
+        if isinstance(node, list):
+            try:
+                node = node[int(token)]
+            except (ValueError, IndexError):
+                return None
+        elif isinstance(node, dict):
+            if token not in node:
+                return None
+            node = node[token]
+        else:
+            return None
+    return node

schemafit-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: schemafit
+Version: 0.1.0
+Summary: Provider-aware structured-output / JSON-Schema CI linter — fail CI before your schema 400s on OpenAI, Anthropic, or Gemini
+Author-email: Dan Mercede <dan@danmercede.com>
+License: MIT
+Project-URL: Homepage, https://github.com/OrionArchitekton/schemafit
+Project-URL: Issues, https://github.com/OrionArchitekton/schemafit/issues
+Keywords: json-schema,structured-output,openai,anthropic,gemini,llm,ci,linter,tool-calling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# schemafit
+
+**Provider-aware structured-output / JSON-Schema CI linter.** Catch the schema
+incompatibilities that make one provider `400` while another succeeds — *before*
+they hit production, as a fast, offline CI check.
+
+A JSON Schema / tool definition / `response_format` that works on OpenAI can
+`400` on Anthropic or Gemini (and vice-versa): nested `oneOf`, a missing
+`additionalProperties: false`, a `default` in a property, Anthropic-rejected
+validation keywords (`minLength`, `format`, `pattern`, …), Gemini's lack of
+`anyOf`/dict support. The API tells you it failed but not *which constraint*
+violated it, so teams hand-port schemas and debug by trial-and-error at runtime.
+
+`schemafit` encodes each provider's documented constraint surface as a
+**versioned, declarative rule pack** and lints your schema statically — pointing
+at the exact JSON-Pointer path, the keyword, and why — with a non-zero exit code
+so CI fails the PR instead of prod.
+
+> Every rule is grounded in a real, cited provider issue (see
+> [`schemafit/rules/`](schemafit/rules/)). It is **not** a runtime client: it
+> makes no model calls, needs no API key, and has **zero runtime dependencies**.
+
+## Why this and not Instructor / BAML / LiteLLM / Vercel AI SDK?
+
+Those are excellent **runtime** clients — they normalize, repair, or constrain a
+schema *at call-time*. `schemafit` fills the gap they leave: a **static,
+pre-ship CI lint** that fails the build before the schema ever reaches a
+provider, over the raw schemas you already ship, with no DSL or codegen buy-in.
+
+## Install
+
+```bash
+# From source (works today):
+pip install "git+https://github.com/OrionArchitekton/schemafit"
+# or build and run the container:
+docker build -t schemafit . && docker run --rm schemafit demo
+```
+
+Once the first release is tagged (`v0.1.0`), `pip install schemafit` (PyPI) and
+`docker run --rm ghcr.io/orionarchitekton/schemafit demo` (GHCR) become
+available — both are published by the release workflow on a `v*` tag (PyPI via
+Trusted Publishing; image to GHCR).
+
+## Usage
+
+```bash
+# Lint one schema against several providers (exit 1 if any error):
+schemafit lint my-schema.json --provider openai,anthropic,gemini
+
+# Machine-readable output for CI annotations:
+schemafit lint my-schema.json --provider anthropic --format json
+
+# Also fail on warnings (e.g. Gemini $ref recursion risk):
+schemafit lint my-schema.json --provider gemini --strict
+
+# Emit a best-effort provider-valid variant (lossy transforms are flagged):
+schemafit repair my-schema.json --provider anthropic --out fixed.json
+
+# List supported providers / run a hermetic end-to-end proof:
+schemafit providers
+schemafit demo
+```
+
+Example:
+
+```
+$ schemafit lint order.json --provider anthropic
+[anthropic] FAIL — 2 error(s), 0 warning(s)
+  ERROR   #/properties/sku/pattern  (anthropic-no-pattern)
+          Anthropic rejects the 'pattern' validation keyword (400 Bad Request).
+          ref: https://github.com/vercel/ai/issues/13355
+  ERROR   #/properties/qty/minimum  (anthropic-no-minimum)
+          Anthropic rejects the 'minimum' validation keyword (400 Bad Request).
+```
+
+## Use in CI
+
+GitHub Actions (this repo ships a composite action):
+
+```yaml
+- uses: OrionArchitekton/schemafit@v0.1.0
+  with:
+    schema: schemas/tool.json
+    providers: openai,anthropic,gemini
+```
+
+Or directly / as a pre-commit hook (`.pre-commit-hooks.yaml` is included):
+
+```yaml
+- repo: https://github.com/OrionArchitekton/schemafit
+  rev: v0.1.0
+  hooks:
+    - id: schemafit
+      args: ["--provider", "openai,anthropic,gemini"]
+      files: '^schemas/.*\.json$'   # scope to YOUR LLM schemas, not every .json
+```
+
+> Scope the hook with `files:` to the directory holding your LLM schemas — the
+> default `types: [json]` would otherwise lint every JSON file in the repo
+> (`package.json`, `tsconfig.json`, lockfiles), which are not LLM schemas.
+
+## Supported providers (v0.1)
+
+| Provider | Checks (grounded in) |
+|---|---|
+| `openai` | `additionalProperties:false` required; all properties required; no `default`; no `oneOf` in array items ([openai-agents-python#474](https://github.com/openai/openai-agents-python/issues/474), [claude-task-master#1522](https://github.com/eyaltoledano/claude-task-master/issues/1522)) |
+| `anthropic` | 13 rejected validation keywords on the **strict structured-output surface**: `minLength`/`maxLength`/`pattern`/`format`/`minimum`/`maximum`/`exclusiveMinimum`/`exclusiveMaximum`/`minItems`/`maxItems`/`uniqueItems`/`minProperties`/`maxProperties` ([vercel/ai#13355](https://github.com/vercel/ai/issues/13355), [anthropic-sdk-python#1034](https://github.com/anthropics/anthropic-sdk-python/issues/1034)). General Messages-API tool `input_schema` is more permissive — run this pack against schemas you send on the structured-output path. |
+| `gemini` | **Portability warnings** (version-sensitive, non-failing by default): `anyOf` (rejected by ≤2.0 / old SDKs, supported by 2.5), `oneOf`, open dict (`additionalProperties` schema), `$ref` recursion. Gemini's schema support changed fast (`anyOf` Jan 2026, `additionalProperties` Nov 2025), so these *warn* — use `--strict` to gate on them. ([python-genai#460](https://github.com/googleapis/python-genai/issues/460), [docs](https://ai.google.dev/gemini-api/docs/structured-output)) |
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| `0` | no errors (warnings allowed unless `--strict`) |
+| `1` | at least one error (CI fail) |
+| `2` | bad input (unreadable / invalid JSON) |
+
+## Scope (v0.1) and roadmap
+
+In scope now: the `lint` + `repair` core, three provider rule packs, JSON/human
+reporters, Docker image, GitHub Action, pre-commit hook.
+
+Deferred (v0.2+): a `--live-verify` mode that calls each provider to confirm,
+an npm/`ajv` port for the JS/TS ecosystem, more providers (Mistral, Cohere,
+Bedrock, Vertex), automatic rule-pack drift detection, SARIF output, and
+source-model (Pydantic/Zod) auto-fix.
+
+## License
+
+MIT © 2026 Dan Mercede

schemafit-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+schemafit/__init__.py,sha256=OKm75l--MWFyLsnccCqeksa-8ovPurvAvIKOdQmyKrA,569
+schemafit/__main__.py,sha256=ueatLyYgr_5e0HWnJz5NnQtr1XYm4Trjt-ReXzeimF4,158
+schemafit/cli.py,sha256=h6V1VRKScL7zENWbFiWQhqJotCrnpYjSPLGiVHHVrtc,7086
+schemafit/linter.py,sha256=0H2nlRlOvYqkOidmafIfVQu107S5o1Hxs0qnwiMSoi8,4564
+schemafit/model.py,sha256=3PWvObnayPFd8IQCpHVIQOfIVcvhb-1rZPB8H2AZaWA,1167
+schemafit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+schemafit/repair.py,sha256=weTja-zDlfG7F_Ed8WEb6IYLDEKV1dn9i3S5tnT3z2s,2659
+schemafit/report.py,sha256=eJxoEjv74MpwWtGj8mVk88UV6U6nwdb7sbKr5bEq8ew,1613
+schemafit/walk.py,sha256=Zx6PsC6TMhLTywBvwQxTkOOYfXxPJ_CfpuR-_8m9p4A,4382
+schemafit/rules/anthropic.json,sha256=UgnTjxJSBWMrJfQjzm1LfbwalpPA4_r_Rgdv52DwSGE,4178
+schemafit/rules/gemini.json,sha256=2dqB29YpwmJq35KWGtW9gzGMxkOeof8d32K0RnezPVY,2181
+schemafit/rules/openai.json,sha256=tnrzYKFE0SwuTBWepMUOnYZ4IqUZyhWIEk2r2I5LMAo,1676
+schemafit-0.1.0.dist-info/licenses/LICENSE,sha256=aEsJcRjMZ6XR41a3faplwrgpqBMl1z3fwBQO624QpW8,1068
+schemafit-0.1.0.dist-info/METADATA,sha256=C2MpqKUXbZ6IFA-4UQwThw6iuV0862eXjryOuxqWn6g,7011
+schemafit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+schemafit-0.1.0.dist-info/entry_points.txt,sha256=WAUOkQAkdGIkE6lZs5q4xymnkJFDdZJVXNTxXUbnDkI,49
+schemafit-0.1.0.dist-info/top_level.txt,sha256=zvvzqzOkWVw8KVruRkvqYC9IUKoXAN7PGiAKlVgVq3w,10
+schemafit-0.1.0.dist-info/RECORD,,

schemafit-0.1.0.dist-info/WHEEL

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

schemafit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+schemafit = schemafit.cli:main

schemafit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Mercede
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schemafit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+schemafit