NVIDIA-NeMo / NVIDIA-NeMo/Switchyard
docs/feat(libsy): classify_trigger = "user_turn" needs a session id, and cannot fall back to a message hash
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 3.2k
- Forks
- 291
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 182
Description
Summary
classify_trigger = "user_turn" (added in #487) only takes effect when the caller supplies a session id. That requirement is stated in the source but not in the TOML reference that operators read, and the setting that would otherwise work around it is rejected.
Detail
TurnPin in crates/libsy/src/algorithms/util/turn_pin.rs stores the chosen target in the composition's State, and its doc comment is explicit:
Without a session id there is no retained state, and every turn is classified.
That is correct and matches crates/libsy/src/algorithms/fall_through.rs, which keeps one state value per session id and uses "unretained per-run state" otherwise. So with no session id, user_turn behaves the same as every_request.
Two things follow.
1. The TOML reference does not say so. docs/reference/toml_schema.md describes the setting as:
user_turnjudges each new user message and holds that target across the tool calls between.
An operator reading only that would reasonably expect the target to be held, and would see one classifier call per request instead, with nothing in the logs indicating why.
2. The fallback that exists for this case is rejected here. message_hash_fallback derives an identity from the first user message for exactly this situation, but llm_class.rs:346 and llm_class.rs:418 reject it unless classify_trigger = "new_session":
if self.message_hash_fallback && self.classify_trigger != ClassifyTrigger::NewSession {
return Err(LibsyError::AlgorithmError {
message: "message_hash_fallback requires classify_trigger = new_session".to_string(),
});
}
This affects callers that do not send a session id, which includes benchmark harnesses and direct API clients.
Suggested changes
- Document the requirement in
docs/reference/toml_schema.md:user_turnrequires a session id, and without one it behaves asevery_request. - Allow
message_hash_fallbackwithclassify_trigger = "user_turn", keying the retained target on the hash of the first user message as it already does fornew_session.
The first is a documentation fix and stands on its own. The second is a small change to the two validation sites above plus the identity lookup, and I am happy to open a PR for it if that is wanted. If the restriction in (2) is deliberate, then documenting the reason would be enough.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/reference/toml_schema.md, then read crates/libsy/src/algorithms/util/turn_pin.rs, crates/libsy/src/algorithms/fall_through.rs, and the validation sites at llm_class.rs:346 and :418. Done means the TOML reference accurately explains the session-id behavior and the message_hash_fallback restriction is either supported for user_turn with the corresponding identity lookup or its rationale is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 62/100