ask-web-search 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c390a4cff0c0fbb46d883f71912c424eaf1c56a131f812c48723b6c1fff160d9
-  data.tar.gz: a926c135fd2a95191a583bb62bd8fb8b29ffda65eb477324c7ebef8abd41e3bf
+  metadata.gz: fe356e9cdc2a7ee736d51ad93d36dfcaaef72168b0a4b3d98bc19945b919dd4a
+  data.tar.gz: e334c6903ab48de0a78fee36c07933487dcab49648cc31bbe3adfd46653de01a
 SHA512:
-  metadata.gz: 555e34c32eec8a00f2bd984cc306e463de6c25b5901b16bea73c4bd004274d5c9b3671c655a79054d807f4e1be247c3a039578aea1ac4506a4daed156b4efbe7
-  data.tar.gz: 33f2a4597debe966b46ae98dcb6b85d44c3ab399fc65917eff99275c6183c327c04bc1016eb1af8437f47e3d391e5749e5f4d320b7964b920d60890c886ce02d
+  metadata.gz: d1fc95c583e7fc95a15ef32b7e1253302c6e2ba1edee41781445c912a1d8631cba839dac044fb94a1cc20d51d219960102cccec5d75eecbf1cef92de0f92e559
+  data.tar.gz: f56f4d8df11e3de5de981e0f5d182d8491cb12840f12dc4e546986fd9c4f6b82668313cd4270468215f460e5a29ece4ecb0e28bc4c301c88dfd39dc1656ae7e6

data/README.md

@@ -1,8 +1,12 @@
 # ask-web-search
 
-A web search tool for the ask-rb ecosystem. Provides `Ask::Tools::WebSearch`, which
-searches the web via a local [SearXNG](https://docs.searxng.org/) instance and returns
-formatted results for LLM consumption.
+[![Gem Version](https://badge.fury.io/rb/ask-web-search.svg)](https://badge.fury.io/rb/ask-web-search)
+
+A web search tool for the ask-rb ecosystem. It provides
+`Ask::Tools::WebSearch`, which searches the web via a local
+[SearXNG](https://docs.searxng.org/) instance and returns numbered markdown
+results for LLM consumption. It has no Rails dependencies; it depends only on
+ask-tools.
 
 ## Prerequisites
 
@@ -14,21 +18,11 @@ Start one with Docker:
 docker run -d --name searxng -p 8888:8080 searxng/searxng
 ```
 
-Or use the provided `docker-compose.yml`:
-
-```sh
-cd searxng
-docker compose up -d
-```
+Or use the provided `docker-compose.yml` in the `searxng` directory of this
+repository:
 
 ## Installation
 
-```sh
-gem install ask-web-search
-```
-
-Or in your Gemfile:
-
 ```ruby
 gem "ask-web-search"
 ```
@@ -43,7 +37,7 @@ export SEARXNG_URL=http://localhost:8888
 
 Defaults to `http://localhost:8888`.
 
-## Usage
+## Quick Start
 
 ```ruby
 require "ask/web_search"
@@ -51,35 +45,12 @@ require "ask/web_search"
 tool = Ask::Tools::WebSearch.new
 result = tool.execute(query: "ruby programming language")
 puts result
-# => 1. Ruby — A Programmer's Best Friend
-#     https://www.ruby-lang.org
-#     Ruby is a dynamic, open-source programming language...
-```
-
-### With ask-rb Chat
-
-```ruby
-chat = Ask::Agent::Chat.new(
-  model: "deepseek-v4-flash",
-  tools: [Ask::Tools::WebSearch.new]
-)
-
-chat.ask("What's the latest on AI? Search the web.")
-```
-
-### With ask-rb Agent
-
-```ruby
-agent = Ask::Agent.new(tools: [Ask::Tools::WebSearch])
-agent.run("Find recent news about SpaceX")
 ```
 
-## Output Format
-
 Results are returned as a numbered markdown-like string:
 
 ```
-1. Ruby — A Programmer's Best Friend
+1. Ruby - A Programmer's Best Friend
    https://www.ruby-lang.org
    Ruby is a dynamic, open-source programming language...
 
@@ -90,11 +61,16 @@ Results are returned as a numbered markdown-like string:
 
 If no results are found, returns `"No results found."`.
 
+## Full documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+[Core: Web Search](https://ask-rb.github.io/ask-docs/core/web-search) covers
+ask-web-search in depth, including the ask-agent integration and the MCP
+server. API reference: https://ask-rb.github.io/ask-docs/reference/api.
+
 ## Development
 
-```sh
-git clone https://github.com/ask-rb/ask-web-search
-cd ask-web-search
+```
 bundle install
 bundle exec rake test
 ```

data/lib/ask/web_search/tool.rb

@@ -1,17 +1,22 @@
+# frozen_string_literal: true
+
 require "ask-tools"
-require "net/http"
-require "uri"
-require "json"
 
 module Ask
   module Tools
+    # The native agent tool for web search — the Ask::Tool framing of the
+    # library. Consumed WITHOUT MCP by agent frameworks (ask-agent's
+    # `tool: :web_search`, ask-app-server, llm-proxy) that resolve tools
+    # from the Ask::Tools registry. A pure adapter: the capability
+    # (search, parsing, formatting) lives in Ask::WebSearch, and this file
+    # loads only when ask-tools is present (see lib/ask/web_search.rb).
     class WebSearch < Ask::Tool
       def self.searxng_url
-        @searxng_url || ENV.fetch("SEARXNG_URL", "http://localhost:8888")
+        Ask::WebSearch.searxng_url
       end
 
       def self.searxng_url=(url)
-        @searxng_url = url
+        Ask::WebSearch.searxng_url = url
       end
 
       description "Search the web for current information. Use this to get up-to-date results, recent events, or facts that may have changed."
@@ -25,49 +30,10 @@ module Ask
       )
 
       def execute(query:)
-        results = search(query)
-        Ask::Result.ok(data: format_results(results))
-      end
-
-      private
-
-      def search(query)
-        uri = URI("#{self.class.searxng_url}/search?q=#{URI.encode_www_form_component(query)}&format=json")
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.open_timeout = 5
-        http.read_timeout = 10
-        req = Net::HTTP::Get.new(uri)
-        req["User-Agent"] = "ask-web-search/1.0"
-        res = http.request(req)
-        raise "SearXNG returned #{res.code}: #{res.body}" unless res.code.start_with?("2")
-
-        data = JSON.parse(res.body)
-        parse_results(data)
-      end
-
-      def parse_results(data)
-        results = []
-        data.fetch("results", []).each do |r|
-          results << { url: r["url"], title: r["title"], content: r["content"] }
-        end
-        data.fetch("infoboxes", []).each do |ib|
-          results << { url: ib["id"], title: ib["infobox"], content: ib["content"] }
-        end
-        results.uniq { |r| r[:url] }
-      end
-
-      def format_results(results)
-        return "No results found." if results.empty?
-
-        results.each_with_index.map do |r, i|
-          line = "#{i + 1}. #{r[:title]}"
-          line += "\n   #{r[:url]}"
-          line += "\n   #{r[:content]}" if r[:content] && !r[:content].empty?
-          line
-        end.join("\n\n")
+        Ask::Result.ok(data: Ask::WebSearch.search(query))
       end
     end
   end
 end
 
-Ask::Tools.register(Ask::Tools::WebSearch) if defined?(Ask::Tools)
+Ask::Tools.register(Ask::Tools::WebSearch)

data/lib/ask/web_search/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module WebSearch
-    VERSION = "0.2.3"
+    VERSION = "0.3.0"
   end
 end

data/lib/ask/web_search.rb

@@ -1,2 +1,84 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
 require_relative "web_search/version"
-require_relative "web_search/tool"
+
+module Ask
+  # Searches the web via a local SearXNG instance and returns the results
+  # as clean, numbered markdown for LLM consumption. The capability layer:
+  # one entry point (WebSearch.search) and a configurable endpoint. Tool
+  # framing — name, parameter schema, result wrapping — lives with the
+  # consumers (the MCP server, the agents) that call this library.
+  module WebSearch
+    # Local SearXNG endpoint. Defaults to the standard local instance;
+    # override with SEARXNG_URL or WebSearch.searxng_url=.
+    def self.searxng_url
+      @searxng_url || ENV.fetch("SEARXNG_URL", "http://localhost:8888")
+    end
+
+    def self.searxng_url=(url)
+      @searxng_url = url
+    end
+
+    # Searches +query+ and returns the results as numbered markdown
+    # ("No results found." when SearXNG found nothing). Raises on
+    # connection/HTTP failures — the caller decides how to surface them.
+    def self.search(query)
+      format_results(search_results(query))
+    end
+
+    # The raw result list: { url:, title:, content: } entries from the
+    # results and infoboxes, deduplicated by url.
+    def self.search_results(query)
+      uri = URI("#{searxng_url}/search?q=#{URI.encode_www_form_component(query)}&format=json")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = 5
+      http.read_timeout = 10
+      req = Net::HTTP::Get.new(uri)
+      req["User-Agent"] = "ask-web-search/#{Ask::WebSearch::VERSION}"
+      res = http.request(req)
+      raise "SearXNG returned #{res.code}: #{res.body}" unless res.code.start_with?("2")
+
+      parse_results(JSON.parse(res.body))
+    end
+
+    def self.parse_results(data)
+      results = []
+      data.fetch("results", []).each do |r|
+        results << { url: r["url"], title: r["title"], content: r["content"] }
+      end
+      data.fetch("infoboxes", []).each do |ib|
+        results << { url: ib["id"], title: ib["infobox"], content: ib["content"] }
+      end
+      results.uniq { |r| r[:url] }
+    end
+    private_class_method :parse_results
+
+    def self.format_results(results)
+      return "No results found." if results.empty?
+
+      results.each_with_index.map do |r, i|
+        line = "#{i + 1}. #{r[:title]}"
+        line += "\n   #{r[:url]}"
+        line += "\n   #{r[:content]}" if r[:content] && !r[:content].empty?
+        line
+      end.join("\n\n")
+    end
+    private_class_method :format_results
+  end
+end
+
+# The native agent tool (Ask::Tools::WebSearch) is an OPTIONAL integration:
+# it loads and registers only when ask-tools is present. The library works
+# standalone — consumers that only call WebSearch.search pay nothing —
+# while agent frameworks (ask-agent, ask-app-server, llm-proxy) all ship
+# ask-tools and get the registry tool with no extra step. Only the
+# ask-tools miss is swallowed; any other LoadError is real.
+begin
+  require "ask-tools"
+  require_relative "web_search/tool"
+rescue LoadError => e
+  raise unless e.path == "ask-tools"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-web-search
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -16,7 +16,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -79,9 +79,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Provides Ask::Tools::WebSearch, a tool that searches the web via SearXNG
-  (local instance). Works with any ask-rb chat or agent. Configure endpoint via SEARXNG_URL
-  env var.
+description: Searches the web via a local SearXNG instance and returns the results
+  as clean numbered markdown. The capability layer (WebSearch.search); the native
+  Ask::Tools::WebSearch agent tool is an optional integration that registers when
+  ask-tools is present. Configure endpoint via SEARXNG_URL env var.
 email:
 - kaka@myrrlabs.com
 executables: []
@@ -117,5 +118,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Web search tool for the ask-rb ecosystem
+summary: Web search library for the ask-rb ecosystem
 test_files: []