schemafit 0.1.0__tar.gz

schemafit-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,130 @@
+# 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/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "schemafit"
+version = "0.1.0"
+description = "Provider-aware structured-output / JSON-Schema CI linter — fail CI before your schema 400s on OpenAI, Anthropic, or Gemini"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Dan Mercede", email = "dan@danmercede.com" }]
+keywords = ["json-schema", "structured-output", "openai", "anthropic", "gemini", "llm", "ci", "linter", "tool-calling"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/OrionArchitekton/schemafit"
+Issues = "https://github.com/OrionArchitekton/schemafit/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+schemafit = "schemafit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["schemafit*"]
+
+[tool.setuptools.package-data]
+schemafit = ["rules/*.json", "py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"

schemafit-0.1.0/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-0.1.0/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-0.1.0/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)