Skip to content

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.baseline
index 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.lock
index 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.toml
index 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.rs
index 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.toml
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.md
index 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 everything
switchyard configure --reset
```
diff --git a/docs/index.md b/docs/index.md
index 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 fit
diff --git a/docs/skill_distillation.md b/docs/skill_distillation.md
new file mode 100644
index 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.yml
index 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.md
diff --git a/switchyard/cli/config/user_config.py b/switchyard/cli/config/user_config.py
index 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 entry
points can reuse the same read/write and resolution behavior.
"""
-from __future__ import annotations
-
import json
import os
from collections.abc import Mapping
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from pathlib import Path
from 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 = None
launch: dict[LaunchTarget, LaunchConfig] | None = None
routing_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-var
diff --git a/switchyard/cli/configure_command.py b/switchyard/cli/configure_command.py
index 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_secrets
logger = 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.py
index 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 Mapping
from 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.py
index 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 os
from collections.abc import Mapping
from 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.py
index 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 exc
if __name__ == "__main__":
diff --git a/tests/test_cli_reference_docs.py b/tests/test_cli_reference_docs.py
index 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(
line
diff --git a/tests/test_user_config.py b/tests/test_user_config.py
index 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 json
import stat
+import sys
import 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-var
references inside the bundle may resolve to secrets at run time)."""