agenticli 0.1.0__py3-none-any.whl

agenticli-0.1.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: agenticli
+Version: 0.1.0
+Summary: Expose tools as lightweight CLI commands for LLM agents
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: anthropic>=0.34; extra == 'examples'
+Requires-Dist: openai>=2.32.0; extra == 'examples'
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# ⚡ agenticli
+
+**Expose tools as lightweight CLI commands for LLM agents** 🔧✨
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/badge/pypi-agenticli-blue.svg)](https://pypi.org/project/agenticli/)
+
+</div>
+
+---
+
+## ✨ What is this?
+
+**llmcli** converts functions, classes, and schema-based tools into a stable CLI semantic layer. Instead of flooding prompts with large schemas, LLMs just output a single command string.
+
+> 💡 **Philosophy: bash is everything.** The command string is the most stable, restrained, and observable intermediate representation between LLMs and tool systems.
+
+## 🎯 When to use llmcli?
+
+| Scenario | llmcli helps? |
+|----------|---------------|
+| You have many tools/functions and need a unified interface for LLMs | ✅ |
+| You don't want massive schemas injected into prompts | ✅ |
+| You want models to see minimal hints, expanding via `--help` | ✅ |
+| You want validation, help, errors, and lifecycle in one place | ✅ |
+
+## 🚀 Quick Start
+
+```bash
+pip install llmcli
+```
+
+```python
+from typing import Annotated
+from llmcli import CommandRegistry, Option, command, command_group
+
+@command_group(name="calc", description="Calculator commands")
+class Calc:
+    @command(name="add", description="Add numbers")
+    def add(self,
+        values: Annotated[list[float], Option(positional=True, value_name="n")]
+    ) -> dict:
+        return {"result": sum(values)}
+
+registry = CommandRegistry()
+registry.register(Calc)
+
+# LLM sees this minimal prompt:
+print(registry.get_llm_prompt())
+# -> You can use the following CLI commands:
+#     calc: Calculator commands
+
+# Execute:
+registry.parse_and_execute("calc add 10 20 30")
+# -> {"result": 60.0}
+```
+
+## 🏗️ Core Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        LLM Output                            │
+│                    "calc add 10 20 30"                      │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      CommandRegistry                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
+│  │  Parse   │─▶│ Validate │─▶│ Execute  │─▶│   Result   │  │
+│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
+│                                                             │
+│  • Command hit/matching      • Lifecycle callbacks          │
+│  • Help generation           • Error with suggestions        │
+│  • Argument injection        • Chain execution (&&, ||, ;)  │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Your Functions / Tools                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 📋 Key Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔌 **Multiple Registrations** | Decorators, class inheritance, dataclass, Pydantic, schema wrapping |
+| ⚡ **CLI Parsing** | Positional args, `--option value`, `-o value`, `--opt=val`, flags |
+| 📖 **Smart Help** | Auto-generated usage, help text, LLM prompts |
+| ✅ **Validation** | Type coercion, `requires`/`excludes`, enums |
+| 💡 **Suggestions** | "Did you mean X?" for unknown commands/options/enums |
+| 🔄 **Lifecycle Hooks** | `before_execute`, `after_execute`, `on_error` |
+| 🏃 **Internal Injection** | Hide callbacks/state from CLI, inject at runtime |
+| 🔗 **Chain Execution** | `cmd1 && cmd2 || cmd3 ; cmd4` |
+
+## 📝 Registration Patterns
+
+### 1️⃣ Decorator (Most Common)
+
+```python
+from typing import Annotated
+from llmcli import command, Option
+
+@command(name="ls", description="List directory")
+def ls(
+    path: Annotated[str, Option(short='p', description="Directory path")],
+    verbose: Annotated[bool, Option(short='v')] = False,
+) -> list[str]:
+    import os
+    return os.listdir(path)
+```
+
+### 2️⃣ Command Group
+
+```python
+from llmcli import command_group, command
+
+@command_group(name="db", description="Database operations")
+class Database:
+    @command(description="Create database")
+    def create(self, name: str) -> None: ...
+
+    @command(description="Drop database")
+    def drop(self, name: str) -> None: ...
+```
+
+### 3️⃣ Wrap Existing Tools
+
+```python
+from llmcli import wrap_tool
+
+class MyTool:
+    name = "my_tool"
+    description = "Does something"
+    parameters = {"type": "object", "properties": {"x": {"type": "int"}}}
+    async def execute(self, **kwargs): return kwargs
+
+registry.register_spec(wrap_tool(MyTool()))
+```
+
+### 4️⃣ Class Inheritance
+
+```python
+from llmcli import CliCommand, CommandRegistry
+
+class AddCommand(CliCommand):
+    name = "add"
+    description = "Add numbers"
+    args_model = AddArgs
+
+    async def run(self, **kwargs) -> dict:
+        return {"result": sum(kwargs["values"])}
+
+registry.register(AddCommand())
+```
+
+## 🤖 LLM Integration
+
+### Minimal Tool Schema
+
+Expose only one `exec` tool to the LLM:
+
+```python
+from llmcli import ExecTool
+
+exec_tool = ExecTool(callback=registry.parse_and_execute)
+# Tool schema: {name: "exec", params: {command: string, timeout?: int}}
+```
+
+### Lifecycle Callbacks
+
+```python
+from llmcli import ExecutionCallbacks
+
+def on_error(ctx):
+    print(f"Error: {ctx.error.code} - {ctx.error.message}")
+
+registry = CommandRegistry(
+    callbacks=ExecutionCallbacks(on_error=on_error)
+)
+```
+
+### Internal Parameter Injection
+
+```python
+from typing import Annotated
+from llmcli import Callback, State, command
+
+@command(name="process")
+def process(
+    data: list[str],
+    cache: Annotated[object, State(factory=lambda ctx: load_cache())] = None,
+):
+    # cache is injected automatically, hidden from CLI
+    return cached_transform(data, cache)
+```
+
+## 📦 Stable API
+
+```python
+# Core
+CommandRegistry
+CommandRegistry.register(target)
+CommandRegistry.register_spec(spec)
+CommandRegistry.execute(command_str)
+CommandRegistry.parse_and_execute(command_str)
+CommandRegistry.render_help(command)
+CommandRegistry.get_llm_prompt(detailed=False)
+
+# Decorators
+command(name=None, description="", aliases=None, hidden=False, deprecated=None)
+command_group(name, description)
+
+# Helpers
+CliCommand
+wrap_tool(tool)
+command_from_model(name, model, handler)
+command_from_method(name, target, method_name)
+Option
+Injected / Callback / State
+ExecutionCallbacks
+ExecTool
+```
+
+## 💡 Examples
+
+See [example/demo.py](example/demo.py) for a complete calc system with OpenAI/Anthropic integration:
+
+```bash
+pip install "llmcli[examples]"
+python -m example.demo --provider openai
+python -m example.demo --provider anthropic
+```
+
+## 📚 Documentation
+
+| Language | Link |
+|----------|------|
+| 🇺🇸 English | [docs/index_en.md](docs/index_en.md) |
+| 🇨🇳 中文 | [docs/index_zh.md](docs/index_zh.md) |
+
+## 📄 License
+
+MIT

agenticli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+llmcli/__init__.py,sha256=Z3xVTfiY9-Bpx4zXk_Z8GKPOUFfdbY2Av3NBc1y3iFI,2835
+llmcli/builtin.py,sha256=PIkGU6PjrIG3lPrtyGJgx3TYQyUzFZ1L_rl3-l0EfJk,2732
+llmcli/core.py,sha256=W_Nygw6KuqWMYqm4Af3-rTi7mrL6D5Yi84fRllVAJFE,32519
+llmcli/decorators.py,sha256=w5i9KkYd8pxM5Bh46sHtlJq_1KYE_oB41jcqjsJTEEo,4260
+llmcli/parser.py,sha256=_2CEqgQhWjwfd_-m3Jo4FhxAgu0uYR5j9WwFCTdtZ28,10826
+llmcli/tooling.py,sha256=oSxCmNutM9IWhaKbQoI2TXZ9PkMbdQXnGBAvqKANxJQ,9895
+llmcli/types.py,sha256=Dl9FWaS124BU8WTyLuLDG-Nt8H_d9ks8gQvHdx80wp0,9741
+llmcli/validation.py,sha256=ka_vDpcjSGHG_MLhF1LzHQV75eJxQDRnoIb5nRJH8AU,38577
+agenticli-0.1.0.dist-info/METADATA,sha256=TihSvi9jZB-TINJ9TVR0f7LKvYCeZ7SVbxD82fmABaA,8684
+agenticli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agenticli-0.1.0.dist-info/licenses/LICENSE,sha256=knHFE1wChIbxkrbYlAr02Z7lAxmWeytdNUAqO3nsp9Y,1065
+agenticli-0.1.0.dist-info/RECORD,,

agenticli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agenticli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 agenticli
+
+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.

llmcli/__init__.py

@@ -0,0 +1,75 @@
+"""llmcli - expose tools as lightweight CLI commands for LLMs.
+
+This package provides a framework for defining CLI commands that can be
+parsed and executed by LLMs. It supports multiple command definition styles
+including decorators, class inheritance, and schema-based wrapping.
+
+Typical usage:
+    from llmcli import CommandRegistry, command
+
+    registry = CommandRegistry()
+
+    @command(description="List directory contents")
+    def ls(path: Annotated[str, Option(description="Directory path")]) -> list[str]:
+        import os
+        return os.listdir(path)
+
+    registry.register(ls)
+    result = registry.execute("ls /tmp")
+
+Exports:
+    ArgSpec: Argument specification data class.
+    CliCommand: Base class for inheritance-based commands.
+    CommandError: Structured error with code, message, and hints.
+    CommandRegistry: Central registry for command management.
+    CommandSpec: Command specification data class.
+    ExecutionCallbacks: Lifecycle callbacks for command execution.
+    ExecutionContext: Context passed to lifecycle callbacks.
+    ExecutionResult: Structured execution result with ok/value/error.
+    ExecTool: Built-in command execution tool.
+    HitResult: Command matching/detection result.
+    Injected: Marker for injected (internal) parameters.
+    ParseResult: Parsed command result with arguments.
+    Callback: Alias for Injected for callback injection.
+    State: Alias for Injected for state injection.
+    clear_commands: Clear the global command registry.
+    command: Decorator to register a function as a command.
+    command_from_method: Create command from a class method.
+    command_from_model: Create command from model + handler.
+    command_group: Decorator for command groups with subcommands.
+    get_registered_commands: Get all registered command specs.
+    Option: Per-argument CLI metadata annotation.
+    wrap_tool: Wrap a schema-based tool as a command.
+"""
+
+from llmcli.builtin import ExecTool
+from llmcli.core import CommandRegistry
+from llmcli.decorators import clear_commands, command, command_group, get_registered_commands
+from llmcli.tooling import CliCommand, command_from_method, command_from_model, wrap_tool
+from llmcli.types import ArgSpec, CommandError, CommandSpec, ExecutionCallbacks, ExecutionContext, ExecutionResult, HitResult, ParseResult
+from llmcli.validation import Callback, Injected, Option, State
+
+__all__ = [
+    "ArgSpec",
+    "CliCommand",
+    "CommandError",
+    "CommandRegistry",
+    "CommandSpec",
+    "ExecutionCallbacks",
+    "ExecutionContext",
+    "ExecutionResult",
+    "ExecTool",
+    "HitResult",
+    "Injected",
+    "ParseResult",
+    "Callback",
+    "State",
+    "clear_commands",
+    "command",
+    "command_from_method",
+    "command_from_model",
+    "command_group",
+    "get_registered_commands",
+    "Option",
+    "wrap_tool",
+]

llmcli/builtin.py

@@ -0,0 +1,90 @@
+"""Builtin tools for llmcli.
+
+This module provides built-in command tools that ship with llmcli,
+including the ExecTool for executing shell commands through a callback.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Awaitable, Callable
+
+
+class ExecTool:
+    """Minimal schema-based exec tool backed by a callback.
+
+    Provides a command execution tool that delegates to a user-provided
+    callback function. The callback receives the command string and any
+    additional arguments.
+
+    Attributes:
+        name: Command name, defaults to "exec".
+        description: Human-readable description of the command.
+        parameters: JSON schema describing the command arguments.
+
+    Example:
+        >>> def execute_cmd(cmd: str, timeout: int = 60):
+        ...     return subprocess.run(cmd, shell=True, timeout=timeout)
+        ...
+        >>> tool = ExecTool(callback=execute_cmd)
+        >>> spec = wrap_tool(tool)
+    """
+
+    name = "exec"
+    description = "Execute a command string through a callback."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "Command text to execute",
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Execution timeout in seconds",
+                "default": 60,
+            },
+        },
+        "required": ["command"],
+    }
+
+    def __init__(self, callback: Callable[..., Any] | Callable[..., Awaitable[Any]]):
+        """Initialize ExecTool with execution callback.
+
+        Args:
+            callback: Function to execute with command. Can be sync or async.
+        """
+        self._callback = callback
+
+    async def execute(self, **kwargs: Any) -> Any:
+        """Execute the command via callback.
+
+        Args:
+            **kwargs: Arguments from parsed command, must include 'command'.
+
+        Returns:
+            Result from the callback function.
+        """
+        command = kwargs.pop("command", None)
+        if command is not None:
+            result = self._callback(command, **kwargs)
+        else:
+            result = self._callback(**kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    def to_schema(self) -> dict[str, Any]:
+        """Convert tool to OpenAI function schema format.
+
+        Returns:
+            Dictionary with type "function" and function definition.
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }