Package org.machanism.machai.ai.tools

Class WebFunctionTools

java.lang.Object

org.machanism.machai.ai.tools.WebFunctionTools

All Implemented Interfaces:

FunctionTools

public class WebFunctionTools
extends Object
implements FunctionTools

Installs HTTP retrieval tools into a Genai.

This tool set provides two host-side functions:

• get_web_content – Fetches web page content over HTTP(S) via GET and optionally returns plain text or content selected via a CSS selector.
• call_rest_api – Executes a generic REST call using an arbitrary HTTP method with optional headers and request body.

Header variable placeholders

Header values may include placeholders in the form ${propertyName}. When a Configurator is provided via setConfigurator(Configurator), those placeholders are resolved at runtime.

Authentication

HTTP Basic authentication is supported via the URL userInfo component (for example https://user:password@host/path), which is converted into an Authorization: Basic ... header. You can also specify an explicit Authorization header.

Outbound network policy (allow/deny lists) is intentionally left to the host application.

Author:

Viktor Tovstyi

Constructor Summary

Constructors

Constructor	Description
WebFunctionTools()

Method Summary

Modifier and Type	Method	Description
(package private) String	applySelectorIfPresent(String selector, String response)	Applies a CSS selector to the response HTML if one was provided.
void	applyTools(Genai provider)	Registers web content and REST API function tools with the provided Genai.
String	callRestApi(Object[] params)	Implements call_rest_api by executing an HTTP request against the provided endpoint.
(package private) void	fillHeader(String headers, HttpURLConnection connection)	Applies headers to the connection.
(package private) HttpURLConnection	getConnection(URI uri, String headers)	Creates and configures an HttpURLConnection.
String	getWebContent(Object[] params)	Implements get_web_content by retrieving web content via an HTTP GET request.
(package private) String	getWebPage(HttpURLConnection connection, int timeout, String charsetName)	Performs the HTTP GET request and returns the response content.
void	setConfigurator(Configurator configurator)	Supplies configuration for resolving header placeholders.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.machanism.machai.ai.tools.FunctionTools

replace

Constructor Details

WebFunctionTools

public WebFunctionTools()

Method Details

applyTools

public void applyTools(Genai provider)

Registers web content and REST API function tools with the provided Genai.

Specified by:

applyTools in interface FunctionTools

Parameters:

provider - the provider to register tools with

getWebContent

public String getWebContent(Object[] params)

Implements get_web_content by retrieving web content via an HTTP GET request.

Parameters are passed in params:

1. JsonNode containing the tool arguments
2. (optional) additional runtime-supplied arguments, ignored by this tool

Supported JSON properties:

• url (required) – target URL
• headers (optional) – newline-separated NAME=VALUE pairs
• timeout (optional) – timeout in milliseconds (default 10000)
• charsetName (optional) – response decoding charset (default UTF-8)
• textOnly (optional) – if true, strips HTML to plain text
• selector (optional) – extracts content matching the CSS selector (text or HTML depending on textOnly)

Parameters:

params - tool arguments

Returns:

response content or an error message

applySelectorIfPresent

String applySelectorIfPresent(String selector,
 String response)

Applies a CSS selector to the response HTML if one was provided.

Parameters:

selector - CSS selector (may be blank)

response - full response content

Returns:

selected HTML content (joined with newlines) or the original response if selector is blank

getConnection

HttpURLConnection getConnection(URI uri,
 String headers)
                         throws IOException

Creates and configures an HttpURLConnection.

If the URI contains userInfo, it is removed from the request URI and used to set an HTTP Basic Authorization header.

Parameters:

uri - URI to connect to

headers - optional headers (newline-separated NAME=VALUE)

Returns:

connection

Throws:

IOException - if opening a connection fails

getWebPage

String getWebPage(HttpURLConnection connection,
 int timeout,
 String charsetName)
           throws IOException

Performs the HTTP GET request and returns the response content.

Parameters:

connection - open connection

timeout - timeout in milliseconds

charsetName - charset used to decode the response

Returns:

response content including an initial status line

Throws:

IOException - if the request cannot be executed

callRestApi

public String callRestApi(Object[] params)

Implements call_rest_api by executing an HTTP request against the provided endpoint.

Supported JSON properties:

• url (required) – endpoint URL
• method (optional) – HTTP method (default GET)
• headers (optional) – newline-separated NAME=VALUE pairs
• body (optional) – request body (used for POST/PUT/PATCH only)
• timeout (optional) – timeout in milliseconds (default 10000)
• charsetName (optional) – request/response charset (default UTF-8)

Parameters:

params - tool arguments

Returns:

response content including an initial HTTP status line, or an error message

fillHeader

void fillHeader(String headers,
 HttpURLConnection connection)

Applies headers to the connection.

Each header line must be in the form NAME=VALUE. Header values may include ${...} placeholders.

Parameters:

headers - newline-separated header definitions

connection - connection to configure

setConfigurator

public void setConfigurator(Configurator configurator)

Supplies configuration for resolving header placeholders.

Specified by:

setConfigurator in interface FunctionTools

Parameters:

configurator - configurator to use (may be null)