toolfuncs 0.1.4__tar.gz → 0.3.1__tar.gz

{toolfuncs-0.1.4 → toolfuncs-0.3.1}/.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
 jobs:
   build:
     name: Build distributions
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, Linux, X64]
     permissions:
       contents: read
 
@@ -55,7 +55,7 @@ jobs:
   publish:
     name: Publish to PyPI
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, Linux, X64]
     environment:
       name: pypi
       url: https://pypi.org/project/toolfuncs/

toolfuncs-0.3.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: toolfuncs
+Version: 0.3.1
+Summary: Executable typed Python function tools discovered through PATH
+Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
+Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
+Author-email: Nima Shoghi <nima@boltz.bio>
+Requires-Python: >=3.10
+Requires-Dist: cyclopts<5,>=4.23.2
+Requires-Dist: packaging>=24
+Requires-Dist: pip>=25
+Requires-Dist: pydantic-core<3,>=2
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: tomli<3,>=2.2; python_version < '3.11'
+Provides-Extra: hooks
+Requires-Dist: typed-agent-hooks; extra == 'hooks'
+Description-Content-Type: text/markdown
+
+# toolfuncs
+
+`toolfuncs` turns typed Python functions into tools that have matching Python and command-line interfaces.
+
+A toolfunc is one executable Python script on `PATH`. Its filename is its command name and dynamic Python import name. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves discoverable toolfuncs.
+
+## Write a toolfunc
+
+Create an extensionless file named `weather`:
+
+```python
+#!/usr/bin/env toolfuncs
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["weather-client"]
+# [tool.toolfuncs]
+# description = "Read current weather conditions."
+# ///
+
+import toolfuncs
+import weather_client
+
+app = toolfuncs.App()
+
+
+@app.command
+def current(city: str) -> dict[str, object]:
+    return weather_client.current(city)
+```
+
+Make it executable and place it in any existing `PATH` directory:
+
+```console
+chmod +x weather
+mv weather ~/.local/bin/
+```
+
+That is the complete registration operation.
+
+## Call it
+
+The executable is the CLI:
+
+```console
+$ weather current London
+{"city": "London", "temperature": 18}
+```
+
+The same file is dynamically importable in a Python process that has `toolfuncs` installed and the same `PATH`:
+
+```python
+from toolfuncs import weather
+
+conditions = weather.current("London")
+```
+
+The explicit equivalent is useful when a tool name conflicts with a public package attribute:
+
+```python
+import toolfuncs
+
+weather = toolfuncs.load("weather")
+```
+
+Direct Python calls return ordinary Python objects and raise the original exceptions. `toolfuncs.load()` prepares the script's requirements in the running Python environment before import. CLI calls use Cyclopts to parse annotated values and serialize successful results as strict JSON through `pydantic-core`.
+
+## Source contract
+
+A discoverable toolfunc must:
+
+1. be one executable file in a directory on `PATH`;
+2. have an extensionless filename that is a valid non-keyword Python identifier;
+3. start with one of the two exact toolfuncs shebangs described below;
+4. contain exactly one PEP 723 `script` block with `dependencies` and a one-line `[tool.toolfuncs].description`;
+5. define a module-level `app = toolfuncs.App()`;
+6. register each CLI-callable function explicitly with `@app.command`.
+
+The PEP 723 dependency list contains the packages needed in addition to the running toolfuncs environment. Listing `toolfuncs` itself is accepted but normally redundant because the shebang has already started the toolfuncs runtime before dependencies are prepared.
+
+Git requirements must use a full 40- or 64-hex commit object ID. Branches such as `@main`, tags, abbreviated hashes, and omitted revisions fail before uv resolves them. A tool that deliberately accepts floating-ref refresh and concurrency costs must say so in its source:
+
+```python
+#!/usr/bin/env -S toolfuncs --allow-floating-vcs
+```
+
+The launcher consumes `--allow-floating-vcs`; the tool's Cyclopts app never sees it. Adjacent `uv lock --script` files are not used because uv does not consult them for `--with-requirements` launches.
+
+Only functions registered on `app` become CLI commands. Imported functions and `__all__` do not define the command surface. Function command and option spelling follows Cyclopts' Python-to-kebab-case projection.
+
+No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its filename before invoking its module-level app. Consequently, `weather ...` is the supported CLI while `python weather ...` merely defines the module and exits, or fails if its dependencies are not already installed.
+
+## Package-backed implementations
+
+A toolfunc remains one script even when most of its implementation lives in a package:
+
+```python
+#!/usr/bin/env toolfuncs
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["my-large-package"]
+# [tool.toolfuncs]
+# description = "Run the package's agent operation."
+# ///
+
+from my_large_package.agent_tool import app, perform_operation
+```
+
+The imported `app` and functions are the original Python objects. Toolfuncs does not inspect the package's project layout, metadata, or import structure.
+
+## Discovery and precedence
+
+Toolfuncs reads the current process's `PATH` from left to right. It considers only executable files and symlinks, reads their first line, and parses PEP 723 metadata only when either exact toolfuncs shebang matches.
+
+The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by name.
+
+`toolfuncs list` returns static JSON records containing `name`, `path`, and `description`. It never imports a tool, prepares its dependencies, or executes its source.
+
+## Install the runtime
+
+```console
+uvx toolfuncs setup
+```
+
+Setup writes two managed, auto-updating uvx wrappers by default:
+
+- `~/.local/bin/toolfuncs` dispatches tools;
+- `~/.agents/hooks/toolfuncs/hook` advertises the current tool catalog to agent harnesses.
+
+For a tool invocation, its effective launch is:
+
+```sh
+#!/bin/sh
+# managed by toolfuncs setup
+exec uvx --quiet --from toolfuncs --with-requirements "$source" \
+  toolfuncs __run-source "$source" "$@"
+```
+
+The wrapper preflights Git requirements before that command unless the source explicitly allows floating VCS revisions. Normal uv cache freshness supplies updates without forcing `--refresh-package` on every call. The destination must already be on `PATH`; setup fails with a concrete instruction otherwise. Setup is idempotent, refuses to overwrite unmanaged commands, and does not modify shell profiles.
+
+The hook wrapper resolves the optional `toolfuncs[hooks]` environment and is registered at user scope for Codex and Claude Code through `typed-agent-hooks`. Running setup again reconciles those registrations, so the managed launcher remains the configured executable even when provider configuration changes.
+
+Setup does not discover, copy, register, link, synchronize, or remove tools. There is no dedicated tools directory, registry, manifest, generated shim, project scope, user scope, or sync command.
+
+## Management commands
+
+```console
+toolfuncs list
+toolfuncs setup [--bin-dir DIRECTORY]
+```
+
+The source-path argument supplied automatically by `#!/usr/bin/env toolfuncs` is runtime plumbing rather than another user-facing command. Tools are invoked directly by their own names.
+
+## Agent integration
+
+The installed hook runs at initial session start and at the session-start event emitted after compaction. It discovers the effective tools directly from that harness process's `PATH`, then adds a compact catalog such as:
+
+```text
+Available toolfuncs:
+- `weather`: Read current weather conditions.
+  CLI: `weather --help`
+  Python: `from toolfuncs import weather`
+```
+
+The hook reads only executable headers and PEP 723 metadata. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
+
+## Development
+
+```console
+uv sync
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+uv run basedpyright
+```
+
+The exact 0.2 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+
+## Releasing
+
+The GitHub Release is the release control point. Set `[project].version`, merge and push that commit, then publish a GitHub Release whose tag is `v<version>`. The self-hosted release workflow verifies that the tag and package version match, builds the wheel and source distribution, and publishes them to PyPI through Trusted Publishing.

toolfuncs-0.3.1/README.md

@@ -0,0 +1,180 @@
+# toolfuncs
+
+`toolfuncs` turns typed Python functions into tools that have matching Python and command-line interfaces.
+
+A toolfunc is one executable Python script on `PATH`. Its filename is its command name and dynamic Python import name. Its implementation may import any packages declared in its PEP 723 requirements, but packages and projects are not themselves discoverable toolfuncs.
+
+## Write a toolfunc
+
+Create an extensionless file named `weather`:
+
+```python
+#!/usr/bin/env toolfuncs
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["weather-client"]
+# [tool.toolfuncs]
+# description = "Read current weather conditions."
+# ///
+
+import toolfuncs
+import weather_client
+
+app = toolfuncs.App()
+
+
+@app.command
+def current(city: str) -> dict[str, object]:
+    return weather_client.current(city)
+```
+
+Make it executable and place it in any existing `PATH` directory:
+
+```console
+chmod +x weather
+mv weather ~/.local/bin/
+```
+
+That is the complete registration operation.
+
+## Call it
+
+The executable is the CLI:
+
+```console
+$ weather current London
+{"city": "London", "temperature": 18}
+```
+
+The same file is dynamically importable in a Python process that has `toolfuncs` installed and the same `PATH`:
+
+```python
+from toolfuncs import weather
+
+conditions = weather.current("London")
+```
+
+The explicit equivalent is useful when a tool name conflicts with a public package attribute:
+
+```python
+import toolfuncs
+
+weather = toolfuncs.load("weather")
+```
+
+Direct Python calls return ordinary Python objects and raise the original exceptions. `toolfuncs.load()` prepares the script's requirements in the running Python environment before import. CLI calls use Cyclopts to parse annotated values and serialize successful results as strict JSON through `pydantic-core`.
+
+## Source contract
+
+A discoverable toolfunc must:
+
+1. be one executable file in a directory on `PATH`;
+2. have an extensionless filename that is a valid non-keyword Python identifier;
+3. start with one of the two exact toolfuncs shebangs described below;
+4. contain exactly one PEP 723 `script` block with `dependencies` and a one-line `[tool.toolfuncs].description`;
+5. define a module-level `app = toolfuncs.App()`;
+6. register each CLI-callable function explicitly with `@app.command`.
+
+The PEP 723 dependency list contains the packages needed in addition to the running toolfuncs environment. Listing `toolfuncs` itself is accepted but normally redundant because the shebang has already started the toolfuncs runtime before dependencies are prepared.
+
+Git requirements must use a full 40- or 64-hex commit object ID. Branches such as `@main`, tags, abbreviated hashes, and omitted revisions fail before uv resolves them. A tool that deliberately accepts floating-ref refresh and concurrency costs must say so in its source:
+
+```python
+#!/usr/bin/env -S toolfuncs --allow-floating-vcs
+```
+
+The launcher consumes `--allow-floating-vcs`; the tool's Cyclopts app never sees it. Adjacent `uv lock --script` files are not used because uv does not consult them for `--with-requirements` launches.
+
+Only functions registered on `app` become CLI commands. Imported functions and `__all__` do not define the command surface. Function command and option spelling follows Cyclopts' Python-to-kebab-case projection.
+
+No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its filename before invoking its module-level app. Consequently, `weather ...` is the supported CLI while `python weather ...` merely defines the module and exits, or fails if its dependencies are not already installed.
+
+## Package-backed implementations
+
+A toolfunc remains one script even when most of its implementation lives in a package:
+
+```python
+#!/usr/bin/env toolfuncs
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["my-large-package"]
+# [tool.toolfuncs]
+# description = "Run the package's agent operation."
+# ///
+
+from my_large_package.agent_tool import app, perform_operation
+```
+
+The imported `app` and functions are the original Python objects. Toolfuncs does not inspect the package's project layout, metadata, or import structure.
+
+## Discovery and precedence
+
+Toolfuncs reads the current process's `PATH` from left to right. It considers only executable files and symlinks, reads their first line, and parses PEP 723 metadata only when either exact toolfuncs shebang matches.
+
+The first executable filename claims a command name even when it is not a toolfunc. Therefore an ordinary executable earlier on `PATH` hides a same-named toolfunc later on `PATH`, matching what the shell actually executes. Repeated directories are scanned once, inaccessible directories are skipped, and discovered records are sorted by name.
+
+`toolfuncs list` returns static JSON records containing `name`, `path`, and `description`. It never imports a tool, prepares its dependencies, or executes its source.
+
+## Install the runtime
+
+```console
+uvx toolfuncs setup
+```
+
+Setup writes two managed, auto-updating uvx wrappers by default:
+
+- `~/.local/bin/toolfuncs` dispatches tools;
+- `~/.agents/hooks/toolfuncs/hook` advertises the current tool catalog to agent harnesses.
+
+For a tool invocation, its effective launch is:
+
+```sh
+#!/bin/sh
+# managed by toolfuncs setup
+exec uvx --quiet --from toolfuncs --with-requirements "$source" \
+  toolfuncs __run-source "$source" "$@"
+```
+
+The wrapper preflights Git requirements before that command unless the source explicitly allows floating VCS revisions. Normal uv cache freshness supplies updates without forcing `--refresh-package` on every call. The destination must already be on `PATH`; setup fails with a concrete instruction otherwise. Setup is idempotent, refuses to overwrite unmanaged commands, and does not modify shell profiles.
+
+The hook wrapper resolves the optional `toolfuncs[hooks]` environment and is registered at user scope for Codex and Claude Code through `typed-agent-hooks`. Running setup again reconciles those registrations, so the managed launcher remains the configured executable even when provider configuration changes.
+
+Setup does not discover, copy, register, link, synchronize, or remove tools. There is no dedicated tools directory, registry, manifest, generated shim, project scope, user scope, or sync command.
+
+## Management commands
+
+```console
+toolfuncs list
+toolfuncs setup [--bin-dir DIRECTORY]
+```
+
+The source-path argument supplied automatically by `#!/usr/bin/env toolfuncs` is runtime plumbing rather than another user-facing command. Tools are invoked directly by their own names.
+
+## Agent integration
+
+The installed hook runs at initial session start and at the session-start event emitted after compaction. It discovers the effective tools directly from that harness process's `PATH`, then adds a compact catalog such as:
+
+```text
+Available toolfuncs:
+- `weather`: Read current weather conditions.
+  CLI: `weather --help`
+  Python: `from toolfuncs import weather`
+```
+
+The hook reads only executable headers and PEP 723 metadata. It does not import tools or resolve their dependencies. The hook itself is harness infrastructure, not a toolfunc, and therefore does not carry the toolfuncs shebang or appear in the catalog.
+
+## Development
+
+```console
+uv sync
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+uv run basedpyright
+```
+
+The exact 0.2 guarantees and non-goals are recorded in [the contract](docs/contract.md).
+
+## Releasing
+
+The GitHub Release is the release control point. Set `[project].version`, merge and push that commit, then publish a GitHub Release whose tag is `v<version>`. The self-hosted release workflow verifies that the tag and package version match, builds the wheel and source distribution, and publishes them to PyPI through Trusted Publishing.

toolfuncs-0.3.1/docs/contract.md

@@ -0,0 +1,84 @@
+# toolfuncs 0.2 contract
+
+## Purpose
+
+Toolfuncs projects one explicitly registered set of typed Python functions into two interfaces: ordinary in-process Python calls and a strict-JSON command line. It is a source convention and runtime, not a transport protocol, package format, registry, plugin system, or filesystem scope.
+
+## Tool source
+
+A toolfunc is one executable regular file or symlink in a directory on `PATH`. Its first line is one of two exact forms. The ordinary form is:
+
+```text
+#!/usr/bin/env toolfuncs
+```
+
+The explicit floating-VCS form is:
+
+```text
+#!/usr/bin/env -S toolfuncs --allow-floating-vcs
+```
+
+Its extensionless filename is its shell command, discovery name, and dynamic Python import name and must be a valid non-keyword Python identifier.
+
+The source contains exactly one PEP 723 `script` block. `dependencies` is a list of valid Python requirement strings, `requires-python` is optional, and `[tool.toolfuncs].description` is a required nonempty one-line string. `description` is the only toolfuncs-specific metadata field.
+
+The source defines a module-level `app` as a Cyclopts app, normally `toolfuncs.App`, and registers every CLI-callable operation explicitly. Function signatures, annotations, defaults, docstrings, return values, side effects, and exceptions define the operations. `__all__` retains its ordinary Python meaning and does not register commands.
+
+`toolfuncs.App` supplies strict JSON serialization as its default result action. An explicit `result_action=` replaces that default unchanged. Tool authors import only `toolfuncs`; the package re-exports the Cyclopts and `pydantic-core` authoring values needed for advanced interfaces.
+
+## Dependencies
+
+For CLI execution, the managed wrapper passes the source to `uvx --with-requirements` and starts toolfuncs inside the resulting cached environment. This is one uv-prepared environment containing the toolfuncs runtime and the script's requirements. The runtime then imports the source without installing the requirements again.
+
+For direct Python composition, `toolfuncs.load(NAME)` installs script requirements into the running interpreter with pip before importing the source. The current interpreter must satisfy `requires-python`. Dependency preparation and module loading are serialized within a process.
+
+The `toolfuncs` distribution may appear in `dependencies`, but it is normally redundant: the shebang has already started a runtime containing toolfuncs before the dependency list is processed. Toolfuncs does not reject or specially interpret that requirement.
+
+A script may import any installed dependency, including a package containing most or all of its implementation. The package is not a toolfunc and has no toolfuncs-specific layout or metadata contract.
+
+Git requirements are immutable by default. A direct Git URL must name a full 40- or 64-hex commit object ID. A branch, tag, abbreviated hash, or omitted revision raises `InvalidToolError` before dependency resolution. A tool may explicitly accept floating-ref refresh and concurrency costs through the `--allow-floating-vcs` shebang. The launcher consumes that option; it is not passed to the tool's Cyclopts app.
+
+An adjacent lock produced by `uv lock --script` is not part of this contract because uv does not consume a script lock when the source is supplied through `--with-requirements`.
+
+## Discovery
+
+Discovery reads the current value of `PATH`. Directories are visited from left to right, relative entries are resolved against the current working directory, empty entries denote the current working directory, repeated resolved directories are visited once, and missing or unreadable directories are skipped.
+
+The first executable filename across `PATH` claims that command name before its shebang is inspected. An earlier non-tool executable therefore hides a later same-named toolfunc. Discovery reads only the first line of ordinary candidates and parses PEP 723 metadata only after one of the two exact shebangs matches.
+
+An exact-shebang source with an invalid name or incomplete metadata is an error because it explicitly opted into the contract. `toolfuncs.discover()` returns effective `Tool(name, path, description)` records sorted by name. `toolfuncs list` serializes the same records as JSON without importing source, preparing dependencies, or executing code.
+
+## Loading and identity
+
+`toolfuncs.load(NAME)` resolves `NAME` through `PATH`, prepares its dependencies, and imports the extensionless source under `NAME`. `from toolfuncs import NAME` is the dynamic shorthand. `import toolfuncs.NAME` is not promised because discovered tools are dynamic package attributes rather than installed submodules.
+
+A name loaded once in an interpreter retains one canonical source and module object. Repeated loads return that object. A different source or pre-existing Python module using the same name is a clear conflict rather than an implicit replacement.
+
+## CLI execution
+
+When the operating system executes a tool, `/usr/bin/env` resolves the managed `toolfuncs` wrapper on `PATH` and passes it the source path followed by the user's arguments. The wrapper validates any unapproved Git requirement before resolution, then executes `uvx --from toolfuncs --with-requirements SOURCE toolfuncs ...`. Toolfuncs validates and imports the prepared source, obtains its module-level app, and invokes the app with the remaining arguments.
+
+The source is imported under its filename rather than executed as `__main__`. A main guard is neither required nor used by the supported execution path. Plain `python SOURCE ARGS...` does not invoke the CLI and does not prepare PEP 723 dependencies.
+
+Successful default CLI operations emit one strict JSON value. CLI parsing or execution failures exit nonzero. Direct Python calls return original Python objects and raise original exceptions.
+
+## Setup
+
+`uvx toolfuncs setup` installs one managed uvx wrapper in `~/.local/bin` or an explicit `--bin-dir`. The destination must already resolve from `PATH`. Setup is idempotent, refuses to overwrite an unmanaged command, and never modifies a shell profile. Normal uv cache freshness governs toolfuncs updates; the wrapper does not force `--refresh-package` on every invocation.
+
+Setup does not discover, install, copy, link, register, synchronize, or remove tool sources. Adding and removing tools are ordinary filesystem operations in directories already on `PATH`.
+
+## Public management interface
+
+The management commands are `toolfuncs list` and `toolfuncs setup [--bin-dir DIRECTORY]`. The source-path argument supplied by the shebang is internal runtime behavior. There is no universal name dispatcher, `run`, `exec`, `describe`, or `sync` command.
+
+## Non-goals
+
+- No discoverable package, project, directory, wheel, archive, remote URL, or configurable import name.
+- No general `import_path` utility.
+- No dedicated tool directory, project scope, user scope, registry, manifest, generated shim, or synchronization operation.
+- No `TOOL.md`, metadata dunders, implicit public-function exposure, or `__main__` execution contract.
+- No subprocess, RPC, or object-proxy isolation for Python composition.
+- No dependency solver spanning several toolfuncs before import.
+- No shell-profile edits, daemon, or implicit harness configuration.
+- Agent event handlers may advertise `toolfuncs list`, but those handlers are integrations rather than toolfuncs.

{toolfuncs-0.1.4 → toolfuncs-0.3.1}/pyproject.toml

@@ -1,23 +1,27 @@
 [project]
 name = "toolfuncs"
-version = "0.1.4"
-description = "Function-first Python tools with matching import and command-line interfaces"
+version = "0.3.1"
+description = "Executable typed Python function tools discovered through PATH"
 readme = "README.md"
 authors = [
     { name = "Nima Shoghi", email = "nima@boltz.bio" }
 ]
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 dependencies = [
     "cyclopts>=4.23.2,<5",
-    "fsspec[github,http]>=2025.3.0",
     "packaging>=24",
     "pip>=25",
     "pydantic>=2,<3",
     "pydantic-core>=2,<3",
+    "tomli>=2.2,<3; python_version < '3.11'",
 ]
 
 [project.scripts]
 toolfuncs = "toolfuncs.__main__:main"
+toolfuncs-agent-hook = "toolfuncs.agent_hooks:main"
+
+[project.optional-dependencies]
+hooks = ["typed-agent-hooks"]
 
 [project.urls]
 Repository = "https://github.com/nimashoghi/toolfuncs"
@@ -34,11 +38,12 @@ dev = [
     "pytest>=8",
     "pytest-cov>=6",
     "ruff>=0.12",
+    "typed-agent-hooks",
 ]
 
 [tool.ruff]
 line-length = 100
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
@@ -48,5 +53,5 @@ addopts = "-ra"
 testpaths = ["tests"]
 
 [tool.basedpyright]
-pythonVersion = "3.11"
+pythonVersion = "3.10"
 typeCheckingMode = "standard"

toolfuncs-0.3.1/src/toolfuncs/__init__.py

@@ -0,0 +1,79 @@
+"""Typed Python functions exposed through matching import and CLI interfaces."""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+from ._errors import (
+    DependencyError,
+    InvalidToolError,
+    SetupError,
+    ToolConflictError,
+    ToolDefinitionError,
+    ToolfuncsError,
+    ToolNotFoundError,
+)
+from ._setup import SetupResult, setup
+from ._tools import ALLOW_FLOATING_VCS_SHEBANG, TOOL_SHEBANG, Tool, discover, load
+from .sdk import (
+    UNSET,
+    App,
+    Group,
+    Parameter,
+    ResultAction,
+    Token,
+    json_result_action,
+    to_jsonable_python,
+    types,
+    validators,
+)
+
+__version__ = "0.3.1"
+
+__all__ = [
+    "ALLOW_FLOATING_VCS_SHEBANG",
+    "TOOL_SHEBANG",
+    "UNSET",
+    "App",
+    "DependencyError",
+    "Group",
+    "InvalidToolError",
+    "Parameter",
+    "ResultAction",
+    "SetupError",
+    "SetupResult",
+    "Token",
+    "Tool",
+    "ToolConflictError",
+    "ToolDefinitionError",
+    "ToolNotFoundError",
+    "ToolfuncsError",
+    "discover",
+    "json_result_action",
+    "load",
+    "setup",
+    "to_jsonable_python",
+    "types",
+    "validators",
+]
+
+_PUBLIC_API = frozenset(__all__)
+
+
+def __getattr__(name: str) -> ModuleType:
+    """Dynamically expose PATH tools for ``from toolfuncs import name``."""
+
+    if name.startswith("_"):
+        raise AttributeError(name)
+    try:
+        module = load(name)
+    except ToolNotFoundError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    """Include effective PATH tools in interactive completion."""
+
+    return sorted(_PUBLIC_API | {tool.name for tool in discover()})