hugpy-tools

hugpy_tools is a standalone capability suite for autonomous agents. Its core uses only the standard library; optional backends provide document extraction, model-specific token counting, rendering, media, images, desktop, and VM tools. It does not import Toolserver or require a running service, database, or fleet.

Standalone use

pip install hugpy-tools
hugpy-tools list
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/ package supplies shared constants, functions, classes, and init_imports, following the workspace's shared-import pattern.

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.