prescient 0.2.0 → 0.4.0

data/README.md

@@ -1,6 +1,10 @@
 # Prescient
 
-Prescient provides a unified interface for AI providers including Ollama (local), Anthropic Claude, OpenAI GPT, and HuggingFace models. Built for prescient applications that need AI predictions with provider switching, error handling, and fallback mechanisms.
+Prescient is a boring AI provider abstraction for Ruby. Configure your AI providers once, then use the same interface regardless of whether the request is handled by OpenAI, Anthropic, Ollama, or Hugging Face. Prescient handles provider selection, retries, health checks, and fallback.
+
+For focused guidance, see the **[examples guide](https://github.com/kanutocd/prescient/tree/main/examples)**,
+**[Rails integration guide](https://github.com/kanutocd/prescient/blob/main/INTEGRATION_GUIDE.md)**, and
+**[pgvector guide](https://github.com/kanutocd/prescient/blob/main/VECTOR_SEARCH_GUIDE.md)**.
 
 ## Features
 
@@ -16,19 +20,19 @@ Prescient provides a unified interface for AI providers including Ollama (local)
 
 ### Ollama (Local)
 
-- **Models**: Any Ollama-compatible model (llama3.1, nomic-embed-text, etc.)
+- **Models**: Any Ollama-compatible model (llama3.2, nomic-embed-text, etc.)
 - **Capabilities**: Embeddings, Text Generation, Model Management
 - **Use Case**: Privacy-focused, local deployments
 
 ### Anthropic Claude
 
-- **Models**: Claude 3 (Haiku, Sonnet, Opus)
+- **Models**: Current Claude models selected through the Anthropic Models API
 - **Capabilities**: Text Generation only (no embeddings)
 - **Use Case**: High-quality conversational AI
 
 ### OpenAI
 
-- **Models**: GPT-3.5, GPT-4, text-embedding-3-small/large
+- **Models**: Current GPT and text-embedding models selected through the OpenAI Models API
 - **Capabilities**: Embeddings, Text Generation
 - **Use Case**: Proven performance, wide model selection
 
@@ -58,6 +62,90 @@ Or install it yourself as:
 gem install prescient
 ```
 
+## Command-Line Interface
+
+Prescient includes a thin CLI for provider inspection and common operations:
+
+```bash
+prescient providers
+prescient health
+prescient config validate
+prescient generate "Explain Ruby Ractors"
+prescient embed "Ruby is a programming language"
+```
+
+Supported options include:
+
+```text
+--provider NAME          Select a provider
+--model NAME             Override the selected operation's model
+--chat-model NAME        Override the chat model for generation
+--embedding-model NAME   Override the embedding model
+--api-key KEY            Use an API key for the operation
+--api-key-env NAME       Read the API key from an environment variable
+--format FORMAT          Select text or json output
+```
+
+Use `--api-key-env` to source credentials from an environment variable. The
+direct `--api-key` option is available for ephemeral automation but may be
+visible in shell history or process listings. Use `--format json` for
+machine-readable output and stdin for shell pipelines:
+
+```bash
+printf '%s' "Explain PostgreSQL logical replication" | \
+  prescient generate --provider openai --format json
+```
+
+Example JSON output:
+
+```json
+{
+    "response": "PostgreSQL logical replication is a method of replicating data between PostgreSQL databases at a logical level, allowing fine-grained control over which data is replicated and how. Unlike physical replication, which copies the entire database cluster’s data files at the storage level, logical replication works by sending changes to data (such as INSERT, UPDATE, DELETE operations) based on logical changes in the database.\n\n### Key Features of PostgreSQL Logical Replication\n\n1. **Row-Level Replication:** Logical replication replicates data changes at the row level. It streams changes to individual tables rather than the entire database.\n\n2. **Selective Replication:** You can choose specific tables to replicate rather than the whole database. This makes it useful for replicating subsets of data.\n\n3. **Asynchronous Replication:** Changes are sent asynchronously from the publisher (source) to the subscriber (target). This means there may be a slight delay between when changes are made and when they appear on the subscriber.\n\n4. **Supports Heterogeneous Setups:** Logical replication can be used between different major versions of PostgreSQL, allowing upgrades with minimal downtime. It can also be used for replication between different architectures or operating systems.\n\n5. **Bidirectional Replication:** By configuring multiple publishers and subscribers, logical replication can support multi-master setups, although care must be taken to avoid conflicts.\n\n### How Logical Replication Works\n\n- **Publisher:** The database that sends data changes. It defines one or more publications, which specify which tables and changes (inserts, updates, deletes) to replicate.\n  \n- **Subscriber:** The database that receives and applies the changes. It subscribes to one or more publications from the publisher.\n\nWhen a change occurs on the publisher's table, the change is captured and sent to the subscriber, where it is applied to the corresponding table.\n\n### Setting Up Logical Replication (Basic Steps)\n\n1. **Enable required settings:** Ensure the PostgreSQL server has `wal_level` set to `logical`, and configure `max_replication_slots` and `max_wal_senders` appropriately.\n\n2. **Create a publication on the publisher:**\n\n   ```sql\n   CREATE PUBLICATION my_publication FOR TABLE my_table;\n   ```\n\n3. **Create a subscription on the subscriber:**\n\n   ```sql\n   CREATE SUBSCRIPTION my_subscription\n   CONNECTION 'host=publisher_host dbname=publisher_db user=replicator password=secret'\n   PUBLICATION my_publication;\n   ```\n\nOnce set up, changes to `my_table` on the publisher will be replicated to the subscriber.\n\n### Use Cases\n\n- **Selective data replication:** Replicating only certain tables or rows.\n- **Data integration:** Feeding data from multiple sources into a central database.\n- **Upgrading PostgreSQL versions:** Using logical replication to migrate data with minimal downtime.\n- **Multi-datacenter replication:** Replicating data across geographically distributed systems.\n\n---\n\nIn summary, PostgreSQL logical replication is a flexible, table-level replication mechanism that allows selective, asynchronous replication of data changes between PostgreSQL databases, useful for upgrades, distributed architectures, and data integration scenarios.",
+    "model": "gpt-4.1-mini",
+    "provider": "openai",
+    "processing_time": null,
+    "metadata": {
+        "usage": {
+            "prompt_tokens": 38,
+            "completion_tokens": 632,
+            "total_tokens": 670,
+            "prompt_tokens_details": {
+                "cached_tokens": 0,
+                "audio_tokens": 0
+            },
+            "completion_tokens_details": {
+                "reasoning_tokens": 0,
+                "audio_tokens": 0,
+                "accepted_prediction_tokens": 0,
+                "rejected_prediction_tokens": 0
+            }
+        },
+        "finish_reason": "stop"
+    }
+}
+```
+
+For automated model and credential overrides:
+
+```bash
+prescient generate \
+  --provider openai \
+  --chat-model gpt-4.1-mini \
+  --api-key-env OPENAI_API_KEY \
+  --format json \
+  "Explain PostgreSQL logical replication"
+
+prescient embed \
+  --provider openai \
+  --embedding-model text-embedding-3-small \
+  --api-key-env OPENAI_API_KEY \
+  "Ruby is a programming language"
+```
+
+The CLI writes results to stdout, diagnostics to stderr, and returns a
+non-zero status for invalid usage, provider errors, or unreachable health
+checks. It uses the same `Prescient::Client` execution path as Ruby callers.
+
 ## Configuration
 
 ### Environment Variables
@@ -66,21 +154,21 @@ gem install prescient
 # Ollama (Local)
 OLLAMA_URL=http://localhost:11434
 OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-OLLAMA_CHAT_MODEL=llama3.1:8b
+OLLAMA_CHAT_MODEL=llama3.2:3b
 
 # Anthropic
 ANTHROPIC_API_KEY=your_api_key
-ANTHROPIC_MODEL=claude-3-haiku-20240307
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
 
 # OpenAI
 OPENAI_API_KEY=your_api_key
 OPENAI_EMBEDDING_MODEL=text-embedding-3-small
-OPENAI_CHAT_MODEL=gpt-3.5-turbo
+OPENAI_CHAT_MODEL=gpt-4.1-mini
 
 # HuggingFace
 HUGGINGFACE_API_KEY=your_api_key
 HUGGINGFACE_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
-HUGGINGFACE_CHAT_MODEL=microsoft/DialoGPT-medium
+HUGGINGFACE_CHAT_MODEL=google/gemma-2-2b-it
 ```
 
 ### Programmatic Configuration
@@ -96,23 +184,23 @@ Prescient.configure do |config|
   config.retry_delay = 1.0
 
   # Add custom Ollama configuration
-  config.add_provider(:ollama, Prescient::Ollama::Provider,
+  config.add_provider(:ollama, Prescient::Provider::Ollama,
     url: 'http://localhost:11434',
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b'
+    chat_model: 'llama3.2:3b'
   )
 
   # Add Anthropic
-  config.add_provider(:anthropic, Prescient::Anthropic::Provider,
+  config.add_provider(:anthropic, Prescient::Provider::Anthropic,
     api_key: ENV['ANTHROPIC_API_KEY'],
-    model: 'claude-3-haiku-20240307'
+    model: 'claude-sonnet-4-20250514'
   )
 
   # Add OpenAI
-  config.add_provider(:openai, Prescient::OpenAI::Provider,
+  config.add_provider(:openai, Prescient::Provider::OpenAI,
     api_key: ENV['OPENAI_API_KEY'],
     embedding_model: 'text-embedding-3-small',
-    chat_model: 'gpt-3.5-turbo'
+    chat_model: 'gpt-4.1-mini'
   )
 end
 ```
@@ -127,19 +215,19 @@ Prescient.configure do |config|
   config.add_provider(:primary, Prescient::Provider::OpenAI,
     api_key: ENV['OPENAI_API_KEY'],
     embedding_model: 'text-embedding-3-small',
-    chat_model: 'gpt-3.5-turbo'
+    chat_model: 'gpt-4.1-mini'
   )
   
   # Configure backup providers
   config.add_provider(:backup1, Prescient::Provider::Anthropic,
     api_key: ENV['ANTHROPIC_API_KEY'],
-    model: 'claude-3-haiku-20240307'
+    model: 'claude-sonnet-4-20250514'
   )
   
   config.add_provider(:backup2, Prescient::Provider::Ollama,
     url: 'http://localhost:11434',
     embedding_model: 'nomic-embed-text',
-    chat_model: 'llama3.1:8b'
+    chat_model: 'llama3.2:3b'
   )
   
   # Configure fallback order
@@ -158,9 +246,10 @@ response = Prescient.generate_response("Hello", provider: :primary, enable_fallb
 
 **Fallback Behavior:**
 - When a provider fails with a persistent error, Prescient automatically tries the next available provider
-- Only available (healthy) providers are tried during fallback
-- If no fallback providers are configured, all available providers are tried as fallbacks
+- Configured fallback providers are tried in order; the provider operation determines availability
+- If no fallback providers are configured, all configured providers are tried as fallbacks
 - Transient errors (rate limits, timeouts) still use retry logic before fallback
+- Provider-service failures, connection failures, rate limits, and unavailable models may trigger fallback; authentication and invalid-request errors are returned to the caller
 - The fallback process preserves all method arguments and options
 
 ## Usage
@@ -175,7 +264,7 @@ client = Prescient.client
 
 # Generate embeddings
 embedding = client.generate_embedding("Your text here")
-# => [0.1, 0.2, 0.3, ...] (768-dimensional vector)
+# => [0.1, 0.2, 0.3, ...] (model-dependent vector dimensions)
 
 # Generate text responses
 response = client.generate_response("What is Ruby?")
@@ -238,12 +327,20 @@ end
 
 ### Health Monitoring
 
+Health results separate transport reachability from configured-model readiness:
+`reachable: true` means the provider answered, while `ready: true` means the
+configured operation models were found or validated. Fallback uses the actual
+operation and does not perform an additional health request.
+
 ```ruby
 # Check all providers
-[:ollama, :anthropic, :openai, :huggingface].each do |provider|
+Prescient.configuration.providers.keys.each do |provider|
   health = Prescient.health_check(provider: provider)
   puts "#{provider}: #{health[:status]}"
-  puts "Ready: #{health[:ready]}" if health[:ready]
+  puts "Reachable: #{health[:reachable]}"
+  puts "Ready: #{health[:ready]}"
+rescue Prescient::Error => e
+  puts "#{provider}: unavailable (#{e.message})"
 end
 ```
 
@@ -256,7 +353,7 @@ Prescient.configure do |config|
   config.add_provider(:customer_service, Prescient::Provider::OpenAI,
     api_key: ENV['OPENAI_API_KEY'],
     embedding_model: 'text-embedding-3-small',
-    chat_model: 'gpt-3.5-turbo',
+    chat_model: 'gpt-4.1-mini',
     prompt_templates: {
       system_prompt: 'You are a friendly customer service representative.',
       no_context_template: <<~TEMPLATE.strip,
@@ -330,12 +427,12 @@ Prescient.configure do |config|
     context_configs: {
       'product' => {
         fields: %w[name description price category brand],
-        format: '%{ name } by %{ brand }: %{ description } - $%{ price } (%{ category })',
+        format: '%{name} by %{brand}: %{description} - $%{price} (%{category})',
         embedding_fields: %w[name description category brand]
       },
       'review' => {
         fields: %w[product_name rating review_text reviewer_name],
-        format: '%{ product_name } - %{ rating }/5 stars: "%{ review_text }"',
+        format: '%{product_name} - %{rating}/5 stars: "%{review_text}"',
         embedding_fields: %w[product_name review_text]
       }
     }
@@ -363,6 +460,14 @@ response = client.generate_response("I need a laptop for work", products)
 - **fields** - Array of field names available for this context type
 - **format** - Template string for displaying context items
 - **embedding_fields** - Specific fields to use when generating embeddings
+- **context_excluded_fields** - Additional field names excluded from generic embedding text; built-in metadata exclusions remain active
+
+```ruby
+config.add_provider(:openai, Prescient::Provider::OpenAI,
+  api_key: ENV['OPENAI_API_KEY'],
+  context_excluded_fields: %w[tenant_id internal_notes]
+)
+```
 
 ### Automatic Context Detection
 
@@ -384,7 +489,7 @@ The system works perfectly without any context configuration - it will:
 
 ```ruby
 # No context_configs needed - works with any data!
-client = Prescient.client(:default)
+client = Prescient.client
 response = client.generate_response("Analyze this", [
   { 'title' => 'Issue', 'content' => 'Server down', 'created_at' => '2024-01-01' },
   { 'name' => 'Alert', 'message' => 'High CPU usage', 'timestamp' => 1234567 }
@@ -393,9 +498,44 @@ response = client.generate_response("Analyze this", [
 
 See `examples/custom_contexts.rb` for complete examples.
 
+### Sensitive Provider Options
+
+`provider_info` always removes the built-in sensitive keys (`api_key`,
+`password`, `token`, and `secret`). Add project-specific keys globally with
+`sensitive_keys`; nested hashes and arrays are sanitized recursively:
+
+```ruby
+Prescient.configure do |config|
+  config.sensitive_keys = %w[workspace_secret private_key]
+end
+```
+
 ## Vector Database Integration (pgvector)
 
-Prescient integrates seamlessly with PostgreSQL's pgvector extension for storing and searching embeddings:
+`Prescient::Pgvector::Store` is an opt-in PostgreSQL integration for storing
+and searching embeddings. It accepts a PG-compatible connection, so `pg` stays
+an application dependency rather than a required dependency of this gem.
+
+```ruby
+require 'pg'
+
+connection = PG.connect(dbname: 'my_app')
+store = Prescient::Pgvector::Store.new(connection: connection, dimensions: 1536)
+store.install!
+store.create_index!
+
+embedding = Prescient.generate_embedding('Semantic search', provider: :openai)
+store.upsert(
+  id: 'document-42', embedding:, provider: 'openai', model: 'text-embedding-3-small',
+  content: 'Semantic search', metadata: { category: 'guide' }
+)
+
+results = store.search(embedding:, provider: :openai, model: 'text-embedding-3-small')
+```
+
+Every vector must exactly match the store's configured dimensions; Prescient
+never pads or truncates vectors. The existing application-schema example below
+remains available for projects that need documents, chunks, and custom metadata.
 
 ### Setup with Docker
 
@@ -403,7 +543,7 @@ The included `docker-compose.yml` provides a complete setup with PostgreSQL + pg
 
 ```bash
 # Start PostgreSQL with pgvector
-docker-compose up -d postgres
+docker compose up -d postgres
 
 # The database will automatically:
 # - Install pgvector extension
@@ -447,7 +587,7 @@ embedding = client.generate_embedding(text)
 vector_str = "[#{embedding.join(',')}]"
 db.exec_params(
   "INSERT INTO document_embeddings (document_id, embedding_provider, embedding_model, embedding_dimensions, embedding, embedding_text) VALUES ($1, $2, $3, $4, $5, $6)",
-  [doc_id, 'ollama', 'nomic-embed-text', 768, vector_str, text]
+  [doc_id, 'ollama', 'nomic-embed-text', embedding.length, vector_str, text]
 )
 
 # Perform similarity search
@@ -588,7 +728,7 @@ Run the complete vector search example:
 
 ```bash
 # Start services
-docker-compose up -d postgres ollama
+docker compose up -d postgres ollama
 
 # Run example
 DB_HOST=localhost ruby examples/vector_search.rb
@@ -606,7 +746,7 @@ The example demonstrates:
 ### Custom Provider Implementation
 
 ```ruby
-class MyCustomProvider < Prescient::BaseProvider
+class MyCustomProvider < Prescient::Base
   def generate_embedding(text, **options)
     # Your implementation
   end
@@ -642,7 +782,7 @@ client = Prescient.client(:ollama)
 info = client.provider_info
 
 puts info[:name]      # => :ollama
-puts info[:class]     # => "Prescient::Ollama::Provider"
+puts info[:class]     # => "Ollama"
 puts info[:available] # => true
 puts info[:options]   # => { ... } (excluding sensitive data)
 ```
@@ -651,7 +791,7 @@ puts info[:options]   # => { ... } (excluding sensitive data)
 
 ### Ollama
 
-- Model management: `pull_model`, `list_models`
+- Model management: `pull_model`, `available_models`
 - Local deployment support
 - No API costs
 
@@ -665,6 +805,7 @@ puts info[:options]   # => { ... } (excluding sensitive data)
 - Multiple embedding model sizes
 - Latest GPT models
 - Reliable performance
+- Uses the Chat Completions endpoint for the stable normalized response contract; the newer Responses API remains a future compatibility extension.
 
 ### HuggingFace
 
@@ -692,7 +833,7 @@ Before starting, ensure your system meets the minimum requirements for running O
 | Model              | RAM Required | Storage | Notes                             |
 | ------------------ | ------------ | ------- | --------------------------------- |
 | `nomic-embed-text` | 1GB          | 274MB   | Embedding model                   |
-| `llama3.1:8b`      | 8GB          | 4.7GB   | Chat model (8B parameters)        |
+| `llama3.2:3b`      | 2GB          | 2.0GB   | Chat model (3B parameters)        |
 | `llama3.1:70b`     | 64GB+        | 40GB    | Large chat model (70B parameters) |
 | `codellama:7b`     | 8GB          | 3.8GB   | Code generation model             |
 
@@ -710,21 +851,21 @@ Before starting, ensure your system meets the minimum requirements for running O
 - **Docker**: NVIDIA Container Toolkit installed
 - **Performance**: 3-10x faster inference with compatible models
 
-> **💡 Tip**: Start with smaller models like `llama3.1:8b` and upgrade based on your hardware capabilities and performance needs.
+> **💡 Tip**: Start with smaller models like `llama3.2:3b` and upgrade based on your hardware capabilities and performance needs.
 
 ### Quick Start with Docker
 
 1. **Start Ollama service:**
 
    ```bash
-   docker-compose up -d ollama
+   docker compose up -d ollama
    ```
 
 2. **Pull required models:**
 
    ```bash
    # Automatic setup
-   docker-compose up ollama-init
+   docker compose run --rm ollama-init
 
    # Or manual setup
    ./scripts/setup-ollama-models.sh
@@ -786,7 +927,7 @@ services:
 # Ollama Configuration
 OLLAMA_URL=http://localhost:11434
 OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-OLLAMA_CHAT_MODEL=llama3.1:8b
+OLLAMA_CHAT_MODEL=llama3.2:3b
 
 # Optional: Other AI providers
 OPENAI_API_KEY=your_key_here
@@ -803,7 +944,7 @@ curl http://localhost:11434/api/tags
 # Pull a specific model
 curl -X POST http://localhost:11434/api/pull \
   -H "Content-Type: application/json" \
-  -d '{ "name": "llama3.1:8b"}'
+  -d '{ "name": "llama3.2:3b"}'
 
 # Health check
 curl http://localhost:11434/api/version
@@ -833,7 +974,7 @@ free -h
 # Settings > Resources > Memory: 8GB+
 
 # Use smaller models if hardware limited
-OLLAMA_CHAT_MODEL=llama3.1:7b ruby examples/custom_contexts.rb
+OLLAMA_CHAT_MODEL=llama3.2:3b ruby examples/custom_contexts.rb
 ```
 
 **Slow Model Loading:**
@@ -853,7 +994,7 @@ iostat -x 1
 df -h
 
 # Manually pull models with retry
-docker exec prescient-ollama ollama pull llama3.1:8b
+docker exec prescient-ollama ollama pull llama3.2:3b
 ```
 
 **GPU Not Detected:**
@@ -878,7 +1019,7 @@ docker logs prescient-ollama
 # Test API response time
 time curl -X POST http://localhost:11434/api/generate \
   -H "Content-Type: application/json" \
-  -d '{ "model": "llama3.1:8b", "prompt": "Hello", "stream": false}'
+  -d '{ "model": "llama3.2:3b", "prompt": "Hello", "stream": false}'
 ```
 
 ## Testing
@@ -886,11 +1027,44 @@ time curl -X POST http://localhost:11434/api/generate \
 The gem includes comprehensive test coverage:
 
 ```bash
-bundle exec rspec
+bundle exec rake test
 ```
 
 ## Development
 
+### Opt-in live provider smoke tests
+
+The default test suite uses mocked provider interactions. To exercise a live
+provider explicitly, set `PRESCIENT_LIVE_SMOKE=1` and select one or more
+providers with `PRESCIENT_LIVE_PROVIDERS`:
+
+```bash
+PRESCIENT_LIVE_SMOKE=1 \
+PRESCIENT_LIVE_PROVIDERS=openai \
+OPENAI_API_KEY=... \
+bundle exec ruby -Itest test/prescient/live_provider_smoke_test.rb
+```
+
+Supported provider names are `ollama`, `anthropic`, `openai`, and
+`huggingface`. The corresponding provider environment variables and model
+overrides are honored. These tests are never live unless both opt-in
+variables are set.
+
+### RBS and Steep
+
+Validate the curated core API signatures with:
+
+```bash
+bundle exec rake rbs:validate
+```
+
+Generate disposable prototypes for comparison with:
+
+```bash
+bundle exec rake rbs:prototype
+bundle exec rake rbs:diff
+```
+
 After checking out the repo, run:
 
 ```bash
@@ -914,34 +1088,3 @@ bundle exec rake install
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Roadmap
-
-### Version 0.2.0 (Planned)
-
-- **MariaDB Vector Support**: Integration with MariaDB using external vector databases
-- **Hybrid Database Architecture**: Support for MariaDB + Milvus/Qdrant combinations
-- **Vector Database Adapters**: Pluggable adapters for different vector storage backends
-- **Enhanced Chunking Strategies**: Smart document splitting with multiple algorithms
-- **Search Result Ranking**: Advanced scoring and re-ranking capabilities
-
-### Version 0.3.0 (Future)
-
-- **Streaming Responses**: Real-time response streaming for chat applications
-- **Multi-Model Ensembles**: Combine responses from multiple AI providers
-- **Advanced Analytics**: Search performance insights and usage analytics
-- **Cloud Provider Integration**: Direct support for Pinecone, Weaviate, etc.
-
-## Changelog
-
-### Version 0.1.0
-
-- Initial release
-- Support for Ollama, Anthropic, OpenAI, and HuggingFace
-- Unified interface for embeddings and text generation
-- Comprehensive error handling and retry logic
-- Health monitoring capabilities
-- PostgreSQL pgvector integration with complete Docker setup
-- Vector similarity search with multiple distance functions
-- Document chunking and metadata filtering
-- Performance optimization guides and troubleshooting

data/Rakefile

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "rbconfig"
 require "rake/testtask"
 require "rubocop/rake_task"
+require "yard"
+require "yard/rake/yardoc_task"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -10,17 +13,89 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = ["--parallel"]
+end
 
-desc "Run tests and linting"
-task default: %w[test rubocop]
+YARD::Rake::YardocTask.new(:yard)
+namespace :yard do
+  desc "Validate YARD documentation coverage"
+  task :validate do
+    require "open3"
+
+    stdout, stderr, status = Open3.capture3("bundle", "exec", "yard", "stats")
+    text = "#{stdout}\n#{stderr}"
+    puts text
+    abort("yard stats failed") unless status.success?
+
+    match = text.match(/([0-9]+(?:\.[0-9]+)?)%\s+documented/)
+    abort("Unable to determine YARD coverage") unless match
+
+    coverage = match[1].to_f
+    minimum = 99.0
+    if coverage < minimum
+      message = format(
+        "YARD coverage %<coverage>.2f%% is below %<minimum>.2f%%",
+        coverage: coverage,
+        minimum: minimum
+      )
+      abort(message)
+    end
+
+    puts format("YARD coverage %.2f%%", coverage)
+  end
+end
+
+namespace :rbs do
+  desc "Remove generated RBS prototype files"
+  task :clobber do
+    sh "rm -rf tmp/sig"
+  end
+
+  desc "Generate disposable RBS prototypes into tmp/sig"
+  task :prototype do
+    sh "rm -rf tmp/sig"
+    sh "mkdir -p tmp/sig"
+    sh "bundle exec rbs prototype rb --out-dir=tmp/sig --base-dir=lib lib"
+  end
 
-desc "Run tests with coverage"
-task :coverage do
-  ENV['COVERAGE'] = 'true'
-  Rake::Task[:test].execute
+  desc "Validate curated RBS signatures with Steep"
+  task :validate do
+    sh "bundle exec steep check"
+  end
+
+  desc "Open diff between curated and generated signatures"
+  task :diff do
+    sh "diff -ru sig tmp/sig || true"
+  end
+
+  desc "Generate disposable RBS prototypes and validate curated signatures"
+  task check: %i[prototype validate]
 end
 
+namespace :examples do
+  desc "Validate Ruby example syntax without contacting providers"
+  task :syntax do
+    Dir["examples/**/*.rb"].sort.each do |file|
+      sh RbConfig.ruby, "-c", file
+    end
+  end
+end
+
+desc "Validate GitHub Actions workflows"
+task :actionlint do
+  actionlint = if File.executable?(".tools/bin/actionlint")
+                 ".tools/bin/actionlint"
+               else
+                 ENV.fetch("ACTIONLINT", "actionlint")
+               end
+  sh actionlint
+end
+
+
+desc "Run tests and linting"
+task default: %w[test rubocop yard yard:validate rbs:validate examples:syntax]
+
 desc "Console with gem loaded"
 task :console do
   require "bundler/setup"

data/Steepfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+target :prescient do
+  signature 'sig'
+  library 'json'
+  library 'net-http'
+
+  check 'lib/prescient/version.rb'
+  check 'lib/prescient/errors.rb'
+  check 'lib/prescient.rb'
+  check 'lib/prescient/client.rb'
+  check 'lib/prescient/base.rb'
+  check 'lib/prescient/provider/openai.rb'
+  check 'lib/prescient/provider/ollama.rb'
+  check 'lib/prescient/provider/anthropic.rb'
+  check 'lib/prescient/provider/huggingface.rb'
+end