feat(skill-distillation): add config and Rust contracts

[elyasmnvidian]

Summary

This PR establishes the first skill-distillation boundary in Switchyard:

• switchyard configure --skill-distillation NAME saves the namespace that later launcher and runtime work will use.
• switchyard configure --disable-skill-distillation removes that saved namespace.
• The new switchyard-skill-distillation Rust crate defines the source-neutral records, validation rules, and async extension points shared by future trajectory sources, distillers, validators, and skill stores.

Existing provider and launcher configuration remains unchanged. A skill-only config update writes ~/.config/switchyard/config.json and does not require provider credentials.

UserConfig owns the saved namespace. The Rust crate owns the cross-implementation API contracts. It does not choose a provider, store, model, agent runtime, or activation policy.

This PR does not yet save sessions, run a distiller, write or activate skills, import external runs, or mount skills into launched agents.

Public Contract

The Rust crate exports:

• safe SkillNamespace, SkillEvidenceId, and SkillVersionId identifiers;
• versioned Trajectory, DistillationRequest, and SkillCandidate records;
• task, execution, source, event, outcome, provenance, validation, and activation records; and
• async TrajectorySource, SkillDistiller, SkillValidator, and SkillStore traits.

DistillationRequest::validate_candidate() checks that a candidate uses the request namespace, references only input evidence, and names the request's base skill as its parent. Candidate validation also requires source-evidence provenance and rejects invalid validation metrics.

The contract crate has no provider, filesystem, Python binding, benchmark, or model implementation dependency. Provider-specific event data stays inside JSON payload and metadata fields.

Feature Proof

$ SWITCHYARD_CONFIG_DIR=/private/tmp/switchyard-skill-pr-proof .venv/bin/switchyard configure --skill-distillation tooluniverse-trialqa
Saved Switchyard config to /private/tmp/switchyard-skill-pr-proof/config.json

$ SWITCHYARD_CONFIG_DIR=/private/tmp/switchyard-skill-pr-proof .venv/bin/switchyard configure --show
Skill distillation
  configured: True
  namespace: tooluniverse-trialqa
  session learning: namespace saved

skill distillation: configured; namespace: tooluniverse-trialqa; session learning: namespace saved

Saved config excerpt:

{
  "skill_distillation": {
    "namespace": "tooluniverse-trialqa"
  }
}

The Rust API can be implemented by independent adapters without depending on Switchyard's Python CLI:

use switchyard_skill_distillation::{
    DistillationRequest, SkillDistiller, SkillStore,
    SkillValidator, TrajectorySource,
};

Invalid namespaces, path traversal in contract identifiers, non-string namespaces, unsupported manually edited skill_distillation keys, missing namespace values, empty CLI namespaces, conflicting configure modes, duplicate skill-evidence IDs, missing candidate provenance, and mismatched candidate/request evidence fail closed.

Design Decisions

The namespace is saved user configuration, not a per-request header. Future requests may be recorded inside saved sessions, but one HTTP request must not reconfigure which skill is learned or used.

Skill generation should happen after sessions finish, not during normal model request handling. Later implementations can use the Rust traits while keeping provider, storage, validation policy, and agent-specific mounting behavior outside the contract crate.

Generated output should remain reviewable text such as SKILL.md plus support reports. Future updates should retain source-session provenance and previous active versions so people can inspect and roll back changes.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-6/
Built to branch gh-pages at 2026-07-06 19:14 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[sabhatinas]

Im not sure I understand what TrajectoryId is and if its different from the session awareness we have implemented already

[elyasmnvidian]

Renaming to "SkillEvidenceId"

basically this will be the thing fed into an LLM that will distill into a skill.

It can be a piece of a session, or perhaps multiple sessions.

[sabhatinas]

@elyasmnvidian Can you share how the rust traits are going to be used within switchyard ? Im trying to follow the API but its not clear to me how everything ties in.

[elyasmnvidian]

@elyasmnvidian Can you share how the rust traits are going to be used within switchyard ? Im trying to follow the API but its not clear to me how everything ties in.

You’re right—the Switchyard code that calls these traits is not in this PR. This PR defines four expected steps: TrajectorySource loads completed runs, SkillDistiller creates a candidate skill, SkillValidator checks it, and SkillStore saves it and can make it active.
Switchyard will own the code that calls these steps, but we have not settled the exact Rust/Python split, when distillation runs, or when a candidate becomes active. We will show the complete working flow in the next draft PR so the full call path is visible. After we validate it end to end, we will split it into smaller PRs.
I also updated the Rust docs to state that no production Switchyard code uses these traits yet.