Distribute and run LLMs with a single file.
C++ cross-platformggufllama-cpplocal-ailocal-inferencelocal-llmopen-source-aisingle-file-executablespeech-to-text
// -*- mode:c++;indent-tabs-mode:nil;c-basic-offset:4;coding:utf-8 -*-
// vi: set et ft=cpp ts=4 sts=4 sw=4 fenc=utf-8 :vi
//
// Copyright 2026 Mozilla.ai
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// web_search: queries a SearXNG instance (https://docs.searxng.org) through
// its JSON API. A server_tool, run through ServerToolAdapter like the
// upstream tools; it lives here because llama.cpp leaves web search to MCP
// or its web UI.
//
// The instance is not a tool argument, so the model can't choose where
// queries go: it comes from --searxng-url or SEARXNG_URL, and without
// either the tool isn't registered. The instance must enable `json` under
// `search: formats:` in settings.yml (public ones usually don't).
//
#pragma once
#include "server-tools.h"
#include <cpp-httplib/httplib.h>
#include "http.h" // common_http_client, common_http_parse_url
#include <string>
namespace agentfile {
namespace tools {
struct WebSearchTool : server_tool {
static constexpr int kTimeoutSeconds = 30;
// Snippet clip is input sanitation only: SearXNG engines send ~160
// chars today, so this triggers only on unusual engines/instances.
static constexpr size_t kMaxSnippet = 512;
std::string base_url; // e.g. "http://localhost:8888", no trailing slash
explicit WebSearchTool(std::string url) : base_url(std::move(url)) {
while (!base_url.empty() && base_url.back() == '/')
base_url.pop_back();
name = "web_search";
display_name = "Web search";
// Network access: confirm before running (unless --yes).
permission_write = true;
}
json get_definition() const override {
return {
{"type", "function"},
{"function", {
{"name", name},
{"description",
"Search the web via a SearXNG instance and return one page "
"of results as JSON (title, url, snippet). Use precise "
"queries; ask for the next page if the answer isn't there; "
"fetch promising URLs with other tools for more detail."},
{"parameters", {
{"type", "object"},
{"properties", {
{"query", {{"type", "string"},
{"description", "The search query"}}},
{"page", {{"type", "integer"},
{"description", "Result page number (default 1)"}}},
{"time_range", {{"type", "string"},
{"enum", json::array({"day", "month", "year"})},
{"description", "Restrict results to this time range"}}},
{"categories", {{"type", "string"},
{"description", "Comma-separated SearXNG categories, "
"e.g. \"general\", \"news\", \"it\""}}},
}},
{"required", json::array({"query"})},
}},
}},
};
}
json invoke(json params, server_tool::stream *) const override {
if (!params.contains("query")) {
return {{"error", "missing required parameter: query"}};
}
std::string query = params.at("query").get<std::string>();
std::string url = base_url + "/search?format=json&q=" +
httplib::encode_query_component(query);
int page = json_value(params, "page", 1);
if (page > 1) url += "&pageno=" + std::to_string(page);
std::string time_range = json_value(params, "time_range", std::string{});
if (time_range == "day" || time_range == "month" ||
time_range == "year") {
url += "&time_range=" + time_range;
}
std::string categories = json_value(params, "categories", std::string{});
if (!categories.empty())
url += "&categories=" + httplib::encode_query_component(categories);
try {
auto [cli, parts] = common_http_client(url);
cli.set_read_timeout(kTimeoutSeconds, 0);
cli.set_connection_timeout(kTimeoutSeconds, 0);
auto res = cli.Get(parts.path,
httplib::Headers{{"Accept", "application/json"}});
if (!res) {
return {{"error", "request failed: " +
httplib::to_string(res.error())}};
}
if (res->status == 403) {
return {{"error",
"SearXNG returned 403: the instance at " + base_url +
" does not allow the JSON API. Enable `json` "
"under `search: formats:` in its settings.yml."}};
}
if (res->status != 200) {
return {{"error", "SearXNG returned HTTP " +
std::to_string(res->status)}};
}
json body = json::parse(res->body);
json results = json::array();
if (body.contains("results") && body["results"].is_array()) {
for (const auto &r : body["results"]) {
// json_value, not r.value(): a null or non-string
// field must not throw away the whole result list.
std::string snippet =
json_value(r, "content", std::string());
if (snippet.size() > kMaxSnippet) {
snippet.resize(kMaxSnippet);
snippet += "…";
}
results.push_back({
{"title", json_value(r, "title", std::string())},
{"url", json_value(r, "url", std::string())},
{"snippet", snippet},
{"engine", json_value(r, "engine", std::string())},
});
}
}
return {
{"query", query},
{"results", results},
};
} catch (const common_json_error &e) {
return {{"error",
std::string("SearXNG returned unparseable JSON: ") +
e.what()}};
} catch (const std::exception &e) {
return {{"error", std::string("web_search failed: ") + e.what()}};
}
}
};
} // namespace tools
} // namespace agentfile