mkdocs.yml

site_name: SchemaRouter
site_description: Typed capability routing and governed execution for AI agents across APIs, tools, and data systems
site_author: Yong-eun Cho
site_url: https://jdeun.github.io/SchemaRouter/
copyright: © 2026 Yong-eun Cho · MIT License
repo_url: https://github.com/JDeun/SchemaRouter
repo_name: JDeun/SchemaRouter
edit_uri: edit/main/docs/

# A page that is written but never added to `nav` builds cleanly and is then
# unreachable on the published site. MkDocs reports that at INFO level, so
# `--strict` does not catch it. Promoting it to a warning makes the existing
# strict docs gate fail instead, which is how 0.12.0 and seven research pages
# were able to go missing from the site while CI stayed green.
validation:
  nav:
    omitted_files: warn

not_in_nav: |
  assets/brand/README.md

extra:
  alternate:
    - name: English
      link: /SchemaRouter/
      lang: en
    - name: 한국어
      link: /SchemaRouter/ko/
      lang: ko
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/JDeun/SchemaRouter
      name: SchemaRouter on GitHub
    - icon: fontawesome/solid/book
      link: https://github.com/JDeun/paper_SchemaRouter
      name: SchemaRouter research

theme:
  name: material
  language: en
  logo: assets/brand/schemarouter-mark-dark.svg
  favicon: assets/brand/schemarouter-mark-light.svg
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.indexes
    - navigation.prune
    - navigation.top
    - navigation.footer
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.tabs.link
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: black
      accent: teal
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: teal
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

extra_css:
  - stylesheets/brand.css

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            heading_level: 2
            members_order: source
            merge_init_into_class: true
            show_root_heading: true
            show_source: false
            show_signature_annotations: true
            separate_signature: true

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path: .
      check_paths: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true

nav:
  - Home: index.md
  - Start:
      - Installation: getting-started/installation.md
      - Quickstart: getting-started/quickstart.md
      - Example and demo gallery: getting-started/examples.md
      - Choose an ingestion path: getting-started/ingestion-paths.md
      - Runtime lifecycle: getting-started/runtime-lifecycle.md
      - Startup rebinding: getting-started/startup-rebinding.md
      - Storage migrations: getting-started/storage-migrations.md
      - Capability Explorer: getting-started/schema-explorer.md
  - Concepts:
      - What SchemaRouter is: concepts/schema-router.md
      - Capability catalog and structured retrieval: concepts/capability-catalog.md
      - Design principles: concepts/design-principles.md
      - Tool and endpoint contracts: concepts/tool-endpoint.md
      - Planning and field projection: concepts/planning.md
      - Field-first execution: concepts/field-first-execution.md
      - Registry and schema identity: concepts/registry.md
      - Execution and trust boundaries: concepts/execution.md
      - Adapter ecosystem: concepts/adapters.md
      - Protocol ingestion decisions: concepts/protocol-ingestion-decisions.md
      - Decision backends: concepts/decision-backends.md
  - Connect:
      - APIs and protocols:
          - OpenAPI: guides/openapi.md
          - OpenAPI compatibility: guides/openapi-compatibility.md
          - OpenRPC / JSON-RPC: guides/openrpc.md
          - OData: guides/odata.md
          - GraphQL: guides/graphql.md
          - OPTIMADE: guides/optimade.md
          - MCP: guides/mcp.md
          - Declarative HTTP/JSON: guides/http-json.md
      - Code and providers:
          - Python tools: guides/python-tools.md
          - Provider-first registration: guides/provider-first-registration.md
          - Third-party adapter plugins: guides/adapter-plugins.md
          - Protocol plugin recipes: guides/protocol-plugin-recipes.md
      - Data systems:
          - Enterprise data onboarding: guides/enterprise-data-onboarding.md
          - Database onboarding: guides/database-onboarding.md
          - Vector store onboarding: guides/vector-store-onboarding.md
          - Graph/RDF onboarding: guides/graph-store-onboarding.md
          - NoSQL record-store onboarding: guides/record-store-onboarding.md
      - Compatibility and discovery:
          - Universal ingestion matrix: guides/universal-ingestion.md
          - Live compatibility matrix: guides/live-compatibility-matrix.md
          - Human-readable documentation: guides/html-documentation.md
      - Recipes:
          - OpenAPI agent boundary: recipes/openapi-agent.md
          - MCP agent boundary: recipes/mcp-agent.md
          - Many-tool catalogs: recipes/many-tools.md
  - Runtime:
      - Execute and authorize:
          - Batch, streaming, and events: guides/runtime.md
          - Execution policy: guides/execution-policy.md
          - Principal authorization: guides/authorization.md
          - Retry policy: guides/retry.md
          - Trusted execution hooks: guides/execution-hooks.md
      - Select and adapt:
          - Provider-aware fallback: guides/provider-fallback.md
          - State-aware retrieval: guides/state-aware-retrieval.md
          - Capability constraints: guides/capability-constraints.md
          - Contract-aware fallback: guides/contract-aware-fallback.md
          - Capability negotiation: guides/capability-negotiation.md
          - Field projection: guides/field-projection.md
          - Candidate indexing: guides/candidate-indexing.md
          - Model-assisted analysis: guides/model-analyzer.md
      - Inspect and govern:
          - Capability decision traces: guides/capability-decision-traces.md
          - Capability drift: guides/capability-graph-drift.md
          - Capability graph scalability: guides/capability-graph-scalability.md
          - Capability eligibility: guides/capability-eligibility.md
          - Capability lineage: guides/capability-lineage.md
          - Capability snapshots: guides/capability-snapshots.md
          - Multi-provider evidence: guides/multi-provider-evidence.md
          - Schema drift analysis: guides/schema-drift.md
          - Portable capability artifacts: guides/capability-artifacts.md
          - Persistent run traces: guides/run-traces.md
          - Operational inspection: guides/inspection.md
      - Validate:
          - Decision routing benchmark: guides/decision-benchmark.md
          - Consumer acceptance validation: guides/consumer-acceptance.md
  - Integrations:
      - LangChain: integrations/langchain.md
      - LangGraph: integrations/langgraph.md
      - LlamaIndex: integrations/llamaindex.md
      - System One compatible: integrations/system-one.md
      - Decision backend plugins: integrations/decision-backend-plugins.md
      - Decision-model ecosystem: integrations/decision-model-ecosystem.md
      - Jev / TypeSafe: integrations/jev.md
      - Laya decisions: integrations/laya.md
      - Ollama decisions: integrations/ollama.md
      - OpenTelemetry: integrations/opentelemetry.md
  - Reference:
      - API:
          - Public API: reference/api.md
          - Runtime: reference/runtime.md
          - Models: reference/models.md
          - Registry and planner: reference/planning.md
      - Architecture: architecture.md
      - Framework maturity: framework-maturity.md
      - Compatibility testing: compatibility.md
      - Adapter authoring: adapter-authoring.md
      - Security model: security/threat-model.md
  - Research:
      - Research status: research/routing-status.md
      - Complete experiment index: research/experiment-index.md
      - Routing break-even result: research/realistic-break-even-result.md
      - Design and experiment history: research/design-and-experiment-history.md
      - Agent utility:
          - B1 local-agent result: research/agent-utility-b1-result.md
          - Large held-out generalization: research/large-heldout-agent-utility.md
          - Final-answer quality: research/final-answer-quality.md
          - Typed retrieval representation ablation: research/typed-capability-retrieval-ablation.md
          - Intent-manual development result: research/intent-manual-dev-result.md
          - Adaptive shortlist depth: research/adaptive-shortlist-depth.md
          - Corrective re-retrieval: research/corrective-reretrieval.md
          - Output-field projection: research/field-projection-answer-quality.md
          - Successor screen: research/successor-screen.md
      - Evidence and protocol:
          - 0.14 paper evidence checkpoint: research/0.14-paper-evidence-checkpoint.md
          - Paper evidence package: research/paper-evidence-package.md
          - Research governance: research/governance.md
          - External validation freeze: research/external-validation-freeze.md
          - HYSET external validation retraining protocol: research/hyset-external-validation.md
          - Research freeze protocol: research/operation-routing-freeze-protocol.md
          - Terminal 0.11 report: research/operation-routing-v4-terminal-report.md
      - Prior-art roadmap: research/prior-art-roadmap.md
  - Project:
      - Governance and roadmap:
          - Stable core contract: stable-core.md
          - Public roadmap: project/roadmap.md
          - Trust, stability, and public evidence: project/trust-and-evidence.md
          - Versioning: versioning.md
      - Adoption and validation:
          - Adoption scorecard: project/adoption-scorecard.md
          - External adoption and validation: project/external-adoption.md
          - PydanticAI ToolSearch validation: project/external-validation-pydanticai.md
          - OpenAI Agents SDK MCP filter validation: project/external-validation-openai-agents.md
          - mcp-agent catalog validation: project/external-validation-mcp-agent.md
          - External case-study template: project/case-study-template.md
      - Launch and positioning:
          - Why not send every tool schema to the model?: project/why-not-all-tool-schemas.md
          - Developer launch playbook: project/launch-playbook.md
          - Launch and outreach log: project/launch-log.md
          - Brand: project/brand.md
          - Discoverability and positioning: project/discoverability.md
      - Release notes:
          - 0.17.0: releases/0.17.0.md
          - 0.16.0: releases/0.16.0.md
          - 0.15.0: releases/0.15.0.md
          - 0.14.0: releases/0.14.0.md
          - 0.13.0: releases/0.13.0.md
          - 0.12.0: releases/0.12.0.md
          - 0.11.0: releases/0.11.0.md
          - 0.10.0: releases/0.10.0.md
          - 0.9.0: releases/0.9.0.md
          - 0.8.0: releases/0.8.0.md
          - 0.7.0: releases/0.7.0.md
          - 0.6.0: releases/0.6.0.md
          - 0.5.0: releases/0.5.0.md
          - 0.4.0: releases/0.4.0.md
          - 0.3.0: releases/0.3.0.md
          - 0.3.0a1: releases/0.3.0a1.md
          - 0.2.0a1: releases/0.2.0a1.md
      - Contribute:
          - Release checklist: release-checklist.md
          - Contributing: contributing.md
          - Changelog: changelog.md
          - License: license.md