Merge branch 'XSpoonAi:main' into main

helloissariel · web-flow · commit 473daa484dca · 2025-11-11T10:12:28.000+08:00
diff --git a/docs/api-reference/graph/index.md b/docs/api-reference/graph/index.md
@@ -15,7 +15,7 @@ SpoonOS's graph system enables:
 ## Core Components
 
 ### [StateGraph](state-graph.md)
-The main graph execution engine providing LangGraph-style workflow orchestration.
+The main graph execution engine providing workflow orchestration.
 
 **Key Features:**
 - Node and edge management
diff --git a/docs/api-reference/llm/config-manager.md b/docs/api-reference/llm/config-manager.md
@@ -2,6 +2,8 @@
 
 The `ConfigurationManager` handles loading, validation, and management of LLM provider configurations from various sources including environment variables, configuration files, and runtime settings.
 
+> **Note (Nov 2025):** The core SDK now defaults to environment-driven configuration. Use the `spoon-cli` configuration manager (or set environment variables manually) to sync `config.json` values before instantiating `ConfigurationManager()`.
+
 ## Class Definition
 
 ```python
@@ -57,8 +59,13 @@ Load configuration from a JSON or TOML file.
 
 **Example:**
 ```python
+import os
+from spoon_ai.llm import ConfigurationManager
+
+# Populate required environment variables before instantiating the manager
+os.environ["OPENAI_API_KEY"] = "sk-..."
+
 config_manager = ConfigurationManager()
-config = config_manager.load_from_file("config.json")
 ```
 
 ### `load_from_env() -> Dict[str, Any]`
@@ -78,6 +85,13 @@ Load configuration from environment variables.
 config = config_manager.load_from_env()
 ```
 
+Environment overrides also control provider priority:
+
+- `DEFAULT_LLM_PROVIDER` selects the preferred provider (e.g. `anthropic`).
+- `LLM_FALLBACK_CHAIN` lists comma-separated providers for cascading retries (e.g. `anthropic,openai,gemini`).
+
+When using `spoon-cli`, these variables are exported automatically after `config.json` loads. If you instantiate the SDK directly, set them yourself before calling `ConfigurationManager()`.
+
 ### `merge_configs(base_config: Dict, override_config: Dict) -> Dict[str, Any]`
 
 Merge two configurations with override priority.
@@ -394,7 +408,7 @@ decrypted = config_manager.decrypt_config(encrypted_config)
 import os
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # environment-first configuration
 
 # Secure: Load from environment
 config_manager.set_provider_config("openai", {
@@ -432,27 +446,12 @@ llm_manager = LLMManager(config_manager=config_manager)
 
 ## Integration Examples
 
-### With LLMManager
-
-```python
-from spoon_ai.llm import ConfigurationManager, LLMManager
-
-# Initialize configuration
-config_manager = ConfigurationManager("config.json")
-
-# Create LLM manager with configuration
-llm_manager = LLMManager(config_manager=config_manager)
-
-# Configuration changes are automatically picked up
-response = await llm_manager.chat(messages)
-```
-
 ### Programmatic Configuration
 
 ```python
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # defaults to environment variables
 
 # Configure providers programmatically
 providers = {
diff --git a/docs/api-reference/llm/index.md b/docs/api-reference/llm/index.md
@@ -6,6 +6,8 @@ The LLM (Large Language Model) system in SpoonOS provides a unified, provider-ag
 
 SpoonOS's LLM system offers:
 
+- > **Note (Nov 2025):** The core Python SDK reads provider settings from environment variables. The `spoon-cli` toolchain loads `config.json` and exports those values into the environment automatically. When using the SDK directly, set the relevant `*_API_KEY`, `*_BASE_URL`, and related environment variables before creating `ConfigurationManager()`.
+
 - **Provider Agnosticism**: Unified API across all providers
 - **Automatic Fallback**: Intelligent provider switching on failures
 - **Load Balancing**: Distribute requests across multiple providers
@@ -59,10 +61,14 @@ Handles configuration loading, validation, and management from multiple sources.
 - Configuration templates and merging
 
 ```python
+import os
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager("config.json")
-config_manager.set_provider_config("openai", {...})
+# Export provider settings into environment variables
+os.environ["OPENAI_API_KEY"] = "sk-..."
+os.environ["DEFAULT_LLM_PROVIDER"] = "openai"
+
+config_manager = ConfigurationManager()
 ```
 
 ## Quick Start
@@ -82,19 +88,28 @@ response = await llm_manager.chat(messages)
 print(response.content)
 ```
 
-### With Configuration
 
-```python
-from spoon_ai.llm import ConfigurationManager, LLMManager
+### Controlling Provider Priority
+
+You can steer which provider is used first—and how the system falls back—purely via environment variables:
+
+```bash
+# Prefer Anthropic by default
+export DEFAULT_LLM_PROVIDER=anthropic
+
+# Allow fallback to OpenAI, then Gemini
+export LLM_FALLBACK_CHAIN="anthropic,openai,gemini"
+```
 
-# Load configuration
-config_manager = ConfigurationManager("config.json")
-llm_manager = LLMManager(config_manager=config_manager)
+On Windows PowerShell:
 
-# Chat with specific provider
-response = await llm_manager.chat(messages, provider="openai")
+```powershell
+$env:DEFAULT_LLM_PROVIDER = "anthropic"
+$env:LLM_FALLBACK_CHAIN = "anthropic,openai,gemini"
 ```
 
+After setting the variables, simply instantiate `ConfigurationManager()` as usual; no code changes are needed. The `spoon-cli` configuration workflow writes these variables for you whenever it loads `config.json`.
+
 ### Streaming Responses
 
 ```python
@@ -240,7 +255,7 @@ LLM_RETRY_ATTEMPTS=3
 ```python
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # uses environment variables by default
 
 # Configure providers
 config_manager.set_provider_config("openai", {
@@ -515,7 +530,7 @@ llm_manager.set_primary_provider("gemini")  # Generally faster
 ```python
 from spoon_ai.llm import ConfigurationManager
 
-config_manager = ConfigurationManager()
+config_manager = ConfigurationManager()  # refreshes from environment variables
 errors = config_manager.validate_config(your_config)
 for error in errors:
     print(f"Config error: {error}")
diff --git a/docs/core-concepts/agents-detailed.md b/docs/core-concepts/agents-detailed.md
@@ -154,7 +154,7 @@ class MyAgent(SpoonReactAI):
         self.max_steps = 10
 
         # Set up tools (if any)
-        self.avaliable_tools = ToolManager([])
+        self.available_tools = ToolManager([])
 ```
 
 ### 2. SpoonReactMCP
@@ -216,7 +216,7 @@ class WeatherAgent(SpoonReactAI):
 
         # Set up tools
         weather_tool = WeatherTool()
-        self.avaliable_tools = ToolManager([weather_tool])
+        self.available_tools = ToolManager([weather_tool])
 ```
 
 ### Advanced Agent with Multiple Tools
@@ -252,7 +252,7 @@ class ResearchAgent(SpoonReactAI):
             )
             tools.append(search_tool)
 
-        self.avaliable_tools = ToolManager(tools)
+        self.available_tools = ToolManager(tools)
         self.system_prompt = """
         You are a research assistant with access to web search tools.
 
@@ -367,8 +367,8 @@ agent.max_steps = 20
 agent.system_prompt = "You are an expert assistant."
 
 # Check available tools
-if hasattr(agent, 'avaliable_tools'):
-    tools = agent.avaliable_tools.list_tools()
+if hasattr(agent, 'available_tools'):
+    tools = agent.available_tools.list_tools()
     print(f"Available tools: {tools}")
 ```
 
@@ -407,7 +407,7 @@ class DataAnalysisAgent(ToolCallAgent):
             DatabaseTool(),    # Data access
         ]
 
-        self.avaliable_tools = ToolManager(tools)
+        self.available_tools = ToolManager(tools)
 ```
 
 ### 3. Error Handling
@@ -550,7 +550,7 @@ class MCPEnabledAgent(SpoonReactMCP):
         )
 
         # Create tool manager
-        self.avaliable_tools = ToolManager([search_tool, context7_tool])
+        self.available_tools = ToolManager([search_tool, context7_tool])
 
         self.system_prompt = """
         You are a research assistant with access to multiple MCP tools:
@@ -669,7 +669,7 @@ class ComprehensiveMCPAgent(SpoonReactMCP):
             ))
 
         # Create tool manager
-        self.avaliable_tools = ToolManager(mcp_tools)
+        self.available_tools = ToolManager(mcp_tools)
 
         self.system_prompt = """
         You are a comprehensive AI assistant with the following MCP tools:
diff --git a/docs/core-concepts/graph-system.md b/docs/core-concepts/graph-system.md
@@ -406,6 +406,90 @@ async def run_crypto_analysis(query: str) -> Dict[str, Any]:
 
 ---
 
+## Memory System Integration
+
+The graph runtime builds on the SpoonOS Memory System to persist context, metadata, and execution state across runs. Every compiled graph can attach a `Memory` store so routers, reducers, and agents reason over accumulated history without bespoke plumbing.
+
+### Overview
+
+- Persistent JSON-backed storage keyed by `session_id`
+- Chronological message history with metadata enrichment
+- Query helpers for search and time-based filtering
+- Automatic wiring inside `GraphAgent` and high-level APIs
+
+### Core Components
+
+```python
+from spoon_ai.graph.agent import Memory
+
+# Use default storage path (~/.spoon_ai/memory)
+default_memory = Memory()
+
+# Customize location and session isolation
+scoped_memory = Memory(storage_path="./custom_memory", session_id="my_session")
+```
+
+- **Persistent storage** keeps transcripts and state checkpoints on disk
+- **Session management** separates contexts per agent or user
+- **Metadata fields** let reducers store structured state
+- **Search helpers** (`search_messages`, `get_recent_messages`) surface relevant history
+
+### Basic Usage Patterns
+
+```python
+message = {"role": "user", "content": "Hello, how can I help?"}
+scoped_memory.add_message(message)
+
+all_messages = scoped_memory.get_messages()
+recent = scoped_memory.get_recent_messages(hours=24)
+metadata = scoped_memory.get_metadata("last_topic")
+```
+
+Use metadata to thread routing hints and conversation topics, and prune history with retention policies or manual cleanup (`memory.clear()`).
+
+### Graph Workflow Integration
+
+`GraphAgent` wires memory automatically and exposes statistics for monitoring:
+
+```python
+from spoon_ai.graph import GraphAgent, StateGraph
+
+agent = GraphAgent(
+    name="crypto_analyzer",
+    graph=my_graph,
+    memory_path="./agent_memory",
+    session_id="crypto_session"
+)
+
+result = await agent.run("Analyze BTC trends")
+stats = agent.get_memory_statistics()
+print(stats["total_messages"])
+```
+
+Switch between sessions to isolate experiments (`agent.load_session("research_session")`) or inject custom `Memory` subclasses for domain-specific validation.
+
+### Advanced Patterns
+
+- Call `memory.get_statistics()` to monitor file size, last update time, and record counts
+- Implement custom subclasses to enforce schemas or add enrichment hooks
+- Use time-window retrieval for reducers that need the most recent facts only
+- Build automated cleanup jobs for oversized stores (>10MB) to keep execution tight
+
+### Troubleshooting
+
+```python
+import json
+try:
+    with open(scoped_memory.session_file, "r") as fh:
+        json.load(fh)
+except json.JSONDecodeError:
+    scoped_memory.clear()  # Reset corrupted memory files
+```
+
+Conflicts typically trace back to duplicated session IDs—compose unique identifiers with timestamps or agent names to avoid contention.
+
+---
+
 ## Best Practices
 
 - **Use declarative templates**: `GraphTemplate` + `NodeSpec` for maintainable workflows
@@ -460,7 +544,8 @@ async def run_crypto_analysis(query: str) -> Dict[str, Any]:
 - **[MCP Protocol](../core-concepts/mcp-protocol.md)** - Explore dynamic tool discovery and execution
 
 ### 📖 **Additional Resources**
-
+- **[State Management](../api-reference/graph/state-graph.md)** - Reducer configuration guide
+- **[Agents Detailed](./agents-detailed.md)** - Long-lived agent design patterns
 - **[Graph Builder API](../api-reference/graph/)** - Complete declarative API documentation
 - **[Performance Optimization](../troubleshooting/performance.md)** - Graph performance tuning guides
 - **[Troubleshooting](../troubleshooting/common-issues.md)** - Common issues and solutions
diff --git a/docs/core-concepts/memory-system.md b/docs/core-concepts/memory-system.md
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
