episteme 0.3.9

Knowledge graph for software engineering — design patterns, refactorings, and laws for AI agents
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
153
154
155
156
157
158
159
160
161
162
163
164

//! Graph domain: entity lookup, neighbor traversal, and shortest-path queries.

use crate::domain::graph::KnowledgeGraph;
use crate::domain::summarizer::{DetailLevel, summarize_entity};
use crate::ports::graph::GraphRepository;

/// Get detailed information about a single entity.
pub fn get_entity(
    graph: &KnowledgeGraph,
    entity_id: &str,
    detail_level: Option<&str>,
) -> serde_json::Value {
    let entity = match graph.get_entity(entity_id) {
        Some(e) => e,
        None => {
            return serde_json::json!({
                "error": format!("Entity '{}' not found.", entity_id)
            });
        }
    };

    let level = match detail_level.unwrap_or("summary") {
        "minimal" => DetailLevel::Minimal,
        "detailed" => DetailLevel::Detailed,
        "full" => DetailLevel::Full,
        _ => DetailLevel::Summary,
    };

    let entity_json = serde_json::to_value(entity).unwrap_or(serde_json::Value::Null);
    summarize_entity(&entity_json, level)
}

/// Get entities related to a given entity, optionally filtered by relation type.
pub fn get_neighbors(
    graph: &KnowledgeGraph,
    entity_id: &str,
    relation_type: Option<&str>,
) -> serde_json::Value {
    if graph.get_entity(entity_id).is_none() {
        return serde_json::json!({
            "error": format!("Entity '{}' not found.", entity_id)
        });
    }

    let neighbor_ids = graph.get_neighbors(entity_id, relation_type);
    let ids_ref: Vec<&str> = neighbor_ids.iter().map(|s| s.as_str()).collect();
    let entities_map = graph.get_entities_batch(&ids_ref);

    let neighbors: Vec<serde_json::Value> = neighbor_ids
        .iter()
        .filter_map(|nid| {
            entities_map.get(nid).map(|e| {
                serde_json::json!({
                    "id": nid,
                    "title": e.title,
                    "type": e.r#type,
                })
            })
        })
        .collect();

    serde_json::json!({
        "entity_id": entity_id,
        "relation_type": relation_type,
        "neighbors": neighbors,
    })
}

/// Get entity from any `GraphRepository` implementor (e.g. CompositeGraph).
pub fn get_entity_from_repo(
    graph: &dyn GraphRepository,
    entity_id: &str,
    detail_level: Option<&str>,
) -> serde_json::Value {
    let entity = match graph.get_entity(entity_id) {
        Some(e) => e,
        None => {
            return serde_json::json!({
                "error": format!("Entity '{}' not found.", entity_id)
            });
        }
    };

    let level = match detail_level.unwrap_or("summary") {
        "minimal" => DetailLevel::Minimal,
        "detailed" => DetailLevel::Detailed,
        "full" => DetailLevel::Full,
        _ => DetailLevel::Summary,
    };

    let entity_json = serde_json::to_value(entity).unwrap_or(serde_json::Value::Null);
    summarize_entity(&entity_json, level)
}

/// Get neighbors from any `GraphRepository` implementor (e.g. CompositeGraph).
pub fn get_neighbors_from_repo(
    graph: &dyn GraphRepository,
    entity_id: &str,
    relation_type: Option<&str>,
) -> serde_json::Value {
    let neighbor_ids = graph.get_neighbors(entity_id, relation_type);
    let ids_ref: Vec<&str> = neighbor_ids.iter().map(|s| s.as_str()).collect();
    let entities_map = graph.get_entities_batch(&ids_ref);

    let neighbors: Vec<serde_json::Value> = neighbor_ids
        .iter()
        .filter_map(|nid| {
            entities_map.get(nid).map(|e| {
                serde_json::json!({
                    "id": nid,
                    "title": e.title,
                    "type": e.r#type,
                })
            })
        })
        .collect();

    serde_json::json!({
        "entity_id": entity_id,
        "relation_type": relation_type,
        "neighbors": neighbors,
    })
}

/// Find the shortest path between two entities in the knowledge graph.
pub fn find_path(
    graph: &KnowledgeGraph,
    from_id: &str,
    to_id: &str,
    max_depth: Option<usize>,
) -> serde_json::Value {
    let max_depth = max_depth.unwrap_or(5);

    match graph.find_shortest_path(from_id, to_id, max_depth) {
        Some(path) => {
            let ids_ref: Vec<&str> = path.iter().map(|s| s.as_str()).collect();
            let entities_map = graph.get_entities_batch(&ids_ref);

            let labeled: Vec<serde_json::Value> = path
                .iter()
                .map(|pid| {
                    let title = entities_map
                        .get(pid.as_str())
                        .map(|e| e.title.as_str())
                        .unwrap_or("");
                    serde_json::json!({
                        "id": pid,
                        "title": title,
                    })
                })
                .collect();

            serde_json::json!({
                "from": from_id,
                "to": to_id,
                "length": path.len() - 1,
                "path": labeled,
            })
        }
        None => serde_json::json!({
            "error": format!("No path found between '{}' and '{}'.", from_id, to_id)
        }),
    }
}