prescient 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e272a00a9f7baaee44c4ad7b9827da6c1e5b930a98228e8d58718474d3090214
-  data.tar.gz: a7ac75b948c326d0829db56e0ab297561d178fa4643a6a4bbd5b4dc11cff150b
+  metadata.gz: 3dc5e5bb3c441f18ba241696a3b37e2bd127b1cdbf312f5ec80adb6717f84b69
+  data.tar.gz: 361bdbe883a03971f796491ff19a30c514e6a105702f3f19cc251ab6eb1feaeb
 SHA512:
-  metadata.gz: 1e4ff77f5dd524e7bc3217b4f8fc1b8045f43d188b751f81dc2964dcf2d15dbfd3ed58efe8598ba40bd875e19a3597de1308e32c066466713b06af8e79fea55a
-  data.tar.gz: 3f5f8e5f78bc8db0566102f686ce1b66e752f9f81faba9dae09adfa49883aaa67c621b108b9a60cb573d695cae4874567e2ebf1c69b90a3971a6686f0316c288
+  metadata.gz: 0b46cf882af6fb5810c320ef5ec5276e7f89c7df6050fa9dd3f953ce6264264c160a9347a91cf79dfc443d882fc1c1304dd26e6a63ae6bd4ae91a18fe8274635
+  data.tar.gz: 7efc84dbb4acbc637914c4839f0ae269d132d3e91aec48253d09f7ae6efd9b44fa7692a4feed86ec36fdbd303e461533f31fbefe66243c683daa4f5f2857ab45

data/.rubocop.yml

@@ -9,8 +9,8 @@ plugins:
   - rubocop-rake
 
 AllCops:
-  # Target Ruby 3.1+ (matches gemspec requirement)
-  TargetRubyVersion: 3.1
+  # Target Ruby 3.2+ (matches gemspec requirement)
+  TargetRubyVersion: 3.2
   # Use new cops by default
   NewCops: enable
   # Exclude common directories
@@ -78,4 +78,4 @@ Metrics/CyclomaticComplexity:
   Max: 10
 
 Style/DirectiveScope:
-  Enabled: false
+  Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## [0.8.2] - 2026-11-09
+
+### Breaking changes
+
+- Dropped support for Ruby 3.1. Ruby 3.2 or newer is now required.
+
+## [0.8.1] - 2025-09-10
+
+### Fixed
+
+- Fixed the Agent audit-log load path to avoid a circular-require warning while
+  preserving lazy loading of the optional Agent implementation.
+- Replaced the Agent parser's polynomial-time fenced-JSON regular expression
+  with a linear scanner to prevent ReDoS behavior on untrusted provider output.
+- Added Agent parser regression coverage for nested objects, escaped string
+  values, malformed fences, and repeated unterminated action prefixes.
+
 ## [0.8.0] - 2025-08-31
 
 ### Added

data/CONTRIBUTING.md

@@ -0,0 +1,192 @@
+# Contributing to Prescient
+
+Thank you for your interest in contributing to Prescient! Prescient is a Ruby gem that provides a unified, predictable gateway to multiple AI providers, including Ollama, OpenAI, Anthropic, Google Gemini, Mistral, Hugging Face, DeepSeek, and xAI.
+
+Prescient is designed as a reusable library rather than an application. The library values explicit provider boundaries, predictable error handling, modern idiomatic Ruby, and stable public APIs.
+
+This guide explains how to set up your local development environment, run tests, follow coding standards, and submit pull requests.
+
+---
+
+## Code of conduct
+
+By participating in this project, you agree to follow the project's [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## Development setup
+
+### Prerequisites
+
+Ensure you have the following installed on your local system:
+
+- **Ruby**: Version 3.2 or higher (the CI matrix tests Ruby 3.2, 3.3, 3.4, and 4.0).
+- **Bundler**: Version 2.0 or higher.
+- **Docker & Docker Compose** *(optional, for local service testing)*: Required if you test against local instances of Ollama, SearXNG, or PostgreSQL with pgvector.
+
+### Setting up the workspace
+
+1. Fork and clone the repository:
+
+   ```bash
+   git clone https://github.com/kanutocd/prescient.git
+   cd prescient
+   ```
+
+2. Install development dependencies:
+
+   ```bash
+   bundle install
+   ```
+
+3. *(Optional)* Start local services using Docker Compose:
+
+   ```bash
+   docker compose up -d ollama postgres searxng
+   docker compose run --rm ollama-init
+   ```
+
+---
+
+## Running tests and checks
+
+Prescient uses Minitest for unit and integration testing, RuboCop for code linting, and RBS/Steep for type checking. Establish a green test baseline before making changes.
+
+### Running unit and integration tests
+
+Run the complete test suite:
+
+```bash
+bundle exec rake test
+```
+
+To run a single test file during development, execute:
+
+```bash
+bundle exec ruby -Itest test/prescient/client_test.rb
+```
+
+To run a specific test by name, pass the line or name filter:
+
+```bash
+bundle exec ruby -Itest test/prescient/client_test.rb -n /generate_response/
+```
+
+### Running code linter
+
+Prescient enforces RuboCop styling rules:
+
+```bash
+bundle exec rubocop
+```
+
+Fix safe auto-correctable offenses with:
+
+```bash
+bundle exec rubocop -A
+```
+
+### Type validation with RBS and Steep
+
+Validate core API type signatures with:
+
+```bash
+bundle exec rake rbs:validate
+```
+
+To inspect generated RBS prototypes or differences:
+
+```bash
+bundle exec rake rbs:prototype
+bundle exec rake rbs:diff
+```
+
+### Opt-in live provider smoke tests
+
+The default test suite uses WebMock and VCR to mock external HTTP requests. Tests never execute against live cloud providers by default.
+
+To test against live provider APIs, set `PRESCIENT_LIVE_SMOKE=1` and specify the target providers in `PRESCIENT_LIVE_PROVIDERS`:
+
+```bash
+PRESCIENT_LIVE_SMOKE=1 \
+PRESCIENT_LIVE_PROVIDERS=openai \
+OPENAI_API_KEY=your_actual_key \
+bundle exec ruby -Itest test/prescient/live_provider_smoke_test.rb
+```
+
+Supported live provider keys are `ollama`, `openai`, `anthropic`, `gemini`, `mistral`, `huggingface`, `deepseek`, and `xai`.
+
+---
+
+## Architecture guidelines
+
+### Provider abstraction
+
+Provider-specific behavior belongs in provider adapters (`lib/prescient/provider/`). Common behavior belongs in base abstractions (`lib/prescient/base.rb`).
+
+When creating or updating a provider adapter:
+
+1. **Inherit from `Prescient::Base`**: Subclass `Prescient::Base` and define required methods: `#generate_response`, `#generate_embedding` (if supported), and `#health_check`.
+2. **Isolate HTTP details**: Use HTTParty or standard-library HTTP tools inside the adapter. Keep raw network details out of caller code.
+3. **Normalize Responses**: Return standard response shapes from `#generate_response`:
+   ```ruby
+   {
+     response: "Generated text response",
+     model: "configured-model-name",
+     provider: "provider_name",
+     processing_time: nil,
+     metadata: { ... }
+   }
+   ```
+4. **Enforce embedding dimensions**: Validate vectors with `validate_embedding_dimensions`. Never pad or truncate vectors silently.
+5. **Map Provider Errors**: Wrap raw HTTP or API errors into standard Prescient exception classes.
+
+### Error mapping hierarchy
+
+All gem exceptions inherit from `Prescient::Error`. Map provider-specific failures into the appropriate exception category:
+
+| Exception Class | Primary Cause | Retryable by Fallback? |
+| :--- | :--- | :--- |
+| `Prescient::ConnectionError` | Network failures, HTTP timeouts, DNS resolution failures | Yes |
+| `Prescient::RateLimitError` | Provider HTTP 429 status | Yes |
+| `Prescient::ModelNotAvailableError` | Provider HTTP 404 status or unavailable model | Yes |
+| `Prescient::ProviderError` | Provider HTTP 5xx server errors | Yes |
+| `Prescient::AuthenticationError` | Provider HTTP 401/403 invalid API keys | No |
+| `Prescient::InvalidResponseError` | Malformed JSON responses or vector dimension mismatches | No |
+| `Prescient::ToolError` | Base class for external search tool adapter failures | Varies |
+
+### Retry vs fallback semantics
+
+- **Retries**: Retries apply to transient network errors (`ConnectionError`, `RateLimitError`) within a single provider, governed by `config.retry_attempts` and `config.retry_delay`.
+- **Fallback**: Provider fallback triggers when a provider encounters a persistent or service-side failure (`ConnectionError`, `RateLimitError`, `ModelNotAvailableError`, `ProviderError`). Fallback cascades in configured provider order. Caller misuse (invalid parameters, authentication failures) is never retried with fallback.
+
+---
+
+## Public API compatibility
+
+Treat the following items as public API contracts:
+
+- Methods on `Prescient`: `.configure`, `.client`, `.generate_embedding`, `.generate_response`, `.search_and_generate`, `.health_check`, `.load_configuration`.
+- Configuration options: `Configuration` class properties (`default_provider`, `timeout`, `retry_attempts`, `retry_delay`, `fallback_providers`, `sensitive_keys`).
+- Standard return shapes for generation, embeddings, health checks, and tool search results.
+
+If your changes modify a public API contract:
+
+1. Update the corresponding unit and integration tests in `test/`.
+2. Update example scripts in `examples/`.
+3. Update documentation files (`README.md`, `INTEGRATION_GUIDE.md`, `VECTOR_SEARCH_GUIDE.md`).
+
+---
+
+## Submitting pull requests
+
+Before opening a pull request:
+
+1. Ensure all tests pass: `bundle exec rake test`.
+2. Ensure RuboCop checks pass: `bundle exec rubocop`.
+3. Inspect your diff to ensure no sensitive credentials, VCR tokens, or temporary files are included:
+   ```bash
+   git diff
+   ```
+4. Write clear, imperative commit messages (for example, `Add Google Gemini model listing support`).
+5. Open a pull request against the `main` branch with a clear description of your changes and motivation.

data/INTEGRATION_GUIDE.md

@@ -11,7 +11,7 @@ and [examples guide](examples/README.md).
 
 ```ruby
 # Add to your Gemfile
-gem 'prescient', '~> 0.8.0'
+gem 'prescient', '~> 0.8.2'
 ```
 
 ### 2. Replace Existing AI Service

data/README.md

@@ -1,7 +1,7 @@
 # Prescient
 
 [![Gem Version](https://img.shields.io/gem/v/prescient?logo=rubygems&logoColor=white)](https://rubygems.org/gems/prescient)
-[![Requires Ruby 3.1+](https://img.shields.io/badge/Requires-Ruby%203.1%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Requires Ruby 3.2+](https://img.shields.io/badge/Requires-Ruby%203.2%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
 [![Docker](https://img.shields.io/badge/Docker-GHCR-2496ED?logo=docker&logoColor=white)](https://github.com/kanutocd/prescient/pkgs/container/prescient)
 [![CI](https://github.com/kanutocd/prescient/actions/workflows/ci.yml/badge.svg)](https://github.com/kanutocd/prescient/actions/workflows/ci.yml)
 [![Security](https://img.shields.io/github/actions/workflow/status/kanutocd/prescient/security.yml?branch=main&event=push&label=Security)](https://github.com/kanutocd/prescient/actions/workflows/security.yml)

data/lib/prescient/agent/parser.rb

@@ -4,8 +4,12 @@
 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
+    # @return [String] Opening fenced JSON marker
+    JSON_FENCE = "```json".b.freeze
+    # @return [String] Closing fenced JSON marker
+    CLOSING_FENCE = "```".b.freeze
+    # @return [Array<Integer>] JSON whitespace byte values
+    WHITESPACE_BYTES = [9, 10, 11, 12, 13, 32].freeze
 
     # Parse one optional action from provider output.
     # @param text [String] Provider response text
@@ -23,11 +27,11 @@ module Prescient::Agent
     # @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
+      action_json = extract_action_json(text.to_s)
+      return nil unless action_json
+      raise MalformedActionError, "agent action exceeds configured size limit" if action_json.bytesize > @max_bytes
 
-      payload = JSON.parse(match[1])
+      payload = JSON.parse(action_json)
       validate_payload(payload)
       { name: payload.fetch("action").to_sym, arguments: payload.fetch("args") }
     rescue JSON::ParserError => e
@@ -36,6 +40,84 @@ module Prescient::Agent
 
     private
 
+    def extract_action_json(text)
+      source = text.b
+      cursor = 0
+
+      while (fence_start = source.index(JSON_FENCE, cursor))
+        content_start = skip_whitespace(source, fence_start + JSON_FENCE.bytesize)
+        unless source.getbyte(content_start) == 123
+          cursor = content_start
+          next
+        end
+
+        action_json, next_cursor = scan_json_object(source, content_start)
+        return action_json if action_json
+
+        cursor = next_cursor
+      end
+
+      nil
+    end
+
+    def scan_json_object(source, start)
+      depth = 0
+      escaped = false
+      in_string = false
+      index = start
+
+      while index < source.bytesize
+        byte = source.getbyte(index)
+        if in_string
+          in_string, escaped = string_state(byte, escaped)
+        elsif fence_at?(source, index)
+          return [nil, index]
+        else
+          in_string = byte == 34
+          depth = depth_after(byte, depth)
+          return completed_action(source, start, index) if byte == 125 && depth.zero?
+        end
+        index += 1
+      end
+
+      [nil, source.bytesize]
+    end
+
+    def string_state(byte, escaped)
+      return [true, false] if escaped
+      return [true, true] if byte == 92
+      return [false, false] if byte == 34
+
+      [true, false]
+    end
+
+    def fence_at?(source, index)
+      byte = source.getbyte(index)
+      byte == 96 && source.byteslice(index, JSON_FENCE.bytesize) == JSON_FENCE
+    end
+
+    def depth_after(byte, depth)
+      case byte
+      when 123 then depth + 1
+      when 125 then depth - 1
+      else depth
+      end
+    end
+
+    def completed_action(source, start, index)
+      closing_start = skip_whitespace(source, index + 1)
+      return [nil, closing_start] unless source.byteslice(closing_start, CLOSING_FENCE.bytesize) == CLOSING_FENCE
+
+      length = index + 1 - start
+      [source.byteslice(start, length).force_encoding(Encoding::UTF_8), index + 1]
+    end
+
+    def skip_whitespace(source, start)
+      index = start
+      index += 1 while index < source.bytesize && WHITESPACE_BYTES.include?(source.getbyte(index))
+      index
+    end
+
     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"

data/lib/prescient/agent.rb

@@ -5,11 +5,11 @@ require "json"
 module Prescient
   # Optional bounded agent orchestration over Prescient Core.
   module Agent
+    autoload :AuditLog, "prescient/agent/audit_log"
   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"

data/lib/prescient/client.rb

@@ -232,8 +232,8 @@ module Prescient
   # @param provider [Symbol, nil] Provider to use
   # @param enable_fallback [Boolean] Whether provider fallback is enabled
   # @return [Array<Float>] Embedding vector
-  def self.generate_embedding(text, provider: nil, enable_fallback: true, **options)
-    client(provider, enable_fallback: enable_fallback).generate_embedding(text, **options)
+  def self.generate_embedding(text, provider: nil, enable_fallback: true, **)
+    client(provider, enable_fallback: enable_fallback).generate_embedding(text, **)
   end
 
   # Generate a response through a configured provider.
@@ -244,8 +244,8 @@ module Prescient
   # @param enable_fallback [Boolean] Whether provider fallback is enabled
   # @return [Hash] Normalized provider response with :response, :model, :provider
   #   and optional metadata
-  def self.generate_response(prompt, context_items = [], provider: nil, enable_fallback: true, **options)
-    client(provider, enable_fallback: enable_fallback).generate_response(prompt, context_items, **options)
+  def self.generate_response(prompt, context_items = [], provider: nil, enable_fallback: true, **)
+    client(provider, enable_fallback: enable_fallback).generate_response(prompt, context_items, **)
   end
 
   # Search with an explicit external tool and optionally use the normalized
@@ -259,7 +259,7 @@ module Prescient
   # @param provider_options [Hash] Temporary provider configuration overrides
   # @return [Hash] Normalized provider response
   def self.search_and_generate(query, tool: :web_search, provider: nil, limit: nil,
-                               enable_fallback: true, provider_options: {}, **options)
+                               enable_fallback: true, provider_options: {}, **)
     search_tool = self.tool(tool)
     raise Prescient::ToolConfigurationError, "tool not configured: #{tool}" unless search_tool
 
@@ -270,7 +270,7 @@ module Prescient
     client(provider, enable_fallback:, provider_options:).generate_response(
       query,
       context_items,
-      **options
+      **
     )
   end
 

data/lib/prescient/document_source.rb

@@ -53,8 +53,8 @@ module Prescient
     # Validate and bound application-provided JSON documents.
     class Memory < Base
       # @param documents [Array<Hash>, Hash] Documents to validate
-      def initialize(documents:, **options)
-        super(**options)
+      def initialize(documents:, **)
+        super(**)
         @documents = documents
       end
 
@@ -67,8 +67,8 @@ module Prescient
     # Read JSON documents from a local file.
     class JsonFile < Base
       # @param path [String] JSON file path
-      def initialize(path:, **options)
-        super(**options)
+      def initialize(path:, **)
+        super(**)
         @path = path
         return if @path.is_a?(String) && !@path.empty?
 
@@ -91,8 +91,8 @@ module Prescient
     class RedisJson < Base
       # @param client [#get] Redis-compatible client
       # @param key [String] Redis key containing a JSON document or array
-      def initialize(client:, key:, **options)
-        super(**options)
+      def initialize(client:, key:, **)
+        super(**)
         @client = client
         @key = key
         return if @key.is_a?(String) && !@key.empty?

data/lib/prescient/version.rb

@@ -2,5 +2,5 @@
 
 module Prescient
   # Current Prescient gem version.
-  VERSION = "0.8.0"
+  VERSION = "0.8.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prescient
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -41,6 +41,7 @@ files:
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - Dockerfile
 - Dockerfile.example
 - INTEGRATION_GUIDE.md
@@ -125,14 +126,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A boring AI provider gateway for Ruby
 test_files: []