whoosh 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f647a91b22fcee8322c6af7bf0ab0ac0108aa3113e2d4db89a3f187bb6a1caa3
-  data.tar.gz: e46c07b2f4fbaf1233bb52a321ff161952989313adbbfebdb5b7bf1c08675f08
+  metadata.gz: 589d3cd63bfe7cb2a7ae32d8de43c064eb0e9dadfae68ecb1907bea9a099cd7d
+  data.tar.gz: a18f684c03fa83b5e7e86febd6eca0bc79d01d5c3cf719b729118eea91510e9c
 SHA512:
-  metadata.gz: 1ca2dbc63ab481d5d61260cfbfca37768a9498fa74fe90d68f039884f05ca2a79f0fa08da07fdca04ba175e95ab0997d5cc00acf0e8b2bbceef5ca576f8fef91
-  data.tar.gz: b0361d6a812b80e093125f7be7d5681977ab615b6ebccacbe87753352223e6058e0076dd2eace8e3092a60a57e3387b9ebe0baed4b2f623befeb8f1c38d9435e
+  metadata.gz: 3ffb5d9e6d905e3914d9cf54738966c5d3ba625a89f33c8c2b3c98698f9a04ba1b6710584efa69917e24ef02b52b870f616a4ad6e6a7d631c4707319d1db7e47
+  data.tar.gz: e57044ee4ec0c6a1b872d85cd0abeb274ee3c260c46dcc38b925994a6b88c7b004188314c7b60e8e3a7ce5aef4198581c817fbd8870ceaca6ddbe20fce4abd75

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
@@ -307,6 +308,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 +453,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
 
@@ -224,45 +373,67 @@ module Whoosh
         end
       }
 
-      desc "ci", "Run full CI pipeline (lint + security + tests)"
+      desc "ci", "Run full CI pipeline (lint + security + audit + tests + coverage)"
       def ci
         puts "=> Whoosh CI Pipeline"
         puts "=" * 50
         puts ""
 
         steps = []
+        skipped = []
 
         # Step 1: Rubocop (lint)
         if system("bundle exec rubocop --version > /dev/null 2>&1")
           steps << { name: "Rubocop (lint)", cmd: "bundle exec rubocop --format simple" }
         else
-          puts "  [skip] Rubocop not installed (add rubocop to Gemfile)"
+          skipped << "Rubocop (add rubocop to Gemfile)"
         end
 
-        # Step 2: Brakeman (security)
+        # Step 2: Brakeman (security scan)
         if system("bundle exec brakeman --version > /dev/null 2>&1")
           steps << { name: "Brakeman (security)", cmd: "bundle exec brakeman -q --no-pager" }
         else
-          puts "  [skip] Brakeman not installed (add brakeman to Gemfile)"
+          skipped << "Brakeman (add brakeman to Gemfile)"
         end
 
-        # Step 3: RSpec (tests)
+        # Step 3: Bundle audit (CVE check)
+        if system("bundle exec bundle-audit version > /dev/null 2>&1")
+          steps << { name: "Bundle Audit (CVE)", cmd: "bundle exec bundle-audit check --update" }
+        elsif system("bundle audit --help > /dev/null 2>&1")
+          steps << { name: "Bundle Audit (CVE)", cmd: "bundle audit" }
+        else
+          skipped << "Bundle Audit (add bundler-audit to Gemfile)"
+        end
+
+        # Step 4: Secret leak scan (built-in, no gem needed)
+        steps << { name: "Secret Scan", type: :secret_scan }
+
+        # Step 5: RSpec (tests)
         if system("bundle exec rspec --version > /dev/null 2>&1")
           steps << { name: "RSpec (tests)", cmd: "bundle exec rspec --format progress" }
         else
-          puts "  [skip] RSpec not installed"
+          skipped << "RSpec (add rspec to Gemfile)"
         end
 
-        # Step 4: Gem build check
-        gemspec = Dir.glob("*.gemspec").first
-        if gemspec
-          steps << { name: "Gem build", cmd: "gem build #{gemspec} --quiet" }
-        end
+        # Step 6: Coverage check (built-in)
+        steps << { name: "Coverage Check", type: :coverage_check }
+
+        skipped.each { |s| puts "  [skip] #{s}" }
+        puts "" unless skipped.empty?
 
         failed = []
         steps.each_with_index do |step, i|
           puts "--- [#{i + 1}/#{steps.length}] #{step[:name]} ---"
-          success = system(step[:cmd])
+
+          success = case step[:type]
+          when :secret_scan
+            run_secret_scan
+          when :coverage_check
+            run_coverage_check
+          else
+            system(step[:cmd])
+          end
+
           if success
             puts "  ✓ #{step[:name]} passed"
           else
@@ -274,7 +445,7 @@ module Whoosh
 
         puts "=" * 50
         if failed.empty?
-          puts "=> All checks passed! ✓"
+          puts "=> All #{steps.length} checks passed! ✓"
           exit 0
         else
           puts "=> FAILED: #{failed.join(', ')}"
@@ -282,6 +453,76 @@ module Whoosh
         end
       end
 
+      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,
+          /(?:sk-|pk-|rk-)[a-zA-Z0-9]{20,}/,
+          /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/,
+          /AKIA[0-9A-Z]{16}/,  # AWS access key
+        ]
+
+        leaked = []
+        Dir.glob("{app.rb,lib/**/*.rb,endpoints/**/*.rb,config/**/*.rb}").each do |file|
+          next if file.include?("spec/") || file.include?("test/")
+          content = File.read(file) rescue next
+          patterns.each do |pattern|
+            content.each_line.with_index do |line, i|
+              if line.match?(pattern) && !line.include?("ENV[") && !line.include?("ENV.fetch")
+                leaked << "#{file}:#{i + 1}: #{line.strip[0..80]}"
+              end
+            end
+          end
+        end
+
+        if leaked.empty?
+          true
+        else
+          puts "  Potential secrets found:"
+          leaked.each { |l| puts "    #{l}" }
+          false
+        end
+      end
+
+      def run_coverage_check
+        coverage_file = File.join(Dir.pwd, "coverage", ".last_run.json")
+        unless File.exist?(coverage_file)
+          puts "  [info] No coverage data found (add simplecov to test_helper for tracking)"
+          true  # Don't fail if SimpleCov not set up
+        else
+          require "json"
+          data = JSON.parse(File.read(coverage_file))
+          coverage = data.dig("result", "line") || data.dig("result", "covered_percent") || 0
+          threshold = 80
+
+          if coverage >= threshold
+            puts "  Coverage: #{coverage.round(1)}% (threshold: #{threshold}%)"
+            true
+          else
+            puts "  Coverage: #{coverage.round(1)}% — below #{threshold}% threshold"
+            false
+          end
+        end
+      end
+
+      public
+
       desc "new NAME", "Create a new Whoosh project"
       option :minimal, type: :boolean, default: false
       option :full, type: :boolean, default: false

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"))
@@ -150,6 +151,8 @@ module Whoosh
               gem "rack-test"
               gem "rubocop", require: false
               gem "brakeman", require: false
+              gem "bundler-audit", require: false
+              gem "simplecov", require: false
             end
           GEM
 
@@ -256,6 +259,13 @@ module Whoosh
           <<~RUBY
             # frozen_string_literal: true
 
+            require "simplecov"
+            SimpleCov.start do
+              add_filter "/test/"
+              add_filter "/spec/"
+              minimum_coverage 80
+            end
+
             require "whoosh/test"
             require_relative "../app"
 
@@ -397,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Whoosh
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 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.1
+  version: 1.3.0
 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