starweaver-core 0.10.0

Core abstractions for the Starweaver agent SDK
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

//! JSON-compatible run attachment helpers.

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::Metadata;

/// JSON-compatible attachment map shared by run context, tool context, and host bindings.
///
/// Attachments are explicitly Starweaver-local execution metadata. They may be persisted in
/// session/run evidence when stored in context state, but they must not be forwarded to model
/// provider HTTP headers or provider-specific request fields by generic SDK code.
#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
pub struct RunAttachments {
    /// Attachment values keyed by stable application-defined names.
    #[serde(default, flatten)]
    pub values: Metadata,
}

impl RunAttachments {
    /// Create an empty attachment map.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Create attachments from a metadata map.
    #[must_use]
    pub const fn from_metadata(values: Metadata) -> Self {
        Self { values }
    }

    /// Convert attachments into the underlying metadata map.
    #[must_use]
    pub fn into_metadata(self) -> Metadata {
        self.values
    }

    /// Return whether the attachment map is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }

    /// Return the number of attachments.
    #[must_use]
    pub fn len(&self) -> usize {
        self.values.len()
    }

    /// Get one attachment value.
    #[must_use]
    pub fn get(&self, key: &str) -> Option<&Value> {
        self.values.get(key)
    }

    /// Insert or replace one attachment value.
    pub fn insert(&mut self, key: impl Into<String>, value: Value) -> Option<Value> {
        self.values.insert(key.into(), value)
    }

    /// Merge another attachment map into this one. Incoming keys replace existing values.
    pub fn merge(&mut self, other: impl Into<Metadata>) {
        self.values.extend(other.into());
    }
}

impl From<Metadata> for RunAttachments {
    fn from(values: Metadata) -> Self {
        Self::from_metadata(values)
    }
}

impl From<RunAttachments> for Metadata {
    fn from(attachments: RunAttachments) -> Self {
        attachments.into_metadata()
    }
}

impl AsRef<Metadata> for RunAttachments {
    fn as_ref(&self) -> &Metadata {
        &self.values
    }
}

impl AsMut<Metadata> for RunAttachments {
    fn as_mut(&mut self) -> &mut Metadata {
        &mut self.values
    }
}