quantumclaw 0.1.0

Single-crate public API for the QuantumClaw agent runtime built on ZeroClaw.
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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

use crate::quantumclaw_core::{Observer, Result, SolverKind};
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::BTreeMap;
use std::sync::{Arc, RwLock};

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TraceEvent {
    pub trace_id: String,
    pub event_type: String,
    pub message: String,
    pub selected_backend: Option<String>,
    pub rejected_backend: Option<String>,
    pub plan_score: Option<f64>,
    pub latency_ms: Option<u64>,
    pub cost_estimate: Option<f64>,
    pub confidence: Option<f64>,
    pub policy_decision: Option<String>,
    pub metadata: BTreeMap<String, String>,
}

impl TraceEvent {
    pub fn new(event_type: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            trace_id: "trace-local".into(),
            event_type: event_type.into(),
            message: message.into(),
            selected_backend: None,
            rejected_backend: None,
            plan_score: None,
            latency_ms: None,
            cost_estimate: None,
            confidence: None,
            policy_decision: None,
            metadata: BTreeMap::new(),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MetricEvent {
    pub name: String,
    pub value: f64,
    pub dimensions: BTreeMap<String, String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PlannerComparisonEvent {
    pub primary_backend: String,
    pub primary_backend_kind: SolverKind,
    pub shadow_backend: String,
    pub shadow_backend_kind: SolverKind,
    pub primary_score: f64,
    pub shadow_score: f64,
    pub latency_ms: u64,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BackendTelemetry {
    pub backend: String,
    pub backend_kind: SolverKind,
    pub selected: bool,
    pub latency_ms: u64,
    pub cost_estimate: f64,
    pub confidence: f64,
}

#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ExecutionTrace {
    pub events: Vec<TraceEvent>,
    pub metrics: Vec<MetricEvent>,
    pub comparisons: Vec<PlannerComparisonEvent>,
}

#[async_trait]
pub trait AuditSink: Send + Sync {
    async fn write_audit(&self, event: Value) -> Result<()>;
}

#[derive(Debug, Default, Clone)]
pub struct InMemoryObserver {
    trace_events: Arc<RwLock<Vec<TraceEvent>>>,
    metric_events: Arc<RwLock<Vec<MetricEvent>>>,
    comparison_events: Arc<RwLock<Vec<PlannerComparisonEvent>>>,
    audit_events: Arc<RwLock<Vec<Value>>>,
}

impl InMemoryObserver {
    pub fn record_trace(&self, event: TraceEvent) {
        self.trace_events
            .write()
            .expect("observer trace lock")
            .push(event);
    }

    pub fn record_metric(&self, event: MetricEvent) {
        self.metric_events
            .write()
            .expect("observer metric lock")
            .push(event);
    }

    pub fn record_comparison(&self, event: PlannerComparisonEvent) {
        self.comparison_events
            .write()
            .expect("observer comparison lock")
            .push(event);
    }

    pub fn execution_trace(&self) -> ExecutionTrace {
        ExecutionTrace {
            events: self
                .trace_events
                .read()
                .expect("observer trace lock")
                .clone(),
            metrics: self
                .metric_events
                .read()
                .expect("observer metric lock")
                .clone(),
            comparisons: self
                .comparison_events
                .read()
                .expect("observer comparison lock")
                .clone(),
        }
    }
}

#[async_trait]
impl Observer for InMemoryObserver {
    async fn observe(&self, event: Value) -> Result<()> {
        self.record_trace(TraceEvent::new("generic", event.to_string()));
        Ok(())
    }
}

#[async_trait]
impl AuditSink for InMemoryObserver {
    async fn write_audit(&self, event: Value) -> Result<()> {
        self.audit_events
            .write()
            .expect("observer audit lock")
            .push(event);
        Ok(())
    }
}