Skip to main content

Algorithm

switchyard_libsy

Trait Algorithm 

Source 
pub trait Algorithm:
    Send
    + Sync
    + 'static {
    // Required methods
    fn name(&self) -> &str;
    fn route<'async_trait>(
        self: Arc<Self>,
        driver: Driver,
        request: Request,
    ) -> Pin<Box<dyn Future<Output = Result<RoutingOutcome>> + Send + 'async_trait>>
       where Self: 'async_trait;

    // Provided method
    fn run_stream(
        self: Arc<Self>,
        request: Request,
        models: Arc<RuntimeModels>,
    ) -> StepStream { ... }
}
Expand description

Routing policy independent of how external calls are executed. Implement route, using Driver to request work from the host. Hosts can use drive for the shared execution loop or consume run_stream for custom execution.

Methods take self: Arc<Self>: one algorithm (Arc<dyn Algorithm>) is shared across requests and run concurrently, so it owns its thread-safety and any shared state.

§Concurrency

A host may run the same algorithm concurrently for many requests. Implementations must synchronize their own mutable shared state. Each call to run_stream creates an independent Driver, so model-call promises and emitted Steps cannot cross between runs.

§Observability

run_stream creates a libsy.run span, and each offloaded model call creates a nested libsy.llm_call span. Successful outcomes record their OutcomeMetadata::outcome_id on libsy.run, alongside selected_model_ids (an ordered OpenTelemetry string array). algorithm and switchyard.algorithm retain the run’s Algorithm::name. Optional evidence.source, evidence.verdict, evidence.trigger, and evidence.reason_code are strings; evidence.score, evidence.confidence, and evidence.threshold are numbers. Unknown evidence fields are not exported. These fields are span attributes, never metric labels.

The run/call observability helpers retain outcome status and operational metrics, but omit error details and arbitrary request extra metadata. Algorithms and hosts may emit their own logs. Errors still reach the caller unchanged. The host controls the tracing subscriber and global OpenTelemetry meter provider; libsy installs no exporter and performs no telemetry network I/O.

Required Methods§

Source

fn name(&self) -> &str

Stable, low-cardinality name identifying this algorithm — the algorithm attribute on every span, metric, and log line the crate emits for its runs.

Source

fn route<'async_trait>( self: Arc<Self>, driver: Driver, request: Request, ) -> Pin<Box<dyn Future<Output = Result<RoutingOutcome>> + Send + 'async_trait>>
where Self: 'async_trait,

Select a route, requesting external work through Driver as needed. run_stream runs this method and exposes its work to the host.

Provided Methods§

Source

fn run_stream( self: Arc<Self>, request: Request, models: Arc<RuntimeModels>, ) -> StepStream

Expose work requests and the final outcome so the host can control execution.

Each call waits for its host reply. A run ends with one terminal item — Step::Done on success, an Err item on failure, including when the algorithm panics. Dropping the stream aborts the spawned algorithm task.

Every invocation owns a separate Driver.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§