hugpy-tools

hugpy_tools is a standalone set of tools for autonomous agents. Its core uses only the standard library. Optional backends add document extraction, model-specific token counting, rendering, media, image, desktop and VM tools. It does not import Toolserver, and it needs no running service, database or fleet.

Distribution hugpy-tools 0.2.7, import hugpy_tools. It has no runtime dependencies.

Status: LIVE. It is installed as a library in /opt/hugpy-core/venv, /opt/hugpy-agent/venv and /opt/hugpy-harness/venv. It runs no service of its own. Its consumers:

• abstract_toolserver 0.0.98 and later: the tool registry
• hugpy-agent
• hugpy-harness: hugpy_harness.tools.portable
• the media, video and agent toolsets: hugpy_tools.schema.build_parameters, imported lazily

The live 7004_toolserver service still runs abstract_toolserver 0.0.91, which predates this split and does not use hugpy_tools. See docs/packages.md.

Standalone use

pip install hugpy-tools
hugpy-tools list [--optional]         # every tool: name, description, inputSchema (JSON)
hugpy-tools call text_estimate_tokens --arguments '{"text":"hello world"}'
# The same CLI is available as python -m hugpy_tools.

from hugpy_tools import call_tool, get_toolset, list_tools

result = call_tool("fs_read_lines", {"path": "/tmp/example.txt", "start": 1, "end": 20})
schemas = list_tools()  # name, description, inputSchema
tools = get_toolset()  # category -> route -> callable; fresh mappings per call

Direct module functions remain available. include_optional=True adds backend tools to each registry API, or use --optional with the CLI. Discovery imports no optional backend; an unavailable dependency fails when that tool is called. Install only the extras needed: files, text, web, legacy (all three), render, images, vision, media, or desktop. Rendering also needs a Playwright browser installation; VM operations require host libvirt/LXD tools.

Toolserver integration

The dependency runs one way: abstract_toolserver imports hugpy_tools.

Boards, handoffs, credentials, database records, and managed browser/VM sessions remain Toolserver services. process.run_command(argv) is available directly; Toolserver exposes it through its allowlist-gated sys_run_cmd adapter.

compat.py preserves established Toolserver arguments and backend results where the native helpers have different contracts. For example, text_estimate_tokens is approximate and dependency-free; optional text_count_tokens retains the model_name argument and model-specific backend. fs_read_text returns metadata and text; fs_read_file retains the text-only result. Old Toolserver visual imports alias the portable modules, so there is one implementation to maintain.

The imports/ layer

hugpy_tools/imports/ is the reference for the workspace-wide imports/ layout (docs/packages.md). Importing it performs no I/O and loads no optional backend:

from hugpy_tools.imports import constants as C
from hugpy_tools.imports.functions import lazy
from hugpy_tools.imports.classes import ToolError
from hugpy_tools.imports.init_imports import *   # the house one-stop surface

Other shared modules: schema.build_parameters(func) builds a JSON-schema inputSchema from a function signature, and toolset.get_toolset(), list_tools() and call_tool() are the registry.

Built-in tools

Every fs function takes an already-confined absolute path — call paths.confine(root, path) first to enforce a workspace jail (rejects .., absolute-outside, and symlink escapes in one check).

Web assessment

assess_webpage returns the same dict shape as abstract_webtools.assessManager.assess_webpage ({url, title, description, text, metadata, jsonld, links, truncated, render}) plus additive keys final_url, status, canonical, lang, headings, and error. The fetch is http(s)-only, refuses redirects to other schemes, disables file:// / ftp://, caps the body, times out, handles gzip/deflate, and detects charset (Content-Type → BOM → <meta charset> → utf-8 → cp1252).

JS rendering is opt-in and lazy: force_render=True (or an automatic fall-back when the cheap fetch yields almost no text) drives a headless browser only if Playwright or Selenium is installed, and raises a clear "install X" error otherwise. The default path never needs a browser.

Layer

Foundation. Core imports use only the standard library. Optional integrations are loaded on use from compat, backends, and visual; they must not import abstract_toolserver. The host owns authorization and resource lifecycle.