prescient 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 176552789656cbda6e78951ab04eb0ecdfa9ffa53dcf88159bec5cdbf403cdef
-  data.tar.gz: 5173a6bdd607dc6aca121079ee6e81243a550575f4702c57133f637a31aac798
+  metadata.gz: e272a00a9f7baaee44c4ad7b9827da6c1e5b930a98228e8d58718474d3090214
+  data.tar.gz: a7ac75b948c326d0829db56e0ab297561d178fa4643a6a4bbd5b4dc11cff150b
 SHA512:
-  metadata.gz: fb309c19aa67f200e806b227f392ff5181e5ef7bc1ea00a6f9a0d4cf5ebbce989c0d9b472885a1c2795efaa7789a8ed61f912453fd20594fba029f8c7bc126d4
-  data.tar.gz: 70187123148e3c0aad70f88fa469c91e3c55200c1c36b9452697109e2746cfe0fe70ef8358b766b3f99b967884aba4b846f3a8cb634c76fe9803ad45925d0e50
+  metadata.gz: 1e4ff77f5dd524e7bc3217b4f8fc1b8045f43d188b751f81dc2964dcf2d15dbfd3ed58efe8598ba40bd875e19a3597de1308e32c066466713b06af8e79fea55a
+  data.tar.gz: 3f5f8e5f78bc8db0566102f686ce1b66e752f9f81faba9dae09adfa49883aaa67c621b108b9a60cb573d695cae4874567e2ebf1c69b90a3971a6686f0316c288

data/.rubocop.yml

@@ -25,7 +25,8 @@ AllCops:
     - 'Rakefile'
     - 'examples/**/*'
 
-# === LAYOUT & FORMATTING ===
+Metrics/ParameterLists:
+  CountKeywordArgs: false
 
 Layout/LineLength:
   Max: 120
@@ -38,291 +39,43 @@ Layout/LineLength:
     - '^\s*context\s'  # Test contexts
     - '^\s*describe\s'  # Test descriptions
 
-Layout/MultilineMethodCallIndentation:
-  EnforcedStyle: indented
-
-Layout/FirstHashElementIndentation:
-  EnforcedStyle: consistent
-
-Layout/FirstArrayElementIndentation:
-  EnforcedStyle: consistent
-
-Layout/HashAlignment:
-  EnforcedHashRocketStyle: table
-  EnforcedColonStyle: table
-
-Layout/SpaceInsideHashLiteralBraces:
-  EnforcedStyle: space
-
-Layout/EmptyLinesAroundModuleBody:
-  Enabled: false
-
-Layout/EmptyLinesAroundClassBody:
-  Enabled: false
-
-# === STYLE ===
-
 Style/StringLiterals:
-  EnforcedStyle: single_quotes
+  EnforcedStyle: double_quotes
 
 Style/StringLiteralsInInterpolation:
-  EnforcedStyle: single_quotes
-
-Style/FrozenStringLiteralComment:
-  Enabled: true
-  EnforcedStyle: always
-  Exclude:
-    - 'examples/**/*'
-
-Style/Documentation:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  EnforcedStyle: compact
-
-Style/TrailingCommaInArguments:
-  EnforcedStyleForMultiline: comma
-
-Style/TrailingCommaInArrayLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/TrailingCommaInHashLiteral:
-  EnforcedStyleForMultiline: comma
-
-Style/HashSyntax:
-  EnforcedStyle: ruby19_no_mixed_keys
-
-Style/Lambda:
-  EnforcedStyle: literal
-
-Style/NumericLiterals:
-  MinDigits: 6
-
-Style/BlockDelimiters:
-  EnforcedStyle: semantic
-  AllowedMethods:
-    - expect
-    - let
-    - subject
-
-Style/WordArray:
-  EnforcedStyle: brackets
-
-Style/SymbolArray:
-  EnforcedStyle: brackets
-
-Style/FormatString:
-  EnforcedStyle: percent
-
-Style/CollectionMethods:
-  PreferredMethods:
-    collect: map
-    collect!: map!
-    detect: find
-    find_all: select
-    reduce: inject
-
-Style/Alias:
-  EnforcedStyle: prefer_alias_method
-
-Style/AccessorGrouping:
-  EnforcedStyle: separated
-
-Style/BisectedAttrAccessor:
-  Enabled: true
-
-Style/RedundantAssignment:
-  Enabled: true
-
-Style/RedundantFetchBlock:
-  Enabled: true
-
-Style/RedundantFileExtensionInRequire:
-  Enabled: true
-
-Style/RedundantRegexpCharacterClass:
-  Enabled: true
-
-Style/RedundantRegexpEscape:
-  Enabled: true
-
-Style/SlicingWithRange:
-  Enabled: true
-
-Style/ExponentialNotation:
-  Enabled: true
-
-Style/HashTransformKeys:
-  Enabled: true
-
-Style/HashTransformValues:
-  Enabled: true
-
-Style/RedundantReturn:
-  AllowMultipleReturnValues: true
-
-# === METRICS ===
-
-Metrics/ModuleLength:
-  Max: 150
+  EnforcedStyle: double_quotes
 
 Metrics/ClassLength:
-  Enabled: false
-  Max: 150
+  Enabled: true
+  Max: 145
   Exclude:
     - 'test/**/*'
 
 Metrics/MethodLength:
-  Enabled: false
-  Max: 25
+  Max: 37
   Exclude:
-    - 'test/**/*'
-    - 'db/**/*'
-    - 'lib/prescient/provider/*.rb'
-
-Metrics/BlockLength:
-  Enabled: false
-  Max: 25
-  Exclude:
-    - 'test/**/*'
-    - 'lib/prescient.rb'  # Configuration block
+    - "test/**/*"
+    - "db/migrate/**/*"
 
 Metrics/AbcSize:
-  Max: 20
+  Enabled: true
+  Max: 55
   Exclude:
-    - 'test/**/*'
-    - 'db/**/*'
-    - 'lib/prescient/provider/*.rb'
+    - "test/**/*"
+    - "db/migrate/**/*"
 
-Metrics/CyclomaticComplexity:
-  Max: 8
-  Exclude:
-    - 'lib/prescient/provider/*.rb'
+Minitest/MultipleAssertions:
+  Max: 20
 
 Metrics/PerceivedComplexity:
-  Enabled: false
-  Max: 8
-  Exclude:
-    - 'lib/prescient/provider/*.rb'
-
-Metrics/ParameterLists:
-  Max: 5
-  CountKeywordArgs: false
-
-# === LINT ===
-
-Lint/RaiseException:
-  Enabled: true
-
-Lint/StructNewOverride:
-  Enabled: true
-
-Lint/DeprecatedOpenSSLConstant:
-  Enabled: true
-
-Lint/MixedRegexpCaptureTypes:
-  Enabled: true
-
-Lint/DuplicateElsifCondition:
-  Enabled: true
-
-Lint/BinaryOperatorWithIdenticalOperands:
-  Enabled: true
-
-Lint/DuplicateRescueException:
-  Enabled: true
-
-Lint/EmptyConditionalBody:
-  Enabled: true
-
-Lint/FloatComparison:
-  Enabled: true
-
-Lint/MissingSuper:
-  Enabled: true
-
-Lint/OutOfRangeRegexpRef:
-  Enabled: true
-
-Lint/SelfAssignment:
-  Enabled: true
-
-Lint/TopLevelReturnWithArgument:
-  Enabled: true
-
-Lint/UnreachableLoop:
-  Enabled: true
-
-# === NAMING ===
-
-Naming/PredicatePrefix:
-  ForbiddenPrefixes:
-    - is_
-  AllowedMethods:
-    - is_a?
-
-Naming/MemoizedInstanceVariableName:
-  EnforcedStyleForLeadingUnderscores: required
-
-Naming/VariableNumber:
-  EnforcedStyle: snake_case
-
-# === SECURITY ===
-
-Security/Open:
-  Enabled: true
-
-Security/YAMLLoad:
-  Enabled: true
-
-Security/JSONLoad:
-  Enabled: true
-
-# === PERFORMANCE ===
-
-Performance/AncestorsInclude:
-  Enabled: true
-
-Performance/BigDecimalWithNumericArgument:
-  Enabled: true
-
-Performance/RedundantSortBlock:
-  Enabled: true
-
-Performance/RedundantStringChars:
-  Enabled: true
-
-Performance/ReverseFirst:
-  Enabled: true
-
-Performance/SortReverse:
-  Enabled: true
-
-Performance/Squeeze:
-  Enabled: true
-
-Performance/StringInclude:
-  Enabled: true
-
-Performance/Sum:
-  Enabled: true
-
-# === MINITEST ===
-
-Minitest/MultipleAssertions:
   Max: 10
 
-Minitest/AssertTruthy:
-  Enabled: true
-
-Minitest/AssertWithExpectedArgument:
-  Enabled: true
+Metrics/BlockLength:
+  Max: 35
 
-Minitest/RefuteFalse:
-  Enabled: true
 
-Minitest/RefuteNil:
-  Enabled: true
+Metrics/CyclomaticComplexity:
+  Max: 10
 
-Minitest/TestMethodName:
-  Enabled: true
+Style/DirectiveScope:
+  Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## [0.8.0] - 2025-08-31
+
+### Added
+
+- Added an optional, bounded Ruby agent runtime with strict single-action tool
+  execution, provider routing through `Prescient::Client`, and safe loop limits.
+- Added deterministic agent context compaction and safe serialization of tool
+  failures before they are returned to the model.
+- Added generic callable agent tools, request-scoped authorization and bounded
+  telemetry hooks, the `prescient agent` CLI command, and `POST /v1/agent`.
+- Added a dedicated `Prescient::Agent::CLIAdapter`, schema validation for
+  generic callable tools, and independent task and response byte limits.
+- Added structured failure telemetry, principal propagation, and an
+  authenticated, bounded MCP Rack transport backed by shared JSON-RPC dispatch.
+- Added valid UTF-8, JSON-safe observation truncation for bounded Agent context.
+- Extended the MCP Rack transport with authenticated sessions, lifecycle
+  termination, notifications, one-shot SSE responses, Origin checks, and a
+  reusable bearer-token authentication policy.
+- Documented the host-owned tenant/principal authorization contract and aligned
+  the Agent implementation plan with the shipped REST and MCP surfaces.
+- Added an opt-in thread-safe JSONL Agent audit sink for durable safe telemetry.
+- Added an optional lazy MCP adapter with capability discovery, safe core
+  operations, agent invocation, resources, and newline-delimited JSON-RPC stdio.
+
+### Fixed
+
+- Fixed Agent tool validation to enforce richer JSON Schema constraints,
+  composition, and local references.
+- Fixed request-scoped Agent authorization context handling for concurrent API
+  requests and added regression coverage for principal isolation.
+- Tightened generic callable Agent tools to require explicit object schemas
+  instead of accepting unconstrained arguments.
+- Added structured Agent failure telemetry for initialization failures and
+  propagated telemetry configuration through CLI and REST Agent execution.
+
 ## [0.7.0] - 2025-08-17
 
 ### Added
@@ -17,6 +52,8 @@
   country, API-key, timeout, and result-limit configuration.
 - Added capability groups for ordered tool-adapter fallback on transient
   connection and rate-limit failures.
+- Added bounded JSON document sources for Ruby, CLI, and REST generation context,
+  including local files, in-memory documents, and injected Redis clients.
 - Documented SearXNG and SearchApi setup and CLI usage side by side.
 - Added explicit `--generate` opt-in behavior to the web-search example.
 - Added `SEARXNG_URL` environment defaults for automatic `web_search` registration.

data/INTEGRATION_GUIDE.md

@@ -11,7 +11,7 @@ and [examples guide](examples/README.md).
 
 ```ruby
 # Add to your Gemfile
-gem 'prescient', '~> 0.7.0'
+gem 'prescient', '~> 0.8.0'
 ```
 
 ### 2. Replace Existing AI Service
@@ -192,6 +192,7 @@ This makes the following routes available under `/prescient`:
 | `POST` | `/v1/generate` | Text generation |
 | `POST` | `/v1/search` | Normalized external-tool search |
 | `POST` | `/v1/search/generate` | Search with opt-in AI generation |
+| `POST` | `/v1/agent` | Bounded allowlisted tool-calling agent |
 | `POST` | `/v1/embeddings` | Single embedding |
 | `POST` | `/v1/embeddings/batch` | Bounded batch embeddings |
 
@@ -214,6 +215,11 @@ curl -X POST http://localhost:3000/prescient/v1/search \
   -H "Authorization: Bearer ${PRESCIENT_API_TOKEN}" \
   -H 'Content-Type: application/json' \
   -d '{"query":"Ruby HTTP clients","limit":5}'
+
+curl -X POST http://localhost:3000/prescient/v1/agent \
+  -H "Authorization: Bearer ${PRESCIENT_API_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt":"Summarize account status","provider":"openai","tools":[]}'
 ```
 
 Responses include a request ID. Request bodies are size-limited, batch inputs

data/README.md

@@ -13,6 +13,94 @@ For focused guidance, see the **[examples guide](https://github.com/kanutocd/pre
 **[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)**.
 
+Prescient has three primary application entry points:
+
+- **Ruby gem** — Use `Prescient` directly from a Ruby application.
+- **CLI** — Run provider operations and configuration checks from scripts or a
+  terminal.
+- **Rack-compatible REST API** — Mount `Prescient::API` in a Rack, Rails, or
+  other Rack-compatible application.
+
+The Ruby entry point does not load the CLI, REST API, or MCP transport. Those
+surfaces are loaded lazily when referenced or explicitly required.
+MCP is an optional protocol integration surface available through explicit
+`prescient/mcp` loading; it does not change the three primary entry points.
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Supported Providers](#supported-providers)
+- [Installation](#installation)
+- [Command-Line Interface](#command-line-interface)
+- [REST API](#rest-api)
+- [Configuration](#configuration)
+- [Ruby API](#ruby-api)
+- [Agent runtime](#agent-runtime)
+- [Custom Prompt Templates](#custom-prompt-templates)
+- [Custom Context Configurations](#custom-context-configurations)
+- [Vector Database Integration](#vector-database-integration-pgvector)
+- [Testing](#testing)
+- [Development](#development)
+
+## Quick Start
+
+Prescient reads provider credentials from the environment. The following
+example uses OpenAI; replace it with a configured provider when appropriate.
+
+```bash
+export OPENAI_API_KEY=your_api_key
+```
+
+Create `example.rb`:
+
+```ruby
+require "prescient"
+
+Prescient.configure do |config|
+  config.default_provider = :openai
+  config.add_provider(
+    :openai,
+    Prescient::Provider::OpenAI,
+    api_key: ENV.fetch("OPENAI_API_KEY"),
+    chat_model: ENV.fetch("OPENAI_CHAT_MODEL", "gpt-4.1-mini")
+  )
+end
+
+result = Prescient.generate_response(
+  "Draft a concise maintenance notice for a scheduled database upgrade."
+)
+
+puts result[:response]
+```
+
+Run it with:
+
+```bash
+bundle exec ruby example.rb
+```
+
+`generate_response` returns a normalized hash containing the generated
+response, provider, model, and provider metadata. Use the client directly when
+you need repeated operations or provider-specific fallback control:
+
+```ruby
+client = Prescient.client(:openai)
+response = client.generate_response("Summarize this release note.")
+embedding = client.generate_embedding("A searchable release note.")
+```
+
+For local development, configure Ollama instead of a hosted provider:
+
+```bash
+docker compose up -d ollama
+docker compose run --rm ollama-init
+```
+
+See the [examples guide](examples/README.md) for complete scripts and the
+[Configuration](#configuration) section for YAML, environment references,
+fallbacks, prompt templates, and external tools.
+
 ## Features
 
 - **Provider abstraction** — One consistent interface across supported AI providers
@@ -106,6 +194,8 @@ prescient config validate
 prescient config example
 prescient generate "Explain Ruby Ractors"
 prescient embed "Ruby is a programming language"
+prescient search "Ruby HTTP clients"
+prescient agent "Summarize the account status" --tool accounts
 ```
 
 Supported options include:
@@ -125,8 +215,15 @@ Supported options include:
 --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
+--json-file PATH         Load JSON documents as generation context
+--no-fallback             Disable provider fallback
 ```
 
+Search-specific options are `--tool NAME`, `--generate`, and `--limit COUNT`.
+Agent-specific options are repeatable `--tool NAME` and `--max-loops COUNT`.
+The full command-specific help is available with `prescient search --help` or
+`prescient agent --help`.
+
 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
@@ -247,6 +344,7 @@ Available endpoints include:
 - **`POST /v1/generate`**
 - **`POST /v1/search`**
 - **`POST /v1/search/generate`**
+- **`POST /v1/agent`**
 - **`POST /v1/embeddings`**
 - **`POST /v1/embeddings/batch`**
 - **`GET /v1/providers`**
@@ -584,6 +682,117 @@ client_no_fallback = Prescient::Client.new(:primary, enable_fallback: false)
 response = Prescient.generate_response("Hello", provider: :primary, enable_fallback: true)
 ```
 
+### JSON document context
+
+For small documentation sets, you can load JSON objects from a file instead of
+creating embeddings:
+
+```ruby
+documents = Prescient::DocumentSource::JsonFile.new(path: "docs.json").fetch
+response = Prescient.generate_response("How do I reset my password?", documents)
+```
+
+The CLI supports the same flow with bounded document loading:
+
+```bash
+prescient generate --json-file docs.json "How do I reset my password?"
+```
+
+Redis-backed documents use an injected Redis-compatible client, so Redis remains
+optional for gem consumers:
+
+```ruby
+source = Prescient::DocumentSource::RedisJson.new(client: redis, key: "docs:acme")
+response = Prescient.generate_response("Summarize the docs", source.fetch)
+```
+
+The REST API accepts the same documents inline as `documents` on
+`POST /v1/generate`. Sources enforce document-count and serialized-byte limits;
+use retrieval or embeddings when the documentation no longer fits comfortably
+in the provider's context window.
+
+## Agent runtime
+
+Prescient also provides an optional, bounded agent runtime. It is loaded
+explicitly and can execute allowlisted search tools through the existing
+provider routing:
+
+```ruby
+require "prescient/agent"
+
+agent = Prescient::Agent::Runtime.new(
+  provider:   :openai,
+  tool_names: [:web_search],
+  configuration: Prescient::Agent::Configuration.new(max_loops: 5)
+)
+result = agent.run("Find and summarize the latest Ruby release")
+puts result.response
+```
+
+The runtime supports one validated JSON action per iteration and stops at its
+loop limit. It does not provide arbitrary Ruby, shell, filesystem, browser, or
+database access. The agent namespace is not loaded by `require "prescient"`.
+
+The same bounded runtime is available from the CLI:
+
+```bash
+prescient agent "Summarize the account status" --provider openai --tool accounts
+```
+
+It is also available through `POST /v1/agent`. Supply an explicit `tools` array;
+the REST API does not grant access to configured tools implicitly:
+
+```json
+{"prompt":"Summarize the account status","provider":"openai","tools":[]}
+```
+
+Applications can provide `authorization` and `request_context` hooks to enforce
+tenant/principal policy, and a bounded `telemetry` hook receives only event
+metadata such as loop count, action names, and success status. The authorization
+hook receives `tool:`, copied `arguments:`, and copied request-scoped
+`context:`; only an exact `true` result permits invocation. Prescient does not
+guess roles, ownership, or organization boundaries, so the host application
+must make the access decision.
+
+For durable, privacy-preserving audit records, pass an opt-in JSONL sink:
+
+```ruby
+audit_log = Prescient::Agent::AuditLog.new(path: "tmp/prescient-agent.jsonl")
+Prescient::Agent::Runtime.new(audit_log:).run("Summarize account status")
+```
+
+The sink persists event metadata and timestamps, never prompts, documents, or
+raw observations. Audit storage failures are isolated from agent execution;
+configure retention, access controls, and storage protection in the host.
+
+For MCP hosts, load the optional dependency-free adapter explicitly with
+`require "prescient/mcp"`, or run `prescient-mcp` for newline-delimited
+JSON-RPC over stdio. MCP exposes only explicitly enabled capabilities and never
+returns credentials or raw provider failure bodies.
+
+The optional Rack adapter provides a bounded Streamable HTTP surface with
+bearer-token authentication, Origin allowlisting, initialize-assigned sessions,
+`Mcp-Session-Id` lifecycle management, notifications, and one-shot JSON or
+server-sent-event responses:
+
+```ruby
+require "prescient/mcp"
+
+app = Prescient::MCP::Rack.new(
+  authentication: Prescient::MCP::Authentication::BearerToken.new(
+    token: ENV.fetch("MCP_TOKEN"),
+    principal: { id: "mcp-client" }
+  ),
+  allowed_origins: ["https://admin.example.com"]
+)
+run app
+```
+
+Clients must send `MCP-Protocol-Version: 2025-06-18` and the returned
+`Mcp-Session-Id` on requests after `initialize`. `DELETE` terminates a session.
+The adapter does not implement a long-lived notification queue or replace a
+host application's token provisioning and authorization policy.
+
 **Fallback Behavior:**
 - When a provider fails with a persistent error, Prescient automatically tries the next available provider
 - Configured fallback providers are tried in order; the provider operation determines availability
@@ -592,7 +801,7 @@ response = Prescient.generate_response("Hello", provider: :primary, enable_fallb
 - 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
+## Ruby API
 
 ### Quick Start
 

data/Steepfile

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 target :prescient do
-  signature 'sig'
-  library 'json'
-  library 'net-http'
+  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'
+  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