whoosh 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 336c26ea284a871dafa4b1d26f173293947e30470000539dbf3e0da799063bea
-  data.tar.gz: 6acf7d5007d008070aaddb543a42de5bddf3b3aa2de838e1be5ccba5d18b9442
+  metadata.gz: 589d3cd63bfe7cb2a7ae32d8de43c064eb0e9dadfae68ecb1907bea9a099cd7d
+  data.tar.gz: a18f684c03fa83b5e7e86febd6eca0bc79d01d5c3cf719b729118eea91510e9c
 SHA512:
-  metadata.gz: 86aebc850e904960fe87d08aa7c6e8d6aba82c5e411e66e0e9ae65fb64d5510b8ddae4125099554fecac71907c163ce854d1adc416bd8e84ee5f6f3376556809
-  data.tar.gz: 99c067d27463fff53a3cb5818836a11e90e0e86d1f886d211770a6407725b6ca0ba72cd3e52c94bd4b204d57e5d282ff89d102863c9410c545c63e3d60bcf332
+  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
 
@@ -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/version.rb

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