Skip to main content

hugpy-tools

hugpy_tools is a standalone set of tools for autonomous agents. Its generic implementations come from hugpy-resources and use 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, import hugpy_tools. Its base runtime dependency is hugpy-resources; optional integrations retain their existing extras.

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

Generic functions are imported directly from hugpy_resources.imports or its implementation modules. Tool capabilities remain in hugpy_tools. 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.

The optional media tools call the authoritative hugpy-media API through backends.media_proxy (default http://127.0.0.1:7340/api, overridable with HUGPY_MEDIA_API_URL). Toolserver and /media therefore share the same Media routes for Whisper, vision, extraction, summaries and the other inference operations; model placement and task selection stay in Hugpy Media/Core.

This package owns Toolserver adds
Portable implementations, backend adapters, registry, and input schemas HTTP/MCP transport, authentication, and discovery
Local screenshot rendering, image operations, grid math, and aiming helpers Hosted screenshot URLs, cleanup, and fleet vision routing
Explicit local execution Command allowlist, node delegation, and session context

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:

module contents
constants.py static defaults: DEFAULT_COMMAND_TIMEOUT, DEFAULT_VM_URI, DEFAULT_RENDER_TIMEOUT_MS
functions.py lazy("module:attr") (import on first call, so a missing backend raises ToolError instead of breaking startup), first_lazy(*paths), strip_remote_kwargs(kwargs)
classes.py ToolError
init_imports.py one-stop: json, logging, os, re, sys, time, C (the constants) and the shared names
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).

Resources group / Tools capability Function What it does
paths confine(root, path, for_write=False) Resolve a path under root; raise PathEscape on any escape.
paths file_parts(path) Decompose into dir/base/name/ext + two enclosing dir levels.
paths sanitize_filename(name) Reduce to one safe path component, length-bounded.
fs read_text(path, max_bytes=None) Read with encoding detection (BOM → utf-8 → cp1252).
fs read_lines(path, start, end, number=False) 1-based inclusive line-range read.
fs atomic_write(path, content, append=False) Durable write (temp file + os.replace); append supported.
fs edit_replace(path, old, new, count=None) Exact string replace with an occurrence-count contract; atomic.
fs file_info(path, hash_files=False) Size, mtime, type, symlink flag, optional sha256.
fs list_dir(path, glob=None, ...) Immediate entries (dirs first), optional fnmatch.
fs tree(path, max_depth=3, max_entries=500) Bounded recursive tree text (never follows dir symlinks).
hashkit sha256_text / sha256_file / quick_hash Content hashing (files streamed in 1 MiB windows).
text count_tokens(text) Dependency-free approximate BPE token count.
text chunk_by_lines / chunk_by_tokens Chunk on line or token budgets (paragraph-aware).
text unified_diff(before, after) Unified diff between two texts.
data read_data(path, fmt=None) Parse JSON always, TOML via stdlib tomllib, YAML if PyYAML present.
data write_json(path, obj) / safe_json_dumps(obj) Atomic JSON write / non-exploding dumps.
timekit now_iso / now_epoch / epoch_to_iso / iso_to_epoch UTC time conversions.
web assess_webpage(url, ...) assessManager-parity structured page assessment over urllib + html.parser.
web prescreen_webpage(url, ...) Cheap title + description + lede relevance pre-screen.

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.

Shared document tools

Install hugpy-tools[documents] or abstract-toolserver[documents] to use document_extract, document_inspect, document_page, and document_search. They call the same media_intelligence.documents engine as Media directly, without a Media HTTP server. Extraction runs in a bounded child process and returns cached artifacts, page references, geometry and completeness status. OCR defaults to off; auto and force use the configured Hugpy OCR backend. Pass the same store_root to extraction and later page/search calls when using a custom artifact store. File authorization belongs to the caller, as for the other local file tools.

The base package remains light. Parsers load only when a document tool is called. The media extra includes document support, and no longer installs legacy OCR/pandas packages or local model runtimes. Existing media_* model tools retain the Media transport and their existing contracts.

Shared implementations in Resources

The dependency runs one way: hugpy-tools → hugpy-resources. Resources owns reusable functions and constants. Tools owns registration, argument schemas, dispatch, compatibility with backend contracts, and optional integrations.

Generic capability Resources implementation
paths imports/functions/paths.py and imports/classes.py
hashkit imports/functions/hashing.py
fs imports/functions/filesystem.py
data imports/functions/structured_data.py and json_utils.py
text imports/functions/text.py
timekit imports/functions/time_utils.py
search imports/functions/search.py
process.run_command imports/functions/processes.py, with Tools supplying its timeout policy

The old generic Tools modules have been removed. Consumers import Resources directly; the Tools registry registers the same callables under its existing tool names. Function signatures, return structures, exception behavior and search filters retain their contracts. Search cancellation, provider objects and reports live only in Resources. JSON serialization and file hashing retain their distinct contracts; a quick hash remains a prefilter, and a plain SHA256 string remains separate from a stable-file proof record.

Local install scripts install an archived Resources wheel before Tools. Offline builders include the staged Resources wheel, and push prerequisite ordering places Resources before Tools. Resources' new ops.sh uses the same archive, local install and publish workflows as the other staged Python packages.

Metadata

Release files for hugpy-tools 0.2.25

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hugpy-tools 0.2.25
File Size Uploaded Provenance Actions
hugpy_tools-0.2.25.tar.gz 66.7 kB Without provenance Details for hugpy_tools-0.2.25.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hugpy-tools 0.2.25
File Interpreter ABI Platform Actions
hugpy_tools-0.2.25-py3-none-any.whl Python 3 none any Details for hugpy_tools-0.2.25-py3-none-any.whl

Total release size: 123.8 kB

Release files / hugpy_tools-0.2.25.tar.gz

Download URL hugpy_tools-0.2.25.tar.gz
Size 66.7 kB
Tags Source
SHA-256 checksum
How to use checksums
cf94490fb5c6a2727e565f22a7b86dbcb2d191d417007f3b8745652197fc415d
BLAKE2b-256 checksum
How to use checksums
781558be4ae0f5733bc5416663c937e45418b654e0dac25f3516d1d0a79b2469
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / hugpy_tools-0.2.25-py3-none-any.whl

Download URL hugpy_tools-0.2.25-py3-none-any.whl
Size 57.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91baecdabf3bd192b9d4108b95cc04f46bb17d38cab474ef03b0daf0234cf38c
BLAKE2b-256 checksum
How to use checksums
db764fc028d9e466588f69f67c9f4cfea2bfe26643e9b324ecf016e512943842
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for hugpy-tools 0.2.25

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page