rasti-ai 2.0.1 → 3.0.0

data/README.md

@@ -41,6 +41,10 @@ Rasti::AI.configure do |config|
   config.gemini_api_key = 'AIza12345' # Default ENV['GEMINI_API_KEY']
   config.gemini_default_model = 'gemini-2.0-flash' # Default ENV['GEMINI_DEFAULT_MODEL']
 
+  # Anthropic
+  config.anthropic_api_key = 'sk-ant-12345' # Default ENV['ANTHROPIC_API_KEY']
+  config.anthropic_default_model = 'claude-opus-4-5' # Default ENV['ANTHROPIC_DEFAULT_MODEL']
+
   # Usage tracking
   config.usage_tracker = ->(usage) { puts "#{usage.provider}: #{usage.input_tokens} in / #{usage.output_tokens} out" }
 end
@@ -50,8 +54,9 @@ end
 
 - **OpenAI** - `Rasti::AI::OpenAI::Assistant`
 - **Gemini** - `Rasti::AI::Gemini::Assistant`
+- **Anthropic** - `Rasti::AI::Anthropic::Assistant`
 
-All providers share the same interface. The examples below use OpenAI, but apply equally to Gemini by replacing `OpenAI` with `Gemini`.
+All providers share the same interface. The examples below use OpenAI, but apply equally to Gemini or Anthropic by replacing `OpenAI` with the provider name.
 
 ### Assistant
 
@@ -110,6 +115,9 @@ Supported form attribute types:
 - `Rasti::Types::Enum[:a, :b]` → `string (enum)`
 - `Rasti::Types::Array[Type]` → `array`
 - `Rasti::Types::Model[FormClass]` → nested `object`
+- `Rasti::Types::Hash` → `object`
+- Custom types registered via `Rasti::Model::Schema.register_type_serializer` or implementing `to_schema` are picked up automatically
+- Unknown types → no constraints (empty schema, no crash)
 
 #### Using tools with an assistant
 ```ruby
@@ -163,8 +171,27 @@ client = Rasti::AI::OpenAI::Client.new(
 )
 
 assistant = Rasti::AI::OpenAI::Assistant.new client: client
+
+# Anthropic client
+client = Rasti::AI::Anthropic::Client.new(
+  http_connect_timeout: 120,
+  http_read_timeout: 300  # Claude can be slow on long responses
+)
+
+assistant = Rasti::AI::Anthropic::Assistant.new client: client
 ```
 
+### Thinking / extended reasoning
+
+Some providers support extended reasoning ("thinking") to improve accuracy on complex tasks. Pass `thinking:` with a level of `'low'`, `'medium'`, or `'high'` when creating an assistant:
+
+```ruby
+assistant = Rasti::AI::Anthropic::Assistant.new thinking: 'high'
+assistant.call 'Solve this step by step: ...'
+```
+
+The level controls how much computation the model can spend reasoning before responding. Higher levels may improve answer quality at the cost of more tokens and latency. Not all models support thinking — check your provider's documentation.
+
 ### Usage tracking
 
 Track token consumption across API calls (including tool calls):
@@ -173,7 +200,8 @@ Track token consumption across API calls (including tool calls):
 tracked_usage = []
 tracker = ->(usage) { tracked_usage << usage }
 
-assistant = Rasti::AI::OpenAI::Assistant.new usage_tracker: tracker
+client = Rasti::AI::OpenAI::Client.new usage_tracker: tracker
+assistant = Rasti::AI::OpenAI::Assistant.new client: client
 assistant.call 'who is the best player'
 
 usage = tracked_usage.first
@@ -183,6 +211,7 @@ usage.input_tokens      # => 150
 usage.output_tokens     # => 42
 usage.cached_tokens     # => 0
 usage.reasoning_tokens  # => 0
+usage.raw               # => Raw usage payload from provider
 ```
 
 The tracker can also be configured globally:
@@ -211,43 +240,113 @@ Rasti::AI::MCP::Server.configure do |config|
 end
 ```
 
-##### Registering Tools
+##### Authentication
 
-Tools must inherit from `Rasti::AI::Tool` and can be registered with the server:
+Use the `authenticate` block to control access to the MCP endpoint. The block receives the current `Rack::Request` and must return a truthy value to allow the request or a falsy value to reject it.
 
 ```ruby
-class HelloWorldTool < Rasti::AI::Tool
-  def self.description
-    'Returns a hello world message'
+Rasti::AI::MCP::Server.configure do |config|
+  config.authenticate do |request|
+    request.env['HTTP_AUTHORIZATION'] == "Bearer #{ENV['MCP_TOKEN']}"
   end
+end
+```
 
-  def execute(form)
-    {text: 'Hello world'}
+When authentication fails the server returns HTTP 401 with a JSON-RPC error body. The check runs before the request body is read, so it covers all MCP methods including `initialize`.
+
+The `authenticate` and `load_tools` blocks are independent — when authentication fails `load_tools` is never called.
+
+##### Registering Tools
+
+Tools are registered per-request via a `load_tools` block. The block receives a `ToolsRegistry` and the current `Rack::Request`, enabling context-aware tool instantiation (e.g. based on the authenticated user).
+
+```ruby
+Rasti::AI::MCP::Server.configure do |config|
+  config.load_tools do |tools_registry, request|
+    user = User.find(request.session[:user_id])
+
+    # Form A: Rasti::AI::Tool instance — name, description and schema derived from the class
+    tools_registry.register tool: MyTool.new(user)
+
+    # Form B: tool instance with a custom name
+    tools_registry.register name: 'search', tool: SearchTool.new(user)
+
+    # Form C: tool instance with description or schema overrides
+    tools_registry.register(
+      tool: MyTool.new(user),
+      description: 'Contextual description for the LLM'
+    )
+
+    # Form D: existing Form class + block — schema from the Form, execution in the block
+    tools_registry.register(name: 'sum', description: 'Sum two numbers', form: SumTool::Form) do |args|
+      SumTool.new.call(args)
+    end
+
+    # Form E: fully inline — raw JSON Schema, no class required
+    tools_registry.register(
+      name: 'report',
+      description: 'Generate a report',
+      input_schema: {
+        type: 'object',
+        properties: {
+          title: {type: 'string'},
+          filters: {
+            type: 'object',
+            properties: {
+              category: {type: 'string', enum: ['sales', 'ops']},
+              date_range: {
+                type: 'object',
+                properties: {
+                  from: {type: 'string', format: 'date'},
+                  to: {type: 'string', format: 'date'}
+                },
+                required: ['from', 'to']
+              }
+            }
+          }
+        },
+        required: ['title']
+      }
+    ) do |args|
+      user.generate_report(args['title'], args['filters'])
+    end
   end
 end
-
-# Register tools
-Rasti::AI::MCP::Server.register_tool HelloWorldTool.new
-Rasti::AI::MCP::Server.register_tool SumTool.new
 ```
 
+`tools_registry.register` accepts all keyword arguments as optional and combines them according to these precedence rules:
+
+| Parameter | Purpose | Precedence |
+|---|---|---|
+| `name:` | Tool identifier | Explicit > derived from `tool.class` |
+| `description:` | Description shown to the LLM | Explicit > `tool.class.description` |
+| `input_schema:` | Raw JSON Schema hash for parameters | Explicit > `form:` > `tool.class.form` |
+| `form:` | `Rasti::Form` subclass for schema | Used when no `input_schema:` |
+| `tool:` | `Rasti::AI::Tool` instance | Provides defaults + executor |
+| block | Executor called with args hash | Block > `tool.call` |
+
+Block executors receive the arguments as a `Hash` with string keys and must return a `String`.
+
 ##### Using as Rack Middleware
 
 ```ruby
 # In your config.ru
 require 'rasti/ai'
 
-# Register your tools
-Rasti::AI::MCP::Server.register_tool HelloWorldTool.new
-Rasti::AI::MCP::Server.register_tool SumTool.new
+Rasti::AI::MCP::Server.configure do |config|
+  config.load_tools do |tools_registry, request|
+    user = User.find(request.session[:user_id])
+    tools_registry.register tool: MyTool.new(user)
+    tools_registry.register tool: OtherTool.new(user)
+  end
+end
 
-# Use as middleware
 use Rasti::AI::MCP::Server
 
 run YourApp
 ```
 
-The server will handle POST requests to the configured path (`/mcp` by default) and pass all other requests to your application.
+The server handles POST requests to the configured path (`/mcp` by default) and forwards all other requests to the application. The `load_tools` block runs on every request, so tools are always fresh and scoped to the current request context.
 
 ##### Supported MCP Methods
 
@@ -262,10 +361,8 @@ The MCP Client allows you to communicate with MCP servers.
 ##### Basic Usage
 
 ```ruby
-# Create a client
-client = Rasti::AI::MCP::Client.new(
-  url: 'https://mcp.server.ai/mcp'
-)
+client = Rasti::AI::MCP::Client.new url: 'https://mcp.server.ai/mcp'
+
 
 # List available tools
 tools = client.list_tools
@@ -315,9 +412,8 @@ client = Rasti::AI::MCP::Client.new(
 You can use MCP clients as tools for any assistant:
 
 ```ruby
-mcp_client = Rasti::AI::MCP::Client.new(
-  url: 'https://mcp.server.ai/mcp'
-)
+mcp_client = Rasti::AI::MCP::Client.new url: 'https://mcp.server.ai/mcp'
+
 
 assistant = Rasti::AI::OpenAI::Assistant.new(
   mcp_servers: {my_mcp: mcp_client}
@@ -327,6 +423,18 @@ assistant = Rasti::AI::OpenAI::Assistant.new(
 assistant.call 'What is 5 plus 3?'
 ```
 
+## Try it out
+
+The gem includes interactive chat tasks wired to the [Pipeworx](https://pipeworx.io) public weather MCP server (no auth required):
+
+```bash
+OPENAI_API_KEY=sk-...    rake assistant:openai
+GEMINI_API_KEY=AIza...   rake assistant:gemini
+ANTHROPIC_API_KEY=sk-... rake assistant:anthropic
+```
+
+Type your message and press Enter. Type `exit` or `Ctrl+C` to quit.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/gabynaiman/rasti-ai.

data/Rakefile

@@ -1,6 +1,8 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
+FileList['tasks/**/*.rake'].each { |f| import f }
+
 Rake::TestTask.new(:spec) do |t|
   t.libs << 'spec'
   t.libs << 'lib'

data/lib/rasti/ai/anthropic/assistant.rb

@@ -0,0 +1,139 @@
+module Rasti
+  module AI
+    module Anthropic
+      class Assistant < Rasti::AI::Assistant
+
+        ALLOWED_SCHEMA_FIELDS = %w[type description properties required enum items format nullable anyOf].freeze
+
+        THINKING_LEVELS = {
+          'low'    => {type: 'enabled', budget_tokens: 1_024}.freeze,
+          'medium' => {type: 'enabled', budget_tokens: 8_000}.freeze,
+          'high'   => {type: 'enabled', budget_tokens: 16_000}.freeze
+        }.freeze
+
+        private
+
+        def build_default_client
+          Client.new
+        end
+
+        def build_user_message(prompt)
+          {role: Roles::USER, content: prompt}
+        end
+
+        def build_assistant_message(content)
+          {role: Roles::ASSISTANT, content: content}
+        end
+
+        def build_assistant_tool_calls_message(response)
+          {role: Roles::ASSISTANT, content: response['content']}
+        end
+
+        def build_tool_result_message(tool_call, name, result)
+          {
+            role:    Roles::USER,
+            content: [{
+              type:        'tool_result',
+              tool_use_id: tool_call['id'],
+              content:     result
+            }]
+          }
+        end
+
+        def request_completion
+          all_tools = serialized_tools.dup
+          all_tools << structured_output_tool if json_schema
+
+          tc = if json_schema
+            {type: 'tool', name: 'structured_output'}
+          elsif all_tools.any?
+            {type: 'auto'}
+          end
+
+          client.messages(
+            messages:    messages,
+            model:       model,
+            system:      state.context,
+            tools:       all_tools,
+            tool_choice: tc,
+            thinking:    thinking_config
+          )
+        end
+
+        def thinking_config
+          THINKING_LEVELS[thinking]
+        end
+
+        def parse_tool_calls(response)
+          content = response['content'] || []
+          content.select { |block| block['type'] == 'tool_use' && block['name'] != 'structured_output' }
+        end
+
+        def parse_content(response)
+          content = response['content'] || []
+
+          if json_schema
+            structured = content.find { |block| block['type'] == 'tool_use' && block['name'] == 'structured_output' }
+            return JSON.dump(structured['input']) if structured
+          end
+
+          text_block = content.find { |block| block['type'] == 'text' }
+          text_block&.[]('text')
+        end
+
+        def finished?(response)
+          !response['stop_reason'].nil?
+        end
+
+        def extract_tool_call_info(tool_call)
+          [tool_call['name'], tool_call['input'] || {}]
+        end
+
+        def wrap_tool_serialization(raw)
+          schema = raw[:inputSchema] || raw['inputSchema']
+
+          result = {
+            name:        raw[:name]        || raw['name'],
+            description: raw[:description] || raw['description'] || raw[:title] || raw['title']
+          }
+          result[:input_schema] = sanitize_schema(schema) if schema
+          result.reject { |_, v| v.nil? }
+        end
+
+        def sanitize_schema(schema)
+          return schema unless schema.is_a?(Hash)
+
+          schema.each_with_object({}) do |(key, value), acc|
+            next unless ALLOWED_SCHEMA_FIELDS.include?(key.to_s)
+            acc[key] = case key.to_s
+                       when 'properties'
+                         value.each_with_object({}) { |(k, v), h| h[k] = sanitize_schema(v) }
+                       when 'items'
+                         sanitize_schema(value)
+                       when 'anyOf'
+                         value.map { |item| sanitize_schema(item) }
+                       else
+                         value
+                       end
+          end
+        end
+
+        def extract_tool_name(wrapped)
+          wrapped[:name] || wrapped['name']
+        end
+
+        def structured_output_tool
+          {
+            name:         'structured_output',
+            description:  'Return the structured response',
+            input_schema: {
+              type:       'object',
+              properties: json_schema
+            }
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/rasti/ai/anthropic/client.rb

@@ -0,0 +1,58 @@
+module Rasti
+  module AI
+    module Anthropic
+      class Client < Rasti::AI::Client
+
+        ANTHROPIC_VERSION = '2023-06-01'.freeze
+        DEFAULT_MAX_TOKENS = 4096
+
+        def messages(messages:, model:nil, system:nil, tools:[], tool_choice:nil, max_tokens:nil, thinking:nil)
+          body = {
+            model:      model || Rasti::AI.anthropic_default_model,
+            max_tokens: max_tokens || DEFAULT_MAX_TOKENS,
+            messages:   messages
+          }
+
+          body[:thinking]    = thinking    if thinking
+          body[:system]      = system      if system
+          body[:tools]       = tools       unless tools.empty?
+          body[:tool_choice] = tool_choice if tool_choice
+
+          post '/messages', body
+        end
+
+        private
+
+        def parse_usage(response)
+          usage = response['usage']
+          return unless usage
+          Usage.new(
+            provider:          'anthropic',
+            model:             response['model'],
+            input_tokens:      usage['input_tokens'],
+            output_tokens:     usage['output_tokens'],
+            cached_tokens:     usage['cache_read_input_tokens'] || 0,
+            reasoning_tokens:  0,
+            raw:               usage
+          )
+        end
+
+        def default_api_key
+          Rasti::AI.anthropic_api_key
+        end
+
+        def base_url
+          'https://api.anthropic.com/v1'
+        end
+
+        def build_request(uri)
+          request = super
+          request['x-api-key']        = api_key
+          request['anthropic-version'] = ANTHROPIC_VERSION
+          request
+        end
+
+      end
+    end
+  end
+end

data/lib/rasti/ai/anthropic/roles.rb

@@ -0,0 +1,12 @@
+module Rasti
+  module AI
+    module Anthropic
+      module Roles
+
+        USER      = 'user'.freeze
+        ASSISTANT = 'assistant'.freeze
+
+      end
+    end
+  end
+end

data/lib/rasti/ai/assistant.rb

@@ -2,17 +2,21 @@ module Rasti
   module AI
     class Assistant
 
-      attr_reader :state
+      attr_reader :state, :model, :thinking
+
+      VALID_THINKING_LEVELS = %w[low medium high].freeze
+
+      def initialize(client:nil, json_schema:nil, state:nil, model:nil, thinking:nil, tools:[], mcp_servers:{}, logger:nil)
+        raise ArgumentError, "Invalid thinking level '#{thinking}'. Valid: #{VALID_THINKING_LEVELS.join(', ')}" if thinking && !VALID_THINKING_LEVELS.include?(thinking)
 
-      def initialize(client:nil, json_schema:nil, state:nil, model:nil, tools:[], mcp_servers:{}, logger:nil, usage_tracker:nil)
         @client = client || build_default_client
         @json_schema = json_schema
         @state = state || AssistantState.new
         @model = model
+        @thinking = thinking
         @tools = {}
         @serialized_tools = []
         @logger = logger || Rasti::AI.logger
-        @usage_tracker = usage_tracker || Rasti::AI.usage_tracker
 
         register_tools(tools)
         register_mcp_servers(mcp_servers)
@@ -23,7 +27,6 @@ module Rasti
 
         loop do
           response = request_completion
-          track_usage response
 
           tool_calls = parse_tool_calls(response)
 
@@ -47,18 +50,12 @@ module Rasti
 
       private
 
-      attr_reader :client, :json_schema, :model, :tools, :serialized_tools, :logger, :usage_tracker
+      attr_reader :client, :json_schema, :tools, :serialized_tools, :logger
 
       def messages
         state.messages
       end
 
-      def track_usage(response)
-        return unless usage_tracker
-        usage = parse_usage response
-        usage_tracker.call usage if usage
-      end
-
       # --- Shared behavior ---
 
       def register_tools(tools)
@@ -140,10 +137,6 @@ module Rasti
         raise NotImplementedError
       end
 
-      def parse_usage(response)
-        raise NotImplementedError
-      end
-
       def extract_tool_call_info(tool_call)
         raise NotImplementedError
       end

data/lib/rasti/ai/client.rb

@@ -4,17 +4,28 @@ module Rasti
 
       RETRYABLE_STATUS_CODES = [502, 503, 504].freeze
 
-      def initialize(api_key:nil, logger:nil, http_connect_timeout:nil, http_read_timeout:nil, http_max_retries:nil)
+      def initialize(api_key:nil, logger:nil, http_connect_timeout:nil, http_read_timeout:nil, http_max_retries:nil, usage_tracker:nil)
         @api_key = api_key || default_api_key
         @logger = logger || Rasti::AI.logger
         @http_connect_timeout = http_connect_timeout || Rasti::AI.http_connect_timeout
         @http_read_timeout = http_read_timeout || Rasti::AI.http_read_timeout
         @http_max_retries = http_max_retries || Rasti::AI.http_max_retries
+        @usage_tracker = usage_tracker || Rasti::AI.usage_tracker
       end
 
       private
 
-      attr_reader :api_key, :logger, :http_connect_timeout, :http_read_timeout, :http_max_retries
+      attr_reader :api_key, :logger, :http_connect_timeout, :http_read_timeout, :http_max_retries, :usage_tracker
+
+      def track_usage(response)
+        return unless usage_tracker
+        usage = parse_usage response
+        usage_tracker.call usage if usage
+      end
+
+      def parse_usage(response)
+        raise NotImplementedError
+      end
 
       def default_api_key
         raise NotImplementedError
@@ -63,7 +74,9 @@ module Rasti
             raise Errors::RequestFail.new(url, body, response)
           end
 
-          JSON.parse response.body
+          parsed_response = JSON.parse response.body
+          track_usage parsed_response
+          parsed_response
 
         rescue SocketError, Net::OpenTimeout, Net::ReadTimeout, Errors::RequestFail => e
           if retry_count < max_retries

data/lib/rasti/ai/gemini/assistant.rb

@@ -3,6 +3,14 @@ module Rasti
     module Gemini
       class Assistant < Rasti::AI::Assistant
 
+        ALLOWED_SCHEMA_FIELDS = %w[type description properties required enum items format nullable anyOf].freeze
+
+        THINKING_LEVELS = {
+          'low'    => {thinking_budget: 1_024}.freeze,
+          'medium' => {thinking_budget: 8_192}.freeze,
+          'high'   => {thinking_budget: 24_576}.freeze
+        }.freeze
+
         private
 
         def build_default_client
@@ -60,32 +68,38 @@ module Rasti
           !response.dig('candidates', 0, 'finishReason').nil?
         end
 
-        def parse_usage(response)
-          usage = response['usageMetadata']
-          return unless usage
-          Usage.new(
-            provider: :gemini,
-            model: response['modelVersion'],
-            input_tokens: usage['promptTokenCount'],
-            output_tokens: usage['candidatesTokenCount'],
-            cached_tokens: usage['cachedContentTokenCount'] || 0,
-            reasoning_tokens: usage['thoughtsTokenCount'] || 0
-          )
-        end
-
         def extract_tool_call_info(tool_call)
           fc = tool_call['functionCall']
           [fc['name'], fc['args'] || {}]
         end
 
         def wrap_tool_serialization(raw)
-          result = raw.dup
-          if result.key?(:inputSchema)
-            result[:parameters] = result.delete(:inputSchema)
-          elsif result.key?('inputSchema')
-            result['parameters'] = result.delete('inputSchema')
+          schema = raw[:inputSchema] || raw['inputSchema']
+
+          result = {
+            name:        raw[:name]        || raw['name'],
+            description: raw[:description] || raw['description'] || raw[:title] || raw['title']
+          }
+          result[:parameters] = sanitize_schema(schema) if schema
+          result.reject { |_, v| v.nil? }
+        end
+
+        def sanitize_schema(schema)
+          return schema unless schema.is_a?(Hash)
+
+          schema.each_with_object({}) do |(key, value), acc|
+            next unless ALLOWED_SCHEMA_FIELDS.include?(key.to_s)
+            acc[key] = case key.to_s
+                       when 'properties'
+                         value.each_with_object({}) { |(k, v), h| h[k] = sanitize_schema(v) }
+                       when 'items'
+                         sanitize_schema(value)
+                       when 'anyOf'
+                         value.map { |item| sanitize_schema(item) }
+                       else
+                         value
+                       end
           end
-          result
         end
 
         def extract_tool_name(wrapped)
@@ -97,13 +111,16 @@ module Rasti
           [{function_declarations: serialized_tools}]
         end
 
-        def generation_config
-          return nil if json_schema.nil?
+        def thinking_config
+          THINKING_LEVELS[thinking]
+        end
 
-          {
-            response_mime_type: 'application/json',
-            response_schema: json_schema
-          }
+        def generation_config
+          config = {}
+          config[:thinking_config]    = thinking_config if thinking
+          config[:response_mime_type] = 'application/json' if json_schema
+          config[:response_schema]    = json_schema        if json_schema
+          config.empty? ? nil : config
         end
 
       end

data/lib/rasti/ai/gemini/client.rb

@@ -17,6 +17,20 @@ module Rasti
 
         private
 
+        def parse_usage(response)
+          usage = response['usageMetadata']
+          return unless usage
+          Usage.new(
+            provider: 'gemini',
+            model: response['modelVersion'],
+            input_tokens: usage['promptTokenCount'],
+            output_tokens: usage['candidatesTokenCount'],
+            cached_tokens: usage['cachedContentTokenCount'] || 0,
+            reasoning_tokens: usage['thoughtsTokenCount'] || 0,
+            raw: usage
+          )
+        end
+
         def default_api_key
           Rasti::AI.gemini_api_key
         end