Skip to main content

qualia_core_db/services/swarm/
executor.rs

1//! Job executors. The [`JobExecutor`] trait is what a worker cell โ€” local or a remote
2//! peer โ€” implements. [`LocalKernelExecutor`] is the **real** one: it runs each job's
3//! kernel through the actual engine (the dynamic GEMM and the real KGE trainer), so a
4//! dispatched job produces genuine computed work โ€” never a stub.
5//!
6//! In the distributed setting the executor is *untrusted* (it could be a stranger's
7//! solar node). That is exactly why dispatch always follows execution with independent
8//! verification ([`super::verify()`]) before any payment.
9
10use super::job::{JobInput, JobResult};
11use super::SwarmError;
12use crate::solvers::learning::kg_embedding::{train, EmbeddingTable};
13use crate::solvers::linear_algebra::gemm::matmul;
14
15/// A node that can execute swarm jobs. Object-safe so it can be boxed and swapped
16/// (a local cell, a remote peer proxy, a test double).
17pub trait JobExecutor {
18    /// Executes a job.
19    fn execute(&self, input: &JobInput) -> Result<JobResult, SwarmError>;
20}
21
22/// Executes jobs on the local CPU through the real engine kernels.
23pub struct LocalKernelExecutor;
24
25impl JobExecutor for LocalKernelExecutor {
26    /// Executes a job.
27    fn execute(&self, input: &JobInput) -> Result<JobResult, SwarmError> {
28        if !input.is_well_formed() {
29            return Err(SwarmError::InvalidJob);
30        }
31        match input {
32            JobInput::DenseLinearProduct { m, k, n, a, b } => {
33                let mut c = vec![0.0; m * n];
34                matmul(*m, *k, *n, a, b, &mut c).map_err(|_| SwarmError::KernelFailed)?;
35                Ok(JobResult::DenseLinearProduct { c })
36            }
37            JobInput::EmbeddingArtifact {
38                triples,
39                n_entities,
40                n_relations,
41                cfg,
42                ..
43            } => {
44                let table: EmbeddingTable = train(triples, *n_entities, *n_relations, *cfg)
45                    .map_err(|_| SwarmError::KernelFailed)?;
46                Ok(JobResult::EmbeddingArtifact { table })
47            }
48        }
49    }
50}
51
52#[cfg(test)]
53mod tests {
54    use super::*;
55    use crate::solvers::learning::kg_embedding::{ScoreModel, TrainConfig};
56
57    #[test]
58    fn local_executor_computes_a_real_product() {
59        let input = JobInput::DenseLinearProduct {
60            m: 2,
61            k: 2,
62            n: 2,
63            a: vec![1.0, 2.0, 3.0, 4.0],
64            b: vec![5.0, 6.0, 7.0, 8.0],
65        };
66        let r = LocalKernelExecutor.execute(&input).unwrap();
67        match r {
68            // [[1,2],[3,4]]ยท[[5,6],[7,8]] = [[19,22],[43,50]]
69            JobResult::DenseLinearProduct { c } => {
70                assert_eq!(c, vec![19.0, 22.0, 43.0, 50.0]);
71            }
72            _ => panic!("wrong result kind"),
73        }
74    }
75
76    #[test]
77    fn local_executor_trains_a_real_artifact() {
78        let input = JobInput::EmbeddingArtifact {
79            triples: vec![(0, 0, 1), (2, 0, 3)],
80            n_entities: 4,
81            n_relations: 1,
82            cfg: TrainConfig {
83                model: ScoreModel::TransE { p: 2 },
84                rank: 8,
85                epochs: 200,
86                lr: 0.05,
87                margin: 1.0,
88                reg: 0.0,
89                neg_per_pos: 4,
90                seed: 7,
91            },
92            check: vec![(0, 0, 1)],
93        };
94        let r = LocalKernelExecutor.execute(&input).unwrap();
95        match r {
96            JobResult::EmbeddingArtifact { table } => {
97                // The trained table scores the true tail above a wrong one.
98                assert!(table.score(0, 0, 1).unwrap() > table.score(0, 0, 3).unwrap());
99            }
100            _ => panic!("wrong result kind"),
101        }
102    }
103
104    #[test]
105    fn malformed_job_fails_closed() {
106        let bad = JobInput::DenseLinearProduct {
107            m: 2,
108            k: 2,
109            n: 2,
110            a: vec![1.0],
111            b: vec![1.0; 4],
112        };
113        assert_eq!(
114            LocalKernelExecutor.execute(&bad).unwrap_err(),
115            SwarmError::InvalidJob
116        );
117    }
118}