whoosh 1.2.2 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 336c26ea284a871dafa4b1d26f173293947e30470000539dbf3e0da799063bea
-  data.tar.gz: 6acf7d5007d008070aaddb543a42de5bddf3b3aa2de838e1be5ccba5d18b9442
+  metadata.gz: 99edefedd7d17b1c477fcd07d7ba72b317560d670706ec1361c197df013a9834
+  data.tar.gz: d94a866bf3e588e64591b1e1e32e62db4b5fae74511420b5942e42a04eb1dc8a
 SHA512:
-  metadata.gz: 86aebc850e904960fe87d08aa7c6e8d6aba82c5e411e66e0e9ae65fb64d5510b8ddae4125099554fecac71907c163ce854d1adc416bd8e84ee5f6f3376556809
-  data.tar.gz: 99c067d27463fff53a3cb5818836a11e90e0e86d1f886d211770a6407725b6ca0ba72cd3e52c94bd4b204d57e5d282ff89d102863c9410c545c63e3d60bcf332
+  metadata.gz: c2d1793270458869874e09f720c053eb3625b2943323bd1ff24a9e9620bebd3cbe9705fb1bde81cfe60211084f8d7a0862407548f1699a5f5a25c4bb392f764b
+  data.tar.gz: f86e8837a57fcbee513a514d6bf32d2901833187f038cd64d0b8bfb71897a97507c65ee5297af3ce92e940ee697d0443165efeda980a8fb1d8b3cb334a4ae89b

data/README.md

@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/ruby-%3E%3D%203.4.0-red" alt="Ruby">
   <img src="https://img.shields.io/badge/rack-3.0-blue" alt="Rack">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-  <img src="https://img.shields.io/badge/tests-509%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-540%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/overhead-2.5%C2%B5s-orange" alt="Performance">
 </p>
 
@@ -21,11 +21,11 @@
 
 ## Why Whoosh?
 
-- **AI-first** — MCP server built-in, LLM streaming, token tracking, plugin auto-discovery for 18+ AI gems
-- **Fast** — 2.5µs framework overhead, 406K req/s on simple JSON, YJIT + Oj auto-enabled
-- **Batteries included** — Auth, rate limiting, caching, background jobs, file uploads, pagination, metrics
-- **Zero config to start** — `whoosh new myapp && cd myapp && whoosh s`
-- **OpenAPI 3.1** — Swagger UI + ReDoc auto-generated from your routes and schemas
+- **AI-first** — Every app is an MCP server automatically. LLM wrapper with structured output, caching, and streaming. Vector search built-in. 18+ AI gem auto-discovery.
+- **Fast** — 2.5µs framework overhead, 87K req/s with Falcon. Beats Fastify on multi-worker PostgreSQL benchmarks.
+- **Batteries included** — Auth, rate limiting, caching, background jobs, file uploads, vector search, pagination, metrics, CI pipeline.
+- **Zero config to start** — `whoosh new myapp && cd myapp && whoosh s` — everything works.
+- **AI-agent friendly** — `whoosh describe` dumps your app as JSON for AI tools. Generated `CLAUDE.md` in every project. `whoosh check` catches mistakes before runtime.
 
 ## Install
 
@@ -130,6 +130,45 @@ app.access_control do
 end
 ```
 
+### AI / LLM Integration
+
+```ruby
+# Chat with any LLM (auto-detects ruby_llm gem)
+app.post "/chat" do |req, llm:|
+  { reply: llm.chat(req.body["message"]) }
+end
+
+# Structured output — LLM returns validated JSON
+app.post "/extract" do |req, llm:|
+  data = llm.extract(req.body["text"], schema: InvoiceSchema)
+  { invoice: data }
+end
+
+# RAG in 3 lines
+app.post "/ask" do |req, vectors:, llm:|
+  context = vectors.search("knowledge", vector: embed(req.body["q"]), limit: 5)
+  { answer: llm.chat(req.body["q"], system: "Context: #{context}") }
+end
+```
+
+### Vector Search
+
+```ruby
+app.post "/index" do |req, vectors:|
+  vectors.insert("docs", id: req.body["id"],
+    vector: req.body["embedding"],
+    metadata: { title: req.body["title"] })
+  { indexed: true }
+end
+
+app.post "/search" do |req, vectors:|
+  results = vectors.search("docs", vector: req.body["embedding"], limit: 10)
+  { results: results }
+end
+```
+
+In-memory by default (cosine similarity). Install `zvec` gem for production-grade HNSW index.
+
 ### LLM Streaming (OpenAI-compatible)
 
 ```ruby
@@ -153,16 +192,21 @@ end
 
 ### MCP (Model Context Protocol)
 
+**Every route is automatically an MCP tool.** No `mcp: true` needed.
+
 ```ruby
-# Any route with mcp: true becomes an MCP tool automatically
-app.post "/summarize", mcp: true, request: SummarizeRequest do |req|
+# These are all MCP tools automatically:
+app.post "/summarize", request: SummarizeRequest do |req|
   { summary: llm.summarize(req.body[:text]) }
 end
 
-# Groups propagate mcp: true to all child routes
-app.group "/tools", mcp: true do
-  post("/translate") { |req| { result: translate(req.body[:text]) } }
-  post("/analyze")   { |req| { result: analyze(req.body[:text]) } }
+app.post "/translate" do |req|
+  { result: translate(req.body["text"]) }
+end
+
+# Opt OUT with mcp: false for internal routes:
+app.get "/internal", mcp: false do
+  { debug: "not exposed as MCP tool" }
 end
 ```
 
@@ -319,9 +363,13 @@ whoosh new my_api             # scaffold project (with Dockerfile)
 whoosh s                      # start server (like rails s)
 whoosh s --reload             # hot reload on file changes
 whoosh routes                 # list all routes
+whoosh describe               # dump app as JSON (AI-friendly)
+whoosh check                  # validate config, catch mistakes
 whoosh console                # IRB with app loaded
+whoosh ci                     # lint + security + audit + tests + coverage
 whoosh worker                 # background job worker
 whoosh mcp                    # MCP stdio server
+whoosh mcp --list             # list all MCP tools
 
 whoosh generate endpoint chat       # endpoint + schema + test
 whoosh generate schema User         # schema file
@@ -335,6 +383,22 @@ whoosh db rollback            # rollback
 whoosh db status              # migration status
 ```
 
+## AI Agent DX
+
+Every `whoosh new` project includes a `CLAUDE.md` with all framework patterns, commands, and conventions — so AI agents (Claude Code, Cursor, Copilot) can build with Whoosh immediately.
+
+```bash
+# Dump your entire app structure as JSON (routes, schemas, config, MCP tools)
+whoosh describe
+
+# AI tools can consume this to understand your API
+whoosh describe --routes     # routes with request/response schemas
+whoosh describe --schemas    # all schema definitions
+
+# Catch mistakes before runtime
+whoosh check                 # validates config, auth, dependencies
+```
+
 ## Performance
 
 ### HTTP Benchmark: `GET /health → {"status":"ok"}`

data/lib/whoosh/ai/llm.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Whoosh
+  module AI
+    class LLM
+      attr_reader :provider, :model
+
+      def initialize(provider: "auto", model: nil, cache_enabled: true)
+        @provider = provider
+        @model = model
+        @cache_enabled = cache_enabled
+        @cache = cache_enabled ? {} : nil
+        @mutex = Mutex.new
+        @ruby_llm = nil
+      end
+
+      # Chat with an LLM — returns response text
+      def chat(message, model: nil, system: nil, max_tokens: nil, temperature: nil, cache: nil)
+        use_cache = cache.nil? ? @cache_enabled : cache
+        cache_key = "chat:#{model || @model}:#{message}" if use_cache
+
+        # Check cache
+        if use_cache && @cache && (cached = @cache[cache_key])
+          return cached
+        end
+
+        result = call_llm(
+          messages: [{ role: "user", content: message }],
+          model: model || @model,
+          system: system,
+          max_tokens: max_tokens,
+          temperature: temperature
+        )
+
+        # Cache result
+        if use_cache && @cache
+          @mutex.synchronize { @cache[cache_key] = result }
+        end
+
+        result
+      end
+
+      # Extract structured data — returns validated hash
+      def extract(text, schema:, model: nil, prompt: nil)
+        schema_desc = describe_schema(schema)
+        system_prompt = prompt || "Extract structured data from the text. Return ONLY valid JSON matching this schema:\n#{schema_desc}"
+
+        response = chat(text, model: model, system: system_prompt, cache: false)
+
+        # Parse JSON from LLM response
+        json_str = extract_json(response)
+        parsed = Serialization::Json.decode(json_str)
+
+        # Validate against schema
+        result = schema.validate(parsed)
+        if result.success?
+          result.data
+        else
+          raise Errors::ValidationError.new(result.errors)
+        end
+      end
+
+      # Stream LLM response — yields chunks
+      def stream(message, model: nil, system: nil, &block)
+        ensure_ruby_llm!
+
+        messages = [{ role: "user", content: message }]
+        # Delegate to ruby_llm's streaming interface
+        if @ruby_llm
+          # ruby_llm streaming would go here
+          # For now, fall back to non-streaming
+          result = chat(message, model: model, system: system, cache: false)
+          yield result if block_given?
+          result
+        end
+      end
+
+      # Check if LLM is available
+      def available?
+        ruby_llm_available?
+      end
+
+      private
+
+      def call_llm(messages:, model:, system: nil, max_tokens: nil, temperature: nil)
+        ensure_ruby_llm!
+
+        if @ruby_llm
+          # Use ruby_llm gem
+          chat = RubyLLM.chat(model: model || "claude-sonnet-4-20250514")
+          chat.with_instructions(system) if system
+          response = chat.ask(messages.last[:content])
+          response.content
+        else
+          raise Errors::DependencyError, "No LLM provider available. Add 'ruby_llm' to your Gemfile."
+        end
+      end
+
+      def ensure_ruby_llm!
+        return if @ruby_llm == false # already checked, not available
+
+        if ruby_llm_available?
+          @ruby_llm = true
+        else
+          @ruby_llm = false
+        end
+      end
+
+      def ruby_llm_available?
+        require "ruby_llm"
+        true
+      rescue LoadError
+        false
+      end
+
+      def describe_schema(schema)
+        return "{}" unless schema.respond_to?(:fields)
+        fields = schema.fields.map do |name, opts|
+          type = OpenAPI::SchemaConverter.type_for(opts[:type])
+          desc = opts[:desc] ? " — #{opts[:desc]}" : ""
+          required = opts[:required] ? " (required)" : ""
+          "  #{name}: #{type}#{required}#{desc}"
+        end
+        "{\n#{fields.join(",\n")}\n}"
+      end
+
+      def extract_json(text)
+        # Try to find JSON in LLM response (may be wrapped in markdown code blocks)
+        if text =~ /```(?:json)?\s*\n?(.*?)\n?```/m
+          $1.strip
+        elsif text.strip.start_with?("{") || text.strip.start_with?("[")
+          text.strip
+        else
+          text.strip
+        end
+      end
+    end
+  end
+end

data/lib/whoosh/ai/structured_output.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Whoosh
+  module AI
+    # Validates LLM output against a Whoosh::Schema
+    module StructuredOutput
+      def self.validate(data, schema:)
+        result = schema.validate(data)
+        return result.data if result.success?
+        raise Errors::ValidationError.new(result.errors)
+      end
+
+      def self.prompt_for(schema)
+        return "" unless schema.respond_to?(:fields)
+
+        lines = schema.fields.map do |name, opts|
+          type = OpenAPI::SchemaConverter.type_for(opts[:type])
+          parts = ["#{name}: #{type}"]
+          parts << "(required)" if opts[:required]
+          parts << "— #{opts[:desc]}" if opts[:desc]
+          parts << "[min: #{opts[:min]}]" if opts[:min]
+          parts << "[max: #{opts[:max]}]" if opts[:max]
+          parts << "[default: #{opts[:default]}]" if opts.key?(:default)
+          "  #{parts.join(" ")}"
+        end
+
+        "Return ONLY valid JSON matching this schema:\n{\n#{lines.join(",\n")}\n}"
+      end
+    end
+  end
+end

data/lib/whoosh/ai.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Whoosh
+  module AI
+    autoload :LLM,              "whoosh/ai/llm"
+    autoload :StructuredOutput, "whoosh/ai/structured_output"
+
+    # Build an AI client from config
+    def self.build(config_data = {})
+      ai_config = config_data["ai"] || {}
+      LLM.new(
+        provider: ai_config["provider"] || "auto",
+        model: ai_config["model"],
+        cache_enabled: ai_config["cache"] != false
+      )
+    end
+  end
+end

data/lib/whoosh/app.rb

@@ -30,6 +30,7 @@ module Whoosh
       auto_register_storage
       auto_register_http
       auto_register_vectors
+      auto_register_ai
       auto_configure_jobs
       @metrics = Metrics.new
       auto_register_metrics
@@ -234,6 +235,13 @@ module Whoosh
       [200, Streaming::LlmStream.headers, body]
     end
 
+    # WebSocket endpoint helper — use in handle_request, returns hijack response
+    def websocket(env, &block)
+      ws = Streaming::WebSocket.new(env)
+      block.call(ws)
+      ws.rack_response
+    end
+
     def paginate(collection, page:, per_page: 20)
       Paginate.offset(collection, page: page, per_page: per_page)
     end
@@ -307,6 +315,10 @@ module Whoosh
       @di.provide(:vectors) { VectorStore.build(@config.data) }
     end
 
+    def auto_register_ai
+      @di.provide(:llm) { AI.build(@config.data) }
+    end
+
     def auto_configure_jobs
       backend = Jobs.build_backend(@config.data)
       Jobs.configure(backend: backend, di: @di)
@@ -448,8 +460,12 @@ module Whoosh
     end
 
     def register_mcp_tools
+      internal_paths = %w[/openapi.json /docs /redoc /metrics /healthz]
+
       @router.routes.each do |route|
-        next unless route[:metadata] && route[:metadata][:mcp]
+        # Auto-expose all routes as MCP tools (opt-out with mcp: false)
+        next if route[:metadata] && route[:metadata][:mcp] == false
+        next if internal_paths.include?(route[:path])
 
         tool_name = "#{route[:method]} #{route[:path]}"
         match = @router.match(route[:method], route[:path])

data/lib/whoosh/cli/main.rb

@@ -92,17 +92,166 @@ module Whoosh
 
       desc "routes", "List all registered routes"
       def routes
+        app = load_app
+        return unless app
+        app.routes.each { |r| puts "  #{r[:method].ljust(8)} #{r[:path]}" }
+      end
+
+      desc "describe", "Dump app structure as JSON (AI-friendly introspection)"
+      option :routes, type: :boolean, default: false, desc: "Routes only"
+      option :schemas, type: :boolean, default: false, desc: "Schemas only"
+      def describe
+        app = load_app
+        return unless app
+        app.to_rack # ensure everything is built
+
+        output = {}
+
+        unless options[:schemas]
+          output[:routes] = app.routes.map do |r|
+            match = app.instance_variable_get(:@router).match(r[:method], r[:path])
+            handler = match[:handler] if match
+            route_info = {
+              method: r[:method],
+              path: r[:path],
+              auth: r[:metadata]&.dig(:auth),
+              mcp: r[:metadata]&.dig(:mcp) || false
+            }
+            if handler && handler[:request_schema]
+              route_info[:request_schema] = OpenAPI::SchemaConverter.convert(handler[:request_schema])
+            end
+            if handler && handler[:response_schema]
+              route_info[:response_schema] = OpenAPI::SchemaConverter.convert(handler[:response_schema])
+            end
+            route_info
+          end
+        end
+
+        unless options[:routes]
+          # Collect all Schema subclasses
+          schemas = {}
+          ObjectSpace.each_object(Class).select { |k| k < Schema && k != Schema }.each do |klass|
+            schemas[klass.name] = OpenAPI::SchemaConverter.convert(klass) if klass.name
+          end
+          output[:schemas] = schemas unless schemas.empty?
+        end
+
+        output[:config] = {
+          app_name: app.config.app_name,
+          port: app.config.port,
+          env: app.config.env,
+          docs_enabled: app.config.docs_enabled?,
+          auth_configured: !!app.authenticator,
+          rate_limit_configured: !!app.rate_limiter_instance,
+          mcp_tools: app.mcp_server.list_tools.map { |t| t[:name] }
+        }
+
+        output[:framework] = {
+          version: Whoosh::VERSION,
+          ruby: RUBY_VERSION,
+          yjit: Performance.yjit_enabled?,
+          json_engine: Serialization::Json.engine
+        }
+
+        puts JSON.pretty_generate(output)
+      end
+
+      desc "check", "Validate app configuration and catch common mistakes"
+      def check
         app_file = File.join(Dir.pwd, "app.rb")
         unless File.exist?(app_file)
-          puts "Error: app.rb not found in #{Dir.pwd}"
+          puts "✗ No app.rb found"
           exit 1
         end
-        require app_file
-        app = ObjectSpace.each_object(Whoosh::App).first
-        if app
-          app.routes.each { |r| puts "  #{r[:method].ljust(8)} #{r[:path]}" }
+
+        puts "=> Whoosh App Check"
+        puts ""
+
+        issues = []
+        warnings = []
+
+        # Check .env
+        if File.exist?(".env")
+          env_content = File.read(".env")
+          if env_content.include?("change_me") || env_content.include?("CHANGE_ME")
+            issues << "JWT_SECRET in .env still has default value — run: ruby -e \"puts SecureRandom.hex(32)\""
+          end
         else
-          puts "No Whoosh::App instance found"
+          warnings << "No .env file — copy .env.example to .env"
+        end
+
+        # Check .gitignore includes .env
+        if File.exist?(".gitignore")
+          unless File.read(".gitignore").include?(".env")
+            issues << ".gitignore does not exclude .env — secrets may be committed"
+          end
+        else
+          warnings << "No .gitignore file"
+        end
+
+        # Load and validate the app
+        begin
+          require app_file
+          app = ObjectSpace.each_object(Whoosh::App).first
+          if app
+            puts "  ✓ App loads successfully"
+
+            # Check auth
+            if app.authenticator
+              puts "  ✓ Auth configured"
+            else
+              warnings << "No auth configured — API is open to everyone"
+            end
+
+            # Check rate limiting
+            if app.rate_limiter_instance
+              puts "  ✓ Rate limiting configured"
+            else
+              warnings << "No rate limiting — vulnerable to abuse"
+            end
+
+            # Check routes
+            route_count = app.routes.length
+            puts "  ✓ #{route_count} routes registered"
+
+            # Check MCP
+            app.to_rack
+            mcp_count = app.mcp_server.list_tools.length
+            puts "  ✓ #{mcp_count} MCP tools"
+
+          else
+            issues << "No Whoosh::App instance found in app.rb"
+          end
+        rescue => e
+          issues << "App failed to load: #{e.message}"
+        end
+
+        # Check dependencies
+        puts ""
+        %w[falcon oj sequel].each do |gem_name|
+          begin
+            require gem_name
+            puts "  ✓ #{gem_name} available"
+          rescue LoadError
+            label = case gem_name
+            when "falcon" then "(recommended server)"
+            when "oj" then "(5-10x faster JSON)"
+            when "sequel" then "(database)"
+            end
+            warnings << "#{gem_name} not installed #{label}"
+          end
+        end
+
+        # Report
+        puts ""
+        if issues.empty? && warnings.empty?
+          puts "=> All checks passed! ✓"
+        else
+          issues.each { |i| puts "  ✗ #{i}" }
+          warnings.each { |w| puts "  ⚠ #{w}" }
+          puts ""
+          puts issues.empty? ? "=> #{warnings.length} warning(s)" : "=> #{issues.length} issue(s), #{warnings.length} warning(s)"
+          exit 1 unless issues.empty?
         end
       end
 
@@ -306,6 +455,21 @@ module Whoosh
 
       private
 
+      def load_app
+        app_file = File.join(Dir.pwd, "app.rb")
+        unless File.exist?(app_file)
+          puts "Error: app.rb not found in #{Dir.pwd}"
+          return nil
+        end
+        require app_file
+        app = ObjectSpace.each_object(Whoosh::App).first
+        unless app
+          puts "Error: No Whoosh::App instance found"
+          return nil
+        end
+        app
+      end
+
       def run_secret_scan
         patterns = [
           /(?:api[_-]?key|secret|password|token)\s*[:=]\s*["'][A-Za-z0-9+\/=]{8,}["']/i,

data/lib/whoosh/cli/project_generator.rb

@@ -33,6 +33,7 @@ module Whoosh
         write(dir, ".dockerignore", dockerignore)
         write(dir, ".rubocop.yml", rubocop_config)
         write(dir, "README.md", readme(name))
+        write(dir, "CLAUDE.md", claude_md(name))
 
         # Create empty SQLite DB directory
         FileUtils.mkdir_p(File.join(dir, "db"))
@@ -406,6 +407,180 @@ module Whoosh
           IGNORE
         end
 
+        def claude_md(name)
+          title = name.gsub(/[-_]/, " ").split.map(&:capitalize).join(" ")
+          <<~MD
+            # #{title}
+
+            ## Framework
+
+            Built with [Whoosh](https://github.com/johannesdwicahyo/whoosh) — AI-first Ruby API framework.
+
+            ## Commands
+
+            ```bash
+            whoosh s                    # start server (http://localhost:9292)
+            whoosh s --reload           # hot reload on file changes
+            whoosh ci                   # run lint + security + tests
+            whoosh routes               # list all routes
+            whoosh describe             # dump app structure as JSON
+            whoosh check                # validate configuration
+            whoosh console              # IRB with app loaded
+            whoosh mcp --list           # list MCP tools
+            whoosh worker               # start background job worker
+            bundle exec rspec           # run tests
+            ```
+
+            ## Project Structure
+
+            ```
+            app.rb              # main app — routes, auth, config
+            config.ru           # Rack entry point
+            config/app.yml      # configuration (database, cache, jobs, logging)
+            config/plugins.yml  # plugin configuration
+            endpoints/          # class-based endpoints (auto-loaded)
+            schemas/            # request/response schemas (dry-schema)
+            models/             # Sequel models
+            db/migrations/      # database migrations
+            middleware/         # custom middleware
+            test/               # RSpec tests
+            .env                # secrets (never commit)
+            ```
+
+            ## Patterns
+
+            ### Adding an endpoint
+
+            ```bash
+            whoosh generate endpoint users name:string email:string
+            ```
+
+            Or manually:
+
+            ```ruby
+            # endpoints/users.rb
+            class UsersEndpoint < Whoosh::Endpoint
+              get "/users"
+              post "/users", request: CreateUserSchema
+
+              def call(req)
+                case req.method
+                when "GET" then { users: [] }
+                when "POST" then { created: true }
+                end
+              end
+            end
+            ```
+
+            ### Adding a schema
+
+            ```ruby
+            # schemas/user.rb
+            class CreateUserSchema < Whoosh::Schema
+              field :name,  String,  required: true, desc: "User name"
+              field :email, String,  required: true, desc: "Email"
+              field :age,   Integer, min: 0, max: 150
+            end
+            ```
+
+            ### Inline routes (in app.rb)
+
+            ```ruby
+            App.get "/health" do
+              { status: "ok" }
+            end
+
+            App.post "/items", request: ItemSchema, auth: :api_key do |req|
+              { created: req.body[:name] }
+            end
+            ```
+
+            ### Auth
+
+            Protected routes use `auth: :api_key` or `auth: :jwt`:
+            ```ruby
+            App.get "/protected", auth: :api_key do |req|
+              { user: req.env["whoosh.auth"][:key] }
+            end
+            ```
+
+            ### Background jobs
+
+            ```ruby
+            class MyJob < Whoosh::Job
+              inject :db  # DI injection
+              queue :default
+              retry_limit 3
+              retry_backoff :exponential
+
+              def perform(user_id:)
+                { done: true }
+              end
+            end
+
+            MyJob.perform_async(user_id: 42)
+            MyJob.perform_in(3600, user_id: 42)  # 1 hour delay
+            ```
+
+            ### Streaming (SSE/LLM)
+
+            ```ruby
+            App.post "/chat" do |req|
+              stream_llm do |out|
+                out << "Hello "
+                out << "World"
+                out.finish
+              end
+            end
+            ```
+
+            ### MCP tools
+
+            Routes with `mcp: true` are auto-exposed as MCP tools:
+            ```ruby
+            App.post "/analyze", mcp: true, request: AnalyzeSchema do |req|
+              { result: "analyzed" }
+            end
+            ```
+
+            ### Testing
+
+            ```ruby
+            require "whoosh/test"
+            RSpec.describe "API" do
+              include Whoosh::Test
+              def app = App.to_rack
+
+              it "works" do
+                post_json "/items", { name: "test" }
+                assert_response 200
+                assert_json(name: "test")
+              end
+            end
+            ```
+
+            ## AI Introspection
+
+            ```bash
+            whoosh describe              # full app structure as JSON
+            whoosh describe --routes     # routes with schemas
+            whoosh describe --schemas    # all schema definitions
+            ```
+
+            ## Configuration
+
+            All config in `config/app.yml`. Environment variables override YAML.
+            Secrets in `.env` (auto-loaded at boot, never committed).
+
+            ## Response Format
+
+            Simple flat JSON. Not JSON:API.
+            - Success: `{"name": "Alice"}`
+            - Error: `{"error": "validation_failed", "details": [...]}`
+            - Pagination: `{"data": [...], "pagination": {"page": 1}}`
+          MD
+        end
+
         def readme(name)
           title = name.gsub(/[-_]/, " ").split.map(&:capitalize).join(" ")
           <<~MD

data/lib/whoosh/streaming/websocket.rb

@@ -1,25 +1,34 @@
-# lib/whoosh/streaming/websocket.rb
 # frozen_string_literal: true
 
 require "json"
+require "digest"
+require "base64"
 
 module Whoosh
   module Streaming
     class WebSocket
-      def initialize(io)
-        @io = io
+      GUID = "258EAFA5-E914-47DA-95CA-5AB5DC65C3E5"
+
+      attr_reader :env
+
+      def initialize(env)
+        @env = env
+        @io = nil
         @closed = false
         @on_message = nil
         @on_close = nil
+        @on_open = nil
       end
 
-      def send(data)
-        return if @closed
-        formatted = data.is_a?(String) ? data : JSON.generate(data)
-        @io.write(formatted + "\n")
-        @io.flush if @io.respond_to?(:flush)
-      rescue IOError, Errno::EPIPE
-        @closed = true
+      # Check if the request is a WebSocket upgrade
+      def self.websocket?(env)
+        env["HTTP_UPGRADE"]&.downcase == "websocket" &&
+          env["HTTP_CONNECTION"]&.downcase&.include?("upgrade")
+      end
+
+      # Register callbacks
+      def on_open(&block)
+        @on_open = block
       end
 
       def on_message(&block)
@@ -30,6 +39,67 @@ module Whoosh
         @on_close = block
       end
 
+      # Send data to the client
+      def send(data)
+        return if @closed
+        formatted = data.is_a?(String) ? data : JSON.generate(data)
+        write_frame(formatted)
+      end
+
+      def close
+        return if @closed
+        @closed = true
+        write_close_frame
+        @io&.close rescue nil
+        @on_close&.call
+      end
+
+      def closed?
+        @closed
+      end
+
+      # Returns a Rack response that hijacks the connection
+      def rack_response
+        unless self.class.websocket?(@env)
+          return [400, { "content-type" => "text/plain" }, ["Not a WebSocket request"]]
+        end
+
+        # WebSocket handshake
+        key = @env["HTTP_SEC_WEBSOCKET_KEY"]
+        accept = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+
+        headers = {
+          "Upgrade" => "websocket",
+          "Connection" => "Upgrade",
+          "Sec-WebSocket-Accept" => accept
+        }
+
+        # Use rack.hijack to take over the connection
+        if @env["rack.hijack"]
+          @env["rack.hijack"].call
+          @io = @env["rack.hijack_io"]
+
+          # Send handshake response manually
+          @io.write("HTTP/1.1 101 Switching Protocols\r\n")
+          headers.each { |k, v| @io.write("#{k}: #{v}\r\n") }
+          @io.write("\r\n")
+          @io.flush
+
+          # Notify open
+          @on_open&.call
+
+          # Start reading frames in a thread
+          Thread.new { read_loop }
+
+          # Return a dummy response (connection is hijacked)
+          [-1, {}, []]
+        else
+          # Fallback: return 101 and let the server handle hijack
+          [101, headers, []]
+        end
+      end
+
+      # For testing — simulate without real socket
       def trigger_message(msg)
         @on_message&.call(msg)
       end
@@ -39,12 +109,86 @@ module Whoosh
         @closed = true
       end
 
-      def close
+      private
+
+      def read_loop
+        while !@closed && @io && !@io.closed?
+          frame = read_frame
+          break unless frame
+
+          case frame[:opcode]
+          when 0x1 # Text frame
+            @on_message&.call(frame[:data])
+          when 0x8 # Close frame
+            close
+            break
+          when 0x9 # Ping
+            write_pong(frame[:data])
+          end
+        end
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE
         @closed = true
+        @on_close&.call
       end
 
-      def closed?
-        @closed
+      def read_frame
+        return nil unless @io && !@io.closed?
+
+        first_byte = @io.readbyte
+        fin = (first_byte & 0x80) != 0
+        opcode = first_byte & 0x0F
+
+        second_byte = @io.readbyte
+        masked = (second_byte & 0x80) != 0
+        length = second_byte & 0x7F
+
+        if length == 126
+          length = @io.read(2).unpack1("n")
+        elsif length == 127
+          length = @io.read(8).unpack1("Q>")
+        end
+
+        mask_key = masked ? @io.read(4).bytes : nil
+        payload = @io.read(length)&.bytes || []
+
+        if masked && mask_key
+          payload = payload.each_with_index.map { |b, i| b ^ mask_key[i % 4] }
+        end
+
+        { opcode: opcode, data: payload.pack("C*"), fin: fin }
+      rescue EOFError, IOError
+        nil
+      end
+
+      def write_frame(data, opcode: 0x1)
+        return unless @io && !@io.closed?
+
+        bytes = data.encode("UTF-8").bytes
+        frame = [0x80 | opcode] # FIN + opcode
+
+        if bytes.length < 126
+          frame << bytes.length
+        elsif bytes.length < 65536
+          frame << 126
+          frame += [bytes.length].pack("n").bytes
+        else
+          frame << 127
+          frame += [bytes.length].pack("Q>").bytes
+        end
+
+        frame += bytes
+        @io.write(frame.pack("C*"))
+        @io.flush
+      rescue IOError, Errno::EPIPE
+        @closed = true
+      end
+
+      def write_close_frame
+        write_frame("", opcode: 0x8) rescue nil
+      end
+
+      def write_pong(data)
+        write_frame(data, opcode: 0xA) rescue nil
       end
     end
   end

data/lib/whoosh/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Whoosh
-  VERSION = "1.2.2"
+  VERSION = "1.3.1"
 end

data/lib/whoosh.rb

@@ -28,6 +28,7 @@ module Whoosh
   autoload :Jobs,                "whoosh/jobs"
   autoload :Metrics,             "whoosh/metrics"
   autoload :Paginate,            "whoosh/paginate"
+  autoload :AI,                  "whoosh/ai"
   autoload :VectorStore,         "whoosh/vector_store"
 
   module Auth

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whoosh
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.1
 platform: ruby
 authors:
 - Johannes Dwi Cahyo
@@ -174,6 +174,9 @@ files:
 - README.md
 - exe/whoosh
 - lib/whoosh.rb
+- lib/whoosh/ai.rb
+- lib/whoosh/ai/llm.rb
+- lib/whoosh/ai/structured_output.rb
 - lib/whoosh/app.rb
 - lib/whoosh/auth/access_control.rb
 - lib/whoosh/auth/api_key.rb