Merge pull request aden-hive#222 from Chrishabh2002/feat/manual-agent-codefirst

Add minimal code-first agent example and isolate core dependencies

Author: RichardTang-Aden

.gitignore

@@ -0,0 +1,122 @@
+"""
+Minimal Manual Agent Example
+----------------------------
+This example demonstrates how to build and run an agent programmatically
+without using the Claude Code CLI or external LLM APIs.
+
+It uses 'function' nodes to define logic in pure Python, making it perfect
+for understanding the core runtime loop:
+Setup -> Graph definition -> Execution -> Result
+
+Run with:
+    PYTHONPATH=core python core/examples/manual_agent.py
+"""
+
+import asyncio
+import logging
+from framework.graph import Goal, NodeSpec, EdgeSpec, GraphSpec, EdgeCondition
+from framework.graph.executor import GraphExecutor
+from framework.runtime.core import Runtime
+
+# 1. Define Node Logic (Pure Python Functions)
+def greet(name: str) -> str:
+    """Generate a simple greeting."""
+    return f"Hello, {name}!"
+
+def uppercase(greeting: str) -> str:
+    """Convert text to uppercase."""
+    return greeting.upper()
+
+async def main():
+    print("🚀 Setting up Manual Agent...")
+
+    # 2. Define the Goal
+    # Every agent needs a goal with success criteria
+    goal = Goal(
+        id="greet-user",
+        name="Greet User",
+        description="Generate a friendly uppercase greeting",
+        success_criteria=[
+            {
+                "id": "greeting_generated", 
+                "description": "Greeting produced",
+                "metric": "custom",
+                "target": "any"
+            }
+        ]
+    )
+
+    # 3. Define Nodes
+    # Nodes describe steps in the process
+    node1 = NodeSpec(
+        id="greeter",
+        name="Greeter",
+        description="Generates a simple greeting",
+        node_type="function",
+        function="greet",  # Matches the registered function name
+        input_keys=["name"],
+        output_keys=["greeting"]
+    )
+
+    node2 = NodeSpec(
+        id="uppercaser",
+        name="Uppercaser",
+        description="Converts greeting to uppercase",
+        node_type="function",
+        function="uppercase", 
+        input_keys=["greeting"],
+        output_keys=["final_greeting"]
+    )
+
+    # 4. Define Edges
+    # Edges define the flow between nodes
+    edge1 = EdgeSpec(
+        id="greet-to-upper",
+        source="greeter",
+        target="uppercaser",
+        condition=EdgeCondition.ON_SUCCESS
+    )
+
+    # 5. Create Graph
+    # The graph works like a blueprint connecting nodes and edges
+    graph = GraphSpec(
+        id="greeting-agent",
+        goal_id="greet-user",
+        entry_node="greeter",
+        terminal_nodes=["uppercaser"],
+        nodes=[node1, node2],
+        edges=[edge1],
+    )
+
+    # 6. Initialize Runtime & Executor
+    # Runtime handles state/memory; Executor runs the graph
+    from pathlib import Path
+    runtime = Runtime(storage_path=Path("./agent_logs"))
+    executor = GraphExecutor(runtime=runtime)
+
+    # 7. Register Function Implementations
+    # Connect string names in NodeSpecs to actual Python functions
+    executor.register_function("greeter", greet)
+    executor.register_function("uppercaser", uppercase)
+
+    # 8. Execute Agent
+    print(f"▶ Executing agent with input: name='Alice'...")
+    
+    result = await executor.execute(
+        graph=graph,
+        goal=goal,
+        input_data={"name": "Alice"}
+    )
+
+    # 9. Verify Results
+    if result.success:
+        print("\n✅ Success!")
+        print(f"Path taken: {' -> '.join(result.path)}")
+        print(f"Final output: {result.output.get('final_greeting')}")
+    else:
+        print(f"\n❌ Failed: {result.error}")
+
+if __name__ == "__main__":
+    # Optional: Enable logging to see internal decision flow
+    # logging.basicConfig(level=logging.INFO)
+    asyncio.run(main())

core/examples/manual_agent.py

@@ -2,7 +2,7 @@
 
 from framework.graph.goal import Goal, SuccessCriterion, Constraint, GoalStatus
 from framework.graph.node import NodeSpec, NodeContext, NodeResult, NodeProtocol
-from framework.graph.edge import EdgeSpec, EdgeCondition
+from framework.graph.edge import EdgeSpec, EdgeCondition, GraphSpec
 from framework.graph.executor import GraphExecutor
 
 # Flexible execution (Worker-Judge pattern)
@@ -42,6 +42,7 @@
     # Edge
     "EdgeSpec",
     "EdgeCondition",
+    "GraphSpec",
     # Executor (fixed graph)
     "GraphExecutor",
     # Plan (flexible execution)

core/framework/graph/__init__.py

@@ -1123,9 +1123,13 @@ async def execute(self, ctx: NodeContext) -> NodeResult:
             )
 
             # Write to output keys
-            output = {"result": result}
+            output = {}
             if ctx.node_spec.output_keys:
-                ctx.memory.write(ctx.node_spec.output_keys[0], result)
+                key = ctx.node_spec.output_keys[0]
+                output[key] = result
+                ctx.memory.write(key, result)
+            else:
+                output = {"result": result}
 
             return NodeResult(success=True, output=output, latency_ms=latency_ms)
 

core/framework/graph/node.py

@@ -1,7 +1,17 @@
 """LLM provider abstraction."""
 
 from framework.llm.provider import LLMProvider, LLMResponse
-from framework.llm.anthropic import AnthropicProvider
-from framework.llm.litellm import LiteLLMProvider
 
-__all__ = ["LLMProvider", "LLMResponse", "AnthropicProvider", "LiteLLMProvider"]
+__all__ = ["LLMProvider", "LLMResponse"]
+
+try:
+    from framework.llm.anthropic import AnthropicProvider
+    __all__.append("AnthropicProvider")
+except ImportError:
+    pass
+
+try:
+    from framework.llm.litellm import LiteLLMProvider
+    __all__.append("LiteLLMProvider")
+except ImportError:
+    pass

core/framework/llm/__init__.py

@@ -10,7 +10,10 @@
 import json
 from typing import Any
 
-import litellm
+try:
+    import litellm
+except ImportError:
+    litellm = None
 
 from framework.llm.provider import LLMProvider, LLMResponse, Tool, ToolUse
 
@@ -72,6 +75,11 @@ def __init__(
         self.api_base = api_base
         self.extra_kwargs = kwargs
 
+        if litellm is None:
+            raise ImportError(
+                "LiteLLM is not installed. Please install it with: pip install litellm"
+            )
+
     def complete(
         self,
         messages: list[dict[str, Any]],

core/framework/llm/litellm.py

@@ -59,6 +59,20 @@ cd exports/my_agent
 PYTHONPATH=core:exports python -m my_agent validate
 ```
 
+### Option 3: Manual Code-First (Minimal Example)
+
+If you prefer to start with code rather than CLI wizards, check out the manual agent example:
+
+```bash
+# View the minimal example
+cat core/examples/manual_agent.py
+
+# Run it (no API keys required)
+PYTHONPATH=core python core/examples/manual_agent.py
+```
+
+This demonstrates the core runtime loop using pure Python functions, skipping the complexity of LLM setup and file-based configuration.
+
 ## Project Structure
 
 ```