SkillPedia Skills Encyclopedia
中文 EN
Today's updates 2026-11-19 UTC

No new commits yet today

Open the update feed

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.

bercaakbayir 4e534ac ratel-ai/ratel

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>