Merge branch 'XSpoonAi:main' into main

Author: moonpyt

docs/graph-system/advanced-features.md

@@ -285,10 +285,11 @@ if __name__ == "__main__":
 Let an LLM decide the next step:
 
 ```python
+import asyncio
 from spoon_ai.graph.config import GraphConfig, RouterConfig
-from typing import TypedDict
+from typing import TypedDict, Any
 
-from spoon_ai.graph import StateGraph
+from spoon_ai.graph import StateGraph, END
 
 config = GraphConfig(
     router=RouterConfig(
@@ -303,15 +304,53 @@ class AnalysisState(TypedDict, total=False):
     user_query: str
     output: str
 
-graph = StateGraph(AnalysisState)
+async def route(state: AnalysisState) -> dict:
+    return {}
+
+async def price_handler(state: AnalysisState) -> dict:
+    return {"output": "Price handler executed"}
+
+async def trade_handler(state: AnalysisState) -> dict:
+    return {"output": "Trade handler executed"}
+
+async def analysis_handler(state: AnalysisState) -> dict:
+    return {"output": "Analysis handler executed"}
+
+async def fallback_handler(state: AnalysisState) -> dict:
+    return {"output": "Fallback handler executed"}
+
+graph = StateGraph[Any](AnalysisState)
+graph.add_node("route", route)
+graph.add_node("price_handler", price_handler)
+graph.add_node("trade_handler", trade_handler)
+graph.add_node("analysis_handler", analysis_handler)
+graph.add_node("fallback_handler", fallback_handler)
+graph.set_entry_point("route")
+
+graph.add_edge("price_handler", END)
+graph.add_edge("trade_handler", END)
+graph.add_edge("analysis_handler", END)
+graph.add_edge("fallback_handler", END)
+
 graph.config = config
 
-# Or enable after creation
+# Enable LLM routing
 graph.enable_llm_routing(config={
     "model": "gpt-4",
     "temperature": 0.1,
     "max_tokens": 50,
 })
+
+app = graph.compile()
+
+
+async def main():
+    result = await app.invoke({"user_query": "What is the price of Bitcoin?", "output": ""})
+    print(result["output"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ### Routing Decision Matrix
@@ -384,6 +423,20 @@ graph.add_edge("fetch_kraken", "aggregate")
 graph.add_edge("aggregate", END)
 
 app = graph.compile()
+
+async def main():
+    result = await app.invoke({
+        "symbol": "BTC",
+        "binance": {},
+        "coinbase": {},
+        "kraken": {},
+        "output": ""
+    })
+    print(result["output"])
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())
 ```
 
 ### Join Strategies
@@ -518,6 +571,38 @@ graph.add_edge("aggregate", END)
 
 graph.set_entry_point("fetch_a")
 app = graph.compile()
+
+
+async def main():
+    # Test case 1: Normal execution
+    print("Test 1: Normal execution (quorum: 2 of 3)")
+    result1 = await app.invoke({
+        "symbol": "BTC",
+        "source_a_data": {},
+        "source_b_data": {},
+        "source_c_data": {},
+        "aggregated_price": 0.0,
+        "errors": []
+    })
+    print(f"  Aggregated price: ${result1['aggregated_price']:.2f}")
+    print(f"  Errors: {result1.get('errors', [])}")
+    
+    # Test case 2: One source fails (quorum still met)
+    print("\nTest 2: Source C fails (quorum: 2 of 3 still met)")
+    result2 = await app.invoke({
+        "symbol": "FAIL",
+        "source_a_data": {},
+        "source_b_data": {},
+        "source_c_data": {},
+        "aggregated_price": 0.0,
+        "errors": []
+    })
+    print(f"  Aggregated price: ${result2['aggregated_price']:.2f}")
+    print(f"  Errors: {result2.get('errors', [])}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ---

docs/graph-system/building-graphs.md

@@ -149,6 +149,28 @@ graph.add_edge("news", END)
 graph.add_edge("general", END)
 
 app = graph.compile()
+
+async def main():
+    # Test with different queries
+    test_queries = [
+        "What is the price of Bitcoin?",
+        "Show me crypto news",
+        "Tell me about blockchain"
+    ]
+    
+    for query in test_queries:
+        result = await app.invoke({
+            "query": query,
+            "category": "",
+            "result": ""
+        })
+        print(f"Query: {query}")
+        print(f"Category: {result['category']}")
+        print(f"Result: {result['result']}")
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())
 ```
 
 ### API Reference
@@ -341,6 +363,29 @@ template = GraphTemplate(
 builder = DeclarativeGraphBuilder(DataState)
 graph = builder.build(template)
 app = graph.compile()
+
+
+async def main():
+    # Test the parallel group execution
+    result = await app.invoke({
+        "symbol": "BTC",
+        "binance_data": {},
+        "coinbase_data": {},
+        "kraken_data": {},
+        "aggregated": {}
+    })
+    
+    print("Parallel Group Execution Results:")
+    print(f"Symbol: {result['symbol']}")
+    print(f"\nBinance Data: {result['binance_data']}")
+    print(f"Coinbase Data: {result['coinbase_data']}")
+    print(f"Kraken Data: {result['kraken_data']}")
+    print(f"\nAggregated Average Price: {result['aggregated']['average_price']}")
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())
 ```
 
 ### Template Serialization
@@ -544,7 +589,7 @@ from typing import TypedDict
 
 from spoon_ai.graph import StateGraph, END
 from spoon_ai.graph.builder import GraphTemplate, NodeSpec, EdgeSpec
-
+from spoon_ai.graph.builder import DeclarativeGraphBuilder
 
 class MyState(TypedDict, total=False):
     input: str
@@ -565,6 +610,11 @@ template = GraphTemplate(
     nodes=[NodeSpec("process", process_fn)],
     edges=[EdgeSpec("process", END)],
 )
+
+# Build declarative graph
+builder = DeclarativeGraphBuilder(MyState)
+declarative_graph = builder.build(template)
+declarative_app = declarative_graph.compile()
 ```
 
 ### 2. Use Meaningful Node Names
@@ -597,11 +647,6 @@ graph = StateGraph(MyState)
 graph.add_node("classify_user_intent", classify_fn)
 graph.add_node("fetch_market_data", fetch_fn)
 graph.add_node("generate_recommendation", recommend_fn)
-
-# Bad: Generic names
-graph.add_node("step1", classify_fn)
-graph.add_node("step2", fetch_fn)
-graph.add_node("step3", recommend_fn)
 ```
 
 ### 3. Group Related Functionality
@@ -686,7 +731,7 @@ from typing import TypedDict
 from spoon_ai.graph import END
 from spoon_ai.graph.builder import GraphTemplate, NodeSpec, EdgeSpec
 from spoon_ai.graph.config import GraphConfig
-
+from spoon_ai.graph.builder import DeclarativeGraphBuilder
 
 class MyState(TypedDict, total=False):
     input: str
@@ -711,6 +756,10 @@ template = GraphTemplate(
         # and market analysis with LLM-powered routing
     ),
 )
+# Build and compile
+builder = DeclarativeGraphBuilder(MyState)
+graph = builder.build(template)
+app = graph.compile()
 ```
 
 ---

docs/graph-system/integration.md

@@ -374,11 +374,24 @@ async def mcp_search_node(state: SearchState) -> dict:
 
     result = await tavily_tool.execute(query=state.get("query", ""), max_results=5)
     return {"search_results": result}
+
+async def main():
+    # Test the MCP tool node
+    result = await mcp_search_node({"query": "Bitcoin price"})
+    print(f"\nQuery: Bitcoin price")
+    print(f"Results: {result.get('search_results', 'No results')}")
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())
 ```
 
 ### High-Level MCP Integration
 
 ```python
+import os
+import asyncio
 from typing import TypedDict
 
 from spoon_ai.graph.builder import HighLevelGraphAPI
@@ -389,19 +402,39 @@ class MyState(TypedDict, total=False):
     user_query: str
 
 
-api = HighLevelGraphAPI(MyState)
+async def main():
+    api = HighLevelGraphAPI(MyState)
+    
+    # Check if TAVILY_API_KEY is configured
+    tavily_key = os.getenv("TAVILY_API_KEY", "").strip()
+    if not tavily_key or "..." in tavily_key:
+        print("Note: TAVILY_API_KEY not configured. MCP tool registration skipped.")
+        print("To use this example, set TAVILY_API_KEY environment variable.")
+        return
+    
+    # Register MCP tool using HighLevelGraphAPI
+    api.register_mcp_tool(
+        intent_category="research",
+        spec=MCPToolSpec(name="tavily-search"),
+        config={
+            "command": "npx",
+            "args": ["--yes", "tavily-mcp"],
+            "env": {"TAVILY_API_KEY": tavily_key},
+        },
+    )
+    
+    # Create the tool instance
+    tool = api.create_mcp_tool("tavily-search")
+    
+    if tool:
+        result = await tool.execute(query="Bitcoin price", max_results=3)
+        print(f"Search results: {len(str(result))} characters returned")
+    else:
+        print("Failed to create MCP tool. Check configuration.")
 
-api.register_mcp_tool(
-    intent_category="research",
-    spec=MCPToolSpec(name="tavily-search"),
-    config={
-        "command": "npx",
-        "args": ["--yes", "tavily-mcp"],
-        "env": {"TAVILY_API_KEY": "..."},
-    },
-)
 
-tool = api.create_mcp_tool("tavily-search")
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ### For More MCP Information
@@ -632,6 +665,15 @@ graph.add_edge("process", END)
 
 graph.enable_monitoring(["execution_time", "success_rate", "routing_performance", "node_stats"])
 app = graph.compile()
+
+async def main():
+    # Execute the graph
+    result = await app.invoke({"input": "test", "output": ""})
+    print(result)
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())
 ```
 
 ### Execution Metrics