prescient 0.2.0 → 0.3.0

data/sig/prescient.rbs

@@ -1,4 +1,224 @@
+module HTTParty
+end
+
 module Prescient
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+    attr_reader provider: String?
+    attr_reader operation: String?
+    attr_reader status: Integer?
+
+    def initialize: (?String?, ?provider: String?, ?operation: String?, ?status: Integer?) -> void
+  end
+
+  class ConnectionError < Error
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class RateLimitError < Error
+  end
+
+  class ModelNotAvailableError < Error
+  end
+
+  class InvalidResponseError < Error
+  end
+
+  class InvalidVectorError < Error
+  end
+
+  class ProviderError < Error
+  end
+
+  class Base
+    attr_reader options: Hash[Symbol, untyped]
+    attr_reader provider_name: String
+
+    def initialize: (**untyped) -> void
+    def generate_embedding: (String, **untyped) -> Array[Float]
+    def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+    def health_check: () -> Hash[Symbol, untyped]
+    def available?: () -> bool
+
+    def validate_configuration!: () -> void
+    def handle_errors: () { () -> untyped } -> untyped
+    def validate_embedding_dimensions: (untyped, Integer) -> Array[untyped]
+    def clean_text: (untyped) -> String
+    def default_prompt_templates: () -> Hash[Symbol, String]
+    def build_prompt: (String, ?Array[untyped]) -> String
+    def default_context_configs: () -> Hash[untyped, untyped]
+    def extract_embedding_text: (untyped, ?String) -> String
+    def extract_text_values: (Hash[untyped, untyped]) -> Array[String]
+    def format_context_item: (untyped) -> String
+
+    private
+
+    def resolve_context_config: (untyped, String?) -> Hash[untyped, untyped]
+    def extract_configured_fields: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[untyped]?
+    def format_hash_item: (Hash[untyped, untyped]) -> String
+    def build_format_data: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+    def apply_format_template: (String, Hash[Symbol, untyped]) -> String?
+    def detect_context_type: (untyped) -> String
+    def match_context_by_fields: (Hash[untyped, untyped], Hash[untyped, untyped]) -> String
+    def find_best_field_match: (Array[String], Hash[untyped, untyped]) -> String?
+    def calculate_field_match_score: (Array[String], Array[String]) -> Numeric
+    def fallback_format_hash: (Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> String
+    def validate_response!: (untyped, String) -> void
+    def provider_error: (String, untyped, operation: String, ?provider: untyped, ?error_class: untyped) -> Error
+  end
+
+  module Provider
+    class Ollama < Base
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> Array[Float]
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def available_models: () -> Array[Hash[Symbol, untyped]]
+      def pull_model: (String) -> Hash[Symbol, untyped]
+
+      private
+
+      def validate_configuration!: () -> void
+      def prepare_generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def fetch_and_parse: (String, String, **untyped) -> untyped
+      def validate_response!: (untyped, String) -> void
+    end
+
+    class Anthropic < Base
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> untyped
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def api_headers: () -> Hash[String, String]
+      def validate_response!: (untyped, String) -> void
+    end
+
+    class OpenAI < Base
+      EMBEDDING_DIMENSIONS: Hash[String, Integer]
+
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> Array[Float]
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def validate_response!: (untyped, String) -> void
+      def provider_error: (String, untyped, operation: String, ?provider: untyped, ?error_class: untyped) -> Error
+    end
+
+    class HuggingFace < Base
+      FEATURE_EXTRACTION_PATH: String
+      CHAT_COMPLETIONS_PATH: String
+      MODEL_LIST_PATH: String
+      EMBEDDING_DIMENSIONS: Hash[String, Integer]
+
+      def self.base_uri: (String) -> untyped
+      def self.default_timeout: (Integer) -> untyped
+      def self.get: (String, **untyped) -> untyped
+      def self.post: (String, **untyped) -> untyped
+
+      def initialize: (**untyped) -> void
+      def generate_embedding: (String, **untyped) -> Array[Float]
+      def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+      def health_check: () -> Hash[Symbol, untyped]
+      def list_models: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      def validate_configuration!: () -> void
+      def validate_response!: (untyped, String) -> void
+    end
+  end
+
+  module Pgvector
+    class Store
+      METRICS: Hash[Symbol, String]
+
+      attr_reader dimensions: Integer
+      attr_reader table: String
+
+      def initialize: (connection: untyped, dimensions: Integer, ?table: String | Symbol) -> void
+      def install!: () -> void
+      def create_index!: (?metric: Symbol) -> void
+      def upsert: (id: untyped, embedding: Array[Numeric], provider: untyped, model: untyped, ?content: String?, ?metadata: Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+      def search: (embedding: Array[Numeric], ?limit: Integer, ?metric: Symbol, ?provider: String | Symbol?, ?model: String?) -> Array[Hash[Symbol, untyped]]
+    end
+  end
+
+  class Configuration
+    DEFAULT_SENSITIVE_KEYS: Array[Symbol]
+
+    attr_accessor default_provider: Symbol
+    attr_accessor timeout: Integer
+    attr_accessor retry_attempts: Integer
+    attr_accessor retry_delay: Float
+    attr_accessor fallback_providers: Array[Symbol]
+    attr_reader sensitive_keys: Array[Symbol]
+    attr_reader providers: Hash[Symbol, Hash[Symbol, untyped]]
+
+    def initialize: () -> void
+    def sensitive_keys=: (Array[Symbol | String]) -> Array[Symbol]
+    def add_provider: (Symbol | String, Class, **untyped) -> void
+    def provider: (Symbol | String) -> untyped
+    def available_providers: () -> Array[Symbol]
+  end
+
+  class Client
+    attr_reader provider_name: Symbol
+    attr_reader provider: untyped
+
+    def initialize: (?Symbol, ?enable_fallback: bool) -> void
+    def generate_embedding: (String, **untyped) -> Array[Float]
+    def generate_response: (String, ?Array[untyped], **untyped) -> Hash[Symbol, untyped]
+    def health_check: () -> Hash[Symbol, untyped]
+    def available?: () -> bool
+    def provider_info: () -> Hash[Symbol, untyped]
+
+    private
+
+    def sanitize_options: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    def with_error_handling: () { () -> untyped } -> untyped
+    def with_fallback_handling: (Symbol, *untyped, **untyped) -> untyped
+    def provider_for: (Symbol, Integer) -> untyped
+    def providers_to_try: () -> Array[Symbol]
+    def fallback_eligible?: (Error) -> bool
+  end
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.reset_configuration!: () -> Configuration
+  def self.client: (?Symbol, ?enable_fallback: bool) -> Client
+  def self.generate_embedding: (String, ?provider: Symbol, ?enable_fallback: bool, **untyped) -> Array[Float]
+  def self.generate_response: (String, ?Array[untyped], ?provider: Symbol, ?enable_fallback: bool, **untyped) -> Hash[Symbol, untyped]
+  def self.health_check: (?provider: Symbol) -> Hash[Symbol, untyped]
+
+  private
+
+  def self.configure_default_providers: (Configuration, untyped) -> void
 end

metadata

@@ -1,228 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: prescient
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-08-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.23.1
+        version: 0.24.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.23.1
-- !ruby/object:Gem::Dependency
-  name: pg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.25'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.25'
-- !ruby/object:Gem::Dependency
-  name: mocha
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.25'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.25'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.3'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.79'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.79'
-- !ruby/object:Gem::Dependency
-  name: rubocop-minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.38.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.38.1
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.25'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.25'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.7.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.7.1
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.3'
-- !ruby/object:Gem::Dependency
-  name: irb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.15'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.15'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.9.37
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.9.37
-- !ruby/object:Gem::Dependency
-  name: kramdown
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.5'
-description: Prescient provides a unified interface for AI providers including local
-  Ollama, Anthropic Claude, OpenAI GPT, and HuggingFace models. Built for AI applications
-  with error handling, health monitoring, and provider switching.
+        version: 0.24.0
+description: "Prescient provides a consistent interface for AI providers including
+  OpenAI, Anthropic, \nOllama, and Hugging Face, with provider selection, retries,
+  health checks, and automatic fallback.\n"
 email:
 - kenneth.c.demanawa@gmail.com
 executables: []
@@ -233,13 +36,13 @@ files:
 - ".rubocop.yml"
 - ".yardopts"
 - CHANGELOG.md
-- CHANGELOG.pdf
 - CODE_OF_CONDUCT.md
 - Dockerfile.example
 - INTEGRATION_GUIDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - VECTOR_SEARCH_GUIDE.md
 - db/init/01_enable_pgvector.sql
 - db/init/02_create_schema.sql
@@ -247,6 +50,7 @@ files:
 - db/init/04_insert_sample_data.sql
 - db/migrate/001_create_prescient_tables.rb
 - docker-compose.yml
+- examples/README.md
 - examples/basic_usage.rb
 - examples/custom_contexts.rb
 - examples/custom_prompts.rb
@@ -254,23 +58,24 @@ files:
 - lib/prescient.rb
 - lib/prescient/base.rb
 - lib/prescient/client.rb
+- lib/prescient/errors.rb
+- lib/prescient/pgvector.rb
 - lib/prescient/provider/anthropic.rb
 - lib/prescient/provider/huggingface.rb
 - lib/prescient/provider/ollama.rb
 - lib/prescient/provider/openai.rb
 - lib/prescient/version.rb
-- prescient.gemspec
 - scripts/setup-ollama-models.sh
 - sig/prescient.rbs
-homepage: https://github.com/yourcompany/prescient
+homepage: https://kanutocd.github.io/prescient
 licenses:
 - MIT
 metadata:
-  allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/yourcompany/prescient
-  source_code_uri: https://github.com/yourcompany/prescient
-  changelog_uri: https://github.com/yourcompany/prescient/blob/main/CHANGELOG.md
-post_install_message: 
+  homepage_uri: https://kanutocd.github.io/prescient
+  source_code_uri: https://github.com/kanutocd/prescient
+  changelog_uri: https://github.com/kanutocd/prescient/blob/main/CHANGELOG.md
+  documentation_uri: https://kanutocd.github.io/prescient
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -285,8 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Prescient AI provider abstraction for Ruby applications
+summary: A boring AI provider abstraction for Ruby
 test_files: []

data/prescient.gemspec

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/prescient/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "prescient"
-  spec.version = Prescient::VERSION
-  spec.authors = ["Ken C. Demanawa"]
-  spec.email = ["kenneth.c.demanawa@gmail.com"]
-
-  spec.summary = "Prescient AI provider abstraction for Ruby applications"
-  spec.description = "Prescient provides a unified interface for AI providers including local Ollama, Anthropic Claude, OpenAI GPT, and HuggingFace models. Built for AI applications with error handling, health monitoring, and provider switching."
-  spec.homepage = "https://github.com/yourcompany/prescient"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.1.0"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/yourcompany/prescient"
-  spec.metadata["changelog_uri"] = "https://github.com/yourcompany/prescient/blob/main/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Runtime dependencies
-  spec.add_dependency "httparty", "~> 0.23.1"
-
-  # Optional dependencies for vector database integration
-  spec.add_development_dependency "pg", "~> 1.6" # PostgreSQL adapter for pgvector integration
-
-  # Development dependencies
-  spec.add_development_dependency "minitest", "~> 5.25"
-  spec.add_development_dependency "mocha", "~> 2.7"
-  spec.add_development_dependency "webmock", "~> 3.25"
-  spec.add_development_dependency "vcr", "~> 6.3"
-  spec.add_development_dependency "rubocop", "~> 1.79"
-  spec.add_development_dependency "rubocop-minitest", "~> 0.38.1"
-  spec.add_development_dependency "rubocop-performance", "~> 1.25"
-  spec.add_development_dependency "rubocop-rake", "~> 0.7.1"
-  spec.add_development_dependency "simplecov", "~> 0.22.0"
-  spec.add_development_dependency "rake", "~> 13.3"
-  spec.add_development_dependency "irb", "~> 1.15"
-  spec.add_development_dependency "yard", "~> 0.9.37"
-  spec.add_development_dependency "kramdown", "~> 2.5"
-end