ferrum-interfaces 0.8.4

Core trait contracts for the Ferrum LLM inference engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

use super::{
    CapabilityCatalog, DeviceDescriptor, ExecutionPlan, PlanBuildRequest, RuntimePolicy, VNextError,
};

/// Minimal trusted view consumed by resource admission and operation dispatch.
/// Product resolution may wrap this with tokenizer, sampling, source, and API
/// policy, but those concerns do not enter the device execution boundary.
pub trait ExecutablePlanView {
    fn execution_plan(&self) -> &ExecutionPlan;
    fn device(&self) -> &DeviceDescriptor;
    fn capabilities(&self) -> &CapabilityCatalog;
}

/// Owned executable produced directly by the planner for a concrete runtime
/// composition root. It is intentionally smaller than a product-level
/// `ResolvedModelPlan`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExecutablePlan {
    plan: ExecutionPlan,
    capabilities: CapabilityCatalog,
}

impl ExecutablePlan {
    pub fn new(plan: ExecutionPlan, capabilities: CapabilityCatalog) -> Result<Self, VNextError> {
        let catalog_fingerprint = capabilities.fingerprint()?;
        if plan.payload().device_id() != &capabilities.device().id
            || plan.payload().device_runtime_implementation_fingerprint()
                != capabilities.device().runtime_implementation_fingerprint
            || plan.payload().capability_catalog_fingerprint() != catalog_fingerprint
        {
            return Err(VNextError::InvalidExecutionPlan {
                reason: "executable plan differs from its device capability catalog".to_owned(),
            });
        }
        Ok(Self { plan, capabilities })
    }

    pub fn into_parts(self) -> (ExecutionPlan, CapabilityCatalog) {
        (self.plan, self.capabilities)
    }
}

impl ExecutablePlanView for ExecutablePlan {
    fn execution_plan(&self) -> &ExecutionPlan {
        &self.plan
    }

    fn device(&self) -> &DeviceDescriptor {
        self.capabilities.device()
    }

    fn capabilities(&self) -> &CapabilityCatalog {
        &self.capabilities
    }
}

/// Pure planner boundary. Execution consumes the immutable plan and performs
/// no capability/backend selection in the token loop.
pub trait ExecutionPlanner: Send + Sync {
    type Policy: RuntimePolicy;

    fn build_plan(
        &self,
        request: PlanBuildRequest<'_, Self::Policy>,
    ) -> Result<ExecutionPlan, VNextError>;
}