prescient 0.7.0 → 0.8.0

data/db/migrate/001_create_prescient_tables.rb

@@ -2,11 +2,10 @@
 
 # Rails migration for Prescient gem vector database tables
 # Copy this file to your Rails db/migrate directory and adjust the timestamp
-
 class CreatePrescientTables < ActiveRecord::Migration[7.0]
   def up
     # Enable pgvector extension
-    enable_extension 'vector'
+    enable_extension "vector"
 
     # Documents table to store original content
     create_table :documents do |t|
@@ -76,14 +75,14 @@ class CreatePrescientTables < ActiveRecord::Migration[7.0]
     add_index :documents, :metadata, using: :gin
 
     add_index :document_embeddings, :document_id
-    add_index :document_embeddings, [:embedding_provider, :embedding_model], name: 'idx_doc_embeddings_provider_model'
+    add_index :document_embeddings, %i[embedding_provider embedding_model], name: "idx_doc_embeddings_provider_model"
     add_index :document_embeddings, :embedding_dimensions
 
-    add_index :document_chunks, [:document_id, :chunk_index], unique: true
+    add_index :document_chunks, %i[document_id chunk_index], unique: true
 
     add_index :chunk_embeddings, :chunk_id
     add_index :chunk_embeddings, :document_id
-    add_index :chunk_embeddings, [:embedding_provider, :embedding_model], name: 'idx_chunk_embeddings_provider_model'
+    add_index :chunk_embeddings, %i[embedding_provider embedding_model], name: "idx_chunk_embeddings_provider_model"
 
     add_index :search_queries, :created_at
     add_index :query_results, :query_id
@@ -94,30 +93,30 @@ class CreatePrescientTables < ActiveRecord::Migration[7.0]
 
     # Vector indexes for document embeddings
     execute <<-SQL
-      CREATE INDEX idx_document_embeddings_cosine#{' '}
-      ON document_embeddings#{' '}
+      CREATE INDEX idx_document_embeddings_cosine#{" "}
+      ON document_embeddings#{" "}
       USING hnsw (embedding vector_cosine_ops)
       WITH (m = 16, ef_construction = 64);
     SQL
 
     execute <<-SQL
-      CREATE INDEX idx_document_embeddings_l2#{' '}
-      ON document_embeddings#{' '}
+      CREATE INDEX idx_document_embeddings_l2#{" "}
+      ON document_embeddings#{" "}
       USING hnsw (embedding vector_l2_ops)
       WITH (m = 16, ef_construction = 64);
     SQL
 
     # Vector indexes for chunk embeddings
     execute <<-SQL
-      CREATE INDEX idx_chunk_embeddings_cosine#{' '}
-      ON chunk_embeddings#{' '}
+      CREATE INDEX idx_chunk_embeddings_cosine#{" "}
+      ON chunk_embeddings#{" "}
       USING hnsw (embedding vector_cosine_ops)
       WITH (m = 16, ef_construction = 64);
     SQL
 
     execute <<-SQL
-      CREATE INDEX idx_chunk_embeddings_l2#{' '}
-      ON chunk_embeddings#{' '}
+      CREATE INDEX idx_chunk_embeddings_l2#{" "}
+      ON chunk_embeddings#{" "}
       USING hnsw (embedding vector_l2_ops)
       WITH (m = 16, ef_construction = 64);
     SQL
@@ -150,9 +149,9 @@ class CreatePrescientTables < ActiveRecord::Migration[7.0]
     drop_table :document_embeddings
     drop_table :documents
 
-    execute 'DROP FUNCTION IF EXISTS cosine_similarity(vector, vector);'
-    execute 'DROP FUNCTION IF EXISTS euclidean_distance(vector, vector);'
+    execute "DROP FUNCTION IF EXISTS cosine_similarity(vector, vector);"
+    execute "DROP FUNCTION IF EXISTS euclidean_distance(vector, vector);"
 
-    disable_extension 'vector'
+    disable_extension "vector"
   end
 end

data/examples/README.md

@@ -18,7 +18,8 @@ bundle install
 - `vector_search.rb` — `Prescient::Pgvector::Store` PostgreSQL/pgvector storage
   and similarity search.
 - `rest_api.ru` — a tiny Rack-compatible application that mounts
-  `Prescient::API` and lists its endpoints at `/`.
+  `Prescient::API` and lists its endpoints at `/`, including the bounded agent
+  and search-generation routes.
 - `web_search.rb` — explicit SearXNG tool invocation with normalized JSON output.
 
 The same `web_search` capability can use SearchApi instead of SearXNG when the

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/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