wyrd-spec 0.1.1

Wyrd foundation types: Card envelope, SpecKinds, and pure data contracts.
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

//! Helpers shared across multiple Card specs.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use crate::reference::{CardRef, Ref};

/// Typed parameter value for experiments, runs, workflows, and tools.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
#[serde(tag = "type", content = "value", rename_all = "snake_case")]
pub enum ParameterValue {
    /// Integer value.
    Int(i64),
    /// Floating-point value.
    Float(f64),
    /// String value.
    Str(String),
    /// Boolean value.
    Bool(bool),
    /// Structured JSON value.
    Json(serde_json::Value),
}

/// Metric summary entry.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
pub struct MetricEntry {
    /// Metric name.
    pub name: String,
    /// Numeric metric value.
    pub value: f64,
    /// Optional step.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub step: Option<i64>,
    /// Metric event timestamp.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timestamp: Option<chrono::DateTime<chrono::Utc>>,
    /// Metric creation timestamp.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created_at: Option<chrono::DateTime<chrono::Utc>>,
    /// Whether this metric came from evaluation.
    #[serde(default)]
    pub is_eval: bool,
}

/// Protocol-specific public metadata for an agent or service interface.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
pub struct ProtocolProfile {
    /// Protocol name, such as `a2a`, `ag_ui`, `a2ui`, `mcp`, or `http`.
    pub protocol: String,
    /// Protocol version.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    /// Protocol-specific declarative metadata.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, NonSecretValue>,
}

/// Agent-facing interface declaration.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
pub struct AgentInterface {
    /// Interface name.
    pub name: String,
    /// Interface mode, such as `text`, `json`, `audio`, or `tool`.
    pub mode: String,
    /// Optional schema Card reference.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub schema_ref: Option<CardRef>,
    /// Interface metadata.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, NonSecretValue>,
}

/// Reference to a credential or secret managed outside public Card specs.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
pub struct CredentialRef {
    /// Credential provider or secret store name.
    pub provider: String,
    /// Key or logical name in that provider.
    pub name: String,
}

/// Non-secret JSON-like configuration value.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
#[serde(tag = "type", content = "value", rename_all = "snake_case")]
pub enum NonSecretValue {
    /// String value.
    Str(String),
    /// Numeric value.
    Number(f64),
    /// Boolean value.
    Bool(bool),
    /// List of non-secret values.
    List(Vec<NonSecretValue>),
    /// Object of non-secret values.
    Object(BTreeMap<String, NonSecretValue>),
}

/// Declarative governance and audit hooks.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
pub struct Governance {
    /// Policy Card references.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policy_refs: Vec<Ref>,
    /// Audit Card reference.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub audit_ref: Option<Ref>,
    /// Required approval labels or scopes.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub approval_requirements: Vec<String>,
    /// Governance metadata.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, NonSecretValue>,
}

/// Observation routing hooks for Cards that produce runs or events.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, schemars::JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::ToSchema))]
pub struct ObservationHooks {
    /// Observation route Card references.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub route_refs: Vec<Ref>,
    /// Event names to observe.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub events: Vec<String>,
}