robot_lab 0.0.1 → 0.0.4

data/docs/api/history/thread-manager.md

@@ -1,139 +1,189 @@
-# ThreadManager
+# History::ThreadManager
 
-Manages conversation thread lifecycle.
+Manages conversation thread lifecycle using a `History::Config` for persistence.
 
 ## Class: `RobotLab::History::ThreadManager`
 
 ```ruby
-manager = History::ThreadManager.new(config: history_config)
+config = RobotLab::History::Config.new(...)
+manager = RobotLab::History::ThreadManager.new(config)
+
+session_id = manager.create_thread(state: memory, input: "Hello")
+history = manager.get_history(session_id)
 ```
 
 ## Constructor
 
 ```ruby
-ThreadManager.new(config:)
+ThreadManager.new(config)
 ```
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `config` | `Config` | History configuration |
+| `config` | `Config` | History configuration with persistence callbacks |
+
+## Attributes
+
+### config
+
+```ruby
+manager.config  # => RobotLab::History::Config
+```
+
+The history configuration object.
 
 ## Methods
 
 ### create_thread
 
 ```ruby
-thread_info = manager.create_thread(state: state, input: input, **context)
+session_id = manager.create_thread(state:, input:)
 ```
 
-Create a new conversation thread.
+Create a new conversation thread. Delegates to `config.create_thread!` and returns the `session_id` from the result hash.
 
-**Returns:** Hash with `:id` and optional metadata.
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `state` | `Object` | Current robot memory or state |
+| `input` | `String`, `UserMessage` | Initial user input |
+
+**Returns:** `String` -- the session ID for the new thread.
 
 ### get_history
 
 ```ruby
-results = manager.get_history(thread_id: id, **context)
+results = manager.get_history(session_id)
 ```
 
-Retrieve conversation history.
+Retrieve conversation history for a thread. Delegates to `config.get!`.
+
+**Parameters:**
 
-**Returns:** Array of `RobotResult`.
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Thread identifier |
+
+**Returns:** `Array<RobotResult>` -- history of results for the thread.
+
+### append_user_message
+
+```ruby
+manager.append_user_message(session_id:, message:)
+```
+
+Append a user message to the thread. Delegates to `config.append_user_message!`.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Thread identifier |
+| `message` | `UserMessage` | User message to append |
 
 ### append_results
 
 ```ruby
-manager.append_results(thread_id: id, new_results: results, **context)
+manager.append_results(session_id:, results:)
 ```
 
-Add results to a thread.
+Append robot results to the thread. Delegates to `config.append_results!`.
 
-### ensure_thread
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Thread identifier |
+| `results` | `Array<RobotResult>` | Results to append |
+
+### load_state
 
 ```ruby
-thread_id = manager.ensure_thread(state: state, input: input, **context)
+state = manager.load_state(session_id:, state:)
 ```
 
-Create thread if state doesn't have one, or return existing.
+Load history from a thread into a state/memory object. Retrieves the history, sets the `session_id` on the state, and calls `append_result` for each historical result.
 
-### load_history
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Thread identifier |
+| `state` | `Object` | State or Memory object to populate |
+
+**Returns:** The state object with loaded history.
+
+### save_state
 
 ```ruby
-state = manager.load_history(state: state, **context)
+manager.save_state(session_id:, state:, since_index: 0)
 ```
 
-Load history into state if thread_id exists.
+Save new results from a state object to the thread. Extracts results from `state.results` starting at `since_index` and appends them.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Thread identifier |
+| `state` | `Object` | State object with results |
+| `since_index` | `Integer` | Save results from this index (default: 0) |
 
 ## Examples
 
 ### Basic Usage
 
 ```ruby
-config = History::Config.new(...)
-manager = History::ThreadManager.new(config: config)
-
-# Start new conversation
-state = RobotLab.create_state(message: "Hello")
-thread_id = manager.ensure_thread(state: state, input: "Hello")
-state.thread_id = thread_id
-
-# Run and save
-result = network.run(state: state)
-manager.append_results(thread_id: thread_id, new_results: result.new_results)
-
-# Continue conversation
-state2 = RobotLab.create_state(message: "Follow up")
-state2.thread_id = thread_id
-state2 = manager.load_history(state: state2)
-# state2 now has previous results
+config = RobotLab::History::Config.new(
+  create_thread: ->(state:, input:, **) { { session_id: SecureRandom.uuid } },
+  get: ->(session_id:, **) { STORE[session_id] || [] },
+  append_results: ->(session_id:, new_results:, **) {
+    STORE[session_id] ||= []
+    STORE[session_id].concat(new_results)
+  }
+)
+
+manager = RobotLab::History::ThreadManager.new(config)
+
+# Start a new conversation
+session_id = manager.create_thread(state: memory, input: "Hello")
+
+# Run a robot and save results
+result = robot.run("Hello")
+manager.append_results(session_id: session_id, results: [result])
+
+# Later, retrieve history
+history = manager.get_history(session_id)
 ```
 
-### In Network
+### Loading History into Memory
 
 ```ruby
-# ThreadManager is used internally by Network
-network = RobotLab.create_network do
-  history config
-  add_robot assistant
-end
-
-# First message - thread created automatically
-result1 = network.run(state: state1)
-thread_id = result1.state.thread_id
-
-# Continue - history loaded automatically
-state2 = RobotLab.create_state(
-  message: UserMessage.new("Continue", thread_id: thread_id)
-)
-result2 = network.run(state: state2)
+manager = RobotLab::History::ThreadManager.new(config)
+
+# Create a memory object and load previous conversation
+memory = RobotLab::Memory.new
+manager.load_state(session_id: existing_session_id, state: memory)
+
+# Memory now contains previous results and session_id
 ```
 
-### Custom Thread Data
+### Saving Incremental Results
 
 ```ruby
-manager = History::ThreadManager.new(
-  config: History::Config.new(
-    create_thread: ->(state:, input:, metadata:, **) {
-      Thread.create(
-        title: input.truncate(50),
-        metadata: metadata,
-        created_at: Time.current
-      )
-    },
-    get: ->(thread_id:, **) { Thread.find(thread_id).results },
-    append_results: ->(thread_id:, new_results:, **) {
-      Thread.find(thread_id).results.concat(new_results)
-    }
-  )
-)
+# Save only new results (since the last save point)
+initial_count = memory.results.length
+
+result = robot.run("Follow-up question")
+memory.append_result(result)
 
-# Pass metadata when creating thread
-thread = manager.create_thread(
-  state: state,
-  input: "Help with billing",
-  metadata: { source: "web", priority: "high" }
+manager.save_state(
+  session_id: session_id,
+  state: memory,
+  since_index: initial_count
 )
 ```
 

data/docs/api/mcp/client.md

@@ -1,49 +1,53 @@
 # MCP Client
 
-Connects to MCP servers and discovers tools.
+Connects to MCP servers, discovers tools, and invokes them via the Model Context Protocol.
 
 ## Class: `RobotLab::MCP::Client`
 
 ```ruby
 client = RobotLab::MCP::Client.new(
   name: "filesystem",
-  transport: { type: "stdio", command: "mcp-server-filesystem" }
+  transport: { type: "stdio", command: "mcp-server-filesystem", args: ["--root", "/data"] }
 )
 
 client.connect
 tools = client.list_tools
+result = client.call_tool("readFile", { path: "/data/readme.txt" })
+client.disconnect
 ```
 
 ## Constructor
 
 ```ruby
-Client.new(name:, transport:)
+Client.new(server_or_config)
 ```
 
+Accepts either a `Server` instance or a Hash configuration. When a Hash is provided, it is used to construct a `Server` internally.
+
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `name` | `String` | Server identifier |
-| `transport` | `Hash` | Transport configuration |
+| `server_or_config` | `Server`, `Hash` | Server instance or configuration hash |
 
-## Attributes
+**Hash Configuration Keys:**
 
-### name
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `name` | `String` | Yes | Server identifier |
+| `transport` | `Hash` | Yes | Transport configuration (must include `type`) |
 
-```ruby
-client.name  # => String
-```
+**Raises:** `ArgumentError` if the config is neither a `Server` nor a `Hash`.
 
-Server identifier.
+## Attributes
 
-### transport
+### server
 
 ```ruby
-client.transport  # => Transport
+client.server  # => RobotLab::MCP::Server
 ```
 
-The underlying transport connection.
+The MCP server configuration object.
 
 ### connected?
 
@@ -51,38 +55,42 @@ The underlying transport connection.
 client.connected?  # => Boolean
 ```
 
-Whether the client is connected.
+Whether the client is currently connected to the server.
 
 ## Methods
 
 ### connect
 
 ```ruby
-client.connect
+client.connect  # => self
 ```
 
-Establish connection to the MCP server.
+Establish a connection to the MCP server. Creates the appropriate transport based on the server's transport type, then connects. If already connected, returns immediately.
+
+Connection failures are logged as warnings and the client remains in a disconnected state (does not raise).
 
 ### disconnect
 
 ```ruby
-client.disconnect
+client.disconnect  # => self
 ```
 
-Close the connection.
+Close the connection to the MCP server. Closes the underlying transport and resets connection state. If not connected, returns immediately.
 
 ### list_tools
 
 ```ruby
-client.list_tools  # => Array<Tool>
+client.list_tools  # => Array<Hash>
 ```
 
-Discover available tools from the server.
+Discover available tools from the server. Returns an array of tool definition hashes.
+
+**Raises:** `MCPError` if not connected.
 
 ### call_tool
 
 ```ruby
-result = client.call_tool(name, params)
+result = client.call_tool(name, arguments = {})
 ```
 
 Execute a tool on the server.
@@ -92,30 +100,81 @@ Execute a tool on the server.
 | Name | Type | Description |
 |------|------|-------------|
 | `name` | `String` | Tool name |
-| `params` | `Hash` | Tool parameters |
+| `arguments` | `Hash` | Tool arguments (default: `{}`) |
+
+**Returns:** Tool result content (from the `content` field of the response).
+
+**Raises:** `MCPError` if not connected.
 
 ### list_resources
 
 ```ruby
-client.list_resources  # => Array<Resource>
+client.list_resources  # => Array<Hash>
 ```
 
-List available resources (if supported).
+List available resources from the server.
+
+**Raises:** `MCPError` if not connected.
 
 ### read_resource
 
 ```ruby
-client.read_resource(uri)  # => Resource
+client.read_resource(uri)  # => Object
 ```
 
 Read a resource by URI.
 
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `uri` | `String` | Resource URI |
+
+**Raises:** `MCPError` if not connected.
+
+### list_prompts
+
+```ruby
+client.list_prompts  # => Array<Hash>
+```
+
+List available prompts from the server.
+
+**Raises:** `MCPError` if not connected.
+
+### get_prompt
+
+```ruby
+client.get_prompt(name, arguments = {})  # => Hash
+```
+
+Get a prompt by name with optional arguments.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Prompt name |
+| `arguments` | `Hash` | Prompt arguments (default: `{}`) |
+
+**Raises:** `MCPError` if not connected.
+
+### to_h
+
+```ruby
+client.to_h  # => Hash
+```
+
+Converts the client to a hash representation containing server config and connection status.
+
 ## Transport Configuration
 
+The transport type is determined by the `type` key in the transport hash of the `Server` configuration.
+
 ### Stdio
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "local",
   transport: {
     type: "stdio",
@@ -128,10 +187,10 @@ client = Client.new(
 ### WebSocket
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "remote",
   transport: {
-    type: "websocket",
+    type: "ws",
     url: "wss://mcp.example.com/ws"
   }
 )
@@ -140,7 +199,7 @@ client = Client.new(
 ### SSE
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "streaming",
   transport: {
     type: "sse",
@@ -149,14 +208,15 @@ client = Client.new(
 )
 ```
 
-### HTTP
+### Streamable HTTP
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "http",
   transport: {
-    type: "http",
-    url: "https://mcp.example.com/mcp"
+    type: "streamable-http",
+    url: "https://mcp.example.com/mcp",
+    session_id: "optional-session-id"
   }
 )
 ```
@@ -166,7 +226,7 @@ client = Client.new(
 ### Basic Usage
 
 ```ruby
-client = Client.new(
+client = RobotLab::MCP::Client.new(
   name: "github",
   transport: { type: "stdio", command: "mcp-server-github" }
 )
@@ -175,7 +235,7 @@ client.connect
 
 # List available tools
 tools = client.list_tools
-tools.each { |t| puts "#{t.name}: #{t.description}" }
+tools.each { |t| puts "#{t[:name]}: #{t[:description]}" }
 
 # Call a tool
 result = client.call_tool("search_repositories", { query: "ruby mcp" })
@@ -184,19 +244,32 @@ puts result
 client.disconnect
 ```
 
-### In Robot
+### From a Server Object
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
+server = RobotLab::MCP::Server.new(
+  name: "neon",
+  transport: { type: "ws", url: "ws://localhost:8080" }
+)
 
-  mcp [
+client = RobotLab::MCP::Client.new(server)
+client.connect
+```
+
+### In a Robot
+
+```ruby
+robot = Robot.new(
+  name: "assistant",
+  system_prompt: "You help with file operations.",
+  mcp: [
     { name: "fs", transport: { type: "stdio", command: "mcp-fs" } }
   ]
-end
+)
 
-# MCP tools are automatically available
-robot.tools.each { |t| puts t.name }
+# MCP tools are automatically discovered and available to the LLM
+result = robot.run("Read the contents of /data/config.yml")
+puts result.last_text_content
 ```
 
 ### Error Handling
@@ -205,10 +278,8 @@ robot.tools.each { |t| puts t.name }
 begin
   client.connect
   result = client.call_tool("unknown_tool", {})
-rescue RobotLab::MCP::ConnectionError => e
-  puts "Failed to connect: #{e.message}"
-rescue RobotLab::MCP::ToolError => e
-  puts "Tool error: #{e.message}"
+rescue RobotLab::MCPError => e
+  puts "MCP error: #{e.message}"
 ensure
   client.disconnect
 end
@@ -217,5 +288,5 @@ end
 ## See Also
 
 - [MCP Overview](index.md)
+- [Server Configuration](server.md)
 - [Transports](transports.md)
-- [MCP Server](server.md)