prescient 0.6.0 → 0.8.0

data/examples/custom_contexts.rb

@@ -96,9 +96,9 @@ Prescient.configure do |config|
         embedding_fields: %w[medical_conditions medications]
       },
       'appointment' => {
-        fields: %w[patient_name date type notes doctor],
-        format: 'Appointment for %{patient_name} on %{date} - %{type} with Dr. %{doctor}: %{notes}',
-        embedding_fields: %w[type notes]
+        fields: %w[patient_name date appointment_type notes doctor],
+        format: 'Appointment for %{patient_name} on %{date} - %{appointment_type} with Dr. %{doctor}: %{notes}',
+        embedding_fields: %w[appointment_type notes]
       }
     },
     prompt_templates: {
@@ -135,7 +135,7 @@ begin
         'type' => 'appointment',
         'patient_name' => 'Patient A',
         'date' => '2024-01-20',
-        'type' => 'Follow-up',
+        'appointment_type' => 'Follow-up',
         'notes' => 'Blood sugar levels improving with current treatment',
         'doctor' => 'Johnson'
       }

data/examples/web_search.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../lib/prescient'
+
+generate = ARGV.delete('--generate')
+if ARGV.include?('--help')
+  puts 'Usage: ruby examples/web_search.rb [--generate] [QUERY]'
+  puts '  --generate  Feed normalized search results to the configured AI provider'
+  puts '  PRESCIENT_PROVIDER  Provider used with --generate (default: configured provider)'
+  exit
+end
+
+query = ARGV.empty? ? 'Ruby HTTP clients' : ARGV.join(' ')
+
+Prescient.configure do |config|
+  config.add_tool(
+    :web_search,
+    Prescient::Tool::SearXNG,
+    url: ENV.fetch('SEARXNG_URL', 'http://localhost:8080'),
+  )
+end
+
+result = if generate
+           Prescient.search_and_generate(
+             query,
+             provider: ENV['PRESCIENT_PROVIDER']&.to_sym,
+             limit:    20,
+           )
+         else
+           Prescient.tool(:web_search).search(query, limit: 20)
+         end
+
+puts JSON.pretty_generate(result)

data/exe/prescient

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'prescient'
-require 'prescient/cli'
+require "prescient"
+require "prescient/cli"
 
 exit Prescient::CLI.run(ARGV)

data/exe/prescient-mcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "prescient"
+require "prescient/mcp"
+
+Prescient::MCP::Stdio.new.run

data/lib/prescient/agent/audit_log.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "time"
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Persists safe Agent telemetry events as newline-delimited JSON.
+  class AuditLog
+    # Telemetry keys permitted in durable audit records.
+    # @return [Array<Symbol>] Safe event fields
+    FIELDS = %i[event loop loops_run actions success phase error].freeze
+
+    # @param path [String, nil] File path opened in append mode
+    # @param io [#write, nil] Writable stream owned by the caller
+    def initialize(path: nil, io: nil)
+      raise ArgumentError, "provide path or io, not both" if path && io
+      raise ArgumentError, "path or io is required" unless path || io
+
+      @io = io || File.open(path, "a")
+      @lock = Monitor.new
+    end
+
+    # Persist one allowlisted telemetry event.
+    # @param event [Hash] Agent event metadata
+    # @return [void]
+    def call(event)
+      record = event.slice(*FIELDS).merge(timestamp: Time.now.utc.iso8601)
+      @lock.synchronize do
+        @io.write("#{JSON.generate(record)}\n")
+        @io.flush if @io.respond_to?(:flush)
+      end
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/cli_adapter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Adapts the bounded agent runtime to CLI streams and exit statuses.
+  class CLIAdapter
+    def initialize(output: $stdout, errors: $stderr)
+      @output = output
+      @errors = errors
+    end
+
+    # Run an agent task and render a text or JSON result.
+    # @return [Integer] Process exit status
+    def run(task:, client: nil, provider: nil, tool_names: [], max_loops: Configuration::DEFAULT_MAX_LOOPS,
+            format: "text", provider_options: {}, generation_options: {}, telemetry: nil)
+      runtime = Runtime.new(
+        client:, provider:, tool_names:, configuration: Configuration.new(max_loops:, telemetry:),
+        provider_options:, generation_options:
+      )
+      result = runtime.run(task)
+      format == "json" ? @output.puts(JSON.generate(result.to_h)) : @output.puts(result.response)
+      0
+    rescue Prescient::Error, ArgumentError => e
+      @errors.puts "prescient: #{e.message}"
+      1
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Runtime policies and safety limits for one agent execution.
+  class Configuration
+    # @return [Integer] Default maximum loop count
+    DEFAULT_MAX_LOOPS = 5
+    # @return [Integer] Default context size limit
+    DEFAULT_MAX_CONTEXT_BYTES = 64_000
+    # @return [Integer] Default action size limit
+    DEFAULT_MAX_ACTION_BYTES = 8_192
+    # @return [Integer] Default observation size limit
+    DEFAULT_MAX_OBSERVATION_BYTES = 16_384
+    # @return [Integer] Default task size limit
+    DEFAULT_MAX_TASK_BYTES = 8_192
+    # @return [Integer] Default generated response size limit
+    DEFAULT_MAX_RESPONSE_BYTES = 32_768
+
+    attr_reader :max_loops, :max_context_bytes, :max_action_bytes, :max_observation_bytes,
+                :max_task_bytes, :max_response_bytes, :authorization, :telemetry
+
+    # @param authorization [#call, nil] Host policy receiving tool, arguments,
+    #   and request-scoped context. Only exactly true permits a tool call.
+    # @param telemetry [#call, nil] Bounded event sink for execution metadata.
+    def initialize(max_loops: DEFAULT_MAX_LOOPS, max_context_bytes: DEFAULT_MAX_CONTEXT_BYTES,
+                   max_action_bytes: DEFAULT_MAX_ACTION_BYTES,
+                   max_observation_bytes: DEFAULT_MAX_OBSERVATION_BYTES,
+                   max_task_bytes: DEFAULT_MAX_TASK_BYTES,
+                   max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
+                   authorization: nil, telemetry: nil)
+      @max_loops = positive_integer(max_loops, "max_loops")
+      @max_context_bytes = positive_integer(max_context_bytes, "max_context_bytes")
+      @max_action_bytes = positive_integer(max_action_bytes, "max_action_bytes")
+      @max_observation_bytes = positive_integer(max_observation_bytes, "max_observation_bytes")
+      @max_task_bytes = positive_integer(max_task_bytes, "max_task_bytes")
+      @max_response_bytes = positive_integer(max_response_bytes, "max_response_bytes")
+      @authorization = callable_or_nil(authorization, "authorization")
+      @telemetry = callable_or_nil(telemetry, "telemetry")
+    end
+
+    private
+
+    def positive_integer(value, name)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise Prescient::Agent::ConfigurationError, "#{name} must be a positive integer"
+    end
+
+    def callable_or_nil(value, name)
+      return value if value.nil? || value.respond_to?(:call)
+
+      raise Prescient::Agent::ConfigurationError, "#{name} must respond to call"
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/context.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Per-run, bounded conversation history rendered as provider context.
+  class Context
+    attr_reader :messages
+
+    def initialize(system_prompt:, task:, max_bytes: Configuration::DEFAULT_MAX_CONTEXT_BYTES)
+      @max_bytes = max_bytes
+      @messages = [
+        { role: "system", content: system_prompt },
+        { role: "user", content: task }
+      ]
+      enforce_limit!
+    end
+
+    # Append a bounded turn to the run history.
+    # @param role [String] Message role
+    # @param content [String] Message content
+    # @return [void]
+    def append(role:, content:)
+      @messages << { role: role, content: content.to_s }
+      enforce_limit!
+    end
+
+    # Return a copy of the provider-compatible history.
+    # @return [Array<Hash>]
+    def to_a
+      @messages.map(&:dup)
+    end
+
+    private
+
+    def enforce_limit!
+      return if serialized_bytes <= @max_bytes
+
+      compact!
+      return if serialized_bytes <= @max_bytes
+
+      raise Prescient::Agent::ConfigurationError, "agent context exceeds configured size limit"
+    end
+
+    def compact!
+      initial_messages = @messages.first(2)
+      recent_messages = @messages.drop(2).last(2)
+      omitted_message = { role: "system", content: "[Earlier agent context omitted due to size limit.]" }
+      @messages = initial_messages + [omitted_message] + recent_messages
+    end
+
+    def serialized_bytes
+      JSON.generate(@messages).bytesize
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/error_serializer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Converts provider and tool failures into bounded, safe agent data.
+  class ErrorSerializer
+    # @return [Array<Array<Class, String>>] Provider/tool error categories
+    CATEGORY_MAP = [
+      [Prescient::AuthenticationError, "authentication_failed"],
+      [Prescient::ConnectionError, "provider_unavailable"],
+      [Prescient::RateLimitError, "rate_limited"],
+      [Prescient::ModelNotAvailableError, "model_unavailable"],
+      [Prescient::InvalidResponseError, "invalid_provider_response"],
+      [Prescient::ProviderError, "provider_failure"],
+      [Prescient::ToolConfigurationError, "tool_configuration_error"],
+      [Prescient::ToolConnectionError, "tool_unavailable"],
+      [Prescient::ToolInvalidResponseError, "invalid_tool_response"],
+      [Prescient::ToolError, "tool_failure"]
+    ].freeze
+
+    class << self
+      # @param error [Exception] Failure to serialize
+      # @return [Hash] Safe error envelope
+      def serialize(error)
+        {
+          error: {
+            category: category_for(error),
+            message: safe_message(error)
+          }
+        }
+      end
+
+      private
+
+      def category_for(error)
+        CATEGORY_MAP.find { |error_class, _category| error.is_a?(error_class) }&.last || "internal_failure"
+      end
+
+      def safe_message(error)
+        return "The requested operation failed." unless error.is_a?(Prescient::Agent::Error)
+
+        error.message.to_s.byteslice(0, 512)
+      end
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Prescient
+  module Agent
+    # Base error for agent-specific failures.
+    class Error < Prescient::Error
+    end
+
+    # Raised for invalid agent configuration.
+    class ConfigurationError < Error
+    end
+
+    # Raised when a provider response contains an invalid action.
+    class MalformedActionError < Error
+    end
+
+    # Raised when a model requests an unavailable tool.
+    class UnauthorizedToolError < Error
+    end
+
+    # Raised when execution reaches its configured loop limit.
+    class MaxLoopsExceededError < Error
+    end
+  end
+end

data/lib/prescient/agent/parser.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Extracts and validates one tool action from provider text.
+  class Parser
+    # @return [Regexp] Fenced JSON action matcher
+    ACTION_PATTERN = /```json\s*(\{.*?\})\s*```/m
+
+    # Parse one optional action from provider output.
+    # @param text [String] Provider response text
+    # @param max_bytes [Integer] Maximum action size
+    # @return [Hash, nil] Parsed action or nil for a final response
+    def self.parse(text, max_bytes: Configuration::DEFAULT_MAX_ACTION_BYTES)
+      new(max_bytes:).parse(text)
+    end
+
+    def initialize(max_bytes: Configuration::DEFAULT_MAX_ACTION_BYTES)
+      @max_bytes = max_bytes
+    end
+
+    # Parse one optional action from provider output.
+    # @param text [String] Provider response text
+    # @return [Hash, nil] Parsed action or nil for a final response
+    def parse(text)
+      match = text.to_s.match(ACTION_PATTERN)
+      return nil unless match
+      raise MalformedActionError, "agent action exceeds configured size limit" if match[1].bytesize > @max_bytes
+
+      payload = JSON.parse(match[1])
+      validate_payload(payload)
+      { name: payload.fetch("action").to_sym, arguments: payload.fetch("args") }
+    rescue JSON::ParserError => e
+      raise MalformedActionError, "agent action contains invalid JSON: #{e.message}"
+    end
+
+    private
+
+    def validate_payload(payload)
+      unless payload.is_a?(Hash) && payload.keys.sort == %w[action args]
+        raise MalformedActionError, "agent action must contain only action and args"
+      end
+      return if payload["action"].is_a?(String) && !payload["action"].empty? && payload["args"].is_a?(Hash)
+
+      raise MalformedActionError, "agent action must define a name and object args"
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/prompt_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Builds deterministic instructions for the single-action agent protocol.
+  class PromptBuilder
+    # Build the system instruction for one agent run.
+    # @param system_instruction [String] Application-specific instruction
+    # @param tools [Array<ToolRegistry::Tool>] Allowed tools
+    # @return [String] Deterministic orchestration prompt
+    def self.build(system_instruction:, tools:)
+      tool_text = tools.empty? ? "None" : tools.map { |tool| tool_instruction(tool) }.join("\n")
+      <<~PROMPT
+        #{system_instruction}
+
+        You may either answer the task directly or request exactly one tool.
+        For a tool request, return one JSON object in a fenced json block:
+        {"action":"tool_name","args":{"key":"value"}}
+        Available tools:
+        #{tool_text}
+        Never request an unavailable tool. Do not return more than one action.
+      PROMPT
+    end
+
+    def self.tool_instruction(tool)
+      "- #{tool.name}: #{tool.description} (arguments: #{JSON.generate(tool.schema)})"
+    end
+    private_class_method :tool_instruction
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Immutable summary of one agent run.
+  class Result
+    attr_reader :response, :provider, :model, :loops_run, :metadata
+
+    def initialize(response:, provider:, model:, loops_run:, success: true, metadata: {})
+      @response = response
+      @provider = provider
+      @model = model
+      @loops_run = loops_run
+      @success = success
+      @metadata = metadata
+    end
+
+    def success?
+      @success
+    end
+
+    # Serialize the result into a safe structured response.
+    # @return [Hash] Result data
+    def to_h
+      {
+        response: @response,
+        provider: @provider,
+        model: @model,
+        loops_run: @loops_run,
+        success: success?,
+        metadata: @metadata
+      }
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/runtime.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Runs a bounded single-agent tool-calling loop through Prescient::Client.
+  class Runtime
+    def initialize(provider: nil, client: nil, tools: nil, tool_names: [], configuration: Configuration.new,
+                   system_prompt: "You are a helpful assistant.", provider_options: {}, generation_options: {},
+                   authorization: nil, telemetry: nil, enable_fallback: true,
+                   request_context: {}, audit_log: nil)
+      @configuration = configuration
+      @telemetry = telemetry || configuration.telemetry
+      @audit_log = audit_log
+      @authorization = authorization || configuration.authorization
+      @request_context = request_context
+      @system_prompt = system_prompt
+      @generation_options = generation_options
+
+      begin
+        @client = client || Prescient.client(provider, enable_fallback:, provider_options:)
+        configured_tools = tools || tool_names.to_h { |name| [name, Prescient.tool(name)] }
+        @registry = ToolRegistry.new(configured_tools.compact)
+      rescue StandardError => e
+        emit_failure(e, phase: :initialization, loops_run: 0, actions: [])
+        raise
+      end
+    end
+
+    # Execute one bounded agent task.
+    # @param task [String] Task instruction
+    # @return [Result] Completed agent result
+    def run(task)
+      actions = []
+      loops_run = 0
+      validate_task(task)
+      context = build_context(task)
+
+      @configuration.max_loops.times do |index|
+        loops_run = index + 1
+        emit(:iteration, loop: index + 1)
+        response = @client.generate_response(task, context.to_a, **@generation_options)
+        validate_response!(response)
+        unless action_appended?(context, response, actions)
+          emit(:completed, loops_run: index + 1, actions: actions.dup, success: true)
+          return result(response, index + 1, actions)
+        end
+      end
+
+      emit(:max_loops_exceeded, loops_run: @configuration.max_loops, actions: actions.dup, success: false)
+      raise MaxLoopsExceededError, "agent exceeded maximum loops: #{@configuration.max_loops}"
+    rescue StandardError => e
+      emit_failure(e, phase: :execution, loops_run:, actions: actions.dup)
+      raise
+    end
+
+    private
+
+    def build_context(task)
+      Context.new(
+        system_prompt: PromptBuilder.build(system_instruction: @system_prompt, tools: @registry.all),
+        task: task,
+        max_bytes: @configuration.max_context_bytes
+      )
+    end
+
+    def action_appended?(context, response, actions)
+      action = Parser.parse(response[:response], max_bytes: @configuration.max_action_bytes)
+      return false unless action
+
+      observation = invoke_tool(action)
+      actions << action[:name].to_s
+      observation_text = bounded_observation(observation)
+      context.append(role: "assistant", content: response[:response])
+      context.append(role: "user", content: "Observation: #{observation_text}")
+      true
+    end
+
+    def bounded_observation(observation)
+      serialized = JSON.generate(observation)
+      return serialized if serialized.bytesize <= @configuration.max_observation_bytes
+
+      limit = @configuration.max_observation_bytes
+      envelope = lambda do |value|
+        JSON.generate(truncated: true, value: value)
+      end
+      return limit < 4 ? "0" : "null" if limit < envelope.call("").bytesize
+
+      low = 0
+      high = serialized.bytesize
+      while low < high
+        midpoint = (low + high + 1) / 2
+        candidate = envelope.call(utf8_prefix(serialized, midpoint))
+        if candidate.bytesize <= limit
+          low = midpoint
+        else
+          high = midpoint - 1
+        end
+      end
+
+      envelope.call(utf8_prefix(serialized, low))
+    end
+
+    def utf8_prefix(value, max_bytes)
+      value.byteslice(0, max_bytes).to_s.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    def invoke_tool(action)
+      authorize_tool!(action)
+      @registry.invoke(action[:name], action[:arguments])
+    rescue Prescient::Error => e
+      raise if e.is_a?(Prescient::Agent::Error)
+
+      ErrorSerializer.serialize(e)
+    end
+
+    def authorize_tool!(action)
+      return unless @authorization
+      return if @authorization.call(
+        tool: action[:name],
+        arguments: action[:arguments].dup,
+        context: @request_context.dup
+      ) == true
+
+      raise UnauthorizedToolError, "agent tool not authorized: #{action[:name]}"
+    end
+
+    def validate_task(task)
+      valid = task.is_a?(String) && !task.strip.empty? && task.bytesize <= @configuration.max_task_bytes
+      return if valid
+
+      raise ConfigurationError, "agent task must be a non-empty string within #{@configuration.max_task_bytes} bytes"
+    end
+
+    def validate_response!(response)
+      text = response[:response]
+      return if text.is_a?(String) && text.bytesize <= @configuration.max_response_bytes
+
+      raise ConfigurationError,
+            "agent response must be a string within #{@configuration.max_response_bytes} bytes"
+    end
+
+    def result(response, loops_run, actions)
+      Result.new(
+        response: response[:response],
+        provider: response[:provider] || @client.provider_name,
+        model: response[:model],
+        loops_run: loops_run,
+        metadata: { actions: actions.dup, success: true }
+      )
+    end
+
+    def emit(event, attributes)
+      payload = { event:, **attributes }.freeze
+      safely_emit(@telemetry, payload)
+      safely_emit(@audit_log, payload)
+    rescue StandardError
+      nil
+    end
+
+    def safely_emit(sink, payload)
+      sink&.call(payload)
+    rescue StandardError
+      nil
+    end
+
+    def emit_failure(error, phase:, loops_run:, actions:)
+      emit(
+        :failed,
+        phase:, loops_run:, actions:, success: false,
+        error: ErrorSerializer.serialize(error).fetch(:error)
+      )
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren