Skills 2026-10-07 22:11 UTC
ratelv0.13.0-rc.11
Version [v0.13.0-rc.11] committed by bercaakbayir. Update Category: Feature Addition & Enhancement. Commit details: feat(sdk): support Ratel Cloud as an adaptive-ranking graph consumer/producer (#169). This update introduces new capabilities and module extensions.
CommitRaw commit message
feat(sdk): support Ratel Cloud as an adaptive-ranking graph consumer/producer (#169) * feat(sdk): add learn:false to adaptive ranking so a registry can rank without learning Lets a runtime consume an IntentGraph produced elsewhere (Ratel Cloud replaying a project's events through the same learner) without its own traffic mutating the graph. Threaded through every active_trace_sink call site, not just enable/disable, so re-installing a sink for an unrelated reason cannot silently resume learning (ADR-0014). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * feat(sdk): declare and test turn_id on the runtime-events envelope turn_id already flowed end to end (projected by both SDKs, read by both native bridges, kept alive during truncation by the generic _id-suffix rule) but was undeclared, untested for truncation survival, and absent from the ADR-0020 envelope table and conformance fixture. Ratel Cloud needs it as a declared contract field to pair search/invoke events when replaying a project's runtime events into the intent graph server-side (RC-204). Adds turn_id to the TS RuntimeEvent type, an optional_envelope_fields entry to the conformance fixture and both SDKs' vocabulary tests, an explicit correlation-fields guarantee (alongside invocation_id) in both truncation normalizers, and host docs on turn_id pairing. No core change, no new search/invoke parameters, no behavior change. * feat(sdk): stamp turn_id on the gateway_search summary event gateway_search already had turn_id in scope at all four emit sites (searchCapabilitiesTool/search_capabilities, and the legacy search_tools shim in both SDKs) but never stamped it, so Ratel Cloud could not join the summary event to its inner search or the invokes that follow when replaying a turn (RC-204). Also forwards turn_id into the legacy shim's inner search, which lacked it entirely. No hits array added to the summary (the inner search already carries it), no core TraceEvent::GatewaySearch change, no behavior change when no turn id is passed. * feat(sdk): add adaptive-ranking diagnostic events to the remotely publishable set usage_boost, usage_model_mismatch, and usage_cluster_policy_changed (ADR-0014) already fire on every search where a graph is attached and already reach any local subscriber (no fan-out filtering by type exists at any layer) -- they were withheld only by omission from ADR-0020's contract, so Ratel Cloud's publisher allowlist dropped them. This adds all three to RUNTIME_EVENT_TYPES and the conformance fixture in both SDKs, extends the truncation product-fact field lists, and documents the change in both ADRs. usage_model_mismatch's dim_mismatch true/false cases already have full deterministic core coverage via StubEmbedder in tool_registry.rs's test module (a_same_dim_model_mismatch_pauses_the_ arm_and_warns, a_dim_mismatch_pauses_the_arm_and_warns) -- no new core test needed there. usage_cluster_policy_changed had no event-level coverage at any layer (only AdaptiveRankingStatus was tested), so one new core unit test closes that gap; usage_boost and usage_cluster_policy_changed also get direct SDK-level coverage in both languages since neither needs an embedder. usage_model_mismatch's SDK-level test is gated behind a locally-cached bge-small model, matching the pre-existing pattern for every other real model-mismatch test in both suites. No new events, no change to when/how core emits these three, no core TraceEvent shape change, nothing in the cloud SDK. * feat(sdk): add usage_ranking_status, emitted by the SDK wrappers Ratel Cloud's dashboard needs to know, per runtime, whether adaptive ranking is on/off/paused and which graph revision it's running -- its own or a cloud-served one -- without waiting for a search. usage_boost only proves a graph is attached once a search happens and never says which graph. Core gains a data-only TraceEvent::UsageRankingStatus variant (status, reason, rev, graph_key, learn, model) so the event can deserialize and travel the trace stream; core itself never emits it, since it has no notion of where a graph came from or of a caller-supplied graph_key. The TS and Python wrappers, which already own enable/disable/rebuild and the learn flag, emit it through the existing record_event seam -- collapsing the native status string to a four-value active/inactive/ unknown/paused contract. Pause is not a separate emission: the search path's usage_model_mismatch already covers it and has been remotely publishable since 760ec99. Also adds an IntentGraph.model getter to both native bridges (napi and pyo3), needed to report the graph's embedding model on the status event. No emission from the core search path, no change to usage_boost / usage_model_mismatch / usage_cluster_policy_changed, nothing in the cloud SDK. * fix(sdk): don't update adaptive-ranking bookkeeping before native accepts enable experimentalEnableAdaptiveRanking / experimental_enable_adaptive_ranking wrote #graph/#graphKey/#learn (self._graph/_graph_key/_learn in Python) before calling native, which can reject the call (bad origins, provenance, cluster_similarity, or cluster_coverage) without mutating its own state. A rejected call therefore left the wrapper's bookkeeping pointing at the graph/key that never actually attached, so a later rebuild's usage_ranking_status event reported the wrong graph_key/ learn/rev -- exactly the thing that event exists to get right for Ratel Cloud's dashboard. Reordered so the bookkeeping is only written after native.enable succeeds, in both registries in both SDKs. Added a regression test in each SDK: enable graph A successfully, fail a second enable attempt with graph B and a bad origins value, then rebuild and assert the emitted status still reports graph A's key/learn, not graph B's. * refactor(sdk): avoid a second native status read on enable/rebuild experimentalEnableAdaptiveRanking / experimental_enable_adaptive_ranking and the rebuild entry points called adaptiveRankingStatus() / adaptive_ranking_status() twice: once inside #maybeWarnModelMismatch and again inside #emitRankingStatusEvent, right after. Both now take the already-read status instead of re-fetching it, in both registries in both SDKs. * chore(release): bump core, sdk-ts, sdk-py to their next RC core 0.12.0-rc.5 -> 0.12.0-rc.6 sdk-ts 0.13.0-rc.5 -> 0.13.0-rc.6 sdk-py 0.13.0-rc.5 -> 0.13.0-rc.6 * release: core-v0.12.0-rc.6 * release: sdk-ts-v0.13.0-rc.6 * release: sdk-py-v0.13.0-rc.6 * feat(sdk): warn on four adaptive-ranking misconfigurations experimentalEnableAdaptiveRanking/experimental_enable_adaptive_ranking now warn once (suppressed by warnOnModelMismatch: false) on: learn: false with rebuildOnModelChange: true; origins: "baseline" on a live catalog; graphKey set while learn is on; and one IntentGraph enabled with mismatched learn values across the tool and skill catalogs. The last case needs cross-call memory keyed on the graph object, so the native IntentGraph pyclass gains weakref support to back a WeakKeyDictionary on the Python side (mirroring TS's WeakMap). * chore(release): bump sdk-ts, sdk-py to their next RC sdk-ts 0.13.0-rc.6 -> 0.13.0-rc.7 sdk-py 0.13.0-rc.6 -> 0.13.0-rc.7 * release: sdk-ts-v0.13.0-rc.7 * release: sdk-py-v0.13.0-rc.7 * feat(core): carry base_hits on search events when an intent graph matched Search and SkillSearch trace events gain an optional base_hits field: the top-k without the usage arm, same shape as hits, present only when a graph matched. Ranking unchanged. TS/Python runtime events allow-list it through oversize trimming; ADR-0020 field list amended. * fix(sdk): key the learn-mismatch warning per catalog and reset learn on disable The cross-catalog learn-mismatch bookkeeping was keyed by graph alone, so one catalog re-enabling its own graph with a different learn warned about a nonexistent other catalog, and one catalog's disable erased the entry another sharing catalog still relied on. Key it by graph then catalog in both SDKs. Disable now also resets the wrapper's learn to true, so a later usage_ranking_status (e.g. a rebuild) no longer reports a stale learn: false. * refactor(sdk): share adaptive-ranking enable/disable logic between registries The misconfiguration warnings, the learn-mismatch warning, the usage_ranking_status event builder and the disabled-status event were copied verbatim in ToolRegistry and SkillRegistry in both SDKs. Move them to module-level helpers (registry.ts; catalog.py, imported by skill_catalog.py). No behavior change; Python warnings keep pointing at the same caller frame (stacklevel 3 from the helper). * refactor(core): type UsageRankingStatus status and reason as enums status and reason were free Strings although each has a fixed set of values. Add UsageRankingState and UsageRankingReason (snake_case, same wire values) so serde rejects a value outside the contract, matching how the other closed sets in event.rs are typed. * test(telemetry): pin the trimming product-fact fields in the conformance fixture The fields an oversized runtime event keeps when trimmed were hand-maintained twice, in runtime-events.ts and runtime_events.py, with nothing keeping them equal. Name them as PRODUCT_FACT_FIELDS / PRODUCT_FACT_SUFFIXES (_PRODUCT_FACT_* in Python), add product_fact_fields and product_fact_suffixes to the runtime_events block of fixtures.json, and assert both SDKs against it. No behavior change. * docs: compact this PR's ADR amendments and fix the Python setup steps Fold the dated learn:false, usage_ranking_status and publishable-diagnostics amendments into ADR-0014 and ADR-0020's main text (ADR-0001: amend in place, compact), and document base_hits and the trimming rule where they now live. AGENTS.md's Python setup now matches CI's install and notes the CONDA_PREFIX conflict with maturin. Drop a dated ADR reference from a test comment. * chore(release): bump sdk-ts, sdk-py to their next RC sdk-ts 0.13.0-rc.7 -> 0.13.0-rc.8 sdk-py 0.13.0-rc.7 -> 0.13.0-rc.8 * release: sdk-ts-v0.13.0-rc.8 * release: sdk-py-v0.13.0-rc.8 * fix(core): stem a query once; words like codebase and database never matched since 0.12.0-rc.5 Bm25Index::search handed the engine distinct_terms(query) joined back into a string: stems, which the bm25 crate tokenizes and stems again. A stem that is not a fixed point of the stemmer changes on that second pass (codebase -> codebas -> codeba) and matches nothing, since documents are stemmed once. Introduced by 539ce57b (#159). Hand the engine surface words instead, one per distinct stem (engine_query), so it stems exactly once and still sees each term once: query_ceiling's dedup invariant holds. distinct_terms, query_ceiling and the BM25 params are unchanged. One fix covers the tool, skill and fact registries, which all go through Bm25Index::search. * docs(changelog): note the BM25 double-stemming fix in the SDK changelogs * chore(release): bump sdk-ts, sdk-py to their next RC sdk-ts 0.13.0-rc.8 -> 0.13.0-rc.9 sdk-py 0.13.0-rc.8 -> 0.13.0-rc.9 * release: sdk-ts-v0.13.0-rc.9 * release: sdk-py-v0.13.0-rc.9 * fix(core): ship base_hits: [] when the arm matched an empty base ranking * fix(core): publish a redacted model identity, never the raw embedder fingerprint * fix(sdk-ts): a rejected enable leaves learn and the usage policy untouched * fix(sdk): replay usage_ranking_status to a sink or subscriber attached after enable * docs: learn: false never learns into a graph, but a rebuild still bumps rev * docs(adr): base_hits is on search/skill_search only, not gateway_search * refactor(sdk-py): require native_status and name the ranking-status types * fix(sdk): no usage_ranking_status for a disable or rebuild with nothing attached * test(sdk): cover how usage_ranking_status collapses each native status * test(sdk): prove correlation ids are seeded into the bounded trim fallback * fix(sdk-py): point enable-time warnings at the caller's line, not ratel_ai * fix(sdk-ts): hold learn-mismatch registries weakly so dropped catalogs are collected * fix(sdk-py): report enable and disable under the same lock as the native call * refactor(sdk-ts): one runtimeEventProjection for event id and turn id --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>