enya-agent 0.1.0

package/crates/enact-core/src/graph/graph_schema.rs

@@ -0,0 +1,218 @@
+//! StateGraph - builder for creating graphs
+//!
+//! Includes cycle detection to prevent infinite loops (DAG invariant).
+
+use super::edge::{ConditionalEdge, Edge, EdgeTarget};
+use super::node::{DynNode, FunctionNode, Node, NodeState};
+use super::CompiledGraph;
+use std::collections::{HashMap, HashSet};
+use std::future::Future;
+use std::sync::Arc;
+
+/// StateGraph - fluent builder for creating DAGs
+pub struct StateGraph {
+    nodes: HashMap<String, DynNode>,
+    edges: Vec<Edge>,
+    conditional_edges: Vec<ConditionalEdge>,
+    entry_point: Option<String>,
+}
+
+impl StateGraph {
+    /// Create a new empty graph
+    pub fn new() -> Self {
+        Self {
+            nodes: HashMap::new(),
+            edges: Vec::new(),
+            conditional_edges: Vec::new(),
+            entry_point: None,
+        }
+    }
+
+    /// Add a node with a function
+    pub fn add_node<F, Fut>(mut self, name: impl Into<String>, func: F) -> Self
+    where
+        F: Fn(NodeState) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = anyhow::Result<NodeState>> + Send + 'static,
+    {
+        let name = name.into();
+        let node = Arc::new(FunctionNode::new(name.clone(), func));
+        self.nodes.insert(name, node);
+        self
+    }
+
+    /// Add a pre-built node
+    pub fn add_node_impl(mut self, node: impl Node + 'static) -> Self {
+        let name = node.name().to_string();
+        self.nodes.insert(name, Arc::new(node));
+        self
+    }
+
+    /// Add a direct edge between two nodes
+    pub fn add_edge(mut self, from: impl Into<String>, to: impl Into<String>) -> Self {
+        self.edges.push(Edge::new(from, EdgeTarget::node(to)));
+        self
+    }
+
+    /// Add an edge to END
+    pub fn add_edge_to_end(mut self, from: impl Into<String>) -> Self {
+        self.edges.push(Edge::new(from, EdgeTarget::End));
+        self
+    }
+
+    /// Add a conditional edge with a router function
+    pub fn add_conditional_edge<F>(mut self, from: impl Into<String>, router: F) -> Self
+    where
+        F: Fn(&str) -> EdgeTarget + Send + Sync + 'static,
+    {
+        self.conditional_edges.push(ConditionalEdge {
+            from: from.into(),
+            router: Arc::new(router),
+        });
+        self
+    }
+
+    /// Set the entry point node
+    pub fn set_entry_point(mut self, name: impl Into<String>) -> Self {
+        self.entry_point = Some(name.into());
+        self
+    }
+
+    /// Compile the graph for execution
+    pub fn compile(self) -> anyhow::Result<CompiledGraph> {
+        // Validate: must have at least one node
+        if self.nodes.is_empty() {
+            anyhow::bail!("Graph must have at least one node");
+        }
+
+        // Determine entry point
+        let entry_point = self.entry_point.clone().or_else(|| {
+            // If no entry point set, use first node added
+            self.nodes.keys().next().cloned()
+        });
+
+        let entry_point = entry_point.ok_or_else(|| anyhow::anyhow!("No entry point defined"))?;
+
+        // Validate: entry point must exist
+        if !self.nodes.contains_key(&entry_point) {
+            anyhow::bail!("Entry point '{}' does not exist", entry_point);
+        }
+
+        // Validate: all edge sources/targets exist
+        for edge in &self.edges {
+            if !self.nodes.contains_key(&edge.from) {
+                anyhow::bail!("Edge source '{}' does not exist", edge.from);
+            }
+            if let EdgeTarget::Node(ref target) = edge.to {
+                if !self.nodes.contains_key(target) {
+                    anyhow::bail!("Edge target '{}' does not exist", target);
+                }
+            }
+        }
+
+        // Validate: no cycles (DAG invariant)
+        // Build adjacency list from edges
+        let adjacency = self.build_adjacency_list();
+        if let Some(cycle) = self.detect_cycle(&adjacency, &entry_point) {
+            anyhow::bail!(
+                "Graph contains a cycle: {} -> ... -> {}. Cycles are not allowed in DAGs.",
+                cycle.first().unwrap_or(&"?".to_string()),
+                cycle.last().unwrap_or(&"?".to_string())
+            );
+        }
+
+        Ok(CompiledGraph {
+            nodes: self.nodes,
+            edges: self.edges,
+            conditional_edges: self.conditional_edges,
+            entry_point,
+        })
+    }
+
+    /// Build adjacency list from edges
+    fn build_adjacency_list(&self) -> HashMap<String, Vec<String>> {
+        let mut adjacency: HashMap<String, Vec<String>> = HashMap::new();
+
+        // Initialize all nodes with empty neighbor lists
+        for node_name in self.nodes.keys() {
+            adjacency.entry(node_name.clone()).or_default();
+        }
+
+        // Add edges
+        for edge in &self.edges {
+            if let EdgeTarget::Node(ref target) = edge.to {
+                adjacency
+                    .entry(edge.from.clone())
+                    .or_default()
+                    .push(target.clone());
+            }
+        }
+
+        adjacency
+    }
+
+    /// Detect cycle using DFS
+    /// Returns Some(cycle_path) if a cycle is found, None otherwise
+    fn detect_cycle(
+        &self,
+        adjacency: &HashMap<String, Vec<String>>,
+        entry_point: &str,
+    ) -> Option<Vec<String>> {
+        let mut visited = HashSet::new();
+        let mut rec_stack = HashSet::new();
+        let mut path = Vec::new();
+
+        if self.dfs_cycle_detect(entry_point, adjacency, &mut visited, &mut rec_stack, &mut path) {
+            return Some(path);
+        }
+
+        // Also check from all nodes in case graph has disconnected components
+        for node in self.nodes.keys() {
+            if !visited.contains(node) {
+                path.clear();
+                if self.dfs_cycle_detect(node, adjacency, &mut visited, &mut rec_stack, &mut path) {
+                    return Some(path);
+                }
+            }
+        }
+
+        None
+    }
+
+    /// DFS helper for cycle detection
+    fn dfs_cycle_detect(
+        &self,
+        node: &str,
+        adjacency: &HashMap<String, Vec<String>>,
+        visited: &mut HashSet<String>,
+        rec_stack: &mut HashSet<String>,
+        path: &mut Vec<String>,
+    ) -> bool {
+        visited.insert(node.to_string());
+        rec_stack.insert(node.to_string());
+        path.push(node.to_string());
+
+        if let Some(neighbors) = adjacency.get(node) {
+            for neighbor in neighbors {
+                if !visited.contains(neighbor) {
+                    if self.dfs_cycle_detect(neighbor, adjacency, visited, rec_stack, path) {
+                        return true;
+                    }
+                } else if rec_stack.contains(neighbor) {
+                    // Found a cycle
+                    path.push(neighbor.clone());
+                    return true;
+                }
+            }
+        }
+
+        rec_stack.remove(node);
+        path.pop();
+        false
+    }
+}
+
+impl Default for StateGraph {
+    fn default() -> Self {
+        Self::new()
+    }
+}

package/crates/enact-core/src/graph/loader.rs

@@ -0,0 +1,155 @@
+use super::schema::{GraphDefinition, NodeDefinition};
+use super::{EdgeTarget, NodeState, StateGraph};
+use anyhow::{anyhow, Context, Result};
+
+pub struct GraphLoader;
+
+impl GraphLoader {
+    pub fn load_from_str(yaml: &str) -> Result<StateGraph> {
+        let def: GraphDefinition =
+            serde_yaml::from_str(yaml).context("Failed to parse graph definition YAML")?;
+
+        let mut graph = StateGraph::new();
+
+        // 1. Add all nodes
+        for (name, node_def) in &def.nodes {
+            match node_def {
+                NodeDefinition::Llm {
+                    model,
+                    system_prompt,
+                    ..
+                } => {
+                    // Placeholder for LLM node
+                    let name_clone = name.clone();
+                    let model = model.clone().unwrap_or_else(|| "default".to_string());
+                    let prompt = system_prompt.clone();
+
+                    graph = graph.add_node(name, move |state: NodeState| {
+                        let n = name_clone.clone();
+                        let m = model.clone();
+                        let p = prompt.clone();
+                        async move {
+                            println!("🤖 [LLM Node: {}] Model: {}, Prompt: {:.30}...", n, m, p);
+                            // In a real implementation, this would call LlmCallable
+                            Ok(state)
+                        }
+                    });
+                }
+                NodeDefinition::Function { action, .. } => {
+                    let name_clone = name.clone();
+                    let action = action.clone();
+
+                    graph = graph.add_node(name, move |state: NodeState| {
+                        let n = name_clone.clone();
+                        let a = action.clone();
+                        async move {
+                            println!("⚙️ [Function Node: {}] Action: {}", n, a);
+                            // In a real implementation, this would execute the actionCommand
+                            // For now, allow simple "echo" for testing
+                            if a.starts_with("echo ") {
+                                let output = a.trim_start_matches("echo ").to_string();
+                                return Ok(NodeState::from_str(&output));
+                            }
+                            Ok(state)
+                        }
+                    });
+                }
+                NodeDefinition::Condition { expr, .. } => {
+                    let name_clone = name.clone();
+                    let expr = expr.clone();
+
+                    // Condition node evaluates expression and returns the result key
+                    // (which matches an edge key)
+                    graph = graph.add_node(name, move |state: NodeState| {
+                        let n = name_clone.clone();
+                        let e = expr.clone();
+                        async move {
+                            println!("❓ [Condition Node: {}] Expr: {}", n, e);
+                            // Simple mock evaluation
+                            // If input contains "error", return "error", else "ok"
+                            let input = state.as_str().unwrap_or("");
+                            if e.contains("contains('error')") {
+                                if input.contains("error") {
+                                    return Ok(NodeState::from_str("error"));
+                                } else {
+                                    return Ok(NodeState::from_str("ok"));
+                                }
+                            }
+                            Ok(NodeState::from_str("default"))
+                        }
+                    });
+                }
+                _ => {
+                    return Err(anyhow!("Unsupported node type in yaml"));
+                }
+            }
+        }
+
+        // 2. Add edges
+        for (name, node_def) in &def.nodes {
+            let edges = node_def.edges();
+
+            // Check if this is a conditional node (router)
+            // If it has multiple edges with keys other than "_default",
+            // valid keys are the outputs of the previous node.
+
+            // For Llm/Function nodes, usually they have a single "_default" edge
+            // or specific keys if they return structured data?
+            // The schema implies simple string matching on output.
+
+            let is_conditional = matches!(node_def, NodeDefinition::Condition { .. });
+
+            if is_conditional {
+                // Conditional edges based on node output
+                let edges_clone = edges.clone();
+                let router = move |output: &str| -> EdgeTarget {
+                    if let Some(target) = edges_clone.get(output) {
+                        if target == "END" {
+                            EdgeTarget::End
+                        } else {
+                            EdgeTarget::Node(target.clone())
+                        }
+                    } else if let Some(default) = edges_clone.get("_default") {
+                        if default == "END" {
+                            EdgeTarget::End
+                        } else {
+                            EdgeTarget::Node(default.clone())
+                        }
+                    } else {
+                        EdgeTarget::End
+                    }
+                };
+
+                graph = graph.add_conditional_edge(name, router);
+            } else {
+                // Standard edges
+                // TODO: Support branching from non-condition nodes?
+                // For now, assume "_default" is the main edge
+                if let Some(target) = edges.get("_default") {
+                    if target == "END" {
+                        graph = graph.add_edge_to_end(name);
+                    } else {
+                        graph = graph.add_edge(name, target);
+                    }
+                }
+            }
+        }
+
+        // 3. Set entry point
+        // Ideally schema allows defining it, or we use first node?
+        // Current StateGraph defaults to first node if not set.
+        // We could look for "start" or "input" node?
+        // The implementation_plan example didn't specify entry point explicitly.
+        // Let's assume the first defined node in YAML (but HashMap is unordered).
+        // Use "start" or "input" if present, else random?
+        // Better: require `triggers` or look for a node named "start".
+
+        if def.nodes.contains_key("start") {
+            graph = graph.set_entry_point("start");
+        } else if def.nodes.contains_key("input") {
+            graph = graph.set_entry_point("input");
+        }
+
+        Ok(graph)
+    }
+}

package/crates/enact-core/src/graph/mod.rs

@@ -0,0 +1,18 @@
+//! Graph module - DAG execution engine and flow semantics
+
+mod checkpoint;
+mod checkpoint_store;
+mod compiled;
+mod edge;
+mod graph_schema;
+pub mod loader;
+pub mod schema;
+
+pub mod node;
+
+pub use checkpoint::Checkpoint;
+pub use checkpoint_store::{CheckpointStore, InMemoryCheckpointStore};
+pub use compiled::CompiledGraph;
+pub use edge::{Edge, EdgeTarget};
+pub use graph_schema::StateGraph;
+pub use node::{FunctionNode, Node, NodeState};

package/crates/enact-core/src/graph/node/function.rs

@@ -0,0 +1,49 @@
+//! Function node - wraps an async function as a node
+
+use super::{Node, NodeState};
+use async_trait::async_trait;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+/// Type alias for async node functions
+pub type NodeFn = Arc<
+    dyn Fn(NodeState) -> Pin<Box<dyn Future<Output = anyhow::Result<NodeState>> + Send>>
+        + Send
+        + Sync,
+>;
+
+/// Function node - wraps an async closure
+pub struct FunctionNode {
+    name: String,
+    func: NodeFn,
+}
+
+impl FunctionNode {
+    pub fn new<F, Fut>(name: impl Into<String>, func: F) -> Self
+    where
+        F: Fn(NodeState) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = anyhow::Result<NodeState>> + Send + 'static,
+    {
+        let func = Arc::new(move |state: NodeState| {
+            let fut = func(state);
+            Box::pin(fut) as Pin<Box<dyn Future<Output = anyhow::Result<NodeState>> + Send>>
+        });
+
+        Self {
+            name: name.into(),
+            func,
+        }
+    }
+}
+
+#[async_trait]
+impl Node for FunctionNode {
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    async fn execute(&self, state: NodeState) -> anyhow::Result<NodeState> {
+        (self.func)(state).await
+    }
+}

package/crates/enact-core/src/graph/node/mod.rs

@@ -0,0 +1,48 @@
+//! Node module - units of execution in a graph
+
+mod function;
+
+use async_trait::async_trait;
+use serde_json::Value;
+use std::sync::Arc;
+
+pub use function::FunctionNode;
+
+/// Node state - input/output passed between nodes
+#[derive(Debug, Clone, Default)]
+pub struct NodeState {
+    pub data: Value,
+}
+
+impl NodeState {
+    pub fn new() -> Self {
+        Self { data: Value::Null }
+    }
+
+    pub fn from_value(data: Value) -> Self {
+        Self { data }
+    }
+
+    pub fn from_str(s: &str) -> Self {
+        Self {
+            data: Value::String(s.to_string()),
+        }
+    }
+
+    pub fn as_str(&self) -> Option<&str> {
+        self.data.as_str()
+    }
+}
+
+/// Node trait - a single step in a graph
+#[async_trait]
+pub trait Node: Send + Sync {
+    /// Node name (unique within graph)
+    fn name(&self) -> &str;
+
+    /// Execute the node
+    async fn execute(&self, state: NodeState) -> anyhow::Result<NodeState>;
+}
+
+/// Boxed node for dynamic dispatch
+pub type DynNode = Arc<dyn Node>;

package/crates/enact-core/src/graph/schema.rs

@@ -0,0 +1,62 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GraphDefinition {
+    pub name: String,
+    #[serde(default = "default_version")]
+    pub version: String,
+    pub description: Option<String>,
+    #[serde(default)]
+    pub triggers: Vec<String>, // "manual", "cron:...", etc.
+    #[serde(default)]
+    pub inputs: HashMap<String, String>, // name -> description or type
+    pub nodes: HashMap<String, NodeDefinition>,
+}
+
+fn default_version() -> String {
+    "1.0".to_string()
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum NodeDefinition {
+    /// LLM-based agent node
+    Llm {
+        #[serde(default)]
+        model: Option<String>, // e.g., "gpt-4o"
+        system_prompt: String,
+        #[serde(default)]
+        tools: Vec<String>, // tool names
+        #[serde(default)]
+        edges: HashMap<String, String>, // output matching -> target node
+    },
+    /// Function execution node (e.g., shell command, script)
+    Function {
+        action: String, // e.g., "scripts/check_style.sh"
+        #[serde(default)]
+        edges: HashMap<String, String>,
+    },
+    /// Conditional branching node (no LLM, just logic)
+    Condition {
+        expr: String,                   // e.g. "input.contains('error')"
+        edges: HashMap<String, String>, // "true" -> nodeA, "false" -> nodeB
+    },
+    /// Sub-graph execution
+    Graph {
+        graph_name: String,
+        #[serde(default)]
+        edges: HashMap<String, String>,
+    },
+}
+
+impl NodeDefinition {
+    pub fn edges(&self) -> &HashMap<String, String> {
+        match self {
+            NodeDefinition::Llm { edges, .. } => edges,
+            NodeDefinition::Function { edges, .. } => edges,
+            NodeDefinition::Condition { edges, .. } => edges,
+            NodeDefinition::Graph { edges, .. } => edges,
+        }
+    }
+}