agenticli 0.1.0__tar.gz

agenticli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.claude
+.pytest_cache

agenticli-0.1.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Bilingual documentation (English and Chinese)
+- Comprehensive docstrings for all modules and public APIs
+
+### Changed
+- Refactored `pyproject.toml` dependencies: core library now has zero required dependencies
+- Updated minimum Python version requirement to 3.10 (from 3.12)
+
+### Documentation
+- Created `docs/index_en.md` - English documentation
+- Created `docs/index_zh.md` - Chinese documentation
+- Updated `README.md` with new documentation links
+
+## [0.1.0] - Initial Release
+
+### Added
+- `CommandRegistry` as the core execution and help system
+- Multiple command registration patterns:
+  - Function decorator (`@command`)
+  - Command groups (`@command_group`)
+  - Class inheritance (`CliCommand`)
+  - Dataclass-based (`command_from_model`)
+  - Schema-based tool wrapping (`wrap_tool`)
+- Command parsing:
+  - Positional arguments
+  - Long options (`--option value`)
+  - Short options (`-o value`)
+  - Boolean flags
+  - Inline values (`--option=value`)
+- Help system:
+  - Local command help
+  - Group help with subcommands
+- Structured execution API:
+  - `ExecutionResult` with ok/value/error
+  - `CommandError` with code, message, hint, and suggestion
+- Command suggestions:
+  - Unknown command suggestions (did you mean)
+  - Unknown option suggestions
+  - Enum value suggestions
+- Command metadata:
+  - Hidden commands (excluded from help)
+  - Deprecated commands with notice
+- Parameter features:
+  - Ordering and positioning control
+  - Example values for documentation
+  - Hidden parameters
+  - Repeatable parameters
+  - List/dict/tuple parameter handling
+  - `requires` / `excludes` validation
+- Lifecycle callbacks (`ExecutionCallbacks`):
+  - `before_execute`
+  - `after_execute`
+  - `on_error`
+- Internal parameter injection (`Injected`, `Callback`, `State`)
+- Chain execution with operators (`&&`, `||`, `;`)
+- Built-in `ExecTool` for shell command execution
+
+[Unreleased]: https://github.com/your-repo/agenticli/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/your-repo/agenticli/releases/tag/v0.1.0

agenticli-0.1.0/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.

agenticli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,248 @@
+<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/docs/index.md

@@ -0,0 +1,14 @@
+# agenticli Documentation
+
+This directory contains the documentation for agenticli.
+
+## Files
+
+- [index_en.md](index_en.md) - English documentation
+- [index_zh.md](index_zh.md) - Chinese documentation (中文文档)
+
+## Quick Links
+
+For English documentation, see [index_en.md](index_en.md).
+
+For Chinese documentation, see [index_zh.md](index_zh.md).