tooli 1.0.1__tar.gz

tooli-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tooli developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tooli-1.0.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: tooli
+Version: 1.0.1
+Summary: The agent-native CLI framework for Python
+Author: tooli developers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/weisberg/tooli
+Project-URL: Repository, https://github.com/weisberg/tooli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == "mcp"
+Provides-Extra: api
+Requires-Dist: starlette>=0.27; extra == "api"
+Requires-Dist: uvicorn>=0.20; extra == "api"
+Dynamic: license-file

tooli-1.0.1/README.md

@@ -0,0 +1,317 @@
+# Tooli
+
+[![CI](https://github.com/weisberg/tooli/actions/workflows/ci.yml/badge.svg)](https://github.com/weisberg/tooli/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/tooli)](https://pypi.org/project/tooli/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/tooli)](https://pypi.org/project/tooli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The agent-native CLI framework for Python. Write one function, get a CLI, an MCP tool, and a self-documenting schema.
+
+The name comes from "tool" + "CLI" = "tooli".
+
+Tooli turns typed Python functions into CLI commands that are simultaneously human-friendly (Rich output, shell completions) and machine-consumable (JSON schemas, structured output, MCP compatibility). No separate "agent version" of your tool required.
+
+## Why Tooli?
+
+AI agents invoke thousands of CLI commands daily, but standard CLIs were designed for humans:
+
+- **Interactive prompts hang agents** that can't navigate pagers or password dialogs
+- **Unstructured output wastes tokens** — agents parse text with regex instead of reading JSON
+- **Vague errors prevent self-correction** — "Error: invalid input" gives agents nothing to work with
+- **No discoverability** — agents hallucinate flags for undocumented tools
+
+Tooli fixes all of this. One decorated function produces a CLI, a JSON Schema, an MCP tool definition, structured errors with recovery suggestions, and auto-generated documentation — from a single source of truth.
+
+## Features
+
+- **Dual-mode output** — Rich tables for humans, JSON/JSONL for agents, auto-detected via TTY
+- **Structured errors** — actionable error objects with suggestion fields that guide agent self-correction
+- **Schema generation** — JSON Schema from type hints, compatible with MCP `inputSchema` and OpenAI function-calling
+- **MCP server mode** — serve your CLI as an MCP tool server over stdio or HTTP with zero extra code
+- **SKILL.md generation** — auto-generated agent-readable documentation, always in sync with code
+- **stdin/file parity** — `StdinOr[T]` type makes files, URLs, and piped data interchangeable
+- **Standard global flags** — `--json`, `--jsonl`, `--plain`, `--quiet`, `--dry-run`, `--schema` injected automatically
+- **Agent-safe by default** — no interactive prompts in non-TTY mode, no stdout pollution, strict exit codes
+
+## Installation
+
+```bash
+pip install tooli
+```
+
+Optional extras:
+
+```bash
+pip install tooli[mcp]   # MCP server support (fastmcp)
+pip install tooli[api]   # HTTP API server (starlette, uvicorn)
+```
+
+## Quick Start
+
+```python
+from tooli import Tooli, Annotated, Option, Argument
+from tooli.annotations import ReadOnly, Idempotent
+from pathlib import Path
+
+app = Tooli(
+    name="file-tools",
+    description="File manipulation utilities",
+    version="1.0.0",
+)
+
+@app.command(
+    annotations=ReadOnly | Idempotent,
+    examples=[
+        {"args": ["--pattern", "*.py", "--root", "/project"],
+         "description": "Find all Python files in a project"},
+    ],
+)
+def find_files(
+    pattern: Annotated[str, Argument(help="Glob pattern to match files")],
+    root: Annotated[Path, Option(help="Root directory to search from")] = Path("."),
+    max_depth: Annotated[int, Option(help="Maximum directory depth")] = 10,
+) -> list[dict]:
+    """Find files matching a glob pattern in a directory tree."""
+    results = []
+    for path in root.rglob(pattern):
+        results.append({"path": str(path), "size": path.stat().st_size})
+    return results
+
+if __name__ == "__main__":
+    app()
+```
+
+### Human usage
+
+```bash
+$ file-tools find-files "*.py" --root ./src
+┌──────────────────────┬───────┐
+│ Path                 │ Size  │
+├──────────────────────┼───────┤
+│ src/main.py          │ 1,204 │
+│ src/utils.py         │   892 │
+└──────────────────────┴───────┘
+```
+
+### Agent usage
+
+```bash
+$ file-tools find-files "*.py" --root ./src --json
+{
+  "ok": true,
+  "result": [
+    {"path": "src/main.py", "size": 1204},
+    {"path": "src/utils.py", "size": 892}
+  ],
+  "meta": {"tool": "file-tools.find-files", "version": "1.0.0", "duration_ms": 34}
+}
+```
+
+### Schema export
+
+```bash
+$ file-tools find-files --schema
+{
+  "name": "find-files",
+  "description": "Find files matching a glob pattern in a directory tree.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "pattern": {"type": "string", "description": "Glob pattern to match files"},
+      "root": {"type": "string", "default": ".", "description": "Root directory to search from"},
+      "max_depth": {"type": "integer", "default": 10, "description": "Maximum directory depth"}
+    },
+    "required": ["pattern"]
+  },
+  "annotations": {"readOnlyHint": true, "idempotentHint": true}
+}
+```
+
+### MCP server mode
+
+```bash
+$ file-tools mcp serve --transport stdio
+$ file-tools mcp serve --transport http --host 127.0.0.1 --port 8080
+```
+
+Add to your MCP client config and every command becomes a tool.
+
+For SSE-enabled clients, use:
+
+```bash
+$ file-tools mcp serve --transport sse --host 127.0.0.1 --port 8080
+```
+
+## Structured Errors
+
+When something goes wrong, agents get actionable recovery guidance instead of opaque messages:
+
+```bash
+$ file-tools find-files "*.rs" --root ./src --json
+{
+  "ok": false,
+  "error": {
+    "code": "E3001",
+    "category": "state",
+    "message": "No files matched pattern '*.rs' in ./src",
+    "suggestion": {
+      "action": "retry_with_modified_input",
+      "fix": "The directory contains .py files. Try pattern '*.py' instead.",
+      "example": "find-files '*.py' --root ./src"
+    },
+    "is_retryable": true
+  }
+}
+```
+
+## Output Modes
+
+Tooli auto-detects the right output format, or you can be explicit:
+
+| Flag | Behavior |
+|---|---|
+| *(TTY, no flag)* | Rich formatted output for humans |
+| `--json` | Single JSON envelope to stdout |
+| `--jsonl` | Newline-delimited JSON for streaming |
+| `--plain` | Unformatted text for grep/awk pipelines |
+| `--quiet` | Suppress non-essential output |
+
+## Optional Telemetry
+
+Tooli supports anonymous, opt-in usage telemetry for tool authors.
+
+- Disabled by default.
+- Enable with `TOOLI_TELEMETRY=true` or `Tooli(telemetry=True)`.
+- Records only command identifiers, duration (ms), success/failure outcome, and exit/error codes.
+- No command arguments or command output payloads are recorded.
+- Local-first by default to `~/.config/tooli/telemetry/events.jsonl`.
+- Remote forwarding is opt-in via `TOOLI_TELEMETRY_ENDPOINT` or `Tooli(telemetry_endpoint=...)`.
+- Retention policy is local-only by default: entries older than 30 days are pruned.
+
+## Dry-Run Planning
+
+Tooli supports opt-in dry-run planning via `@dry_run_support`.
+
+- Decorate command functions with `@dry_run_support`.
+- Use `record_dry_action(action, target, details={...})` to add plan steps.
+- Invoke with `--dry-run` to return the action plan instead of executing side effects.
+- In JSON output, dry-run responses set `meta.dry_run` to `true`.
+
+## Auto-Generated Documentation
+
+```bash
+# Agent-readable skill documentation
+$ file-tools generate-skill > SKILL.md
+
+# LLM-friendly docs (llms.txt standard)
+$ file-tools docs llms
+
+# Unix man page
+$ file-tools docs man
+```
+
+## Input Unification
+
+The `StdinOr[T]` type makes files, URLs, and piped data interchangeable:
+
+```python
+from tooli import StdinOr
+
+@app.command()
+def process(
+    input_data: Annotated[StdinOr[Path], Argument(help="Input file, URL, or stdin")],
+) -> dict:
+    """Process data from any input source."""
+    ...
+```
+
+```bash
+# All equivalent:
+$ file-tools process data.csv
+$ file-tools process https://example.com/data.csv
+$ cat data.csv | file-tools process -
+```
+
+## Global Flags
+
+Every Tooli command automatically gets:
+
+```
+--output, -o       auto|json|jsonl|text|plain
+--json/--jsonl     Convenience aliases
+--quiet, -q        Suppress non-essential output
+--verbose, -v      Increase verbosity (-vvv)
+--dry-run          Preview without executing
+--yes              Skip confirmation prompts (for automation/agents)
+--no-color         Disable colors (also respects NO_COLOR)
+--print0           Emit NUL-separated output for list types in text/plain modes
+--timeout          Max execution time in seconds
+--null             Parse NUL-delimited list input from stdin (list-processing)
+--schema           Print JSON Schema and exit
+--response-format  concise|detailed
+--help-agent       Token-optimized help for agents
+```
+
+## Architecture
+
+Tooli builds on the Python typing + decorator pipeline, adding a parallel schema generation path:
+
+```
+          @app.command()
+     Python function + type hints
+            │              │
+            ▼              ▼
+      CLI Pipeline    Schema Pipeline
+     → CLI params     → Pydantic model
+     → CLI parser     → JSON Schema
+            │              │
+            ▼              ▼
+      CLI Output       Agent Output
+      Rich tables      MCP tool schema
+      Completions      SKILL.md / JSON
+```
+
+Key design decisions:
+- **Library-first API** — the public surface is Tooli-native (no framework objects leaked into user code)
+- **Pydantic schemas** — same pipeline as FastAPI and FastMCP
+- **Functions stay callable** — no mutation; test with `CliRunner` or call directly as Python
+
+## Examples
+
+The [`examples/`](examples/) directory contains 18 complete CLI apps built with Tooli, each demonstrating different features:
+
+| App | Features |
+|---|---|
+| **[docq](examples/docq/)** | ReadOnly, paginated, stdin input, output formats |
+| **[gitsum](examples/gitsum/)** | ReadOnly, subprocess, StdinOr for diffs |
+| **[csvkit_t](examples/csvkit_t/)** | StdinOr, JSONL output, paginated, OpenWorld |
+| **[syswatch](examples/syswatch/)** | ReadOnly, paginated, structured errors |
+| **[taskr](examples/taskr/)** | Idempotent, Destructive, paginated CRUD |
+| **[proj](examples/proj/)** | Destructive, DryRunRecorder, Idempotent |
+| **[envar](examples/envar/)** | SecretInput, AuthContext scopes |
+| **[imgsort](examples/imgsort/)** | Destructive+Idempotent, DryRunRecorder, batch ops |
+| **[note_indexer](examples/note_indexer/)** | ReadOnly, paginated, JSON index, error handling |
+
+See the [examples README](examples/README.md) for the full list and usage guide.
+
+## Development
+
+```bash
+# Clone and install for development
+git clone https://github.com/weisberg/tooli.git
+cd tooli
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint and type check
+ruff check .
+mypy tooli
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

tooli-1.0.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tooli"
+version = "1.0.1"
+description = "The agent-native CLI framework for Python"
+readme = "pypi/pypi_project.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "tooli developers"}
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.9",
+    "pydantic>=2.0",
+    "rich>=13.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+    "mypy>=1.0",
+]
+mcp = [
+    "fastmcp>=2.0",
+]
+api = [
+    "starlette>=0.27",
+    "uvicorn>=0.20",
+]
+
+[tool.setuptools.packages.find]
+include = ["tooli*"]
+
+[project.urls]
+Homepage = "https://github.com/weisberg/tooli"
+Repository = "https://github.com/weisberg/tooli"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = false
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

tooli-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tooli-1.0.1/tests/test_api.py

@@ -0,0 +1,27 @@
+"""Tests for HTTP API integration."""
+
+from __future__ import annotations
+
+import json
+
+from tooli import Tooli
+from tooli.testing import TooliTestClient
+
+
+def test_api_export_openapi() -> None:
+    """api export-openapi should output valid OpenAPI schema."""
+    app = Tooli(name="test-api")
+
+    @app.command()
+    def compute(x: int, y: int) -> int:
+        """Add two numbers."""
+        return x + y
+
+    client = TooliTestClient(app)
+    result = client.invoke(["api", "export-openapi"])
+    assert result.exit_code == 0
+
+    schema = json.loads(result.output)
+    assert schema["openapi"] == "3.1.0"
+    assert "/compute" in schema["paths"]
+    assert "x" in schema["paths"]["/compute"]["post"]["requestBody"]["content"]["application/json"]["schema"]["properties"]