schemarouter 0.2.0a1__tar.gz → 0.3.0a1__tar.gz

schemarouter-0.3.0a1/.github/workflows/auto-tag-release.yml

@@ -0,0 +1,99 @@
+name: Auto Tag Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: auto-tag-release-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: false
+
+jobs:
+  tag:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Verify release commit is still current main
+        env:
+          RELEASE_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          git fetch origin main --depth=1
+          current_main="$(git rev-parse origin/main)"
+          if [[ "$current_main" != "$RELEASE_SHA" ]]; then
+            echo "CI succeeded for $RELEASE_SHA, but current main is $current_main; skipping stale run."
+            echo "SKIP_RELEASE_TAG=true" >> "$GITHUB_ENV"
+          fi
+
+      - name: Resolve release metadata
+        if: env.SKIP_RELEASE_TAG != 'true'
+        id: metadata
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          if ".dev" in version:
+              with Path(os.environ["GITHUB_OUTPUT"]).open("a", encoding="utf-8") as output:
+                  print("releasable=false", file=output)
+              raise SystemExit(0)
+
+          release_notes = Path("docs") / "releases" / f"{version}.md"
+          if not release_notes.is_file():
+              raise SystemExit(f"missing release notes for releasable version: {release_notes}")
+
+          changelog = Path("CHANGELOG.md").read_text(encoding="utf-8")
+          if f"## {version} -" not in changelog:
+              raise SystemExit(f"CHANGELOG.md is missing a dated {version} release heading")
+
+          if not re.fullmatch(r"\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?", version):
+              raise SystemExit(f"unsupported automatic release version format: {version!r}")
+
+          with Path(os.environ["GITHUB_OUTPUT"]).open("a", encoding="utf-8") as output:
+              print("releasable=true", file=output)
+              print(f"version={version}", file=output)
+              print(f"tag=v{version}", file=output)
+          PY
+
+      - name: Check whether release tag already exists
+        if: >-
+          env.SKIP_RELEASE_TAG != 'true' &&
+          steps.metadata.outputs.releasable == 'true'
+        id: existing
+        env:
+          RELEASE_TAG: ${{ steps.metadata.outputs.tag }}
+        run: |
+          if git ls-remote --exit-code --tags origin "refs/tags/$RELEASE_TAG" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "$RELEASE_TAG already exists; nothing to do."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create annotated release tag
+        if: >-
+          env.SKIP_RELEASE_TAG != 'true' &&
+          steps.metadata.outputs.releasable == 'true' &&
+          steps.existing.outputs.exists == 'false'
+        env:
+          RELEASE_SHA: ${{ github.event.workflow_run.head_sha }}
+          RELEASE_TAG: ${{ steps.metadata.outputs.tag }}
+          RELEASE_VERSION: ${{ steps.metadata.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$RELEASE_TAG" "$RELEASE_SHA" -m "SchemaRouter $RELEASE_VERSION"
+          git push origin "refs/tags/$RELEASE_TAG"

schemarouter-0.3.0a1/.github/workflows/ci.yml

@@ -0,0 +1,205 @@
+name: CI
+
+on:
+  workflow_call:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q -m "not mcp_integration"
+      - run: python examples/quickstart.py
+
+  python-preview:
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.15.0-rc.2"
+          allow-prereleases: true
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q -m "not mcp_integration"
+      - run: python examples/quickstart.py
+
+  windows-smoke:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q -m "not mcp_integration"
+      - run: python examples/quickstart.py
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,mcp,langchain,llamaindex,jev,otel]"
+      - run: pyright
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,mcp,langchain,llamaindex,jev,otel]"
+      - run: pytest -q --cov=schemarouter --cov-branch --cov-report=term-missing --cov-report=xml:coverage.xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml
+          if-no-files-found: error
+          retention-days: 14
+
+  minimum-dependencies:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.10"
+      - run: python -m pip install --upgrade pip
+      - run: pip install "pytest>=8.2" "pytest-asyncio>=0.23"
+      - run: pip install "httpx==0.27.0" "jsonschema==4.23.0" "pydantic==2.8.0" "pyyaml==6.0.0"
+      - run: pip install -e . --no-deps
+      - run: pytest -q -m "not mcp_integration"
+      - run: python examples/quickstart.py
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: Verify license is packaged
+        run: |
+          python - <<'PY'
+          import glob
+          import zipfile
+
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert any(name.endswith("/licenses/LICENSE") for name in names), names
+          PY
+      - run: python -m venv /tmp/schemarouter-wheel
+      - run: /tmp/schemarouter-wheel/bin/python -m pip install --upgrade pip
+      - run: /tmp/schemarouter-wheel/bin/pip install dist/*.whl
+      - run: /tmp/schemarouter-wheel/bin/python -c "from importlib.metadata import version; import schemarouter; assert schemarouter.__version__ == version('schemarouter')"
+      - run: /tmp/schemarouter-wheel/bin/python examples/quickstart.py
+      - run: /tmp/schemarouter-wheel/bin/python scripts/benchmark_decision_routing.py
+      - run: python -m venv /tmp/schemarouter-sdist
+      - run: /tmp/schemarouter-sdist/bin/python -m pip install --upgrade pip
+      - run: /tmp/schemarouter-sdist/bin/pip install dist/*.tar.gz
+      - run: /tmp/schemarouter-sdist/bin/python -c "from importlib.metadata import version; import schemarouter; assert schemarouter.__version__ == version('schemarouter')"
+      - run: /tmp/schemarouter-sdist/bin/python examples/quickstart.py
+
+  langchain-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,langchain]"
+      - run: pytest -q tests/test_langchain_integration.py
+      - run: python examples/langchain_quickstart.py
+
+  llamaindex-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,llamaindex]"
+      - run: pytest -q tests/test_llamaindex_integration.py
+      - run: python examples/llamaindex_quickstart.py
+
+  jev-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,jev]"
+      - run: pytest -q tests/test_jev_integration.py
+
+  otel-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,otel]"
+      - run: pytest -q tests/test_opentelemetry_integration.py
+
+  mcp-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,mcp]"
+      - run: pytest -q tests/test_mcp_integration.py
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+        env:
+          NO_MKDOCS_2_WARNING: "1"

schemarouter-0.3.0a1/.github/workflows/release.yml

@@ -0,0 +1,161 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: quality
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.metadata.outputs.version }}
+      release_notes: ${{ steps.metadata.outputs.release_notes }}
+      prerelease: ${{ steps.metadata.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Resolve and verify release metadata
+        id: metadata
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if tag != expected:
+              raise SystemExit(f"tag {tag!r} does not match package version {expected!r}")
+          if ".dev" in version:
+              raise SystemExit("development versions cannot be published by the release workflow")
+
+          release_notes = Path("docs") / "releases" / f"{version}.md"
+          if not release_notes.is_file():
+              raise SystemExit(f"missing release notes: {release_notes}")
+
+          prerelease = bool(re.search(r"(?:a|b|rc)\d+(?:$|[.+-])", version))
+          with Path(os.environ["GITHUB_OUTPUT"]).open("a", encoding="utf-8") as output:
+              print(f"version={version}", file=output)
+              print(f"release_notes={release_notes.as_posix()}", file=output)
+              print(f"prerelease={'true' if prerelease else 'false'}", file=output)
+          PY
+      - run: python -m pip install --upgrade pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: Verify release artifact
+        env:
+          RELEASE_VERSION: ${{ steps.metadata.outputs.version }}
+        run: |
+          python - <<'PY'
+          import glob
+          import os
+          import subprocess
+          import sys
+          import tempfile
+          import venv
+          import zipfile
+          from pathlib import Path
+
+          wheel = glob.glob("dist/*.whl")[0]
+          sdist = glob.glob("dist/*.tar.gz")[0]
+
+          wheel_names = zipfile.ZipFile(wheel).namelist()
+          assert any(name.endswith("/licenses/LICENSE") for name in wheel_names), wheel_names
+
+          import tarfile
+
+          with tarfile.open(sdist, "r:gz") as archive:
+              sdist_names = archive.getnames()
+          assert any(name.endswith("/LICENSE") for name in sdist_names), sdist_names
+
+          for artifact in (wheel, sdist):
+              with tempfile.TemporaryDirectory() as root:
+                  env = Path(root) / "venv"
+                  venv.EnvBuilder(with_pip=True).create(env)
+                  python = env / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
+                  subprocess.check_call([str(python), "-m", "pip", "install", artifact])
+                  subprocess.check_call([
+                      str(python),
+                      "-c",
+                      (
+                          "from importlib.metadata import version; "
+                          "import schemarouter; "
+                          f"assert schemarouter.__version__ == {os.environ['RELEASE_VERSION']!r}; "
+                          f"assert version('schemarouter') == {os.environ['RELEASE_VERSION']!r}"
+                      ),
+                  ])
+                  subprocess.check_call([str(python), "examples/quickstart.py"])
+          PY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  github-release:
+    needs: build
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+      - name: Create or update GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ needs.build.outputs.version }}
+          RELEASE_NOTES: ${{ needs.build.outputs.release_notes }}
+          IS_PRERELEASE: ${{ needs.build.outputs.prerelease }}
+        run: |
+          prerelease_args=()
+          if [[ "$IS_PRERELEASE" == "true" ]]; then
+            prerelease_args+=(--prerelease)
+          fi
+
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+            gh release edit "$GITHUB_REF_NAME" \
+              --title "SchemaRouter $RELEASE_VERSION" \
+              --notes-file "$RELEASE_NOTES" \
+              "${prerelease_args[@]}"
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* \
+              --title "SchemaRouter $RELEASE_VERSION" \
+              --notes-file "$RELEASE_NOTES" \
+              "${prerelease_args[@]}" \
+              --verify-tag
+          fi
+
+  pypi:
+    needs: build
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/schemarouter/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

schemarouter-0.3.0a1/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to SchemaRouter are documented here.
+
+The project is pre-1.0 and follows the compatibility rules in
+[`docs/versioning.md`](docs/versioning.md).
+
+## Unreleased
+
+No unreleased changes yet.
+
+## 0.3.0a1 - 2026-09-22
+
+### Added
+
+- provider-neutral bounded `DecisionBackend` contracts with deterministic fallback;
+- optional `JevDecisionBackend` backed by TypeSafe System One through `schemarouter[jev]`;
+- optional LlamaIndex `FunctionTool` integration;
+- runnable LangChain and LlamaIndex integration examples enforced in CI;
+- provider-neutral decision-routing benchmark harness covering accuracy, abstention, latency,
+  token usage, and optional cost estimation;
+- explicit ecosystem compatibility matrix and integration maintenance policy;
+- Korean project overview in `README.ko.md`;
+- Python 3.13 and 3.14 core CI coverage;
+- a non-blocking Python 3.15 release-candidate preview;
+- a Windows + Python 3.14 smoke surface;
+- a Pyright static-type gate for the typed package surface;
+- full-suite branch-coverage reporting with an 82% blocking floor;
+- declared lower-bound runtime dependency testing;
+- clean wheel and sdist installation smoke tests;
+- a checked-in 144-case multilingual/adversarial decision-routing corpus with JSON/CSV output,
+  category metrics, invalid-plan rate, abstention/fallback tracking, and p50/p95 latency;
+- machine-readable OpenAPI compatibility reports for partial/unsupported constructs;
+- authenticated MCP trusted-header and custom client-factory transport boundaries;
+- trusted sync/async per-call approval callbacks;
+- per-run execution budgets for logical calls, attempts, remote attempts, elapsed time, per-tool
+  quotas, and application-defined cost units;
+- optional privacy-preserving OpenTelemetry run/tool span export;
+- explicit allowlisted third-party adapter plugins through `schemarouter.adapters` entry points.
+
+### Changed
+
+- current `main` now identifies as `0.3.0.dev0`, separating unreleased development builds from
+  the published `0.2.0a1` alpha;
+- release automation now derives version, release title, release-note path, prerelease state, and
+  artifact verification from `pyproject.toml` instead of hard-coded release literals;
+- tag releases reuse the same full CI quality workflow as pull requests and verify both wheel and
+  sdist artifacts in clean environments before publication;
+- superseded pull-request CI runs are cancelled automatically to avoid stale validation consuming
+  runner capacity;
+- releasable `main` commits are automatically annotated with `v<version>` only after green CI,
+  current-head verification, release-note/changelog validation, and duplicate-tag checks.
+
+### Security
+
+- OpenAPI runtime responses are now streamed through a bounded reader with a 16 MiB default limit,
+  enforcing the bound both from declared `Content-Length` and actual bytes received;
+- Jev option IDs are validated before confidence-based abstention, so unknown IDs always fail
+  closed;
+- Jev credentials remain SDK client configuration and are never placed in model state;
+- `DecisionOption.metadata` is not forwarded to Jev;
+- provider failures can deterministically fall back without weakening execution policy;
+- MCP credentials are rejected in URLs and remain outside tool/planner metadata;
+- MCP protocol-controlled headers cannot be overridden through trusted runtime headers;
+- adapter entry points are metadata-only during discovery and are never auto-imported;
+- OpenTelemetry export omits payload values, RunConfig metadata, tags, and exception messages;
+- approval callback failures and execution budget exhaustion fail closed.
+
+## 0.2.0a1 - 2026-09-20
+
+### Added
+
+- pluggable structured-source `AdapterRegistry` with explicit and priority-based auto discovery;
+- OPTIMADE v1 discovery through base and entry-type info endpoints;
+- OPTIMADE field-aware execution that maps planned fields to `response_fields`;
+- call-aware invoker support for protocol adapters that need the full `ToolCall`;
+- typed tool, endpoint, parameter, response-field, plan, and result contracts;
+- namespaced versioned registry;
+- schema-aware planning with recall-preserving field projection;
+- provider-neutral model-assisted query analysis;
+- OpenAPI 3.x URL ingestion and guarded HTTP execution;
+- MCP tool discovery and execution;
+- evidence-grounded proposals for human-readable API documentation;
+- runtime JSON Schema validation for arguments and raw outputs;
+- schema and invoker-binding drift detection;
+- fail-closed execution policy for mutations, destructive calls, and unclassified remote tools;
+- Runnable-style `invoke`, `batch`, `stream`, and typed event APIs;
+- run configuration, concurrency control, and safe retry policy;
+- typed Python callable registration with `@schema_tool`;
+- optional LangChain `StructuredTool` integration;
+- framework maturity, architecture, release, and versioning documentation;
+- MIT licensing and package metadata;
+- MkDocs Material documentation site with guides, recipes, and generated API reference;
+- SchemaRouter brace-and-routing-hub brand system with light/dark marks, lockups, favicon, and
+  social preview source artwork.
+
+### Security
+
+- separated schema-fetch credentials from runtime API credentials;
+- restricted schema redirects and runtime API origins;
+- blocked model/tool control of sensitive runtime headers;
+- redacted event payloads by default;
+- prevented automatic retries for non-read-only calls.

{schemarouter-0.2.0a1 → schemarouter-0.3.0a1}/CONTRIBUTING.md

@@ -10,17 +10,19 @@ python -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
 ruff check .
-pytest -q
+pytest -q -m "not mcp_integration"
 python examples/quickstart.py
-```
-
-Optional integrations have separate extras and tests. For example:
 
-```bash
-pip install -e ".[dev,langchain]"
-pytest -q tests/test_langchain_integration.py
+# Check the complete typed surface and optional integrations.
+pip install -e ".[dev,mcp,langchain,llamaindex,jev,otel]"
+pyright
+pytest -q --cov=schemarouter --cov-branch --cov-report=term-missing
 ```
 
+Optional integrations have separate extras and focused tests. The required CI exercises
+LangChain, LlamaIndex, Jev/TypeSafe, MCP, and OpenTelemetry independently in addition to the full
+coverage run.
+
 ## Design rules
 
 Changes must preserve these principles:
@@ -32,7 +34,9 @@ Changes must preserve these principles:
 5. raw input/output values are validated before crossing the trusted execution boundary;
 6. mutations, destructive calls, and ambiguous remote side effects require local policy;
 7. observability must not expose payloads by default;
-8. integrations must call through SchemaRouter execution rather than bypassing it.
+8. integrations must call through SchemaRouter execution rather than bypassing it;
+9. installed adapter plugins must never be auto-imported from discovery alone;
+10. approval and execution-budget failures must remain fail-closed.
 
 ## Adding an adapter
 
@@ -65,7 +69,10 @@ A change is not complete until:
 
 - tests cover its public behavior and adversarial failure cases;
 - warnings remain clean;
-- supported Python versions pass;
+- supported Python versions pass, including the Windows smoke surface;
+- Pyright and the 82% branch-coverage floor pass;
+- minimum declared runtime dependencies remain usable;
+- wheel and sdist clean-install smokes pass;
 - public behavior is documented;
 - new optional dependencies are isolated behind extras;
 - breaking API changes include a changelog and migration note.