docs: cleanup readme

Signed-off-by: Greg Clark <grclark@nvidia.com>

Author: messiaen

crates/libsy/README.md

@@ -1,64 +1,63 @@
 # libsy — Switchyard-Lib
 
-A lightweight library for multi-LLM agent optimization, with **routing** as the first case. An
-algorithm decides — statefully, using more than the request — which model(s) to call and how, and
-never performs the call itself ("ask, don't call"), so it owns no HTTP/provider SDK and embeds cleanly
-in a proxy, gateway, or agent runtime.
+A lightweight library for multi-LLM agent optimization, with **routing** as the first case.
+The library is provider agnostic and gives the user control of the llm api calls.
 
-Two audiences:
+## Example
 
-- **Integrators** — build a target set, pick an algorithm, run requests through a
-  [`MultiLlmOrchestrator`](#the-orchestrator--multillmorchestrator).
-- **Algorithm developers** — add strategies by [implementing `OrchAlgo`](#the-orchalgo-trait).
+Build a target set, pick an algorithm, run a request:
 
-Narrative design: [`DESIGN.md`](DESIGN.md).
-
-## Concepts
+```rust
+use libsy::llm_class::LlmClassifierOrchAlgo;
+use libsy::{LlmRequest, LlmTarget, LlmTargetSet, MultiLlmOrchestrator, OrchestratorRequest};
+use std::sync::Arc;
 
-| Type | Role |
-|------|------|
-| `OrchAlgo` | The **algorithm**: runs once per request, makes model calls, returns a decision trace + response. |
-| `LlmTarget` | A **target**: a `name` the algorithm routes by, the provider `model` id, and an optional `LlmClient`. |
-| `LlmTargetSet` | The set of targets an algorithm routes among. |
-| `LlmClient` | The one piece of I/O libsy doesn't own — a target's real model call over *your* transport. |
-| `MultiLlmOrchestrator` | Drives one algorithm; the integrator's entry point. |
-| `DecisionTrace` | Why the algorithm chose as it did — read uniformly, downcast when the algo is known. |
+// Targets the algorithm routes among, each backed by your LlmClient (see below).
+let client = Arc::new(MyClient { /* .. */ }) as Arc<dyn LlmClient>;
+let t = |name: &str, model: &str| LlmTarget {
+    name: name.into(), model: model.into(), llm_client: Some(client.clone()),
+};
 
-Per request: `MultiLlmOrchestrator` → `OrchAlgo::process_request` → one or more `LlmTarget::call`
-(each **served** by an `LlmClient`, or **offloaded** to you) → `(trace, response)`.
+let algo = Arc::new(LlmClassifierOrchAlgo::new(
+    "classifier", "strong", "weak", 0.5,
+    LlmTargetSet::new(vec![
+        t("classifier", "openai/gpt-4o-mini"),
+        t("strong",     "openai/gpt-4o"),
+        t("weak",       "openai/gpt-4o-mini"),
+    ]),
+));
+let orch = MultiLlmOrchestrator::new(algo);
 
----
+let req = OrchestratorRequest {
+    llm_request: LlmRequest { model_name: "auto".into(), prompt: "explain tail latency".into() },
+    raw_request: None, metadata: None,
+};
+let (trace, response) = orch.orchestrate_direct(req).await?;   // one call in, trace + response out
+println!("routed to {}", trace.last().unwrap().model_decision());
+```
 
-# For integrators
+Runnable: [`examples/research_agent.rs`](examples/research_agent.rs).
 
-## The orchestrator — `MultiLlmOrchestrator`
+## Requests & responses
 
 ```rust
-impl MultiLlmOrchestrator {
-    pub fn new(algo: Arc<dyn OrchAlgo>) -> Self;   // the algorithm owns its target set
-
-    // libsy holds every client: makes the calls, returns (trace, response).
-    // Errors up front if any target is client-less.
-    pub async fn orchestrate_direct(&self, request: OrchestratorRequest)
-        -> Result<(Vec<Arc<dyn DecisionTrace>>, OrchestratorResponse), Box<dyn Error + Send + Sync>>;
-
-    // "Ask, don't call": client-less targets stream back as `CallLlm` promises you
-    // fulfill, then a final `ReturnToAgent`.
-    pub fn orchestrate(&self, request: OrchestratorRequest)
-        -> impl Stream<Item = OrchestratorStepResult>;
+pub struct OrchestratorRequest {
+    pub llm_request: LlmRequest,                // normalized:  { model_name, prompt }
+    pub raw_request: Option<serde_json::Value>, // original provider body, forwarded verbatim if present
+    pub metadata: Option<Metadata>,             // correlation: session / agent / task / correlation_id / extra
+}
 
-    pub async fn process_signals(&self, signals: AgentSysSignals)   // out-of-band events
-        -> Result<(), Box<dyn Error + Send + Sync>>;
+pub struct OrchestratorResponse {
+    pub llm_response: LlmResponse,              // normalized:  { completion, raw_response? }
+    pub metadata: Option<Metadata>,
 }
 ```
 
-One instance is cheap to share (`Arc<dyn OrchAlgo>` inside, no lock) and serves requests from many
-threads in parallel.
+## Building a target set / using a client
 
-## Building a target set
-
-Implement `LlmClient` over your transport, wrap each model as an `LlmTarget`, collect into an
-`LlmTargetSet`:
+An `LlmTarget` pairs a routing `name` with a provider `model` id and an optional `LlmClient`.
+Although `libsy` provides a `SwitchyardClient` and a reference implementation, `LlmClient`
+is designed to be implemented by the user.
 
 ```rust
 struct MyClient { /* http client, base url, key */ }
@@ -72,40 +71,42 @@ impl LlmClient for MyClient {
         Ok(OrchestratorResponse { llm_response: LlmResponse { completion, raw_response: None }, metadata: None })
     }
 }
-
-// `name` is the routing label; `model` is the provider id the client calls. They can differ.
-let client = Arc::new(MyClient { /* .. */ }) as Arc<dyn LlmClient>;
-let target = |name: &str, model: &str| LlmTarget {
-    name: name.into(), model: model.into(),
-    llm_client: Some(client.clone()),   // `None` -> offloaded (streaming mode)
-};
-let targets = LlmTargetSet::new(vec![
-    target("classifier", "openai/gpt-4o-mini"),
-    target("strong",     "openai/gpt-4o"),
-    target("weak",       "openai/gpt-4o-mini"),
-]);
 ```
 
-## Running a request
+`name` is the label an algorithm routes by; `model` is the id the client calls — they can differ
+(`"strong"` -> `"openai/gpt-4o"`) or coincide. A target with `llm_client: None` is **offloaded**
+instead of served (streaming, below). The planned optional `SwitchyardClient` will provide an
+`LlmClient` that maps in Switchyard's OpenAI / Anthropic / Responses translations, so you needn't
+hand-roll one.
+
+## The orchestrator — `MultiLlmOrchestrator`
 
-`orchestrate_direct` when libsy holds the clients — one call in, trace + response out. Runnable:
-[`examples/research_agent.rs`](examples/research_agent.rs).
+The entry point. Cheap to share (`Arc<dyn OrchAlgo>` inside, no lock) and safe to drive from many
+threads at once:
 
 ```rust
-use libsy::llm_class::LlmClassifierOrchAlgo;
+impl MultiLlmOrchestrator {
+    pub fn new(algo: Arc<dyn OrchAlgo>) -> Self;   // the algorithm owns its target set
 
-let algo = Arc::new(LlmClassifierOrchAlgo::new("classifier", "strong", "weak", 0.5, targets));
-let orch = MultiLlmOrchestrator::new(algo);
+    // libsy holds every client: makes the calls, returns (trace, response).
+    // Errors up front if any target is client-less.
+    pub async fn orchestrate_direct(&self, request: OrchestratorRequest)
+        -> Result<(Vec<Arc<dyn DecisionTrace>>, OrchestratorResponse), Box<dyn Error + Send + Sync>>;
 
-let request = OrchestratorRequest {
-    llm_request: LlmRequest { model_name: "auto".into(), prompt: "explain tail latency".into() },
-    raw_request: None, metadata: None,
-};
-let (trace, response) = orch.orchestrate_direct(request).await?;
-println!("routed to {}", trace.last().unwrap().model_decision());
+    // "Ask, don't call": client-less targets stream back as `CallLlm` promises you
+    // fulfill, then a final `ReturnToAgent`.
+    pub fn orchestrate(&self, request: OrchestratorRequest)
+        -> impl Stream<Item = OrchestratorStepResult>;
+
+    pub async fn process_signals(&self, signals: AgentSysSignals)   // out-of-band events
+        -> Result<(), Box<dyn Error + Send + Sync>>;
+}
 ```
 
-`orchestrate` when your targets are client-less (`llm_client: None`) and *you* own the calls. Runnable:
+## Streaming — you own the model calls (`orchestrate`)
+
+Build the targets client-less (`llm_client: None`) and every `target.call` is offloaded: `orchestrate`
+yields `CallLlm` promises you fulfill with your own transport, then a final `ReturnToAgent`. Runnable:
 [`examples/research_agent_core.rs`](examples/research_agent_core.rs).
 
 ```rust
@@ -122,21 +123,10 @@ while let Some(step) = stream.next().await {
 }
 ```
 
-## `SwitchyardClient` (planned, optional feature)
-
-An optional-feature `LlmClient` that maps in Switchyard's provider translations (OpenAI / Anthropic /
-Responses) and calls an upstream endpoint for you — so integrators needn't hand-roll one while the
-default build ships no transport. The [`demo/libsy-proxy`](../../demo/libsy-proxy) binary hand-rolls it
-today.
-
----
-
-# For algorithm developers
-
-## The `OrchAlgo` trait
+## Building an algorithm (`OrchAlgo`)
 
-`process_request` runs once per request and makes as many `LlmTarget::call`s as it needs (a router one,
-a classifier two, an ensemble many):
+Implement `OrchAlgo` to add a strategy. `process_request` runs once per request and makes as many
+`LlmTarget::call`s as it needs.
 
 ```rust
 #[async_trait]
@@ -151,32 +141,21 @@ pub trait OrchAlgo: Send + Sync {
 }
 ```
 
-Give it a `new(config.., target_set)` constructor; integrators `Arc`-wrap it for
-`MultiLlmOrchestrator::new`. There is no builder.
-
-## Targets and decisions
+Give it a `new(config.., target_set)` constructor and `Arc`-wrap it for `MultiLlmOrchestrator::new` —
+there is no builder. A `target.call` serves the call if the target has a client, else offloads it via
+`ctx` — invisible to the algorithm. Attach a `DecisionTrace` to each call so a consumer can see *why*
+(it's a trait object, read uniformly, downcast when the algo is known):
 
 ```rust
-pub struct LlmTarget { pub name: String, pub model: String, pub llm_client: Option<Arc<dyn LlmClient>> }
-
 pub trait DecisionTrace: Send + Sync {
     fn model_decision(&self) -> &str;         // the model chosen
     fn reasoning(&self) -> Option<&str>;       // human-readable "why"
-    fn as_any(&self) -> &dyn std::any::Any;    // downcast when the algo is known
+    fn as_any(&self) -> &dyn std::any::Any;    // downcast to the concrete decision
 }
 ```
 
-`LlmTarget::call(ctx, request, decision)` serves the call if the target has a client, else offloads it
-via `ctx`'s channel — invisible to the algorithm. The target stamps its `model` onto
-`request.llm_request.model_name`, so an algorithm routes by the logical `name` and the client still
-hits the concrete model. `DecisionTrace` is a trait object (not a generic), so a consumer reads any
-algorithm's decision uniformly.
-
-## Implementing a router (LLM classifier, minimized)
-
-Two `target.call`s in one `process_request`: classify, then route. (Full version in
-[`src/llm_class.rs`](src/llm_class.rs); random router in [`src/rand.rs`](src/rand.rs), ensemble in
-[`src/ensemble.rs`](src/ensemble.rs).)
+Example — the LLM classifier (classify, then route; full version in
+[`src/llm_class.rs`](src/llm_class.rs)):
 
 ```rust
 #[async_trait]
@@ -200,12 +179,26 @@ impl OrchAlgo for LlmClassifierOrchAlgo {
 }
 ```
 
-## Reference algorithms
+## Explore
+
+**Reference algorithms** — implementations to read and route with:
+
+- [`src/rand.rs`](src/rand.rs) — `RandomOrchAlgo`: uniform random over the set (one call).
+- [`src/llm_class.rs`](src/llm_class.rs) — `LlmClassifierOrchAlgo`: classify, then route strong/weak;
+  fail open to strong.
+- [`src/ensemble.rs`](src/ensemble.rs) — `EnsembleOrchAlgo`: stateful — fan out to candidates, judge
+  the best, commit to the winner after N exploration turns 
+
+**Runnable examples** (`cargo run -p libsy --example <name>`):
+
+- [`examples/research_agent.rs`](examples/research_agent.rs) — client-backed targets, `orchestrate_direct`
+  (libsy makes the calls).
+- [`examples/research_agent_core.rs`](examples/research_agent_core.rs) — client-less targets,
+  `orchestrate` stream (the agent makes the calls).
 
-- **`RandomOrchAlgo`** — uniform random over the set (one call).
-- **`LlmClassifierOrchAlgo`** — classify, then route strong/weak; fail open to strong.
-- **`EnsembleOrchAlgo`** — stateful: fan out to candidates, judge the best, commit after N exploration
-  turns. State sits behind a `Mutex` over just its own fields.
+**Demo proxy** — [`demo/libsy-proxy`](../../demo/libsy-proxy): a real HTTP proxy where switchyard's
+crates serve the OpenAI / Anthropic / Responses APIs and translate formats, while *all* routing is
+libsy's classifier calling upstream through switchyard's backend.
 
 ## Not yet built