chore: add specific return type hints to file_system_toolkits functions

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ruff check --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null; true"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/building-agents-construction/SKILL.md

@@ -520,6 +520,8 @@ class RuntimeConfig:
     model: str = "cerebras/zai-glm-4.7"
     temperature: float = 0.7
     max_tokens: int = 4096
+    api_key: str | None = None
+    api_base: str | None = None
 
 default_config = RuntimeConfig()
 
@@ -972,7 +974,11 @@ class {agent_class_name}:
         llm = None
         if not mock_mode:
             # LiteLLMProvider uses environment variables for API keys
-            llm = LiteLLMProvider(model=self.config.model)
+            llm = LiteLLMProvider(
+                model=self.config.model,
+                api_key=self.config.api_key,
+                api_base=self.config.api_base,
+            )
 
         self._graph = GraphSpec(
             id="{agent_name}-graph",

.claude/skills/building-agents-construction/examples/online_research_agent/__main__.py

@@ -108,8 +108,10 @@ async def _interactive_shell(verbose=False):
     try:
         while True:
             try:
-                topic = await asyncio.get_event_loop().run_in_executor(None, input, "Topic> ")
-                if topic.lower() in ['quit', 'exit', 'q']:
+                topic = await asyncio.get_event_loop().run_in_executor(
+                    None, input, "Topic> "
+                )
+                if topic.lower() in ["quit", "exit", "q"]:
                     click.echo("Goodbye!")
                     break
 
@@ -130,7 +132,11 @@ async def _interactive_shell(verbose=False):
                         click.echo(f"\nReport saved to: {output['file_path']}\n")
                     if "final_report" in output:
                         click.echo("\n--- Report Preview ---\n")
-                        preview = output["final_report"][:500] + "..." if len(output.get("final_report", "")) > 500 else output.get("final_report", "")
+                        preview = (
+                            output["final_report"][:500] + "..."
+                            if len(output.get("final_report", "")) > 500
+                            else output.get("final_report", "")
+                        )
                         click.echo(preview)
                         click.echo("\n")
                 else:
@@ -142,6 +148,7 @@ async def _interactive_shell(verbose=False):
             except Exception as e:
                 click.echo(f"Error: {e}", err=True)
                 import traceback
+
                 traceback.print_exc()
     finally:
         await agent.stop()

.claude/skills/building-agents-construction/examples/online_research_agent/agent.py

@@ -1,4 +1,5 @@
 """Agent graph construction for Online Research Agent."""
+
 from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
 from framework.graph.edge import GraphSpec
 from framework.graph.executor import ExecutionResult
@@ -8,6 +9,16 @@
 from framework.runner.tool_registry import ToolRegistry
 
 from .config import default_config, metadata
+from .nodes import (
+    parse_query_node,
+    search_sources_node,
+    fetch_content_node,
+    evaluate_sources_node,
+    synthesize_findings_node,
+    write_report_node,
+    quality_check_node,
+    save_report_node,
+)
 
 # Goal definition
 goal = Goal(
@@ -78,17 +89,6 @@
         ),
     ],
 )
-# Import nodes
-from .nodes import (
-    parse_query_node,
-    search_sources_node,
-    fetch_content_node,
-    evaluate_sources_node,
-    synthesize_findings_node,
-    write_report_node,
-    quality_check_node,
-    save_report_node,
-)
 
 # Node list
 nodes = [
@@ -195,13 +195,15 @@ def _build_entry_point_specs(self) -> list[EntryPointSpec]:
                 trigger_type = "manual"
                 name = ep_id.replace("-", " ").title()
 
-            specs.append(EntryPointSpec(
-                id=ep_id,
-                name=name,
-                entry_node=node_id,
-                trigger_type=trigger_type,
-                isolation_level="shared",
-            ))
+            specs.append(
+                EntryPointSpec(
+                    id=ep_id,
+                    name=name,
+                    entry_node=node_id,
+                    trigger_type=trigger_type,
+                    isolation_level="shared",
+                )
+            )
         return specs
 
     def _create_runtime(self, mock_mode=False) -> AgentRuntime:
@@ -226,14 +228,21 @@ def _create_runtime(self, mock_mode=False) -> AgentRuntime:
             for server_name, server_config in mcp_servers.items():
                 server_config["name"] = server_name
                 # Resolve relative cwd paths
-                if "cwd" in server_config and not Path(server_config["cwd"]).is_absolute():
+                if (
+                    "cwd" in server_config
+                    and not Path(server_config["cwd"]).is_absolute()
+                ):
                     server_config["cwd"] = str(agent_dir / server_config["cwd"])
                 tool_registry.register_mcp_server(server_config)
 
         llm = None
         if not mock_mode:
             # LiteLLMProvider uses environment variables for API keys
-            llm = LiteLLMProvider(model=self.config.model)
+            llm = LiteLLMProvider(
+                model=self.config.model,
+                api_key=self.config.api_key,
+                api_base=self.config.api_base,
+            )
 
         self._graph = GraphSpec(
             id="online-research-agent-graph",
@@ -294,7 +303,9 @@ async def trigger(
         """
         if self._runtime is None or not self._runtime.is_running:
             raise RuntimeError("Agent runtime not started. Call start() first.")
-        return await self._runtime.trigger(entry_point, input_data, correlation_id, session_state=session_state)
+        return await self._runtime.trigger(
+            entry_point, input_data, correlation_id, session_state=session_state
+        )
 
     async def trigger_and_wait(
         self,
@@ -317,9 +328,13 @@ async def trigger_and_wait(
         """
         if self._runtime is None or not self._runtime.is_running:
             raise RuntimeError("Agent runtime not started. Call start() first.")
-        return await self._runtime.trigger_and_wait(entry_point, input_data, timeout, session_state=session_state)
+        return await self._runtime.trigger_and_wait(
+            entry_point, input_data, timeout, session_state=session_state
+        )
 
-    async def run(self, context: dict, mock_mode=False, session_state=None) -> ExecutionResult:
+    async def run(
+        self, context: dict, mock_mode=False, session_state=None
+    ) -> ExecutionResult:
         """
         Run the agent (convenience method for simple single execution).
 
@@ -338,7 +353,9 @@ async def run(self, context: dict, mock_mode=False, session_state=None) -> Execu
             else:
                 entry_point = "start"
 
-            result = await self.trigger_and_wait(entry_point, context, session_state=session_state)
+            result = await self.trigger_and_wait(
+                entry_point, context, session_state=session_state
+            )
             return result or ExecutionResult(success=False, error="Execution timeout")
         finally:
             await self.stop()
@@ -400,7 +417,9 @@ def validate(self):
         # Validate entry points
         for ep_id, node_id in self.entry_points.items():
             if node_id not in node_ids:
-                errors.append(f"Entry point '{ep_id}' references unknown node '{node_id}'")
+                errors.append(
+                    f"Entry point '{ep_id}' references unknown node '{node_id}'"
+                )
 
         return {
             "valid": len(errors) == 0,

.claude/skills/building-agents-construction/examples/online_research_agent/config.py

@@ -1,4 +1,5 @@
 """Runtime configuration."""
+
 from dataclasses import dataclass
 
 
@@ -7,10 +8,13 @@ class RuntimeConfig:
     model: str = "groq/moonshotai/kimi-k2-instruct-0905"
     temperature: float = 0.7
     max_tokens: int = 16384
+    api_key: str | None = None
+    api_base: str | None = None
 
 
 default_config = RuntimeConfig()
 
+
 # Agent metadata
 @dataclass
 class AgentMetadata: