Skip to main content

galet-tools

Self-contained generic tool handlers and the handler framework they run on.

Lineage

This package is extracted from the Lucy monorepo (src/handlers) as described in the Lucy design doc software/ai/lucy/design/handlers-extraction.md and the plan software/ai/lucy/plan/handlers-extraction.md.

It is a fresh repository with no shared git history. Handler logic moves verbatim; the only intentional changes are the import namespace (src.handlers.* -> galet_tools.*) and the configuration boundary: tools depend on narrow port interfaces owned by this package (ConfigProvider, StorageLocationResolver, SandboxRootResolver, SecurityPolicy, ...), never on Lucy's ConfigManager. Lucy implements those ports at its composition root.

Features

  • Handler framework — HandlerV2 ABC, HandlerRegistry, schema handling, and permission filtering.
  • Generic tools — file_load, file_save, patch_apply, execute_command, execute_command2, generate_svg, and generate_image, registered under their existing names. file_load supports bounded line-range reads.
  • Ports — sibling-owned interfaces the host implements, keeping the tools free of any host dependency.
  • Handler discovery — installed packages can contribute handlers through Python package entry points without changing Lucy or galet-tools.

Quick start

python -m venv .venv
.venv/bin/pip install -e .

Run the suite:

python -m pytest -q

Using the registry in a host

Galet owns the handler contract and base registry. A host such as Lucy composes the generic handlers, its own host-specific handlers, and installed extension packages:

from galet_tools import HandlerRegistry, register_installed_handlers
from galet_tools.register_generic_defaults import register_generic_defaults

registry = HandlerRegistry()
register_generic_defaults(registry)
register_lucy_handlers(registry)
register_installed_handlers(registry)

Discovery adds installed capabilities to the registry; it does not grant them to an agent. The host should continue to apply its agent and context allowlists when selecting tool definitions.

Creating a handler extension

An extension package declares a registrar in its pyproject.toml:

[project.entry-points."galet_tools.handlers"]
web = "galet_web_tools:register"

The target is a callable that receives the shared registry:

def register(registry):
    registry.register(SearchHandler)
    registry.register(FetchHandler)

Entry points are loaded in deterministic name order. A plugin that cannot be loaded, does not resolve to a callable, or fails during registration raises HandlerPluginError with the responsible entry-point name. This is intentionally fail-fast so a host cannot start with an unexpectedly incomplete tool set.

Memory tools example

The episodic_memory handler takes an injected episodic store, and curate_chat takes an injected curation service, and reset_session takes the same episodic store. semantic_memory takes an injected galet_memory.semantic.SemanticMemory. These tools are intentionally not registered as a generic MCP default because the host must supply the episodic store, digest generator, and trusted account.

Run a small SQLite session through creation, event append and read, digest preview, archive, an active-session read, and an idempotent archive retry, and a reset that clears events while retaining the session metadata. It then writes and indexes the archived digest and recalls it through VectorSemanticMemory in the digests namespace, using deterministic embedding and index ports without an API key:

python -m pip install -e '.[memory]'
python examples/curate_chat.py

If galet-memory 0.1.5 is only available from a sibling checkout, install that checkout first with python -m pip install -e ../galet-memory.

The example uses a deterministic digest generator and runs all four tool adapters with one temporary session. The example explicitly writes the digest text, embeds it, and inserts a StoredEmbedding into an in-memory index; curation does not automatically publish to semantic memory. It checks that recall is empty before publication and returns the digest afterward. In an application, inject galet_memory.curation.CurationService with the application's digest generator and construct CurateChatHandler(service) through a registry factory.

MCP server

An optional MCP (Model Context Protocol) server exposes the generic tools over streamable HTTP. Install the extra:

.venv/bin/pip install -e '.[mcp]'

Copy the example config and start the server:

cp galet-mcp.example.json galet-mcp.json
galet-tools-mcp

galet-tools-mcp reads galet-mcp.json from the current directory by default; point it elsewhere with --config <path>.

Configuration

galet-mcp.json mirrors galet-mcp.example.json. Required keys are account, storage_root, storage_namespace, and sandbox_root; a null, blank, or (for the two path keys) relative value fails validation. Optional keys left out or set to null fall back to their defaults:

  • allowlist — tools to expose; the default includes file_load, file_save, patch_apply, legacy execute_command, structured execute_command2, generate_svg, and generate_image.
  • external_roots — named external roots the tools may access; default none.
  • host — default 127.0.0.1; loopback only.
  • port — default 8765.
  • fonts — font paths for the generators; default none.

What it exposes

tools/list and tools/call over streamable HTTP at http://127.0.0.1:8765/mcp.

Smoke-test from the CLI

galet-tools-smoke is the end-to-end CLI client: it connects over HTTP (streamable HTTP) to a running galet MCP server using the official MCP SDK and performs real tools/list and tools/call round trips.

galet-tools-smoke list
galet-tools-smoke list --json
galet-tools-smoke call <tool> '<json args>'

The default URL is http://127.0.0.1:8765/mcp; override it with --url. The default read timeout is 30s; override it with --timeout.

Example round trip (storage root from galet-mcp.json):

galet-tools-smoke call file_save '{"path":"smoke/hello.txt","file_content":"hello galet smoke"}'
galet-tools-smoke call file_load '{"path":"smoke/hello.txt"}'
galet-tools-smoke call execute_command2 '{"mode":"process","executable":"python","arguments":["-c","print(123)"],"script":"","shell":"none","location":"sandbox","external_root":"","working_directory":".","timeout_seconds":30,"success_exit_codes":[0]}'

Exit codes: 0 ok; 1 tool reported an error (isError); 2 usage or bad JSON; 3 could not reach the server.

Fail-closed behaviour

The server refuses to start when the allowlist is empty or has no overlap with the registered tools, and only the advertised tools are callable. Unknown tool names in the allowlist fail validation.

Security

Binding is loopback-only by design: host must resolve to a loopback address. Remote access needs a separate reverse-proxy design.

License

MIT — see LICENSE.

Metadata

Release files for galet-tools 0.1.12

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

Source distribution (sdist)

Source distribution for galet-tools 0.1.12
File Size Uploaded Provenance Actions
galet_tools-0.1.12.tar.gz 74.4 kB Without provenance Details for galet_tools-0.1.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for galet-tools 0.1.12
File Interpreter ABI Platform Actions
galet_tools-0.1.12-py3-none-any.whl Python 3 none any Details for galet_tools-0.1.12-py3-none-any.whl

Total release size: 142.6 kB

Release files / galet_tools-0.1.12.tar.gz

Download URL galet_tools-0.1.12.tar.gz
Size 74.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1ea38c9788e70660776b0ae9478969ba81ebfa353a55ddf8e67bebcad9df989f
BLAKE2b-256 checksum
How to use checksums
6c11228babc3b45aeaeba1cb8bee1b6dfd5146214d040871c14fa1013459961f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / galet_tools-0.1.12-py3-none-any.whl

Download URL galet_tools-0.1.12-py3-none-any.whl
Size 68.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fb8812f7bc3c9b3025c0c03c2dd7c16e40fc917dc8e0e0fa871e2e2bd9b872c
BLAKE2b-256 checksum
How to use checksums
1fe7ebe9eecef929d4733e8b2657712dc6393cff7e0d27f17124b9c0ffe601e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for galet-tools 0.1.12

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.

Release history Release notifications | RSS feed

This release

0.1.12 This release

2 release files No provenance

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