Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
feat(skill-distillation): add config and Rust contracts (#6)
Elyas Mehtabuddin35465c919104
diff --git a/.secrets.baseline b/.secrets.baselineindex 26b9e874f..8c106c9c6 100644--- a/.secrets.baseline+++ b/.secrets.baseline@@ -322,7 +322,7 @@"filename": "docs/cli_reference.md","hashed_secret": "414cb2d928610e260b1b00de84c809d2adef2480","is_verified": false,- "line_number": 537+ "line_number": 561}],"examples/minimal.py": [@@ -1124,42 +1124,42 @@"filename": "tests/test_user_config.py","hashed_secret": "e9a5f12a8ecbb3eb46eca5096b5c52aa5e7c9fdd","is_verified": false,- "line_number": 47+ "line_number": 51},{"type": "Secret Keyword","filename": "tests/test_user_config.py","hashed_secret": "dafbac184f8181c1ee065f77673fa9ff6732151f","is_verified": false,- "line_number": 152+ "line_number": 366},{"type": "Secret Keyword","filename": "tests/test_user_config.py","hashed_secret": "ee82dc5afbdde185b8b4fd4d177300b87c97da0f","is_verified": false,- "line_number": 165+ "line_number": 379},{"type": "Secret Keyword","filename": "tests/test_user_config.py","hashed_secret": "1b8a6878472757aff534e4d8be594c3422c85c93","is_verified": false,- "line_number": 171+ "line_number": 385},{"type": "Secret Keyword","filename": "tests/test_user_config.py","hashed_secret": "8ed1b64b9458f680811deea107475f442301354f","is_verified": false,- "line_number": 342+ "line_number": 556},{"type": "Secret Keyword","filename": "tests/test_user_config.py","hashed_secret": "86b4a095a59f87e8e99747d032daba8927df5689","is_verified": false,- "line_number": 354+ "line_number": 568}],"tests/test_verify.py": [@@ -1207,5 +1207,5 @@}]},- "generated_at": "2026-06-30T16:33:42Z"+ "generated_at": "2026-07-06T19:13:06Z"}diff --git a/Cargo.lock b/Cargo.lockindex efb553969..cc34de7dd 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1453,6 +1453,17 @@ dependencies = ["tracing",]+[[package]]+name = "switchyard-skill-distillation"+version = "0.1.0"+dependencies = [+ "async-trait",+ "serde",+ "serde_json",+ "thiserror",+ "tokio",+]+[[package]]name = "switchyard-translation"version = "0.1.0"diff --git a/Cargo.toml b/Cargo.tomlindex 56e23bbf4..526169afb 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -10,6 +10,7 @@ members = ["crates/switchyard-core","crates/switchyard-py","crates/switchyard-server",+ "crates/switchyard-skill-distillation","crates/switchyard-translation",]diff --git a/crates/switchyard-server/tests/profile_migration.rs b/crates/switchyard-server/tests/profile_migration.rsindex a3735cc48..cc973d2ee 100644--- a/crates/switchyard-server/tests/profile_migration.rs+++ b/crates/switchyard-server/tests/profile_migration.rs@@ -17,10 +17,14 @@ use switchyard_components_v2::{parse_profile_config_str, profile_stats_accumulator, ProfileConfigFormat,};use switchyard_server::{build_switchyard_router, ServerState};+use tokio::sync::Mutex as TokioMutex;use tower::ServiceExt;+static STATS_TEST_LOCK: TokioMutex<()> = TokioMutex::const_new(());+#[tokio::test]async fn noop_profile_serves_all_inbound_formats_without_upstream() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let app = build_switchyard_router(state_from_yaml(r#"@@ -83,6 +87,7 @@ profiles:#[tokio::test]async fn passthrough_profile_routes_all_inbound_formats_to_configured_target() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let Some(stub) = HttpStub::start(vec![StubResponse::ok(),@@ -160,6 +165,7 @@ profiles:#[tokio::test]async fn random_routing_profile_covers_strong_and_weak_selection() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let cases = [(1.0, "provider/strong"), (0.0, "provider/weak")];for (strong_probability, expected_model) in cases {@@ -207,6 +213,7 @@ profiles:#[tokio::test]async fn cascade_profile_threshold_zero_uses_dimensions_signal_path() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let Some(stub) = HttpStub::start(vec![StubResponse::ok()])? else {log_loopback_bind_skip();@@ -259,6 +266,7 @@ profiles:#[tokio::test]async fn cascade_profile_threshold_one_uses_llm_classifier_path() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let Some(stub) = HttpStub::start(vec![StubResponse::classifier("strong"), StubResponse::ok()])?else {@@ -318,6 +326,7 @@ profiles:#[tokio::test]async fn cascade_profile_retries_fallback_after_context_overflow() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let Some(stub) = HttpStub::start(vec![StubResponse::context_overflow(), StubResponse::ok()])?else {@@ -371,6 +380,7 @@ profiles:#[tokio::test]async fn latency_service_profile_uses_health_selection_and_retries_failed_target() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let Some(stub) = HttpStub::start(vec![StubResponse::latency_health(),@@ -420,6 +430,7 @@ async fn latency_service_profile_uses_health_selection_and_retries_failed_target#[tokio::test]async fn latency_service_profile_propagates_last_upstream_error_after_retries() -> TestResult {+ let _stats_guard = STATS_TEST_LOCK.lock().await;reset_stats()?;let Some(stub) = HttpStub::start(vec![StubResponse::latency_health(),diff --git a/crates/switchyard-skill-distillation/Cargo.toml b/crates/switchyard-skill-distillation/Cargo.tomlnew file mode 100644index 000000000..b09432d38--- /dev/null+++ b/crates/switchyard-skill-distillation/Cargo.toml@@ -0,0 +1,21 @@+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+# SPDX-License-Identifier: Apache-2.0++[package]+name = "switchyard-skill-distillation"+version = "0.1.0"+description = "Source-neutral Rust contracts for Switchyard skill distillation"+authors.workspace = true+edition.workspace = true+license.workspace = true+repository.workspace = true+rust-version.workspace = true++[dependencies]+async-trait = "0.1"+serde = { version = "1", features = ["derive"] }+serde_json = "1"+thiserror = "2"++[dev-dependencies]+tokio = { version = "1", features = ["macros", "rt", "sync"] }diff --git a/crates/switchyard-skill-distillation/src/error.rs b/crates/switchyard-skill-distillation/src/error.rsnew file mode 100644index 000000000..d46143cc7--- /dev/null+++ b/crates/switchyard-skill-distillation/src/error.rs@@ -0,0 +1,79 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Errors returned while validating or executing skill-distillation contracts.++use thiserror::Error;++/// Result type shared by the skill-distillation APIs.+pub type Result<T> = std::result::Result<T, SkillDistillationError>;++/// Error returned by record validation or an extension-point implementation.+#[derive(Clone, Debug, Error, PartialEq, Eq)]+pub enum SkillDistillationError {+ /// An identifier is not a safe local path component.+ #[error("invalid {kind}: {reason}")]+ InvalidIdentifier {+ /// Identifier category, such as `skill evidence id`.+ kind: &'static str,+ /// Concrete validation failure.+ reason: String,+ },++ /// A serialized record did not satisfy a required invariant.+ #[error("invalid {record}: {reason}")]+ InvalidRecord {+ /// Record category, such as `trajectory`.+ record: &'static str,+ /// Concrete validation failure.+ reason: String,+ },++ /// A record uses a schema version this crate cannot validate.+ #[error("unsupported schema version {actual}; expected {expected}")]+ UnsupportedSchemaVersion {+ /// Schema version supported by this crate.+ expected: u16,+ /// Schema version found in the record.+ actual: u16,+ },++ /// A score or metric is not a finite number.+ #[error("{field} must be finite")]+ NonFiniteNumber {+ /// Field containing the invalid number.+ field: String,+ },++ /// A trajectory source could not load its records.+ #[error("trajectory source failed: {0}")]+ Source(String),++ /// A distiller could not produce a skill candidate.+ #[error("skill distiller failed: {0}")]+ Distiller(String),++ /// A validator could not evaluate a skill candidate.+ #[error("skill validator failed: {0}")]+ Validator(String),++ /// A skill store could not read or update its state.+ #[error("skill store failed: {0}")]+ Store(String),++ /// A requested skill version was not available.+ #[error("skill version {version} was not found for namespace {namespace}")]+ VersionNotFound {+ /// Namespace searched by the store.+ namespace: String,+ /// Requested version identifier.+ version: String,+ },++ /// Rollback was requested without a previous active version.+ #[error("namespace {namespace} has no previous active skill version")]+ NoPreviousVersion {+ /// Namespace whose history was inspected.+ namespace: String,+ },+}diff --git a/crates/switchyard-skill-distillation/src/ids.rs b/crates/switchyard-skill-distillation/src/ids.rsnew file mode 100644index 000000000..f1821947d--- /dev/null+++ b/crates/switchyard-skill-distillation/src/ids.rs@@ -0,0 +1,157 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Validated identifiers used by skill-distillation records and store paths.++use std::fmt;+use std::str::FromStr;++use serde::{Deserialize, Serialize};++use crate::error::{Result, SkillDistillationError};++fn validate_path_component(value: &str, kind: &'static str) -> Result<()> {+ let reason = if value != value.trim() {+ Some("must not have leading or trailing whitespace")+ } else if value.is_empty() || matches!(value, "." | "..") {+ Some("must be a non-empty safe local path component")+ } else if !value+ .bytes()+ .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))+ {+ Some("may contain only letters, numbers, dot, underscore, and hyphen")+ } else {+ None+ };++ if let Some(reason) = reason {+ return Err(SkillDistillationError::InvalidIdentifier {+ kind,+ reason: reason.to_string(),+ });+ }+ Ok(())+}++macro_rules! path_component_id {+ ($name:ident, $kind:literal, $doc:literal) => {+ #[doc = $doc]+ #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]+ #[serde(try_from = "String", into = "String")]+ pub struct $name(String);++ impl $name {+ /// Creates an identifier after validating its path-component form.+ pub fn new(value: impl Into<String>) -> Result<Self> {+ let value = value.into();+ validate_path_component(&value, $kind)?;+ Ok(Self(value))+ }++ /// Returns the identifier as a borrowed string.+ pub fn as_str(&self) -> &str {+ &self.0+ }++ /// Consumes the identifier and returns its owned string.+ pub fn into_inner(self) -> String {+ self.0+ }+ }++ impl AsRef<str> for $name {+ fn as_ref(&self) -> &str {+ self.as_str()+ }+ }++ impl TryFrom<String> for $name {+ type Error = SkillDistillationError;++ fn try_from(value: String) -> Result<Self> {+ Self::new(value)+ }+ }++ impl TryFrom<&str> for $name {+ type Error = SkillDistillationError;++ fn try_from(value: &str) -> Result<Self> {+ Self::new(value)+ }+ }++ impl From<$name> for String {+ fn from(value: $name) -> Self {+ value.into_inner()+ }+ }++ impl FromStr for $name {+ type Err = SkillDistillationError;++ fn from_str(value: &str) -> Result<Self> {+ Self::new(value)+ }+ }++ impl fmt::Display for $name {+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {+ f.write_str(self.as_str())+ }+ }+ };+}++path_component_id!(+ SkillNamespace,+ "skill namespace",+ "Namespace for one skill that improves over time. Many separately identified \+ trajectories can contribute to it; it does not identify a session or trajectory."+);+path_component_id!(+ SkillEvidenceId,+ "skill evidence id",+ "Stable within a skill namespace for one completed run saved as distillation \+ evidence. Code that converts a session into evidence must reuse a safe session ID \+ or derive the same value each time. Requests use it to reject duplicate evidence, \+ and candidates record which evidence they used. It does not track a live session."+);+path_component_id!(+ SkillVersionId,+ "skill version id",+ "Stable identifier for one generated skill version."+);++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn identifiers_accept_safe_path_components() {+ for value in ["tooluniverse-trialqa", "a.b_c-1", "..."] {+ assert!(SkillNamespace::new(value).is_ok(), "{value}");+ assert!(SkillEvidenceId::new(value).is_ok(), "{value}");+ assert!(SkillVersionId::new(value).is_ok(), "{value}");+ }+ }++ #[test]+ fn identifiers_reject_path_traversal_and_unsafe_characters() {+ for value in [+ "",+ " ",+ " .",+ ".",+ "..",+ "../escape",+ "has/slash",+ "has space",+ "ümlaut",+ ] {+ assert!(SkillNamespace::new(value).is_err(), "{value}");+ assert!(SkillEvidenceId::new(value).is_err(), "{value}");+ assert!(SkillVersionId::new(value).is_err(), "{value}");+ }+ }+}diff --git a/crates/switchyard-skill-distillation/src/lib.rs b/crates/switchyard-skill-distillation/src/lib.rsnew file mode 100644index 000000000..ac7dae00a--- /dev/null+++ b/crates/switchyard-skill-distillation/src/lib.rs@@ -0,0 +1,30 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Source-neutral contracts for turning agent trajectories into reusable skills.+//!+//! This crate owns the serializable records and async extension points shared by+//! trajectory sources, distillers, validators, and skill stores. It deliberately+//! does not choose a provider, storage format, agent runtime, or model implementation.+//!+//! These contracts do not run a workflow by themselves. A Switchyard-owned coordinator+//! loads saved trajectories and the active skill, builds a distillation request, checks+//! the candidate, then saves it and decides whether to make it active. This crate does+//! not define that coordinator, its schedule, or its activation policy.++#![deny(missing_docs)]++mod error;+mod ids;+mod model;+mod ports;++pub use error::{Result, SkillDistillationError};+pub use ids::{SkillEvidenceId, SkillNamespace, SkillVersionId};+pub use model::{+ ActivationOperation, ActivationRecord, DistillationRequest, ExecutionMetadata, Metadata,+ SkillCandidate, SkillProvenance, TaskDescriptor, Trajectory, TrajectoryEvent,+ TrajectoryEventKind, TrajectoryOutcome, TrajectorySourceInfo, ValidationCheck,+ ValidationReport, ValidationStatus, SCHEMA_VERSION,+};+pub use ports::{SkillDistiller, SkillStore, SkillValidator, TrajectorySource};diff --git a/crates/switchyard-skill-distillation/src/model.rs b/crates/switchyard-skill-distillation/src/model.rsnew file mode 100644index 000000000..f06457733--- /dev/null+++ b/crates/switchyard-skill-distillation/src/model.rs@@ -0,0 +1,705 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Versioned, source-neutral records exchanged by skill-distillation stages.++use std::collections::{BTreeMap, HashSet};++use serde::{Deserialize, Serialize};+use serde_json::Value;++use crate::error::{Result, SkillDistillationError};+use crate::ids::{SkillEvidenceId, SkillNamespace, SkillVersionId};++/// Current version of serialized skill-distillation records.+pub const SCHEMA_VERSION: u16 = 1;++/// Extensible metadata with deterministic serialized key ordering.+pub type Metadata = BTreeMap<String, Value>;++/// Description of the task attempted by an agent.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct TaskDescriptor {+ /// Human-readable task description.+ pub description: String,+ /// Optional source-specific task identifier.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub task_id: Option<String>,+ /// Additional source-specific task fields.+ #[serde(default)]+ pub metadata: Metadata,+}++/// Runtime metadata associated with one trajectory.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct ExecutionMetadata {+ /// Agent harness or runner name.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub harness: Option<String>,+ /// Model used for the run, when known.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub model: Option<String>,+ /// Run start time; adapters should use RFC3339 UTC.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub started_at: Option<String>,+ /// Run end time; adapters should use RFC3339 UTC.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub ended_at: Option<String>,+ /// Additional execution fields.+ #[serde(default)]+ pub metadata: Metadata,+}++/// Provenance identifying the system that supplied a trajectory.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct TrajectorySourceInfo {+ /// Source adapter name, such as a local runner or benchmark importer.+ pub kind: String,+ /// Optional source-local run or session ID kept when this record is created.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub id: Option<String>,+ /// Additional source fields.+ #[serde(default)]+ pub metadata: Metadata,+}++/// Standard event categories understood by distillation implementations.+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+#[non_exhaustive]+pub enum TrajectoryEventKind {+ /// User, assistant, or system message.+ Message,+ /// Tool invocation request.+ ToolCall,+ /// Result returned by a tool invocation.+ ToolResult,+ /// Observation emitted by an agent or environment.+ Observation,+ /// Error encountered during execution.+ Error,+ /// Final output produced by the agent.+ FinalOutput,+}++/// One ordered event in an agent trajectory.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct TrajectoryEvent {+ /// Zero-based contiguous event position.+ pub sequence: u64,+ /// Optional event time; adapters should use RFC3339 UTC.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub timestamp: Option<String>,+ /// Standard event category.+ pub kind: TrajectoryEventKind,+ /// Source-neutral event payload containing provider-specific data when needed.+ pub payload: Value,+ /// Additional event fields, including source-specific identifiers.+ #[serde(default)]+ pub metadata: Metadata,+}++/// Optional outcome evidence attached to a trajectory.+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct TrajectoryOutcome {+ /// Source-defined label, such as `success`, `failure`, or `needs_review`.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub label: Option<String>,+ /// Optional numeric score or reward.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub score: Option<f64>,+ /// Optional failure or evaluator message.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub error: Option<String>,+ /// Additional numeric evaluation metrics.+ #[serde(default)]+ pub metrics: BTreeMap<String, f64>,+}++/// One completed agent run saved as evidence for skill distillation.+///+/// This is not the live session ID carried through request metadata. Code that builds+/// the record must reuse or deterministically derive its [`SkillEvidenceId`] from that+/// session ID.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct Trajectory {+ /// Serialized record schema version.+ pub schema_version: u16,+ /// Evidence ID used to reject duplicate inputs and record which runs a candidate used.+ pub id: SkillEvidenceId,+ /// Task attempted by the agent.+ pub task: TaskDescriptor,+ /// Runner and model metadata.+ pub execution: ExecutionMetadata,+ /// Source provenance.+ pub source: TrajectorySourceInfo,+ /// Ordered agent events.+ pub events: Vec<TrajectoryEvent>,+ /// Optional score or outcome evidence.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub outcome: Option<TrajectoryOutcome>,+ /// Additional trajectory fields.+ #[serde(default)]+ pub metadata: Metadata,+}++impl Trajectory {+ /// Validates the record before it is passed to a distiller.+ pub fn validate(&self) -> Result<()> {+ validate_schema(self.schema_version)?;+ validate_required_text("trajectory", "task.description", &self.task.description)?;+ validate_required_text("trajectory", "source.kind", &self.source.kind)?;+ validate_optional_text("trajectory", "execution.harness", &self.execution.harness)?;+ validate_optional_text("trajectory", "execution.model", &self.execution.model)?;+ validate_optional_text(+ "trajectory",+ "execution.started_at",+ &self.execution.started_at,+ )?;+ validate_optional_text("trajectory", "execution.ended_at", &self.execution.ended_at)?;+ validate_events(&self.events)?;+ if let Some(outcome) = &self.outcome {+ validate_outcome(outcome)?;+ }+ Ok(())+ }+}++/// Input supplied to a distiller for one target namespace.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct DistillationRequest {+ /// Serialized record schema version.+ pub schema_version: u16,+ /// Namespace that receives the resulting candidate skill.+ pub namespace: SkillNamespace,+ /// Source-neutral trajectories to analyze.+ pub trajectories: Vec<Trajectory>,+ /// Existing skill to deepen or revise, when one exists.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub base_skill: Option<SkillCandidate>,+ /// Additional request fields.+ #[serde(default)]+ pub metadata: Metadata,+}++impl DistillationRequest {+ /// Validates the request and every supplied trajectory.+ pub fn validate(&self) -> Result<()> {+ validate_schema(self.schema_version)?;+ if self.trajectories.is_empty() {+ return Err(invalid_record(+ "distillation request",+ "at least one trajectory is required",+ ));+ }++ let mut ids = HashSet::with_capacity(self.trajectories.len());+ for trajectory in &self.trajectories {+ trajectory.validate()?;+ if !ids.insert(&trajectory.id) {+ return Err(invalid_record(+ "distillation request",+ "skill evidence ids must be unique",+ ));+ }+ }++ if let Some(base_skill) = &self.base_skill {+ base_skill.validate()?;+ if base_skill.namespace != self.namespace {+ return Err(invalid_record(+ "distillation request",+ "base skill namespace does not match request namespace",+ ));+ }+ }+ Ok(())+ }++ /// Validates a distiller result against this request's namespace and evidence.+ pub fn validate_candidate(&self, candidate: &SkillCandidate) -> Result<()> {+ self.validate()?;+ candidate.validate()?;+ if candidate.namespace != self.namespace {+ return Err(invalid_record(+ "skill candidate",+ "candidate namespace does not match request namespace",+ ));+ }++ let request_ids: HashSet<_> = self+ .trajectories+ .iter()+ .map(|trajectory| &trajectory.id)+ .collect();+ if candidate+ .provenance+ .source_evidence_ids+ .iter()+ .any(|id| !request_ids.contains(id))+ {+ return Err(invalid_record(+ "skill candidate",+ "provenance references skill evidence outside the request",+ ));+ }++ let expected_parent = self.base_skill.as_ref().map(|skill| &skill.version);+ if candidate.provenance.parent_version.as_ref() != expected_parent {+ return Err(invalid_record(+ "skill candidate",+ "parent version does not match the request base skill",+ ));+ }+ Ok(())+ }+}++/// Provenance recorded on a generated skill candidate.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct SkillProvenance {+ /// Completed runs used as evidence for the candidate.+ pub source_evidence_ids: Vec<SkillEvidenceId>,+ /// Previously active skill version, when this is an update.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub parent_version: Option<SkillVersionId>,+ /// Distiller or generator identifier.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub generator: Option<String>,+ /// Generation time; adapters should use RFC3339 UTC.+ pub generated_at: String,+ /// Additional provenance fields.+ #[serde(default)]+ pub metadata: Metadata,+}++/// State of one validation check or validation report.+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+#[non_exhaustive]+pub enum ValidationStatus {+ /// Validation passed.+ Passed,+ /// Validation failed.+ Failed,+ /// A person must review the result.+ NeedsReview,+}++/// One named validation result.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct ValidationCheck {+ /// Stable human-readable check name.+ pub name: String,+ /// Check result.+ pub status: ValidationStatus,+ /// Optional result detail.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub message: Option<String>,+ /// Numeric measurements produced by the check.+ #[serde(default)]+ pub metrics: BTreeMap<String, f64>,+}++/// Validation evidence associated with a skill candidate.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct ValidationReport {+ /// Overall validation result.+ pub status: ValidationStatus,+ /// Individual checks supporting the result.+ pub checks: Vec<ValidationCheck>,+ /// Aggregate numeric measurements.+ #[serde(default)]+ pub metrics: BTreeMap<String, f64>,+ /// Human-readable review notes.+ #[serde(default)]+ pub notes: Vec<String>,+ /// Evaluation time; adapters should use RFC3339 UTC.+ pub evaluated_at: String,+}++impl ValidationReport {+ /// Validates names, timestamps, and numeric measurements in the report.+ pub fn validate(&self) -> Result<()> {+ validate_required_text("validation report", "evaluated_at", &self.evaluated_at)?;+ if self.checks.is_empty() {+ return Err(invalid_record(+ "validation report",+ "at least one validation check is required",+ ));+ }+ validate_finite_metrics("validation report.metrics", &self.metrics)?;+ for check in &self.checks {+ validate_required_text("validation report", "check.name", &check.name)?;+ validate_optional_text("validation report", "check.message", &check.message)?;+ validate_finite_metrics("validation check.metrics", &check.metrics)?;+ }+ Ok(())+ }+}++/// Generated skill content and its evidence.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct SkillCandidate {+ /// Serialized record schema version.+ pub schema_version: u16,+ /// Namespace receiving this candidate.+ pub namespace: SkillNamespace,+ /// Stable candidate version identifier.+ pub version: SkillVersionId,+ /// Portable Agent Skills document content.+ pub skill_md: String,+ /// Evidence and generation metadata.+ pub provenance: SkillProvenance,+ /// Validation result, when validation has run.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub validation: Option<ValidationReport>,+ /// Additional candidate fields.+ #[serde(default)]+ pub metadata: Metadata,+}++impl SkillCandidate {+ /// Validates the candidate before persistence or activation.+ pub fn validate(&self) -> Result<()> {+ validate_schema(self.schema_version)?;+ validate_required_text("skill candidate", "skill_md", &self.skill_md)?;+ validate_required_text(+ "skill candidate",+ "provenance.generated_at",+ &self.provenance.generated_at,+ )?;+ validate_optional_text(+ "skill candidate",+ "provenance.generator",+ &self.provenance.generator,+ )?;+ if self.provenance.source_evidence_ids.is_empty() {+ return Err(invalid_record(+ "skill candidate",+ "provenance must contain at least one source evidence id",+ ));+ }+ let unique_ids: HashSet<_> = self.provenance.source_evidence_ids.iter().collect();+ if unique_ids.len() != self.provenance.source_evidence_ids.len() {+ return Err(invalid_record(+ "skill candidate",+ "provenance source evidence ids must be unique",+ ));+ }+ if self.provenance.parent_version.as_ref() == Some(&self.version) {+ return Err(invalid_record(+ "skill candidate",+ "parent version must differ from candidate version",+ ));+ }+ if let Some(validation) = &self.validation {+ validation.validate()?;+ }+ Ok(())+ }+}++/// Whether an activation record represents promotion or rollback.+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum ActivationOperation {+ /// Promote a saved version to active.+ Activate,+ /// Restore the immediately preceding active version.+ Rollback,+}++/// Observable result of changing the active skill version.+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct ActivationRecord {+ /// Namespace whose active version changed.+ pub namespace: SkillNamespace,+ /// Operation performed by the store.+ pub operation: ActivationOperation,+ /// Version active after the operation.+ pub active_version: SkillVersionId,+ /// Version active immediately before the operation, when one existed.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub previous_version: Option<SkillVersionId>,+ /// Operation time; stores should use RFC3339 UTC.+ pub recorded_at: String,+}++impl ActivationRecord {+ /// Validates the activation result before it is persisted or emitted.+ pub fn validate(&self) -> Result<()> {+ validate_required_text("activation record", "recorded_at", &self.recorded_at)?;+ if self.previous_version.as_ref() == Some(&self.active_version) {+ return Err(invalid_record(+ "activation record",+ "previous version must differ from active version",+ ));+ }+ Ok(())+ }+}++fn validate_schema(actual: u16) -> Result<()> {+ if actual != SCHEMA_VERSION {+ return Err(SkillDistillationError::UnsupportedSchemaVersion {+ expected: SCHEMA_VERSION,+ actual,+ });+ }+ Ok(())+}++fn validate_required_text(record: &'static str, field: &str, value: &str) -> Result<()> {+ if value.trim().is_empty() {+ return Err(invalid_record(+ record,+ &format!("{field} must not be empty"),+ ));+ }+ Ok(())+}++fn validate_optional_text(record: &'static str, field: &str, value: &Option<String>) -> Result<()> {+ if let Some(value) = value {+ validate_required_text(record, field, value)?;+ }+ Ok(())+}++fn validate_events(events: &[TrajectoryEvent]) -> Result<()> {+ if events.is_empty() {+ return Err(invalid_record(+ "trajectory",+ "at least one event is required",+ ));+ }+ for (expected, event) in (0_u64..).zip(events) {+ if event.sequence != expected {+ return Err(invalid_record(+ "trajectory",+ "event sequence values must be contiguous and start at zero",+ ));+ }+ validate_optional_text("trajectory", "event.timestamp", &event.timestamp)?;+ }+ Ok(())+}++fn validate_outcome(outcome: &TrajectoryOutcome) -> Result<()> {+ validate_optional_text("trajectory", "outcome.label", &outcome.label)?;+ validate_optional_text("trajectory", "outcome.error", &outcome.error)?;+ if outcome.score.is_some_and(|score| !score.is_finite()) {+ return Err(SkillDistillationError::NonFiniteNumber {+ field: "trajectory outcome score".to_string(),+ });+ }+ validate_finite_metrics("trajectory outcome metrics", &outcome.metrics)+}++fn validate_finite_metrics(field: &str, metrics: &BTreeMap<String, f64>) -> Result<()> {+ if let Some((name, _)) = metrics.iter().find(|(_, value)| !value.is_finite()) {+ return Err(SkillDistillationError::NonFiniteNumber {+ field: format!("{field}.{name}"),+ });+ }+ Ok(())+}++fn invalid_record(record: &'static str, reason: &str) -> SkillDistillationError {+ SkillDistillationError::InvalidRecord {+ record,+ reason: reason.to_string(),+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ fn namespace() -> Result<SkillNamespace> {+ SkillNamespace::new("trialqa")+ }++ fn trajectory() -> Result<Trajectory> {+ Ok(Trajectory {+ schema_version: SCHEMA_VERSION,+ id: SkillEvidenceId::new("run-1")?,+ task: TaskDescriptor {+ description: "answer the task".to_string(),+ ..TaskDescriptor::default()+ },+ execution: ExecutionMetadata::default(),+ source: TrajectorySourceInfo {+ kind: "test".to_string(),+ ..TrajectorySourceInfo::default()+ },+ events: vec![TrajectoryEvent {+ sequence: 0,+ timestamp: None,+ kind: TrajectoryEventKind::Message,+ payload: serde_json::json!({"role": "user", "content": "hello"}),+ metadata: Metadata::default(),+ }],+ outcome: None,+ metadata: Metadata::default(),+ })+ }++ fn candidate() -> Result<SkillCandidate> {+ Ok(SkillCandidate {+ schema_version: SCHEMA_VERSION,+ namespace: namespace()?,+ version: SkillVersionId::new("v1")?,+ skill_md: "# Skill".to_string(),+ provenance: SkillProvenance {+ source_evidence_ids: vec![SkillEvidenceId::new("run-1")?],+ parent_version: None,+ generator: None,+ generated_at: "2026-06-30T00:00:00Z".to_string(),+ metadata: Metadata::default(),+ },+ validation: None,+ metadata: Metadata::default(),+ })+ }++ #[test]+ fn trajectory_validation_accepts_unscored_runs() -> Result<()> {+ trajectory()?.validate()+ }++ #[test]+ fn trajectory_validation_rejects_missing_required_content() -> Result<()> {+ let mut value = trajectory()?;+ value.task.description.clear();+ assert!(matches!(+ value.validate(),+ Err(SkillDistillationError::InvalidRecord { .. })+ ));+ Ok(())+ }++ #[test]+ fn trajectory_validation_rejects_non_contiguous_event_sequences() -> Result<()> {+ let mut value = trajectory()?;+ value.events[0].sequence = 1;+ assert!(matches!(+ value.validate(),+ Err(SkillDistillationError::InvalidRecord { .. })+ ));+ Ok(())+ }++ #[test]+ fn trajectory_validation_rejects_non_finite_scores() -> Result<()> {+ let mut value = trajectory()?;+ value.outcome = Some(TrajectoryOutcome {+ score: Some(f64::NAN),+ ..TrajectoryOutcome::default()+ });+ assert!(matches!(+ value.validate(),+ Err(SkillDistillationError::NonFiniteNumber { .. })+ ));+ Ok(())+ }++ #[test]+ fn request_rejects_duplicate_skill_evidence_ids() -> Result<()> {+ let run = trajectory()?;+ let request = DistillationRequest {+ schema_version: SCHEMA_VERSION,+ namespace: namespace()?,+ trajectories: vec![run.clone(), run],+ base_skill: None,+ metadata: Metadata::default(),+ };+ assert!(matches!(+ request.validate(),+ Err(SkillDistillationError::InvalidRecord { .. })+ ));+ Ok(())+ }++ #[test]+ fn candidate_requires_source_evidence_provenance() -> Result<()> {+ let mut value = candidate()?;+ value.provenance.source_evidence_ids.clear();+ assert!(matches!(+ value.validate(),+ Err(SkillDistillationError::InvalidRecord { .. })+ ));+ Ok(())+ }++ #[test]+ fn candidate_rejects_non_finite_validation_metrics() -> Result<()> {+ let mut value = candidate()?;+ value.validation = Some(ValidationReport {+ status: ValidationStatus::Failed,+ checks: vec![ValidationCheck {+ name: "leakage".to_string(),+ status: ValidationStatus::Failed,+ message: None,+ metrics: BTreeMap::from([("score".to_string(), f64::INFINITY)]),+ }],+ metrics: BTreeMap::new(),+ notes: Vec::new(),+ evaluated_at: "2026-06-30T00:01:00Z".to_string(),+ });+ assert!(matches!(+ value.validate(),+ Err(SkillDistillationError::NonFiniteNumber { .. })+ ));+ Ok(())+ }++ #[test]+ fn request_rejects_candidate_provenance_outside_input() -> Result<()> {+ let request = DistillationRequest {+ schema_version: SCHEMA_VERSION,+ namespace: namespace()?,+ trajectories: vec![trajectory()?],+ base_skill: None,+ metadata: Metadata::default(),+ };+ let mut value = candidate()?;+ value.provenance.source_evidence_ids = vec![SkillEvidenceId::new("other-run")?];+ assert!(matches!(+ request.validate_candidate(&value),+ Err(SkillDistillationError::InvalidRecord { .. })+ ));+ Ok(())+ }++ #[test]+ fn request_requires_matching_base_skill_namespace() -> Result<()> {+ let mut base = candidate()?;+ base.namespace = SkillNamespace::new("other")?;+ let request = DistillationRequest {+ schema_version: SCHEMA_VERSION,+ namespace: namespace()?,+ trajectories: vec![trajectory()?],+ base_skill: Some(base),+ metadata: Metadata::default(),+ };+ assert!(matches!(+ request.validate(),+ Err(SkillDistillationError::InvalidRecord { .. })+ ));+ Ok(())+ }+}diff --git a/crates/switchyard-skill-distillation/src/ports.rs b/crates/switchyard-skill-distillation/src/ports.rsnew file mode 100644index 000000000..0203157bd--- /dev/null+++ b/crates/switchyard-skill-distillation/src/ports.rs@@ -0,0 +1,60 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Async extension points implemented by source adapters and runtimes.+//!+//! These traits describe separate workflow steps. They do not call one another or+//! decide when distillation runs or when a candidate becomes the active skill.++use async_trait::async_trait;++use crate::error::Result;+use crate::ids::{SkillNamespace, SkillVersionId};+use crate::model::{+ ActivationRecord, DistillationRequest, SkillCandidate, Trajectory, ValidationReport,+};++/// Loads normalized trajectories for a target namespace.+#[async_trait]+pub trait TrajectorySource: Send + Sync {+ /// Loads all trajectories currently available for `namespace`.+ async fn load(&self, namespace: &SkillNamespace) -> Result<Vec<Trajectory>>;+}++/// Converts normalized trajectories into a candidate skill.+#[async_trait]+pub trait SkillDistiller: Send + Sync {+ /// Produces a candidate without implicitly activating it.+ async fn distill(&self, request: &DistillationRequest) -> Result<SkillCandidate>;+}++/// Evaluates a candidate against optional evaluation trajectories.+#[async_trait]+pub trait SkillValidator: Send + Sync {+ /// Returns validation evidence; activation remains a caller decision.+ async fn validate(+ &self,+ candidate: &SkillCandidate,+ evaluation: &[Trajectory],+ ) -> Result<ValidationReport>;+}++/// Persists candidates and controls the active skill version.+#[async_trait]+pub trait SkillStore: Send + Sync {+ /// Returns the active candidate for `namespace`, when one exists.+ async fn active(&self, namespace: &SkillNamespace) -> Result<Option<SkillCandidate>>;++ /// Persists a candidate without activating it.+ async fn save_candidate(&self, candidate: &SkillCandidate) -> Result<()>;++ /// Activates a previously saved version.+ async fn activate(+ &self,+ namespace: &SkillNamespace,+ version: &SkillVersionId,+ ) -> Result<ActivationRecord>;++ /// Restores the immediately preceding active version.+ async fn rollback(&self, namespace: &SkillNamespace) -> Result<ActivationRecord>;+}diff --git a/crates/switchyard-skill-distillation/tests/contracts.rs b/crates/switchyard-skill-distillation/tests/contracts.rsnew file mode 100644index 000000000..508448ed2--- /dev/null+++ b/crates/switchyard-skill-distillation/tests/contracts.rs@@ -0,0 +1,286 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Public-contract tests from an external crate consumer's perspective.++use std::collections::BTreeMap;+use std::sync::Arc;++use async_trait::async_trait;+use serde_json::json;+use switchyard_skill_distillation::{+ ActivationOperation, ActivationRecord, DistillationRequest, ExecutionMetadata, Metadata,+ Result, SkillCandidate, SkillDistillationError, SkillDistiller, SkillEvidenceId,+ SkillNamespace, SkillProvenance, SkillStore, SkillValidator, SkillVersionId, TaskDescriptor,+ Trajectory, TrajectoryEvent, TrajectoryEventKind, TrajectoryOutcome, TrajectorySource,+ TrajectorySourceInfo, ValidationCheck, ValidationReport, ValidationStatus, SCHEMA_VERSION,+};+use tokio::sync::Mutex;++fn namespace() -> Result<SkillNamespace> {+ SkillNamespace::new("trialqa")+}++fn trajectory() -> Result<Trajectory> {+ Ok(Trajectory {+ schema_version: SCHEMA_VERSION,+ id: SkillEvidenceId::new("run-1")?,+ task: TaskDescriptor {+ description: "answer the task".to_string(),+ ..TaskDescriptor::default()+ },+ execution: ExecutionMetadata {+ harness: Some("test-harness".to_string()),+ model: Some("test-model".to_string()),+ started_at: Some("2026-06-30T00:00:00Z".to_string()),+ ended_at: Some("2026-06-30T00:01:00Z".to_string()),+ metadata: Metadata::default(),+ },+ source: TrajectorySourceInfo {+ kind: "test".to_string(),+ id: Some("source-run-1".to_string()),+ metadata: Metadata::default(),+ },+ events: vec![+ event(0, TrajectoryEventKind::Message, json!({"role": "user"})),+ event(1, TrajectoryEventKind::ToolCall, json!({"name": "search"})),+ event(+ 2,+ TrajectoryEventKind::ToolResult,+ json!({"content": "result"}),+ ),+ event(+ 3,+ TrajectoryEventKind::Observation,+ json!({"content": "observed"}),+ ),+ event(+ 4,+ TrajectoryEventKind::Error,+ json!({"message": "recoverable"}),+ ),+ event(+ 5,+ TrajectoryEventKind::FinalOutput,+ json!({"content": "done"}),+ ),+ ],+ outcome: Some(TrajectoryOutcome {+ label: Some("success".to_string()),+ score: Some(0.9),+ error: None,+ metrics: BTreeMap::from([("tokens".to_string(), 42.0)]),+ }),+ metadata: BTreeMap::from([("split".to_string(), json!("train"))]),+ })+}++fn event(sequence: u64, kind: TrajectoryEventKind, payload: serde_json::Value) -> TrajectoryEvent {+ TrajectoryEvent {+ sequence,+ timestamp: None,+ kind,+ payload,+ metadata: Metadata::default(),+ }+}++fn candidate(namespace: SkillNamespace, version: &str) -> Result<SkillCandidate> {+ Ok(SkillCandidate {+ schema_version: SCHEMA_VERSION,+ namespace,+ version: SkillVersionId::new(version)?,+ skill_md: "---\nname: trialqa\n---\n\n# Skill\n".to_string(),+ provenance: SkillProvenance {+ source_evidence_ids: vec![SkillEvidenceId::new("run-1")?],+ parent_version: None,+ generator: Some("stub-distiller".to_string()),+ generated_at: "2026-06-30T00:02:00Z".to_string(),+ metadata: Metadata::default(),+ },+ validation: None,+ metadata: Metadata::default(),+ })+}++#[test]+fn all_event_kinds_round_trip_through_stable_json() -> Result<()> {+ let value = trajectory()?;+ value.validate()?;+ let encoded = serde_json::to_value(&value)+ .map_err(|error| SkillDistillationError::Store(error.to_string()))?;++ assert_eq!(encoded["schema_version"], SCHEMA_VERSION);+ assert_eq!(encoded["events"][0]["kind"], "message");+ assert_eq!(encoded["events"][1]["kind"], "tool_call");+ assert_eq!(encoded["events"][2]["kind"], "tool_result");+ assert_eq!(encoded["events"][3]["kind"], "observation");+ assert_eq!(encoded["events"][4]["kind"], "error");+ assert_eq!(encoded["events"][5]["kind"], "final_output");+ assert_eq!(encoded["metadata"]["split"], "train");++ let decoded: Trajectory = serde_json::from_value(encoded)+ .map_err(|error| SkillDistillationError::Store(error.to_string()))?;+ assert_eq!(decoded, value);+ Ok(())+}++#[derive(Clone)]+struct StaticSource {+ values: Vec<Trajectory>,+}++#[async_trait]+impl TrajectorySource for StaticSource {+ async fn load(&self, _namespace: &SkillNamespace) -> Result<Vec<Trajectory>> {+ Ok(self.values.clone())+ }+}++struct StubDistiller;++#[async_trait]+impl SkillDistiller for StubDistiller {+ async fn distill(&self, request: &DistillationRequest) -> Result<SkillCandidate> {+ request.validate()?;+ candidate(request.namespace.clone(), "v1")+ }+}++struct StubValidator;++#[async_trait]+impl SkillValidator for StubValidator {+ async fn validate(+ &self,+ candidate: &SkillCandidate,+ evaluation: &[Trajectory],+ ) -> Result<ValidationReport> {+ candidate.validate()?;+ Ok(ValidationReport {+ status: ValidationStatus::Passed,+ checks: vec![ValidationCheck {+ name: "has-evidence".to_string(),+ status: ValidationStatus::Passed,+ message: Some(format!("{} trajectories", evaluation.len())),+ metrics: BTreeMap::new(),+ }],+ metrics: BTreeMap::new(),+ notes: Vec::new(),+ evaluated_at: "2026-06-30T00:03:00Z".to_string(),+ })+ }+}++#[derive(Default)]+struct StoreState {+ saved: BTreeMap<(SkillNamespace, SkillVersionId), SkillCandidate>,+ active: BTreeMap<SkillNamespace, SkillCandidate>,+ previous: BTreeMap<SkillNamespace, SkillCandidate>,+}++#[derive(Clone, Default)]+struct MemoryStore {+ state: Arc<Mutex<StoreState>>,+}++#[async_trait]+impl SkillStore for MemoryStore {+ async fn active(&self, namespace: &SkillNamespace) -> Result<Option<SkillCandidate>> {+ Ok(self.state.lock().await.active.get(namespace).cloned())+ }++ async fn save_candidate(&self, candidate: &SkillCandidate) -> Result<()> {+ candidate.validate()?;+ self.state.lock().await.saved.insert(+ (candidate.namespace.clone(), candidate.version.clone()),+ candidate.clone(),+ );+ Ok(())+ }++ async fn activate(+ &self,+ namespace: &SkillNamespace,+ version: &SkillVersionId,+ ) -> Result<ActivationRecord> {+ let mut state = self.state.lock().await;+ let key = (namespace.clone(), version.clone());+ let saved = state.saved.get(&key).cloned().ok_or_else(|| {+ SkillDistillationError::VersionNotFound {+ namespace: namespace.to_string(),+ version: version.to_string(),+ }+ })?;+ let previous = state.active.insert(namespace.clone(), saved);+ if let Some(previous) = &previous {+ state.previous.insert(namespace.clone(), previous.clone());+ }+ let record = ActivationRecord {+ namespace: namespace.clone(),+ operation: ActivationOperation::Activate,+ active_version: version.clone(),+ previous_version: previous.map(|value| value.version),+ recorded_at: "2026-06-30T00:04:00Z".to_string(),+ };+ record.validate()?;+ Ok(record)+ }++ async fn rollback(&self, namespace: &SkillNamespace) -> Result<ActivationRecord> {+ let mut state = self.state.lock().await;+ let restored = state.previous.remove(namespace).ok_or_else(|| {+ SkillDistillationError::NoPreviousVersion {+ namespace: namespace.to_string(),+ }+ })?;+ let replaced = state.active.insert(namespace.clone(), restored.clone());+ let record = ActivationRecord {+ namespace: namespace.clone(),+ operation: ActivationOperation::Rollback,+ active_version: restored.version,+ previous_version: replaced.map(|value| value.version),+ recorded_at: "2026-06-30T00:05:00Z".to_string(),+ };+ record.validate()?;+ Ok(record)+ }+}++#[tokio::test]+async fn external_rust_implementations_can_compose_the_contracts() -> Result<()> {+ let namespace = namespace()?;+ let source = StaticSource {+ values: vec![trajectory()?],+ };+ let trajectories = source.load(&namespace).await?;+ let request = DistillationRequest {+ schema_version: SCHEMA_VERSION,+ namespace: namespace.clone(),+ trajectories: trajectories.clone(),+ base_skill: None,+ metadata: Metadata::default(),+ };++ let mut generated = StubDistiller.distill(&request).await?;+ request.validate_candidate(&generated)?;+ let report = StubValidator.validate(&generated, &trajectories).await?;+ report.validate()?;+ generated.validation = Some(report);+ request.validate_candidate(&generated)?;++ let store = MemoryStore::default();+ store.save_candidate(&generated).await?;+ let first_activation = store.activate(&namespace, &generated.version).await?;+ assert_eq!(first_activation.active_version, generated.version);++ let mut second = candidate(namespace.clone(), "v2")?;+ second.provenance.parent_version = Some(generated.version.clone());+ store.save_candidate(&second).await?;+ store.activate(&namespace, &second.version).await?;++ let rollback = store.rollback(&namespace).await?;+ assert_eq!(rollback.operation, ActivationOperation::Rollback);+ assert_eq!(store.active(&namespace).await?, Some(generated));+ Ok(())+}diff --git a/docs/cli_reference.md b/docs/cli_reference.mdindex 640bcc86a..d12d56da2 100644--- a/docs/cli_reference.md+++ b/docs/cli_reference.md@@ -404,6 +404,7 @@ switchyard launch openclaw --model openai/gpt-4o-mini -- --message "Hello"## `switchyard configure`Persist user-level Switchyard defaults under `~/.config/switchyard/`. Credentials are stored separately from non-secret config, with owner-only file permissions.+Skill distillation config also lives in `~/.config/switchyard/config.json` under `skill_distillation` and can be updated without configuring provider credentials.**Synopsis**@@ -416,6 +417,7 @@ switchyard [--routing-profiles PATH] configure [--show [--check] [--json] | --re[--claude-model ID] [--claude-base-url URL] [--claude-api-key VALUE][--codex-model ID] [--codex-base-url URL] [--codex-api-key VALUE][--openclaw-model ID] [--openclaw-base-url URL] [--openclaw-api-key VALUE]+ [--skill-distillation NAMESPACE] [--disable-skill-distillation][--no-model-discovery] [--no-tui]```@@ -436,12 +438,28 @@ switchyard [--routing-profiles PATH] configure [--show [--check] [--json] | --re| `--provider`, `--base-url`, `--api-key` | Provider-level defaults applied to every launcher. Also act as one-off overrides for `--show` (changes the row that's used to resolve "base URL source" and "API key source") and for the `--list-models` discovery call. || `--claude-*` / `--codex-*` / `--openclaw-*` | Per-launcher overrides on top of the provider defaults. || `--routing-profiles PATH` | Global flag; pass before `configure`. Parses the YAML at `PATH` and stores the parsed bundle inline in `~/.config/switchyard/config.json`. Subsequent `serve` and `launch` runs use this when no `--routing-profiles` is on the CLI. Pass an empty string to clear. |+| `--skill-distillation NAMESPACE` | Save a namespace for one skill that improves over time. Many sessions or trajectories can contribute to it; the namespace is not a session ID. This release stores only the namespace; session saving, distillation, and launch-time skill loading are separate implementation work. |+| `--disable-skill-distillation` | Remove the saved skill distillation config. Cannot be combined with `--skill-distillation`. || `--query` / `-q SUBSTRING` | With `--list-models`, case-insensitive substring filter. || `--limit N` | With `--list-models`, cap on the number of models printed (default: 50; pass `0` for unlimited). || `--no-model-discovery` | Skip `GET /models` and rely on explicit or existing model values during interactive setup. || `--no-tui` | Use plain text prompts instead of the TUI selector. || `--check` | With `--show`, call `GET /models` against the resolved provider and report pass/fail in the output. |+**Skill distillation config**++```json+{+ "skill_distillation": {+ "namespace": "tooluniverse-trialqa"+ }+}+```++Namespaces must be a single safe path component: letters, numbers, dot, underscore, and hyphen only.+One namespace identifies one skill that improves over time, and many sessions or trajectories can contribute to it. Use a different namespace when you want a separate skill. A namespace is not a session ID; each future launcher run will receive its own internal session ID.+The top-level key is omitted when skill distillation is not configured. `namespace` is the only supported key today; any extra manually edited keys are rejected instead of being treated as inactive future options.+**Examples**```bash@@ -475,6 +493,12 @@ switchyard configure --target provider --provider openrouter \--api-key "$OPENROUTER_API_KEY" --base-url https://openrouter.ai/api/v1 \--no-tui --no-model-discovery+# Save a skill distillation namespace without provider credentials+switchyard configure --skill-distillation tooluniverse-trialqa++# Remove the skill distillation namespace without touching provider credentials+switchyard configure --disable-skill-distillation+# Wipe everythingswitchyard configure --reset```diff --git a/docs/index.md b/docs/index.mdindex c4e86f6af..5067d45bf 100644--- a/docs/index.md+++ b/docs/index.md@@ -57,6 +57,13 @@ For source installs, non-interactive configuration, and a curl sanity check, use[Routing Overview](routing_algorithms/overview.md)+- **Prepare skill distillation**++ Save a namespace for the intended automatic skill learning flow without+ changing request routing.++ [Skill Distillation](skill_distillation.md)+- **Understand the system**See how clients, routing policy, model backends, and operations fitdiff --git a/docs/skill_distillation.md b/docs/skill_distillation.mdnew file mode 100644index 000000000..c66d50171--- /dev/null+++ b/docs/skill_distillation.md@@ -0,0 +1,171 @@+# Skill Distillation++Skill distillation turns agent sessions into a reusable skill for the same+kind of work. The model is not retrained. Switchyard saves the session history,+uses it to update a `SKILL.md`, and makes the active skill available to later+agent launches for the same namespace.++The current release adds the saved configuration and the Rust contracts that+later implementations will share. It does not yet save session files, run+distillation, update skills, import external runs, validate results, or mount+skills into launched agents.++## Configure It++Choose a short namespace for the task or workflow you want the skill to learn:++```bash+switchyard configure --skill-distillation tooluniverse-trialqa+switchyard configure --show+```++One namespace identifies one skill that improves over time. Keep using the same+namespace when more sessions or trajectories should contribute to that skill;+choose a different namespace when you want a separate skill. A namespace is not+a session ID. In the automatic workflow, Switchyard will generate a separate+internal session ID for each launcher run.++The namespace is stored in the user config and can be updated without provider+credentials. To remove it:++```bash+switchyard configure --disable-skill-distillation+```++## Intended Workflow++Once launcher support lands, the flow should be automatic:++```text+configure a namespace+run an agent through switchyard launch+save the session under that namespace+distill when the session ends+create or update the namespace's active SKILL.md+load that active skill in the next launch for the same namespace+```++If no skill exists yet, the first distilled session creates one. Later sessions+update the existing skill and keep enough history to inspect or roll back the+change.++Skill distillation is namespace-based. The namespace is saved user+configuration, not a per-request header. A future request may be recorded as+part of a saved session, but a single HTTP request should not change which skill+is being learned or used.++## Session Ownership++The user configures only the namespace. In the automatic workflow, Switchyard+will own session capture and the session lifecycle. Each `switchyard launch`+will generate a separate session ID, record completed model turns as they pass+through the local proxy, and finalize the project-local session record when the+launched agent exits. The user will not provide a session ID, choose a storage+path, or run a separate recorder.++The capture backend is an internal implementation detail. The initial+implementation will use a Switchyard-managed project-local store; a later+trajectory source or storage backend can replace or supplement it without+changing the configuration or launcher workflow.++## Config++Skill distillation config is stored in `~/.config/switchyard/config.json` under+the top-level `skill_distillation` key:++```json+{+ "skill_distillation": {+ "namespace": "tooluniverse-trialqa"+ }+}+```++The config is intentionally small:++| Field | Default | Meaning |+|---|---|---|+| `namespace` | unset | Stable name for one skill that improves over time. Many sessions or trajectories can contribute to it; it is not a session ID. |++Namespaces must be safe local path components: letters, numbers, dot,+underscore, and hyphen only. They cannot be `.` or `..`.++The top-level `skill_distillation` key is omitted when skill distillation is+not configured. `namespace` is the only supported key today. Extra manually+edited keys are rejected instead of being treated as inactive future options.++## Decisions++Generated output should stay portable and easy to review. Switchyard should+write `SKILL.md` and human-readable reports, not generated Python or other+executable files.++Skill generation should happen after sessions finish, not during normal model+request handling. Switchyard owns the session-to-skill lifecycle, including+capture, distillation, validation, history, and launch-time skill loading. It+should not turn every request into a memory update.++The automatic workflow still needs guardrails. Every skill update should record+which sessions supported it, keep the previous active skill available for+rollback, and produce review output. Later checks should flag answer leakage,+source IDs, URLs, benchmark shortcuts, and task-specific details before a skill+is trusted.++## Planned Store Layout++Future work should use inspectable local files:++```text+<project>/.switchyard/skill-distillation/<namespace>/+ sessions/<session-id>/+ session.json+ turns.jsonl+ stats.json+ distillation-ledger.jsonl+ candidates/<version-id>/+ skill/SKILL.md+ report.md+ active/SKILL.md+ history.jsonl+```++The ledger should track which saved sessions have already contributed to a+skill update. That lets distillation use new sessions by default instead of+depending on a long-lived lookback-count setting.++## Rust Contracts++The `switchyard-skill-distillation` crate defines the source-neutral records+and extension points shared by future implementations and adapters. It does not+choose a provider, storage format, agent runtime, or model implementation.++The public contract includes:++- safe `SkillNamespace`, `SkillEvidenceId`, and `SkillVersionId` identifiers;+- versioned trajectories with task, execution, source, event, and outcome data;+- versioned skill candidates with required source-evidence provenance and+ optional validation reports; and+- async `TrajectorySource`, `SkillDistiller`, `SkillValidator`, and `SkillStore`+ traits.++The traits define workflow steps, but they do not run by themselves. No+production Switchyard code uses them today. A Switchyard runtime must load+saved trajectories and the active skill, build a distillation request, create+and check a candidate, then save it and decide whether to make it active. This+crate does not choose the code that implements each trait or decide when those+steps run.++`SkillEvidenceId` is not a second session tracker. A session ID groups requests+and turns while an agent is running. A `SkillEvidenceId` identifies the+completed run after Switchyard saves it for distillation. The initial workflow+will create one evidence record for each completed launcher session. Switchyard+keeps this ID stable within the namespace. The Rust contract uses it to reject+duplicate inputs in one distillation request and to record which evidence a+skill candidate used. The code that creates an evidence record reuses a safe+session ID or derives the evidence ID from it in a repeatable way. It can keep+the original run or session ID in `TrajectorySourceInfo.id`.++Provider-specific event data stays inside JSON payload and metadata fields.+The crate validates record invariants but does not redact source data, run a+model, write files, or activate a candidate by itself. Adapters and runtime+implementations own those operations.diff --git a/mkdocs.yml b/mkdocs.ymlindex d7bdb75b8..8ab0c48ed 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -22,6 +22,7 @@ nav:- Known Issues in 0.1.0: known_issues.md- Guides:- Agent Launchers: guides/agent_launchers.md+ - Skill Distillation: skill_distillation.md- Concepts:- Core Concepts: core_concepts.md- Architecture: architecture.mddiff --git a/switchyard/cli/config/user_config.py b/switchyard/cli/config/user_config.pyindex 777314b33..d7c13a40b 100644--- a/switchyard/cli/config/user_config.py+++ b/switchyard/cli/config/user_config.py@@ -9,12 +9,10 @@ intentionally independent of argparse so tests and future non-CLI entrypoints can reuse the same read/write and resolution behavior."""-from __future__ import annotations-import jsonimport osfrom collections.abc import Mapping-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom pathlib import Pathfrom typing import Literal, cast@@ -35,6 +33,8 @@ LaunchRouteType = Literal["single", "random", "deterministic", "plan_execute"]PRIMARY_TIER = "primary"WEAK_TIER = "weak"+_SKILL_DISTILLATION_KEYS = frozenset({"namespace"})+class UserConfigError(RuntimeError):"""Raised when a persisted user config file is malformed."""@@ -99,6 +99,28 @@ class LaunchConfig:)+@dataclass(frozen=True)+class SkillDistillationConfig:+ """User-level skill distillation defaults."""++ namespace: str | None = None++ def __post_init__(self) -> None:+ if self.namespace is not None:+ _validate_skill_namespace(self.namespace)++ @property+ def configured(self) -> bool:+ """Return whether skill distillation has a namespace to operate on."""++ return self.namespace is not None++ def is_default(self) -> bool:+ """Return whether this matches an unconfigured skill distillation config."""++ return self == SkillDistillationConfig()++@dataclass(frozen=True)class UserConfig:"""Non-secret Switchyard defaults stored under the user config dir.@@ -116,6 +138,9 @@ class UserConfig:providers: dict[str, ProviderConfig] | None = Nonelaunch: dict[LaunchTarget, LaunchConfig] | None = Nonerouting_profiles: dict[str, object] | None = None+ skill_distillation: SkillDistillationConfig = field(+ default_factory=SkillDistillationConfig,+ )def provider(self, name: str | None = None) -> ProviderConfig:providers = self.providers or {}@@ -126,6 +151,16 @@ class UserConfig:return launch.get(target, LaunchConfig())+@dataclass(frozen=True)+class LaunchCredentials:+ """Secret per-launcher tier credentials."""++ api_keys: dict[str, str] | None = None++ def api_key(self, tier: str = PRIMARY_TIER) -> str | None:+ return (self.api_keys or {}).get(tier)++@dataclass(frozen=True)class UserCredentials:"""Secret provider credentials stored separately from config."""@@ -141,16 +176,6 @@ class UserCredentials:return launch.get(target, LaunchCredentials())-@dataclass(frozen=True)-class LaunchCredentials:- """Secret per-launcher tier credentials."""-- api_keys: dict[str, str] | None = None-- def api_key(self, tier: str = PRIMARY_TIER) -> str | None:- return (self.api_keys or {}).get(tier)--@dataclass(frozen=True)class ProviderConnectivity:"""Resolved provider connectivity after applying precedence rules."""@@ -207,6 +232,24 @@ def _str_value(data: Mapping[str, object], key: str) -> str | None:return value if isinstance(value, str) and value else None+def _validate_skill_namespace(namespace: str) -> None:+ if namespace != namespace.strip():+ raise UserConfigError(+ "skill_distillation.namespace must not have leading or trailing "+ "whitespace"+ )+ if namespace in {".", ".."}:+ raise UserConfigError(+ "skill_distillation.namespace must be a safe local path component"+ )+ allowed = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")+ if not namespace or any(ch not in allowed for ch in namespace):+ raise UserConfigError(+ "skill_distillation.namespace may contain only letters, numbers, "+ "dot, underscore, and hyphen"+ )++def _float_value(data: Mapping[str, object], key: str, default: float,) -> float:@@ -309,6 +352,40 @@ def _launch_config_to_json(target_config: LaunchConfig) -> dict[str, object]:return body+def _parse_skill_distillation_config(raw_config: object) -> SkillDistillationConfig:+ if raw_config is None:+ return SkillDistillationConfig()+ if not isinstance(raw_config, dict):+ raise UserConfigError("skill_distillation must contain a JSON object")+ config_data = cast(dict[str, object], raw_config)+ unsupported_keys = sorted(set(config_data) - _SKILL_DISTILLATION_KEYS)+ if unsupported_keys:+ raise UserConfigError(+ "skill_distillation supports only namespace; unsupported key(s): "+ f"{', '.join(unsupported_keys)}"+ )+ raw_namespace = config_data.get("namespace")+ if raw_namespace is None or raw_namespace == "":+ raise UserConfigError(+ "skill_distillation.namespace is required when skill distillation "+ "is configured"+ )+ if not isinstance(raw_namespace, str):+ raise UserConfigError(+ "skill_distillation.namespace must be a non-empty string"+ )+ return SkillDistillationConfig(namespace=raw_namespace)+++def _skill_distillation_to_json(+ config: SkillDistillationConfig,+) -> dict[str, object]:+ body: dict[str, object] = {}+ if config.namespace:+ body["namespace"] = config.namespace+ return body++def load_user_config(config_dir: Path | None = None) -> UserConfig:"""Load non-secret user config, returning defaults when absent."""@@ -344,6 +421,9 @@ def load_user_config(config_dir: Path | None = None) -> UserConfig:providers=providers,launch=launch,routing_profiles=routing_profiles,+ skill_distillation=_parse_skill_distillation_config(+ data.get("skill_distillation"),+ ),)@@ -398,6 +478,10 @@ def _config_to_json(config: UserConfig) -> dict[str, object]:}if config.routing_profiles:top["routing_profiles"] = config.routing_profiles+ if not config.skill_distillation.is_default():+ top["skill_distillation"] = _skill_distillation_to_json(+ config.skill_distillation,+ )return top@@ -515,6 +599,9 @@ def build_redacted_snapshot(config_dir: Path | None = None) -> dict[str, object]"default_provider": config.default_provider,"providers": providers,"launch": launch,+ "skill_distillation": _skill_distillation_to_json(+ config.skill_distillation,+ ),}if config.routing_profiles:# Surface only route ids — the saved bundle can carry env-vardiff --git a/switchyard/cli/configure_command.py b/switchyard/cli/configure_command.pyindex 1aeba4336..d3ce2a56b 100644--- a/switchyard/cli/configure_command.py+++ b/switchyard/cli/configure_command.py@@ -23,7 +23,9 @@ from switchyard.cli.config.user_config import (LaunchRouteConfig,LaunchTierEndpointConfig,ProviderConfig,+ SkillDistillationConfig,UserConfig,+ UserConfigError,UserCredentials,_default_base_url_for_provider,build_redacted_snapshot,@@ -54,6 +56,57 @@ from switchyard.server.server_util import load_secretslogger = logging.getLogger(__name__)+def _skill_distillation_args_present(args: argparse.Namespace) -> bool:+ return bool(args.disable_skill_distillation) or args.skill_distillation is not None+++def _provider_or_launcher_args_present(args: argparse.Namespace) -> bool:+ return any(+ value+ for value in (+ args.api_key,+ args.base_url,+ args.claude_model,+ args.claude_base_url,+ args.claude_api_key,+ args.codex_model,+ args.codex_base_url,+ args.codex_api_key,+ args.openclaw_model,+ args.openclaw_base_url,+ args.openclaw_api_key,+ )+ ) or args.routing_profiles is not None+++def _skill_only_config_update(args: argparse.Namespace) -> bool:+ return (+ _skill_distillation_args_present(args)+ and not _provider_or_launcher_args_present(args)+ )+++def _apply_skill_distillation_args(+ existing: SkillDistillationConfig,+ args: argparse.Namespace,+) -> SkillDistillationConfig:+ if args.disable_skill_distillation:+ if args.skill_distillation is not None:+ raise UserConfigError(+ "--disable-skill-distillation cannot be combined with "+ "--skill-distillation"+ )+ return SkillDistillationConfig()++ return SkillDistillationConfig(+ namespace=(+ args.skill_distillation+ if args.skill_distillation is not None+ else existing.namespace+ ),+ )++@dataclass(frozen=True)class _LaunchEndpointSelection:"""Configure-time endpoint choice for one launch tier."""@@ -321,6 +374,23 @@ def cmd_configure(args: argparse.Namespace) -> None:configure_openclaw = target_scope in ("all", "openclaw")existing_config = load_user_config()existing_credentials = load_user_credentials()+ skill_distillation = _apply_skill_distillation_args(+ existing_config.skill_distillation,+ args,+ )+ if _skill_only_config_update(args):+ save_user_config(+ UserConfig(+ default_provider=existing_config.default_provider,+ providers=existing_config.providers,+ launch=existing_config.launch,+ routing_profiles=existing_config.routing_profiles,+ skill_distillation=skill_distillation,+ ),+ )+ print(f"Saved Switchyard config to {get_config_path()}")+ return+existing_provider = existing_config.provider(provider)existing_claude = existing_config.launch_target("claude")existing_codex = existing_config.launch_target("codex")@@ -585,6 +655,7 @@ def cmd_configure(args: argparse.Namespace) -> None:providers=providers,launch=launch,routing_profiles=routing_profiles,+ skill_distillation=skill_distillation,),)diff --git a/switchyard/cli/output.py b/switchyard/cli/output.pyindex e745d0fc1..c2f614a71 100644--- a/switchyard/cli/output.py+++ b/switchyard/cli/output.py@@ -3,8 +3,6 @@"""Human-readable CLI output helpers."""-from __future__ import annotations-from collections.abc import Mappingfrom typing import cast@@ -110,6 +108,16 @@ def format_config_snapshot(snapshot: Mapping[str, object]) -> str:for route_id in route_ids:lines.append(f" {route_id}")+ skill_distillation = _mapping(snapshot.get("skill_distillation"))+ if skill_distillation:+ lines.append("")+ lines.append("Skill distillation")+ namespace = _string(skill_distillation.get("namespace"))+ lines.append(f" configured: {bool(namespace)}")+ lines.append(f" namespace: {namespace or '<not configured>'}")+ if namespace:+ lines.append(" session learning: namespace saved")+launch = _mapping(snapshot.get("launch"))if launch:lines.append("")diff --git a/switchyard/cli/status.py b/switchyard/cli/status.pyindex 2abc45606..7e07dcdd5 100644--- a/switchyard/cli/status.py+++ b/switchyard/cli/status.py@@ -3,8 +3,6 @@"""Status view for launcher configuration and local tool readiness."""-from __future__ import annotations-import osfrom collections.abc import Mappingfrom dataclasses import dataclass@@ -13,6 +11,7 @@ from switchyard.cli.config.user_config import (DEFAULT_PROVIDER,DEFAULT_SECRETS_SECTION_PRIORITY,LaunchTarget,+ SkillDistillationConfig,load_user_config,load_user_credentials,resolve_provider_connectivity,@@ -147,6 +146,15 @@ def _format_launch_target(target: LaunchTarget) -> list[str]:return lines+def _format_skill_distillation(config: SkillDistillationConfig) -> str:+ if not config.configured:+ return "skill distillation: not configured"+ return (+ f"skill distillation: configured; namespace: {config.namespace}; "+ "session learning: namespace saved"+ )++def render_status(request: StatusRequest) -> str:"""Return a human-readable status report."""@@ -184,6 +192,7 @@ def render_status(request: StatusRequest) -> str:"strong/weak); plan-execute (strong-planner + weak-executor) via a ""type: plan_execute route in a --routing-profiles bundle",)+ lines.append(_format_skill_distillation(user_config.skill_distillation))lines += ["","Launch defaults",diff --git a/switchyard/cli/switchyard_cli.py b/switchyard/cli/switchyard_cli.pyindex a44fbb2ee..92e71bf57 100644--- a/switchyard/cli/switchyard_cli.py+++ b/switchyard/cli/switchyard_cli.py@@ -73,6 +73,7 @@ from switchyard.cli.config.user_config import (DEFAULT_OPENROUTER_BASE_URL,DEFAULT_PROVIDER,DEFAULT_SECRETS_SECTION_PRIORITY,+ UserConfigError,resolve_provider_connectivity,)from switchyard.cli.configure_command import (@@ -1030,6 +1031,22 @@ def _build_parser() -> argparse.ArgumentParser:"--openclaw-api-key", type=str, default=None,help="OpenClaw model API-key override. Omit to use the default API key.",)+ cfg_mode.add_argument(+ "--skill-distillation",+ metavar="NAMESPACE",+ default=None,+ help=(+ "Save a namespace for one skill that improves over time. Many "+ "sessions or trajectories can contribute to it; the namespace is "+ "not a session ID. Use a safe local path component (for example: "+ "tooluniverse-trialqa)."+ ),+ )+ cfg_mode.add_argument(+ "--disable-skill-distillation",+ action="store_true",+ help="Remove saved skill distillation config.",+ )cfg.add_argument("--no-model-discovery", action="store_true",help="Skip GET /models and rely on explicit or existing model values",@@ -1447,6 +1464,8 @@ def main() -> None:# surface the dedicated message as a one-line CLI diagnostic with a# non-zero exit instead of letting it propagate as a raw traceback.raise SystemExit(f"error: invalid route bundle: {exc}") from exc+ except UserConfigError as exc:+ raise SystemExit(f"error: invalid user config: {exc}") from excif __name__ == "__main__":diff --git a/tests/test_cli_reference_docs.py b/tests/test_cli_reference_docs.pyindex 15d69cee4..5f6e39753 100644--- a/tests/test_cli_reference_docs.py+++ b/tests/test_cli_reference_docs.py@@ -63,6 +63,42 @@ def test_cli_reference_documents_every_serve_flag() -> None:)+def test_cli_reference_documents_every_configure_flag() -> None:+ parser = _build_parser()+ configure = _subparsers(parser)["configure"]+ doc = CLI_REFERENCE.read_text()+ configure_section = _markdown_section(doc, "switchyard configure")++ expected = _long_options(configure) | {"--routing-profiles"}+ missing = sorted(flag for flag in expected if flag not in configure_section)++ assert not missing, (+ "docs/cli_reference.md configure section missing flags: "+ + ", ".join(missing)+ )+++def test_cli_reference_omits_unsupported_skill_distillation_flags() -> None:+ configure_section = _markdown_section(+ CLI_REFERENCE.read_text(),+ "switchyard configure",+ )+ unsupported_flags = {+ "--skill-session-store",+ "--skill-trigger",+ "--skill-mount",+ "--skill-stage-only",+ "--skill-lookback-sessions",+ }++ stale = sorted(flag for flag in unsupported_flags if flag in configure_section)++ assert not stale, (+ "docs/cli_reference.md configure section documents unsupported flags: "+ + ", ".join(stale)+ )++def test_cli_reference_serve_overview_points_to_config_path() -> None:serve_row = next(linediff --git a/tests/test_user_config.py b/tests/test_user_config.pyindex 0e06f2ac7..ec5a57da4 100644--- a/tests/test_user_config.py+++ b/tests/test_user_config.py@@ -1,9 +1,9 @@# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.# SPDX-License-Identifier: Apache-2.0-from __future__ import annotations-+import jsonimport stat+import sysimport pytest@@ -15,7 +15,9 @@ from switchyard.cli.config.user_config import (LaunchRouteConfig,LaunchTierEndpointConfig,ProviderConfig,+ SkillDistillationConfig,UserConfig,+ UserConfigError,UserCredentials,build_redacted_snapshot,load_user_config,@@ -24,6 +26,8 @@ from switchyard.cli.config.user_config import (save_user_config,save_user_credentials,)+from switchyard.cli.output import format_config_snapshot+from switchyard.cli.status import StatusRequest, render_status@pytest.fixture(autouse=True)@@ -119,6 +123,216 @@ def test_top_level_routing_profiles_clears_when_none(tmp_path):assert load_user_config(tmp_path).routing_profiles is None+def test_default_skill_distillation_config_is_not_persisted(tmp_path):+ save_user_config(UserConfig(), config_dir=tmp_path)++ raw = json.loads((tmp_path / "config.json").read_text())+ assert "skill_distillation" not in raw+ assert load_user_config(tmp_path).skill_distillation == SkillDistillationConfig()+++def test_skill_distillation_config_round_trips_and_surfaces(+ monkeypatch,+ tmp_path,+):+ skill_config = SkillDistillationConfig(+ namespace="tooluniverse-trialqa",+ )+ save_user_config(+ UserConfig(skill_distillation=skill_config),+ config_dir=tmp_path,+ )++ raw = json.loads((tmp_path / "config.json").read_text())+ assert raw["skill_distillation"] == {+ "namespace": "tooluniverse-trialqa",+ }+ assert load_user_config(tmp_path).skill_distillation == skill_config++ snapshot = build_redacted_snapshot(tmp_path)+ assert snapshot["skill_distillation"] == raw["skill_distillation"]+ rendered = format_config_snapshot(snapshot)+ assert "Skill distillation" in rendered+ assert "namespace: tooluniverse-trialqa" in rendered++ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))+ status = render_status(StatusRequest())+ assert "skill distillation: configured; namespace: tooluniverse-trialqa" in status+ assert "session learning: namespace saved" in status+++ ("body", "message"),+ [+ ({}, "namespace is required"),+ ({"namespace": "ok", "enabled": False}, "supports only namespace"),+ ({"namespace": "ok", "save_sessions": False}, "supports only namespace"),+ ({"namespace": 7}, "must be a non-empty string"),+ ({"namespace": "bad/name"}, "letters, numbers"),+ ({"namespace": " bad"}, "leading or trailing whitespace"),+ ({"namespace": "ok", "session_store": "remote"}, "supports only namespace"),+ ({"namespace": "ok", "trigger": "instant"}, "supports only namespace"),+ ({"namespace": "ok", "mount": "global"}, "supports only namespace"),+ ({"namespace": "ok", "lookback_sessions": 0}, "supports only namespace"),+ ],+)+def test_skill_distillation_config_validates(+ tmp_path,+ body,+ message,+):+ (tmp_path / "config.json").write_text(json.dumps({+ "skill_distillation": body,+ }))++ with pytest.raises(UserConfigError, match=message):+ load_user_config(tmp_path)+++def test_configure_skill_only_update_does_not_require_api_key(+ monkeypatch,+ tmp_path,+ capsys,+):+ from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure++ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))+ monkeypatch.setattr(+ "switchyard.cli.command_utils.is_interactive_terminal",+ lambda: False,+ )+ monkeypatch.setattr(+ "switchyard.cli.configure_command.is_interactive_terminal",+ lambda: False,+ )++ parser = _build_parser()+ args = parser.parse_args([+ "configure",+ "--skill-distillation", "tooluniverse-trialqa",+ ])++ _cmd_configure(args)++ config = load_user_config(tmp_path)+ assert config.skill_distillation.configured is True+ assert config.skill_distillation.namespace == "tooluniverse-trialqa"+ assert not (tmp_path / "credentials.json").exists()+ assert "Saved Switchyard config" in capsys.readouterr().out+++def test_configure_disable_skill_distillation_clears_config(+ monkeypatch,+ tmp_path,+ capsys,+):+ from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure++ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))+ save_user_config(+ UserConfig(+ skill_distillation=SkillDistillationConfig(+ namespace="tooluniverse-trialqa",+ ),+ ),+ config_dir=tmp_path,+ )++ parser = _build_parser()+ args = parser.parse_args([+ "configure",+ "--disable-skill-distillation",+ ])++ _cmd_configure(args)++ assert load_user_config(tmp_path).skill_distillation == SkillDistillationConfig()+ raw = json.loads((tmp_path / "config.json").read_text())+ assert "skill_distillation" not in raw+ assert not (tmp_path / "credentials.json").exists()+ assert "Saved Switchyard config" in capsys.readouterr().out+++def test_configure_disable_skill_distillation_rejects_conflicting_flags():+ from switchyard.cli.switchyard_cli import _build_parser++ parser = _build_parser()+ with pytest.raises(SystemExit):+ parser.parse_args([+ "configure",+ "--disable-skill-distillation",+ "--skill-distillation",+ "tooluniverse-trialqa",+ ])++[email protected]("mode", ["--show", "--reset", "--list-models"])+ "skill_args",+ [+ ["--skill-distillation", "tooluniverse-trialqa"],+ ["--disable-skill-distillation"],+ ],+)+def test_configure_skill_distillation_rejects_read_or_reset_modes(+ mode,+ skill_args,+):+ from switchyard.cli.switchyard_cli import _build_parser++ parser = _build_parser()+ with pytest.raises(SystemExit):+ parser.parse_args([+ "configure",+ mode,+ *skill_args,+ ])+++def test_configure_empty_skill_namespace_does_not_keep_existing_value(+ monkeypatch,+ tmp_path,+):+ from switchyard.cli.switchyard_cli import _build_parser, _cmd_configure++ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))+ existing = SkillDistillationConfig(namespace="existing")+ save_user_config(UserConfig(skill_distillation=existing), config_dir=tmp_path)++ parser = _build_parser()+ args = parser.parse_args([+ "configure",+ "--skill-distillation",+ "",+ ])++ with pytest.raises(UserConfigError, match="letters, numbers"):+ _cmd_configure(args)++ assert load_user_config(tmp_path).skill_distillation == existing+++def test_configure_invalid_skill_namespace_reports_user_error(+ monkeypatch,+ tmp_path,+):+ from switchyard.cli import switchyard_cli++ monkeypatch.setenv("SWITCHYARD_CONFIG_DIR", str(tmp_path))+ monkeypatch.setattr(sys, "argv", [+ "switchyard",+ "configure",+ "--skill-distillation", "bad/name",+ ])++ with pytest.raises(SystemExit) as excinfo:+ switchyard_cli.main()++ message = str(excinfo.value)+ assert "error: invalid user config" in message+ assert "letters, numbers, dot, underscore, and hyphen" in message++def test_redacted_snapshot_surfaces_only_route_ids(tmp_path):"""The snapshot exposes route ids but never the full bundle (env-varreferences inside the bundle may resolve to secrets at run time)."""