chore: update API docs from spoon-ai-sdk

Author: actions-user

docs/api-reference/index.md

@@ -2,4 +2,115 @@
 
 Generated from spoon_ai sources. Each module below has its own page.
 
-- [spoon_ai](./spoon_ai.md)
+- [spoon_ai](./spoon_ai/)
+- [spoon_ai.agents](./spoon_ai/agents/)
+- [spoon_ai.agents.base](./spoon_ai/agents/base.md)
+- [spoon_ai.agents.custom_agent](./spoon_ai/agents/custom_agent.md)
+- [spoon_ai.agents.graph_agent](./spoon_ai/agents/graph_agent.md)
+- [spoon_ai.agents.mcp_client_mixin](./spoon_ai/agents/mcp_client_mixin.md)
+- [spoon_ai.agents.monitor](./spoon_ai/agents/monitor.md)
+- [spoon_ai.agents.rag](./spoon_ai/agents/rag.md)
+- [spoon_ai.agents.react](./spoon_ai/agents/react.md)
+- [spoon_ai.agents.spoon_react](./spoon_ai/agents/spoon_react.md)
+- [spoon_ai.agents.spoon_react_mcp](./spoon_ai/agents/spoon_react_mcp.md)
+- [spoon_ai.agents.toolcall](./spoon_ai/agents/toolcall.md)
+- [spoon_ai.bridge](./spoon_ai/bridge/)
+- [spoon_ai.bridge.eth_neofs_indexer](./spoon_ai/bridge/eth_neofs_indexer.md)
+- [spoon_ai.callbacks](./spoon_ai/callbacks/)
+- [spoon_ai.callbacks.base](./spoon_ai/callbacks/base.md)
+- [spoon_ai.callbacks.manager](./spoon_ai/callbacks/manager.md)
+- [spoon_ai.callbacks.statistics](./spoon_ai/callbacks/statistics.md)
+- [spoon_ai.callbacks.stream_event](./spoon_ai/callbacks/stream_event.md)
+- [spoon_ai.callbacks.streaming_stdout](./spoon_ai/callbacks/streaming_stdout.md)
+- [spoon_ai.chat](./spoon_ai/chat.md)
+- [spoon_ai.graph](./spoon_ai/graph/)
+- [spoon_ai.graph.agent](./spoon_ai/graph/agent.md)
+- [spoon_ai.graph.builder](./spoon_ai/graph/builder.md)
+- [spoon_ai.graph.checkpointer](./spoon_ai/graph/checkpointer.md)
+- [spoon_ai.graph.config](./spoon_ai/graph/config.md)
+- [spoon_ai.graph.decorators](./spoon_ai/graph/decorators.md)
+- [spoon_ai.graph.engine](./spoon_ai/graph/engine.md)
+- [spoon_ai.graph.exceptions](./spoon_ai/graph/exceptions.md)
+- [spoon_ai.graph.mcp_integration](./spoon_ai/graph/mcp_integration.md)
+- [spoon_ai.graph.reducers](./spoon_ai/graph/reducers.md)
+- [spoon_ai.graph.types](./spoon_ai/graph/types.md)
+- [spoon_ai.identity](./spoon_ai/identity/)
+- [spoon_ai.identity.attestation](./spoon_ai/identity/attestation.md)
+- [spoon_ai.identity.did_models](./spoon_ai/identity/did_models.md)
+- [spoon_ai.identity.did_resolver](./spoon_ai/identity/did_resolver.md)
+- [spoon_ai.identity.erc8004_abi](./spoon_ai/identity/erc8004_abi.md)
+- [spoon_ai.identity.erc8004_client](./spoon_ai/identity/erc8004_client.md)
+- [spoon_ai.identity.storage_client](./spoon_ai/identity/storage_client.md)
+- [spoon_ai.llm](./spoon_ai/llm/)
+- [spoon_ai.llm.base](./spoon_ai/llm/base.md)
+- [spoon_ai.llm.cache](./spoon_ai/llm/cache.md)
+- [spoon_ai.llm.config](./spoon_ai/llm/config.md)
+- [spoon_ai.llm.errors](./spoon_ai/llm/errors.md)
+- [spoon_ai.llm.factory](./spoon_ai/llm/factory.md)
+- [spoon_ai.llm.interface](./spoon_ai/llm/interface.md)
+- [spoon_ai.llm.manager](./spoon_ai/llm/manager.md)
+- [spoon_ai.llm.monitoring](./spoon_ai/llm/monitoring.md)
+- [spoon_ai.llm.providers](./spoon_ai/llm/providers/)
+- [spoon_ai.llm.providers.anthropic_provider](./spoon_ai/llm/providers/anthropic_provider.md)
+- [spoon_ai.llm.providers.deepseek_provider](./spoon_ai/llm/providers/deepseek_provider.md)
+- [spoon_ai.llm.providers.gemini_provider](./spoon_ai/llm/providers/gemini_provider.md)
+- [spoon_ai.llm.providers.ollama_provider](./spoon_ai/llm/providers/ollama_provider.md)
+- [spoon_ai.llm.providers.openai_compatible_provider](./spoon_ai/llm/providers/openai_compatible_provider.md)
+- [spoon_ai.llm.providers.openai_provider](./spoon_ai/llm/providers/openai_provider.md)
+- [spoon_ai.llm.providers.openrouter_provider](./spoon_ai/llm/providers/openrouter_provider.md)
+- [spoon_ai.llm.registry](./spoon_ai/llm/registry.md)
+- [spoon_ai.llm.response_normalizer](./spoon_ai/llm/response_normalizer.md)
+- [spoon_ai.memory](./spoon_ai/memory/)
+- [spoon_ai.memory.mem0_client](./spoon_ai/memory/mem0_client.md)
+- [spoon_ai.memory.remove_message](./spoon_ai/memory/remove_message.md)
+- [spoon_ai.memory.short_term_manager](./spoon_ai/memory/short_term_manager.md)
+- [spoon_ai.memory.utils](./spoon_ai/memory/utils.md)
+- [spoon_ai.neofs](./spoon_ai/neofs/)
+- [spoon_ai.neofs.client](./spoon_ai/neofs/client.md)
+- [spoon_ai.neofs.models](./spoon_ai/neofs/models.md)
+- [spoon_ai.neofs.utils](./spoon_ai/neofs/utils.md)
+- [spoon_ai.payments](./spoon_ai/payments/)
+- [spoon_ai.payments.app](./spoon_ai/payments/app.md)
+- [spoon_ai.payments.cli](./spoon_ai/payments/cli.md)
+- [spoon_ai.payments.config](./spoon_ai/payments/config.md)
+- [spoon_ai.payments.exceptions](./spoon_ai/payments/exceptions.md)
+- [spoon_ai.payments.facilitator_client](./spoon_ai/payments/facilitator_client.md)
+- [spoon_ai.payments.models](./spoon_ai/payments/models.md)
+- [spoon_ai.payments.server](./spoon_ai/payments/server.md)
+- [spoon_ai.payments.x402_service](./spoon_ai/payments/x402_service.md)
+- [spoon_ai.prompts](./spoon_ai/prompts/)
+- [spoon_ai.prompts.spoon_react](./spoon_ai/prompts/spoon_react.md)
+- [spoon_ai.prompts.toolcall](./spoon_ai/prompts/toolcall.md)
+- [spoon_ai.rag](./spoon_ai/rag/)
+- [spoon_ai.rag.config](./spoon_ai/rag/config.md)
+- [spoon_ai.rag.embeddings](./spoon_ai/rag/embeddings.md)
+- [spoon_ai.rag.index](./spoon_ai/rag/index.md)
+- [spoon_ai.rag.loader](./spoon_ai/rag/loader.md)
+- [spoon_ai.rag.qa](./spoon_ai/rag/qa.md)
+- [spoon_ai.rag.retriever](./spoon_ai/rag/retriever.md)
+- [spoon_ai.rag.vectorstores](./spoon_ai/rag/vectorstores/)
+- [spoon_ai.rag.vectorstores.base](./spoon_ai/rag/vectorstores/base.md)
+- [spoon_ai.rag.vectorstores.chroma_store](./spoon_ai/rag/vectorstores/chroma_store.md)
+- [spoon_ai.rag.vectorstores.faiss_store](./spoon_ai/rag/vectorstores/faiss_store.md)
+- [spoon_ai.rag.vectorstores.pinecone_store](./spoon_ai/rag/vectorstores/pinecone_store.md)
+- [spoon_ai.rag.vectorstores.qdrant_store](./spoon_ai/rag/vectorstores/qdrant_store.md)
+- [spoon_ai.rag.vectorstores.registry](./spoon_ai/rag/vectorstores/registry.md)
+- [spoon_ai.runnables](./spoon_ai/runnables/)
+- [spoon_ai.runnables.base](./spoon_ai/runnables/base.md)
+- [spoon_ai.runnables.events](./spoon_ai/runnables/events.md)
+- [spoon_ai.schema](./spoon_ai/schema.md)
+- [spoon_ai.tools](./spoon_ai/tools/)
+- [spoon_ai.tools.base](./spoon_ai/tools/base.md)
+- [spoon_ai.tools.mcp_tool](./spoon_ai/tools/mcp_tool.md)
+- [spoon_ai.tools.neofs_tools](./spoon_ai/tools/neofs_tools.md)
+- [spoon_ai.tools.rag_tools](./spoon_ai/tools/rag_tools.md)
+- [spoon_ai.tools.tool_manager](./spoon_ai/tools/tool_manager.md)
+- [spoon_ai.tools.turnkey_tools](./spoon_ai/tools/turnkey_tools.md)
+- [spoon_ai.tools.x402_payment](./spoon_ai/tools/x402_payment.md)
+- [spoon_ai.turnkey](./spoon_ai/turnkey/)
+- [spoon_ai.turnkey.client](./spoon_ai/turnkey/client.md)
+- [spoon_ai.utils](./spoon_ai/utils/)
+- [spoon_ai.utils.config](./spoon_ai/utils/config.md)
+- [spoon_ai.utils.config_manager](./spoon_ai/utils/config_manager.md)
+- [spoon_ai.utils.streaming](./spoon_ai/utils/streaming.md)
+- [spoon_ai.utils.utils](./spoon_ai/utils/utils.md)

docs/api-reference/spoon_ai/agents/base.md

@@ -0,0 +1,198 @@
+---
+id: spoon_ai.agents.base
+slug: /api-reference/spoon_ai/agents/base
+title: spoon_ai.agents.base
+---
+
+# Table of Contents
+
+* [spoon\_ai.agents.base](#spoon_ai.agents.base)
+  * [ThreadSafeOutputQueue](#spoon_ai.agents.base.ThreadSafeOutputQueue)
+    * [get](#spoon_ai.agents.base.ThreadSafeOutputQueue.get)
+  * [BaseAgent](#spoon_ai.agents.base.BaseAgent)
+    * [add\_message](#spoon_ai.agents.base.BaseAgent.add_message)
+    * [state\_context](#spoon_ai.agents.base.BaseAgent.state_context)
+    * [run](#spoon_ai.agents.base.BaseAgent.run)
+    * [step](#spoon_ai.agents.base.BaseAgent.step)
+    * [is\_stuck](#spoon_ai.agents.base.BaseAgent.is_stuck)
+    * [handle\_stuck\_state](#spoon_ai.agents.base.BaseAgent.handle_stuck_state)
+    * [add\_documents](#spoon_ai.agents.base.BaseAgent.add_documents)
+    * [save\_chat\_history](#spoon_ai.agents.base.BaseAgent.save_chat_history)
+    * [stream](#spoon_ai.agents.base.BaseAgent.stream)
+    * [process\_mcp\_message](#spoon_ai.agents.base.BaseAgent.process_mcp_message)
+    * [shutdown](#spoon_ai.agents.base.BaseAgent.shutdown)
+    * [get\_diagnostics](#spoon_ai.agents.base.BaseAgent.get_diagnostics)
+
+<a id="spoon_ai.agents.base"></a>
+
+# Module `spoon_ai.agents.base`
+
+<a id="spoon_ai.agents.base.ThreadSafeOutputQueue"></a>
+
+## `ThreadSafeOutputQueue` Objects
+
+```python
+class ThreadSafeOutputQueue()
+```
+
+Thread-safe output queue with fair access and timeout protection
+
+<a id="spoon_ai.agents.base.ThreadSafeOutputQueue.get"></a>
+
+#### `get`
+
+```python
+async def get(timeout: Optional[float] = 30.0) -> Any
+```
+
+Get item with timeout and fair access
+
+<a id="spoon_ai.agents.base.BaseAgent"></a>
+
+## `BaseAgent` Objects
+
+```python
+class BaseAgent(BaseModel, ABC)
+```
+
+Thread-safe base class for all agents with proper concurrency handling.
+
+<a id="spoon_ai.agents.base.BaseAgent.add_message"></a>
+
+#### `add_message`
+
+```python
+async def add_message(role: Literal["user", "assistant", "tool"],
+                      content: str,
+                      tool_call_id: Optional[str] = None,
+                      tool_calls: Optional[List[ToolCall]] = None,
+                      tool_name: Optional[str] = None,
+                      timeout: Optional[float] = None) -> None
+```
+
+Thread-safe message addition with timeout protection
+
+<a id="spoon_ai.agents.base.BaseAgent.state_context"></a>
+
+#### `state_context`
+
+```python
+@asynccontextmanager
+async def state_context(new_state: AgentState,
+                        timeout: Optional[float] = None)
+```
+
+Thread-safe state context manager with deadlock prevention.
+Acquires the state lock only to perform quick transitions, not for the
+duration of the work inside the context, avoiding long-held locks and
+false timeouts during network calls.
+
+<a id="spoon_ai.agents.base.BaseAgent.run"></a>
+
+#### `run`
+
+```python
+async def run(request: Optional[str] = None,
+              timeout: Optional[float] = None) -> str
+```
+
+Thread-safe run method with proper concurrency control and callback support.
+
+<a id="spoon_ai.agents.base.BaseAgent.step"></a>
+
+#### `step`
+
+```python
+async def step(run_id: Optional[uuid.UUID] = None) -> str
+```
+
+Override this method in subclasses - now with step-level locking and callback support.
+
+<a id="spoon_ai.agents.base.BaseAgent.is_stuck"></a>
+
+#### `is_stuck`
+
+```python
+async def is_stuck() -> bool
+```
+
+Thread-safe stuck detection
+
+<a id="spoon_ai.agents.base.BaseAgent.handle_stuck_state"></a>
+
+#### `handle_stuck_state`
+
+```python
+async def handle_stuck_state()
+```
+
+Thread-safe stuck state handling
+
+<a id="spoon_ai.agents.base.BaseAgent.add_documents"></a>
+
+#### `add_documents`
+
+```python
+def add_documents(documents) -> None
+```
+
+Store documents on the agent so CLI load-docs works without RAG mixin.
+
+This default implementation keeps the documents in-memory under
+self._loaded_documents. Agents that support retrieval should override
+this method to index documents into their vector store.
+
+<a id="spoon_ai.agents.base.BaseAgent.save_chat_history"></a>
+
+#### `save_chat_history`
+
+```python
+def save_chat_history()
+```
+
+Thread-safe chat history saving
+
+<a id="spoon_ai.agents.base.BaseAgent.stream"></a>
+
+#### `stream`
+
+```python
+async def stream(timeout: Optional[float] = None)
+```
+
+Thread-safe streaming with proper cleanup and timeout
+
+<a id="spoon_ai.agents.base.BaseAgent.process_mcp_message"></a>
+
+#### `process_mcp_message`
+
+```python
+async def process_mcp_message(content: Any,
+                              sender: str,
+                              message: Dict[str, Any],
+                              agent_id: str,
+                              timeout: Optional[float] = None)
+```
+
+Thread-safe MCP message processing with timeout protection
+
+<a id="spoon_ai.agents.base.BaseAgent.shutdown"></a>
+
+#### `shutdown`
+
+```python
+async def shutdown(timeout: float = 30.0)
+```
+
+Graceful shutdown with cleanup of active operations
+
+<a id="spoon_ai.agents.base.BaseAgent.get_diagnostics"></a>
+
+#### `get_diagnostics`
+
+```python
+def get_diagnostics() -> Dict[str, Any]
+```
+
+Get diagnostic information about the agent's state
+