prescient 0.7.0 → 0.8.0

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

data/lib/prescient/agent/schema_validator.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Validates the JSON-schema subset used by agent tools.
+  # rubocop:disable Metrics/ClassLength
+  class SchemaValidator
+    # Validate a value against a schema.
+    # @param schema [Hash] Supported JSON-schema subset
+    # @param value [Object] Value to validate
+    # @return [Object] The validated value
+    def self.validate!(schema, value)
+      new(schema).validate!(value)
+    end
+
+    def initialize(schema)
+      @schema = schema.is_a?(Hash) ? schema : {}
+    end
+
+    # Validate a value against this validator's schema.
+    # @param value [Object] Value to validate
+    # @return [Object] The validated value
+    def validate!(value)
+      validate_schema(@schema, value, [])
+      value
+    end
+
+    private
+
+    def validate_schema(schema, value, path)
+      schema = resolve_reference(schema)
+      validate_composition(schema, value, path)
+      validate_enum(schema, value, path)
+      validate_type(schema, value, path)
+      validate_string_constraints(schema, value, path)
+      validate_number_constraints(schema, value, path)
+      validate_array_constraints(schema, value, path)
+      validate_object_constraints(schema, value, path)
+    end
+
+    def validate_composition(schema, value, path)
+      schemas = schema_value(schema, "oneOf")
+      return unless schemas
+
+      matches = schemas.count do |candidate|
+        validate_schema(candidate, value, path)
+        true
+      rescue MalformedActionError
+        false
+      end
+      return if matches == 1
+
+      raise MalformedActionError, "agent tool arguments must match exactly one schema#{path_suffix(path)}"
+    end
+
+    def validate_enum(schema, value, path)
+      values = schema_value(schema, "enum")
+      return unless values
+      return if values.include?(value)
+
+      raise MalformedActionError, "agent tool argument is not an allowed value#{path_suffix(path)}"
+    end
+
+    def validate_type(schema, value, path)
+      type = schema_value(schema, "type")
+      return unless type
+
+      valid = {
+        "object" => value.is_a?(Hash),
+        "array" => value.is_a?(Array),
+        "string" => value.is_a?(String),
+        "integer" => value.is_a?(Integer),
+        "number" => value.is_a?(Numeric) && !value.is_a?(Complex),
+        "boolean" => [true, false].include?(value)
+      }.fetch(type.to_s, false)
+      return if valid
+
+      raise MalformedActionError, "agent tool arguments must be a #{type}#{path_suffix(path)}"
+    end
+
+    def validate_string_constraints(schema, value, path)
+      return unless value.is_a?(String)
+
+      minimum = schema_value(schema, "minLength")
+      maximum = schema_value(schema, "maxLength")
+      pattern = schema_value(schema, "pattern")
+      if minimum && value.length < minimum
+        raise MalformedActionError, "agent string is shorter than allowed#{path_suffix(path)}"
+      end
+      if maximum && value.length > maximum
+        raise MalformedActionError, "agent string is longer than allowed#{path_suffix(path)}"
+      end
+      return unless pattern && !Regexp.new(pattern).match?(value)
+
+      raise MalformedActionError, "agent string does not match the required pattern#{path_suffix(path)}"
+    rescue RegexpError
+      raise ConfigurationError, "agent tool schema contains an invalid pattern"
+    end
+
+    def validate_number_constraints(schema, value, path)
+      return unless value.is_a?(Numeric) && !value.is_a?(Complex)
+
+      minimum = schema_value(schema, "minimum")
+      maximum = schema_value(schema, "maximum")
+      exclusive_minimum = schema_value(schema, "exclusiveMinimum")
+      exclusive_maximum = schema_value(schema, "exclusiveMaximum")
+      validate_lower_bound(value, minimum, path)
+      validate_upper_bound(value, maximum, path)
+      validate_lower_bound(value, exclusive_minimum, path, exclusive: true)
+      validate_upper_bound(value, exclusive_maximum, path, exclusive: true)
+    end
+
+    def validate_array_constraints(schema, value, path)
+      return unless value.is_a?(Array)
+
+      minimum = schema_value(schema, "minItems")
+      maximum = schema_value(schema, "maxItems")
+      if minimum && value.length < minimum
+        raise MalformedActionError, "agent array has too few items#{path_suffix(path)}"
+      end
+      if maximum && value.length > maximum
+        raise MalformedActionError, "agent array has too many items#{path_suffix(path)}"
+      end
+
+      item_schema = schema_value(schema, "items")
+      return unless item_schema.is_a?(Hash)
+
+      value.each_with_index { |item, index| validate_schema(item_schema, item, path + [index]) }
+    end
+
+    def validate_object_constraints(schema, value, path)
+      return unless value.is_a?(Hash)
+
+      validate_required(value, schema, path)
+      validate_properties(value, schema, path)
+      validate_additional_properties(value, schema, path)
+    end
+
+    def validate_required(value, schema, path)
+      (schema_value(schema, "required") || []).each do |key|
+        next if value.key?(key) || value.key?(key.to_sym)
+
+        raise MalformedActionError, "agent tool arguments missing: #{key}#{path_suffix(path)}"
+      end
+    end
+
+    def validate_properties(value, schema, path)
+      (schema_value(schema, "properties") || {}).each do |key, property_schema|
+        next unless value.key?(key) || value.key?(key.to_sym)
+
+        property_value = value.key?(key) ? value[key] : value[key.to_sym]
+        validate_schema(property_schema, property_value, path + [key])
+      end
+    end
+
+    def validate_additional_properties(value, schema, path)
+      return unless schema_value(schema, "additionalProperties") == false
+
+      property_names = (schema_value(schema, "properties") || {}).keys.map(&:to_s)
+      value.each_key do |key|
+        next if property_names.include?(key.to_s)
+
+        raise MalformedActionError, "agent tool arguments not allowed: #{key}#{path_suffix(path)}"
+      end
+    end
+
+    def validate_lower_bound(value, bound, path, exclusive: false)
+      return unless bound.is_a?(Numeric)
+      return if exclusive ? value > bound : value >= bound
+
+      description = exclusive ? "exclusive minimum" : "minimum"
+      raise MalformedActionError, "agent number is below the #{description}#{path_suffix(path)}"
+    end
+
+    def validate_upper_bound(value, bound, path, exclusive: false)
+      return unless bound.is_a?(Numeric)
+      return if exclusive ? value < bound : value <= bound
+
+      description = exclusive ? "exclusive maximum" : "maximum"
+      raise MalformedActionError, "agent number exceeds the #{description}#{path_suffix(path)}"
+    end
+
+    def resolve_reference(schema)
+      reference = schema_value(schema, "$ref")
+      return schema unless reference
+      return resolve_pointer(reference) if reference.start_with?("#/")
+
+      raise ConfigurationError, "agent tool schema only supports local $ref values"
+    end
+
+    def resolve_pointer(reference)
+      reference.delete_prefix("#/").split("/").reduce(@schema) do |current, token|
+        key = token.gsub("~1", "/").gsub("~0", "~")
+        current.fetch(key) { current.fetch(key.to_sym) }
+      end
+    rescue KeyError, NoMethodError
+      raise ConfigurationError, "agent tool schema contains an unresolved $ref"
+    end
+
+    def schema_value(schema, key)
+      return schema[key] if schema.key?(key)
+      return schema[key.to_sym] if schema.key?(key.to_sym)
+
+      nil
+    end
+
+    def path_suffix(path)
+      return "" if path.empty?
+
+      " at #{path.map { |part| part.is_a?(Integer) ? "[#{part}]" : part }.join(".")}"
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent/tool_registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/ClassAndModuleChildren
+module Prescient::Agent
+  # Explicit allowlist and invocation boundary for agent tools.
+  class ToolRegistry
+    # @return [Class] Internal immutable tool descriptor
+    Tool = Struct.new(:name, :description, :schema, :callable, keyword_init: true)
+
+    def initialize(tools)
+      @tools = tools.to_h { |name, tool| [name.to_sym, build_tool(name, tool)] }
+    end
+
+    # Return all explicitly allowed tools.
+    # @return [Array<Tool>] Tool descriptors
+    def all
+      @tools.values
+    end
+
+    def invoke(name, arguments)
+      tool = @tools[name.to_sym]
+      raise UnauthorizedToolError, "agent tool not allowed: #{name}" unless tool
+
+      SchemaValidator.validate!(tool.schema, arguments)
+      tool.callable.call(arguments)
+    end
+
+    private
+
+    def build_tool(name, tool)
+      unless tool.respond_to?(:search) || tool.respond_to?(:call)
+        raise ConfigurationError, "agent tool does not support invocation: #{name}"
+      end
+
+      validate_callable_schema!(name, tool) if tool.respond_to?(:call) && !tool.respond_to?(:search)
+
+      Tool.new(
+        name: name.to_sym,
+        description: tool_description(tool),
+        schema: tool_schema(tool),
+        callable: ->(arguments) { invoke_tool(tool, arguments) }
+      )
+    end
+
+    def invoke_tool(tool, arguments)
+      return tool.call(arguments) if tool.respond_to?(:call)
+
+      invoke_search(tool, arguments)
+    end
+
+    def invoke_search(tool, arguments)
+      query = arguments["query"] || arguments[:query]
+      valid_query = query.is_a?(String) && !query.strip.empty?
+      raise MalformedActionError, "search tool requires a non-empty query" unless valid_query
+
+      tool.search(query, limit: arguments["limit"] || arguments[:limit])
+    end
+
+    def tool_description(tool)
+      return tool.description if tool.respond_to?(:description)
+
+      return "Search using the configured external capability." if tool.respond_to?(:search)
+
+      raise ConfigurationError, "generic agent tool requires a description"
+    end
+
+    def tool_schema(tool)
+      return tool.schema if tool.respond_to?(:schema)
+
+      { type: "object", required: ["query"] }
+    end
+
+    def validate_callable_schema!(name, tool)
+      schema = tool.respond_to?(:schema) ? tool.schema : nil
+      valid = schema.is_a?(Hash) && !schema.empty? && schema_value(schema, "type") == "object"
+      return if valid
+
+      raise ConfigurationError, "generic agent tool requires a non-empty object schema: #{name}"
+    end
+
+    def schema_value(schema, key)
+      return schema[key] if schema.key?(key)
+      return schema[key.to_sym] if schema.key?(key.to_sym)
+
+      nil
+    end
+  end
+end
+# rubocop:enable Style/ClassAndModuleChildren

data/lib/prescient/agent.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Prescient
+  # Optional bounded agent orchestration over Prescient Core.
+  module Agent
+  end
+end
+
+require_relative "agent/configuration"
+require_relative "agent/audit_log"
+require_relative "agent/errors"
+require_relative "agent/error_serializer"
+require_relative "agent/schema_validator"
+require_relative "agent/cli_adapter"
+require_relative "agent/result"
+require_relative "agent/context"
+require_relative "agent/parser"
+require_relative "agent/prompt_builder"
+require_relative "agent/tool_registry"
+require_relative "agent/runtime"