feat(libsy): affinity - sub-agent aware routing

[messiaen]

What

Short summary of what this PR changes.

Why

The motivation — what problem does this solve, or which ticket does it close?

Closes #

How tested

• uv run ruff check . clean
• uv run mypy switchyard clean
• uv run pytest tests/ green
• Manual smoke (describe what was run)

Checklist

• One class per file; filename = snake_case of the primary class.
• New public symbols exported from switchyard/__init__.py.__all__ if intended for downstream use.
• Unit tests added for new components / bug fixes.
• README / --help updated if customer-facing surface changed.
• Commits signed off (Signed-off-by: Your Name <email>) per the DCO.

Notes for reviewers

Anything reviewers should pay extra attention to — risky paths, follow-up tickets, intentional trade-offs.

Summary by CodeRabbit

• New Features

  • Added configurable routing algorithms, including affinity-based routing, classifier fall-through, and random selection.
  • Added reusable classification, processing, and state-management APIs.
  • Added support for retaining model assignments across related requests and sub-agents.
  • Expanded public library exports for routing and processing capabilities.

• Bug Fixes

  • Improved driver validation and added a timeout for unanswered requests.

• Documentation

  • Added guidance for configuring sub-agent affinity routing and request identity.

[coderabbitai]

Walkthrough

Adds core classifier, processor, and state abstractions; introduces fall-through, random, and affinity routing algorithms; strengthens driver lifecycle and timeout handling; and exposes and documents the new APIs.

Changes

Composable routing

Layer / File(s)	Summary
Core routing abstractions crates/libsy/src/core/{state,classifier,processor}.rs, crates/libsy/src/core.rs	Adds type-keyed state, classification and processor contracts, tests, and public re-exports.
Driver lifecycle guards crates/libsy/src/core/driver.rs, crates/libsy/src/core/algorithm.rs	Requires the driver stream before publishing steps, adds bounded response waiting, and updates rustdoc references.
Fall-through and affinity routing crates/libsy/src/algorithms/{fall_through,affinity,random_classifier}.rs, crates/libsy/src/algorithms.rs	Adds classifier cascading, random fallback selection, session/sub-agent model affinity, associated tests, and algorithm re-exports.
Public API documentation crates/libsy/README.md, crates/libsy/src/lib.rs	Documents random classification and sub-agent affinity composition with metadata-derived identities.

Estimated code review effort: 5 (Critical) | ~120 minutes

Poem

A rabbit hops through scores so bright,
And latches models left and right.
Through turns and agents, routes align,
While fall-through paths neatly twine.
The driver waits, the state grows true—
New routing magic springs anew!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is specific and matches the main routing change, including sub-agent-aware affinity.
Docstring Coverage	✅ Passed	Docstring coverage is 88.79% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

crates/libsy/src/algorithms/fall_through.rs (1)

92-139: 🚀 Performance & Scalability | 🔵 Trivial | ⚖️ Poor tradeoff

Optional: release the session lock before the routed LLM call.

state is not read or mutated after the decision replay (Line 134), yet the guard is held across call_llm_target (Lines 136-139). For a shared-session router this serializes concurrent turns for the entire duration of the model call, not just the fact-fold. Dropping the guard after step 4 would keep the fold atomic while shortening contention. If holding it across the call is intentional (e.g. strict per-session ordering), disregard.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/libsy/src/algorithms/fall_through.rs` around lines 92 - 139, The
session state lock in the fall-through routing method remains held during
call_llm_target even though state is no longer used after decision replay.
Release the state guard immediately after the processor loop handling
Event::Decision, before invoking driver.call_llm_target, while preserving
atomicity through the fact-fold and decision replay.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/libsy/src/algorithms/affinity.rs`:
- Around line 31-33: Update the comment for MAX_ASSIGNMENTS to describe eviction
as removing an arbitrary entry when the bound is reached, matching evict_if_full
and HashMap iteration semantics; remove the claim that the oldest entry is
evicted.

In `@crates/libsy/src/core/driver.rs`:
- Around line 146-157: Add a concise Rust doc comment to the private
ensure_started method describing that it verifies stream() was called before
publish operations proceed, and preserves its existing error behavior.
- Around line 67-68: Update FULFILL_REQUEST_TIMEOUT to represent the intended
10-minute default by changing its duration value accordingly, while preserving
the existing timeout usage and configurability TODO.

---

Nitpick comments:
In `@crates/libsy/src/algorithms/fall_through.rs`:
- Around line 92-139: The session state lock in the fall-through routing method
remains held during call_llm_target even though state is no longer used after
decision replay. Release the state guard immediately after the processor loop
handling Event::Decision, before invoking driver.call_llm_target, while
preserving atomicity through the fact-fold and decision replay.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 517c5aa7-fce6-44af-94cc-086f286ef99d

📥 Commits

Reviewing files that changed from the base of the PR and between 880f9be and 6ae1be6.

📒 Files selected for processing (12)

• crates/libsy/README.md
• crates/libsy/src/algorithms.rs
• crates/libsy/src/algorithms/affinity.rs
• crates/libsy/src/algorithms/fall_through.rs
• crates/libsy/src/algorithms/random_classifier.rs
• crates/libsy/src/core.rs
• crates/libsy/src/core/algorithm.rs
• crates/libsy/src/core/classifier.rs
• crates/libsy/src/core/driver.rs
• crates/libsy/src/core/processor.rs
• crates/libsy/src/core/state.rs
• crates/libsy/src/lib.rs

[ayushag-nv]

Looks good to me