spec-ai 0.6.12

A framework for building AI agents with structured outputs, policy enforcement, and execution tracking
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
150
151
152

//! Persistence trait for graph synchronization.
//!
//! This module defines the trait that must be implemented by any storage backend
//! that wants to use the sync engine.

use anyhow::Result;
use crate::spec_ai_knowledge_graph::{EdgeType, NodeType};

use crate::spec_ai_graph_sync::types::{ChangelogEntry, SyncedEdgeRecord, SyncedNodeRecord};

/// Trait for persistence operations required by the sync engine.
///
/// This trait abstracts the database operations needed for graph synchronization,
/// allowing the sync engine to be used with any storage backend.
pub trait SyncPersistence: Send + Sync {
    /// Get the instance ID for this persistence instance.
    fn instance_id(&self) -> &str;

    // ========== Sync State Operations ==========

    /// Get the vector clock for the sync state of a specific graph.
    fn graph_sync_state_get(
        &self,
        instance_id: &str,
        session_id: &str,
        graph_name: &str,
    ) -> Result<Option<String>>;

    /// Update the vector clock for the sync state of a specific graph.
    fn graph_sync_state_update(
        &self,
        instance_id: &str,
        session_id: &str,
        graph_name: &str,
        vector_clock: &str,
    ) -> Result<()>;

    // ========== Node Count ==========

    /// Count nodes in a session.
    fn count_graph_nodes(&self, session_id: &str) -> Result<i64>;

    // ========== Changelog Operations ==========

    /// Append an entry to the changelog.
    #[allow(clippy::too_many_arguments)]
    fn graph_changelog_append(
        &self,
        session_id: &str,
        instance_id: &str,
        entity_type: &str,
        entity_id: i64,
        operation: &str,
        vector_clock: &str,
        data: Option<&str>,
    ) -> Result<i64>;

    /// Get changelog entries since a timestamp.
    fn graph_changelog_get_since(
        &self,
        session_id: &str,
        since_timestamp: &str,
    ) -> Result<Vec<ChangelogEntry>>;

    // ========== Synced Node Operations ==========

    /// Get a node with its sync metadata.
    fn graph_get_node_with_sync(&self, node_id: i64) -> Result<Option<SyncedNodeRecord>>;

    /// List nodes with sync metadata.
    fn graph_list_nodes_with_sync(
        &self,
        session_id: &str,
        sync_enabled_only: bool,
        include_deleted: bool,
    ) -> Result<Vec<SyncedNodeRecord>>;

    /// Update sync metadata for a node.
    fn graph_update_node_sync_metadata(
        &self,
        node_id: i64,
        vector_clock: &str,
        last_modified_by: &str,
        sync_enabled: bool,
    ) -> Result<()>;

    /// Mark a node as deleted.
    fn graph_mark_node_deleted(
        &self,
        node_id: i64,
        vector_clock: &str,
        deleted_by: &str,
    ) -> Result<()>;

    // ========== Synced Edge Operations ==========

    /// Get an edge with its sync metadata.
    fn graph_get_edge_with_sync(&self, edge_id: i64) -> Result<Option<SyncedEdgeRecord>>;

    /// List edges with sync metadata.
    fn graph_list_edges_with_sync(
        &self,
        session_id: &str,
        sync_enabled_only: bool,
        include_deleted: bool,
    ) -> Result<Vec<SyncedEdgeRecord>>;

    /// Update sync metadata for an edge.
    fn graph_update_edge_sync_metadata(
        &self,
        edge_id: i64,
        vector_clock: &str,
        last_modified_by: &str,
        sync_enabled: bool,
    ) -> Result<()>;

    /// Mark an edge as deleted.
    fn graph_mark_edge_deleted(
        &self,
        edge_id: i64,
        vector_clock: &str,
        deleted_by: &str,
    ) -> Result<()>;

    // ========== Node/Edge Insert and Update ==========

    /// Insert a new graph node.
    fn insert_graph_node(
        &self,
        session_id: &str,
        node_type: NodeType,
        label: &str,
        properties: &serde_json::Value,
        embedding_id: Option<i64>,
    ) -> Result<i64>;

    /// Update node properties.
    fn update_graph_node(&self, node_id: i64, properties: &serde_json::Value) -> Result<()>;

    /// Insert a new graph edge.
    #[allow(clippy::too_many_arguments)]
    fn insert_graph_edge(
        &self,
        session_id: &str,
        source_id: i64,
        target_id: i64,
        edge_type: EdgeType,
        predicate: Option<&str>,
        properties: Option<&serde_json::Value>,
        weight: f32,
    ) -> Result<i64>;
}