콘텐츠로 이동

SchemaRouter 0.5.0

SchemaRouter 0.5.0은 failure, time budget, 실제 OpenAPI 문서 환경에서 기존 execution contract를 더 authoritative하게 만드는 runtime-hardening release입니다.

일반 agent framework로 범위를 넓히지 않습니다. 대신 retry behavior를 명확히 하고 elapsed-time budget이 trusted execution path를 더 넓게 포함하며 OpenAPI import/runtime이 source semantics를 더 충실히 따르도록 기존 tool-schema boundary를 강화합니다.

주요 변경

  • deterministic invocation failure용 public NonRetryableInvocationError
  • built-in OpenAPI/OPTIMADE transport의 보수적 transient HTTP retry 분류
  • 남은 wall-clock budget을 넘겨 sleep하지 않는 retry backoff
  • 첫 retry delay부터 max_backoff_seconds 적용
  • approval callback과 before/after execution hook까지 elapsed-time budget 적용
  • Operation-over-Path-Item OpenAPI parameter precedence 수정
  • explicit operationId를 바꾸지 않는 collision-safe generated endpoint name
  • flattened property가 모두 optional이어도 required JSON object request body 존재 보존
  • schema 없는 JSON body를 빈 object로 조작하지 않고 보고
  • Parameter Object contract에 따라 Accept, Content-Type, Authorization header를 planner argument에서 제외
  • 여러 2xx JSON/no-content response variant 보존
  • no-content success를 None으로 표현
  • 첫 response가 아니라 모든 successful OpenAPI response에 compatibility scan 적용

설치

pip install schemarouter

Optional integration은 독립 선택 가능합니다.

pip install "schemarouter[mcp]"
pip install "schemarouter[langchain]"
pip install "schemarouter[langgraph]"
pip install "schemarouter[llamaindex]"
pip install "schemarouter[jev]"
pip install "schemarouter[otel]"

Retry semantics

Built-in OpenAPI/OPTIMADE HTTP transport는 transient status와 deterministic failure를 구분합니다. HTTP 408, 425, 429, 500, 502, 503, 504는 endpoint와 RetryPolicy가 허용하면 retry 가능하며 다른 HTTP error는 fail fast합니다.

Trusted custom invoker는 ordinary exception에 기존 behavior를 유지하고 반복 invocation이 안전하게 복구될 수 없을 때 NonRetryableInvocationError를 발생시킬 수 있습니다.

Retry backoff도 elapsed-time budget의 일부입니다. Delay가 ExecutionBudget.max_elapsed_seconds를 넘겨 execution을 연장할 수 없고 max_backoff_seconds는 첫 retry부터 적용됩니다.

Execution budgets

경과 시간 예산에는 실제 실행기 호출 시도뿐 아니라 완료를 기다리는 승인 콜백 및 신뢰된 실행 전후 훅의 시간도 포함됩니다. 이를 통해 신뢰된 미들웨어가 실행 단위의 실제 경과 시간 제한을 초과해 동작할 수 있던 허점을 차단합니다.

Mutation/destructive policy, approval requirement, schema validation, retry policy, budget accounting은 서로 분리된 local authority layer로 유지됩니다.

OpenAPI fidelity

0.5.0은 OpenAPI correctness를 집중적으로 보강합니다.

Parameter와 endpoint identity

Operation-level parameter가 동일한 (name, in) identity의 Path Item parameter를 올바르게 override합니다. Generated endpoint name은 모호하지 않을 때 안정적으로 유지되고 서로 다른 valid path가 충돌할 때만 deterministic suffix를 받습니다. Explicit operationId는 변경하지 않습니다.

Request body와 header

지원되는 application/json object body에서 requestBody.required: true이면 모든 property가 optional이어도 body 존재를 보존하여 빈 required body를 {}로 전송합니다.

Explicit schema가 없는 JSON request body를 object라고 가정하지 않습니다. 표현하지 않은 상태로 두고 machine-readable compatibility limitation으로 노출합니다.

Accept, Content-Type, Authorization OpenAPI header parameter는 import에서 무시합니다. Runtime authentication과 trusted header는 model-owned argument가 아니라 local configuration입니다.

Success responses

Operation은 2xx code마다 다른 payload를 선언할 수 있습니다. SchemaRouter는 첫 2xx에 validation을 고정하지 않고 지원되는 JSON/no-content success variant를 수집합니다.

여러 schema가 있으면 runtime validation은 combined JSON Schema를 사용하고 planner output field는 JSON variant 전체에서 유지합니다. 실제 no-content success는 None을 반환합니다. Successful variant가 unsupported media type이면 valid response를 잘못 거부하는 대신 strict output validation을 비활성화하고 compatibility report에 limitation을 노출합니다.

호환성

0.5.0은 0.4.0 대비 public API를 제거하지 않습니다.

주요 behavior change는 복구 불가능한 case를 retry하거나 explicit budget을 넘기거나 OpenAPI semantics를 잘못 해석하던 edge case의 correctness fix입니다. 이에 의존한 application은 CHANGELOG.md를 확인해야 합니다.

SchemaRouter는 pre-1.0이므로 이후 0.x minor release에도 문서화된 compatibility change가 있을 수 있습니다.

검증

Protected release gate는 다음을 포함합니다.

  • Python 3.10~3.14 core tests
  • Windows + Python 3.14 smoke
  • Pyright static typing
  • blocking branch-coverage threshold
  • minimum runtime dependency versions
  • wheel/sdist build 및 clean-install smoke
  • strict MkDocs build
  • LangChain, LangGraph, LlamaIndex, Jev, MCP, OpenTelemetry 연동 테스트 묶음

Python 3.15는 별도 non-blocking forward-compatibility preview입니다. Live provider/model benchmark는 credential, hardware, provider version, pricing이 deterministic CI input이 아니므로 external research track으로 유지합니다.

Security posture

0.5.0은 기존 fail-closed trust model을 유지하면서 operational boundary를 강화합니다.

  • remote schema와 model output은 execution authority를 부여할 수 없음
  • deterministic built-in transport failure는 불필요한 retry 없이 실패 가능
  • retry delay는 run wall-clock budget을 우회할 수 없음
  • approval callback/execution hook도 elapsed-time boundary 내부
  • model-selected argument는 OpenAPI contract에서 제외된 protocol/auth header를 제어할 수 없음
  • unsupported schema-less request body는 조작하지 않고 보고
  • runtime payload tracing은 기본 redaction
  • stale schema fingerprint와 stale invoker binding은 계속 거부

상세 contract와 roadmap은 CHANGELOG.md, SECURITY.md, docs/versioning.md, docs/framework-maturity.md를 참고하십시오.