SchemaRouter 0.14.0¶

SchemaRouter 0.14.0은 0.12에서 정한 stable-core 검색·실행 경계를 유지하면서 운영 수명주기와 외부 생태계 검증을 보강한 릴리스입니다.

이 버전에서 SchemaRouter를 자율 agent framework로 바꾸거나, 진행 중인 연구 결과를 제품 보장으로 승격하지는 않습니다. 실제 서비스에서 필요한 source 진단, 재시작 이후 binding 복원, schema 변경 검토, capability 확인, 외부 framework와의 조합을 정리하는 데 초점을 맞췄습니다.

Source 확인과 인증 경계¶

실행 권한을 만들지 않고도 structured source를 먼저 확인할 수 있습니다.

probe_url(...)로 source를 등록하거나 실행하기 전에 진단할 수 있습니다.
일반 HTML이나 지원하지 않는 URL은 빈 tool 목록으로 조용히 끝나지 않고 이유를 알려 줍니다.
URL 자동 탐색은 기본적으로 passive하게 동작합니다.
OpenAPI의 인증 요구사항은 endpoint/tool 계약에 포함하지만 credential 값은 runtime 설정에 남깁니다.
schema watch와 HTTP validator는 승인된 source/contract identity에 묶입니다.

즉 어떤 source인지 알아내는 단계와 실제로 호출할 권한을 주는 단계를 분리합니다.

Runtime 수명주기와 저장된 상태¶

Registry를 한 process보다 오래 유지할 때 필요한 운영 기능을 보강했습니다.

저장된 registry에 trusted binding을 명시적으로 다시 연결할 수 있습니다.
SQLite registry/trace format에 version을 붙이고 기존 unversioned format을 검증 후 migration할 수 있습니다.
breaking change나 보안 의미가 달라지는 schema drift를 accept/reject할 수 있습니다.
capability 제거를 하나의 high-level lifecycle API로 처리할 수 있습니다.
승인된 schema 변경 뒤에도 health probe 상태를 일관되게 유지합니다.
watcher, monitor, binding, owned resource를 닫는 통합 shutdown 경로를 제공합니다.
adapter plugin도 같은 보수적인 schema refresh 경계를 사용할 수 있습니다.

저장소에는 credential, live client, socket, subprocess handle 같은 실행 권한을 기록하지 않습니다.

Capability Explorer와 첫 사용 경로¶

등록된 capability를 확인하는 화면과 첫 사용 예제를 실제 제품 구조에 맞췄습니다.

Capability Explorer는 tool, endpoint, parameter, output field, unit/qualifier, fingerprint, binding, 인증 요구사항, health, schema-watch 상태를 읽기 전용으로 보여 줍니다. Swagger처럼 등록된 계약을 훑어볼 수 있지만 tool 실행 버튼이나 credential 편집 기능은 없습니다.

첫 quickstart는 인증키가 필요 없는 실제 OpenAPI provider를 사용합니다. 반면 필수 CI는 외부 서비스 장애에 영향을 받지 않도록 같은 동작을 local fixture로 검증합니다. Python callable, SDK 바인딩, 다중 제공자 연동, 스키마 변경 감지, MCP stdio, 프레임워크 통합, 컨텍스트 절감, 점검 예제도 실행 가능한 형태로 제공합니다.

Adapter와 agent 생태계 조합 검증¶

Repository 내부 fixture만 보는 대신, 빌드된 wheel을 외부 style의 integration 경계에서도 검증합니다.

0.14.0에는 다음 경로의 예제와 검증이 포함됩니다.

PydanticAI ToolSearch 조합
OpenAI Agents SDK의 dynamic MCP filtering
mcp-agent의 large-tool catalog
SourceAdapter entry-point plugin

이는 고정된 테스트 대상에서 호환성을 확인했다는 근거입니다. SchemaRouter가 해당 framework를 대체한다거나 모든 버전을 지원한다는 뜻은 아닙니다.

한 사이트에서 영어/한국어 전환¶

GitHub Pages 상단에서 English와 한국어를 바꿀 수 있습니다.

영문 문서를 정본으로 유지하고, 한국어판은 설치·quickstart·핵심 개념·주요 protocol·inspection· trust 문서를 우선 번역했습니다. 아직 번역되지 않은 문서는 같은 /ko/ 경로에 안내 페이지를 두어 404 대신 최신 영문 원문으로 이동할 수 있게 했습니다.

번역된 페이지는 영문 source의 Git blob SHA를 기록합니다. 영문이 바뀌었는데 번역이 그대로면 docs CI가 실패하므로 오래된 번역을 조용히 배포하지 않습니다.

릴리스와 연구 기록 자동화¶

버전이나 실험 수처럼 기계적으로 확인할 수 있는 값은 정본에서 읽습니다.

안정판 버전과 날짜: CHANGELOG.md
현재 package version: pyproject.toml
공개 실험 수: benchmarks/research-experiment-ledger.json

Protected CI가 문서의 값과 정본이 다르면 merge를 막습니다. 별도 workflow는 정기적으로 같은 값을 확인하고, 차이가 생기면 직접 main을 수정하지 않고 검토 가능한 동기화 PR을 만듭니다. Research evidence export도 관련 main 변경과 정기 schedule에서 다시 생성합니다.

Release workflow는 wheel/sdist/SBOM과 함께 SHA256SUMS.txt와 release-manifest.json도 생성합니다. manifest에는 정확한 source SHA, artifact 이름과 크기, SHA-256이 들어갑니다.

제품과 연구의 경계¶

0.14 연구는 패키지 릴리스와 별도로 계속됩니다. Corrective re-retrieval, runtime qualification, held-out generalization, final-answer quality, field projection 실험은 사전 등록한 gate와 근거 규칙을 통과하기 전까지 제품 기본값으로 취급하지 않습니다.

따라서 이 릴리스는 진행 중인 실험이 이미 끝났다거나, 일부 중간 결과만으로 운영 환경에서 우월성이 입증됐다고 주장하지 않습니다.

호환성¶

0.13.0 대비 의도한 breaking public API change는 없습니다.

제품 경계는 그대로입니다.

등록된 typed capability
  -> bounded retrieval / planning
  -> local schema + policy + binding validation
  -> trusted execution
  -> validated/projected ToolResult

SchemaRouter는 계속 Beta / pre-1.0입니다.

릴리스 검증¶

배포는 정확한 release commit이 protected CI/security 검증을 모두 통과한 뒤 진행됩니다. Release workflow는 다음 순서로 동작합니다.

green main SHA에 annotated v0.14.0 tag를 생성합니다.
wheel과 sdist를 빌드하고 깨끗한 환경에 설치해 확인합니다.
SPDX JSON SBOM을 생성합니다.
GitHub provenance attestation을 생성합니다.
SHA256SUMS.txt와 release-manifest.json을 생성합니다.
PyPI Trusted Publishing으로 배포합니다.
공개 PyPI에서 같은 버전을 다시 받아 trusted build와 digest를 비교합니다.
공개 wheel, sdist, lightweight extras, combined integration extras를 checkout 밖에서 설치해 확인합니다.