schemarouter 0.2.0a1__tar.gz

schemarouter-0.2.0a1/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"

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

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    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
+
+  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 "import schemarouter; assert schemarouter.__version__ == '0.2.0a1'"
+      - run: /tmp/schemarouter-wheel/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
+
+
+  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.2.0a1/.github/workflows/compatibility.yml

@@ -0,0 +1,43 @@
+name: Compatibility Smoke
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 3 * * 1"
+  pull_request:
+    paths:
+      - "src/schemarouter/adapters/**"
+      - "src/schemarouter/ingestion.py"
+      - "scripts/live_*"
+      - ".github/workflows/compatibility.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  public-openapi:
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    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 .
+      - run: python scripts/live_openapi_smoke.py
+
+
+  public-optimade:
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    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 .
+      - run: python scripts/live_optimade_smoke.py

schemarouter-0.2.0a1/.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    permissions:
+      contents: read
+      pages: write
+    runs-on: ubuntu-latest
+    outputs:
+      pages_enabled: ${{ steps.pages.outputs.enabled }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Check whether GitHub Pages is enabled
+        id: pages
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh api "repos/${GITHUB_REPOSITORY}/pages" >/dev/null 2>&1; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::GitHub Pages is not enabled; deployment will be skipped."
+          fi
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+        env:
+          NO_MKDOCS_2_WARNING: "1"
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: needs.build.outputs.pages_enabled == 'true'
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

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

@@ -0,0 +1,113 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          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}")
+          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
+        run: |
+          python - <<'PY'
+          import glob
+          import subprocess
+          import sys
+          import tempfile
+          import venv
+          import zipfile
+          from pathlib import Path
+
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert any(name.endswith("/licenses/LICENSE") for name in names), names
+
+          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", wheel])
+              subprocess.check_call([
+                  str(python),
+                  "-c",
+                  "import schemarouter; assert schemarouter.__version__ == '0.2.0a1'",
+              ])
+          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 prerelease
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          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 0.2.0a1" \
+              --notes-file "docs/releases/0.2.0a1.md" \
+              --prerelease
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* \
+              --title "SchemaRouter 0.2.0a1" \
+              --notes-file "docs/releases/0.2.0a1.md" \
+              --prerelease \
+              --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.2.0a1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+site/

schemarouter-0.2.0a1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# 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.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/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to SchemaRouter
+
+SchemaRouter is a focused schema-aware planning and execution layer. Contributions should extend
+that boundary without turning the project into a second general-purpose agent framework.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+pytest -q
+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
+```
+
+## Design rules
+
+Changes must preserve these principles:
+
+1. remote metadata describes capability but never grants execution authority;
+2. model output is untrusted until projected onto registered schemas;
+3. credentials remain outside model-visible arguments;
+4. schema and invoker drift fail closed;
+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.
+
+## Adding an adapter
+
+Adapters should produce normal `ToolSpec` / `EndpointSpec` contracts and a trusted invoker.
+See [adapter authoring](docs/adapter-authoring.md).
+
+Do not embed provider-specific authorization decisions into generic schema parsing.
+
+## Adding a framework integration
+
+Integrations belong under `schemarouter.integrations` and should use optional dependencies with
+lazy imports. The core package must remain importable without integration extras installed.
+
+An integration should expose SchemaRouter contracts to another ecosystem; it should not duplicate
+SchemaRouter planning, policy, schema validation, or transport authorization.
+
+## Brand changes
+
+Production brand assets live under `docs/assets/brand/`. Treat the SVG files as the source of truth.
+
+Brand changes should preserve the brace + routing-hub concept, graphite/teal palette, light/dark
+contrast, and compact-mark legibility. Do not replace production SVGs with raster-only generated
+artwork.
+
+See the [brand guide](docs/project/brand.md).
+
+## Pull requests
+
+A change is not complete until:
+
+- tests cover its public behavior and adversarial failure cases;
+- warnings remain clean;
+- supported Python versions pass;
+- public behavior is documented;
+- new optional dependencies are isolated behind extras;
+- breaking API changes include a changelog and migration note.
+
+See [versioning](docs/versioning.md) and the [release checklist](docs/release-checklist.md).

schemarouter-0.2.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yong-eun Cho
+
+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.