robot_lab 0.0.1

data/docs/api/core/state.md

@@ -0,0 +1,273 @@
+# State
+
+Manages conversation data, results, and memory.
+
+## Class: `RobotLab::State`
+
+```ruby
+state = RobotLab.create_state(
+  message: "Hello",
+  data: { user_id: "123" }
+)
+```
+
+## Attributes
+
+### thread_id
+
+```ruby
+state.thread_id  # => String | nil
+```
+
+Conversation thread identifier for persistence.
+
+### memory
+
+```ruby
+state.memory  # => Memory
+```
+
+Shared key-value store.
+
+## Methods
+
+### data
+
+```ruby
+state.data  # => StateProxy
+```
+
+Access workflow data as a proxy object.
+
+```ruby
+state.data[:user_id]          # Hash access
+state.data.user_id            # Method access
+state.data[:status] = "active"
+```
+
+### results
+
+```ruby
+state.results  # => Array<RobotResult>
+```
+
+All robot execution results.
+
+### messages
+
+```ruby
+state.messages  # => Array<Message>
+```
+
+Formatted conversation messages for LLM.
+
+### append_result
+
+```ruby
+state.append_result(robot_result)
+```
+
+Add a robot result to history.
+
+### set_results
+
+```ruby
+state.set_results(array_of_results)
+```
+
+Replace all results.
+
+### results_from
+
+```ruby
+state.results_from(5)  # => Array<RobotResult>
+```
+
+Get results starting at index.
+
+### thread_id=
+
+```ruby
+state.thread_id = "thread_123"
+```
+
+Set the thread identifier.
+
+### format_history
+
+```ruby
+state.format_history  # => Array<Message>
+```
+
+Format results as conversation history.
+
+### clone
+
+```ruby
+new_state = state.clone
+```
+
+Create a deep copy.
+
+### to_h
+
+```ruby
+state.to_h  # => Hash
+```
+
+Hash representation.
+
+### to_json
+
+```ruby
+state.to_json  # => String
+```
+
+JSON representation.
+
+### from_hash (class method)
+
+```ruby
+state = State.from_hash(hash)
+```
+
+Restore from hash.
+
+## StateProxy
+
+The `data` attribute is a `StateProxy`:
+
+```ruby
+proxy = state.data
+
+# Hash-style access
+proxy[:key]
+proxy[:key] = value
+
+# Method-style access
+proxy.key
+proxy.key = value
+
+# Hash operations
+proxy.key?(:key)
+proxy.keys
+proxy.values
+proxy.each { |k, v| ... }
+proxy.merge!(other_hash)
+proxy.delete(:key)
+proxy.to_h
+proxy.empty?
+proxy.size
+```
+
+## Creating State
+
+### Basic
+
+```ruby
+state = RobotLab.create_state(message: "Hello")
+```
+
+### With Data
+
+```ruby
+state = RobotLab.create_state(
+  message: "Process order",
+  data: {
+    user_id: "user_123",
+    order_id: "ord_456"
+  }
+)
+```
+
+### With Thread ID
+
+```ruby
+# Via UserMessage
+message = UserMessage.new("Continue", thread_id: "thread_123")
+state = RobotLab.create_state(message: message)
+
+# Direct assignment
+state = RobotLab.create_state(message: "Continue")
+state.thread_id = "thread_123"
+```
+
+### With Existing Results
+
+```ruby
+state = RobotLab.create_state(
+  message: "Follow up",
+  results: previous_results
+)
+```
+
+## UserMessage
+
+Enhanced message with metadata:
+
+```ruby
+message = UserMessage.new(
+  "What's my order status?",
+  thread_id: "thread_123",
+  system_prompt: "Respond in Spanish",
+  metadata: { source: "web" }
+)
+
+message.content       # => "What's my order status?"
+message.thread_id     # => "thread_123"
+message.system_prompt # => "Respond in Spanish"
+message.metadata      # => { source: "web" }
+message.id            # => UUID
+message.created_at    # => Time
+```
+
+## Examples
+
+### Accessing Data
+
+```ruby
+state = RobotLab.create_state(
+  message: "Help",
+  data: { user: { name: "Alice", plan: "pro" } }
+)
+
+state.data[:user][:name]  # => "Alice"
+state.data.to_h           # => { user: { name: "Alice", plan: "pro" } }
+```
+
+### Working with Results
+
+```ruby
+# After running network
+state.results.size           # Number of results
+state.results.last           # Most recent
+state.results.map(&:robot_name)  # ["classifier", "support"]
+```
+
+### Using Memory
+
+```ruby
+state.memory.remember("intent", "billing")
+intent = state.memory.recall("intent")
+
+scoped = state.memory.scoped("user:123")
+scoped.remember("preference", "dark_mode")
+```
+
+### Serialization
+
+```ruby
+# Save state
+json = state.to_json
+File.write("state.json", json)
+
+# Restore state
+data = JSON.parse(File.read("state.json"))
+state = State.from_hash(data)
+```
+
+## See Also
+
+- [State Management Architecture](../../architecture/state-management.md)
+- [Memory](memory.md)
+- [History Guide](../../guides/history.md)

data/docs/api/core/tool.md

@@ -0,0 +1,353 @@
+# Tool
+
+Callable function that robots can use to interact with external systems.
+
+## Class: `RobotLab::Tool`
+
+```ruby
+tool = RobotLab::Tool.new(
+  name: "get_weather",
+  description: "Get weather for a location",
+  parameters: { location: { type: "string", required: true } },
+  handler: ->(location:, **_) { WeatherService.fetch(location) }
+)
+```
+
+## Constructor
+
+```ruby
+Tool.new(
+  name:,
+  description: nil,
+  parameters: {},
+  handler:,
+  mcp: false,
+  strict: false
+)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Tool identifier |
+| `description` | `String` | What the tool does |
+| `parameters` | `Hash` | Parameter definitions |
+| `handler` | `Proc` | Execution function |
+| `mcp` | `Boolean` | Is this an MCP tool? |
+| `strict` | `Boolean` | Strict parameter validation |
+
+## Attributes
+
+### name
+
+```ruby
+tool.name  # => String
+```
+
+Tool identifier.
+
+### description
+
+```ruby
+tool.description  # => String
+```
+
+Human-readable description.
+
+### parameters
+
+```ruby
+tool.parameters  # => Hash
+```
+
+Parameter schema.
+
+### handler
+
+```ruby
+tool.handler  # => Proc
+```
+
+Function that executes the tool.
+
+### mcp
+
+```ruby
+tool.mcp  # => Boolean
+```
+
+Whether this is an MCP-sourced tool.
+
+### strict
+
+```ruby
+tool.strict  # => Boolean
+```
+
+Whether to use strict parameter validation.
+
+## Methods
+
+### call
+
+```ruby
+result = tool.call(
+  params,
+  robot: robot,
+  network: network,
+  state: state
+)
+```
+
+Execute the tool with parameters.
+
+### to_h
+
+```ruby
+tool.to_h  # => Hash
+```
+
+Hash representation.
+
+### to_json
+
+```ruby
+tool.to_json  # => String
+```
+
+JSON representation.
+
+### to_json_schema
+
+```ruby
+tool.to_json_schema  # => Hash
+```
+
+JSON Schema representation for LLM.
+
+## Parameter Schema
+
+### Basic Types
+
+```ruby
+parameters: {
+  name: { type: "string" },
+  count: { type: "integer" },
+  price: { type: "number" },
+  active: { type: "boolean" },
+  tags: { type: "array" }
+}
+```
+
+### Required Parameters
+
+```ruby
+parameters: {
+  id: { type: "string", required: true }
+}
+```
+
+### Descriptions
+
+```ruby
+parameters: {
+  query: {
+    type: "string",
+    description: "Search query (supports wildcards)"
+  }
+}
+```
+
+### Enums
+
+```ruby
+parameters: {
+  status: {
+    type: "string",
+    enum: ["pending", "active", "completed"]
+  }
+}
+```
+
+### Defaults
+
+```ruby
+parameters: {
+  limit: {
+    type: "integer",
+    default: 10
+  }
+}
+```
+
+## Handler
+
+### Basic Handler
+
+```ruby
+handler: ->(param:, **_context) {
+  do_something(param)
+}
+```
+
+### With Context
+
+```ruby
+handler: ->(param:, robot:, network:, state:) {
+  # robot - The executing Robot
+  # network - The NetworkRun
+  # state - Current State
+
+  user = state.data[:user_id]
+  state.memory.remember("last_action", param)
+
+  perform_action(param, user)
+}
+```
+
+### Error Handling
+
+```ruby
+handler: ->(id:, **_) {
+  record = Record.find_by(id: id)
+
+  if record
+    { success: true, data: record.to_h }
+  else
+    { success: false, error: "Not found" }
+  end
+rescue StandardError => e
+  { success: false, error: e.message }
+}
+```
+
+## Builder DSL
+
+In robot builder:
+
+```ruby
+tool :tool_name do
+  description "What it does"
+
+  parameter :param1, type: :string, required: true
+  parameter :param2, type: :integer, default: 10
+
+  handler do |param1:, param2:, **_context|
+    # Implementation
+  end
+end
+```
+
+## ToolManifest
+
+Wrap tools with modified metadata:
+
+```ruby
+manifest = RobotLab::ToolManifest.new(
+  tool: original_tool,
+  name: "custom_name",
+  description: "Custom description"
+)
+
+# Original tool is used, metadata is overridden
+```
+
+### Attributes
+
+- `tool` - The wrapped tool
+- `name` - Override name (or original)
+- `description` - Override description (or original)
+- `aliases` - Alternative names
+
+## Examples
+
+### Simple Tool
+
+```ruby
+tool = Tool.new(
+  name: "current_time",
+  description: "Get the current time",
+  handler: ->(**, _) { Time.now.iso8601 }
+)
+```
+
+### Tool with Parameters
+
+```ruby
+tool = Tool.new(
+  name: "search_users",
+  description: "Search users by criteria",
+  parameters: {
+    query: {
+      type: "string",
+      description: "Search query",
+      required: true
+    },
+    limit: {
+      type: "integer",
+      description: "Max results",
+      default: 10
+    },
+    status: {
+      type: "string",
+      enum: ["active", "inactive", "all"],
+      default: "active"
+    }
+  },
+  handler: ->(query:, limit:, status:, **_) {
+    User.search(query, limit: limit, status: status)
+  }
+)
+```
+
+### API Integration Tool
+
+```ruby
+tool = Tool.new(
+  name: "fetch_stock_price",
+  description: "Get current stock price",
+  parameters: {
+    symbol: { type: "string", required: true }
+  },
+  handler: ->(symbol:, **_) {
+    response = HTTP.get("https://api.stocks.example/#{symbol}")
+
+    if response.status.success?
+      JSON.parse(response.body)
+    else
+      { error: "Failed to fetch", status: response.status.code }
+    end
+  rescue HTTP::Error => e
+    { error: "Network error: #{e.message}" }
+  }
+)
+```
+
+### Database Tool
+
+```ruby
+tool = Tool.new(
+  name: "get_order",
+  description: "Get order details",
+  parameters: {
+    order_id: { type: "string", required: true }
+  },
+  handler: ->(order_id:, state:, **_) {
+    user_id = state.data[:user_id]
+    order = Order.find_by(id: order_id, user_id: user_id)
+
+    if order
+      order.as_json(include: [:items, :shipping])
+    else
+      { error: "Order not found or unauthorized" }
+    end
+  }
+)
+```
+
+## See Also
+
+- [Using Tools Guide](../../guides/using-tools.md)
+- [Robot](robot.md)
+- [MCP Integration](../../guides/mcp-integration.md)