Metadata-Version: 2.4
Name: henchman-ai
Version: 0.2.21
Summary: A model-agnostic AI agent CLI - your AI henchman for the terminal
Project-URL: Homepage, https://github.com/MGPowerlytics/henchman-ai
Project-URL: Repository, https://github.com/MGPowerlytics/henchman-ai
Project-URL: Documentation, https://github.com/MGPowerlytics/henchman-ai/tree/main/docs
Project-URL: Changelog, https://github.com/MGPowerlytics/henchman-ai/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/MGPowerlytics/henchman-ai/issues
Project-URL: Discussions, https://github.com/MGPowerlytics/henchman-ai/discussions
Author-email: Matthew <matthew@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,assistant,cli,deepseek,henchman,llm,openai,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: anthropic>=0.40
Requires-Dist: anyio>=4.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: chromadb>=0.4
Requires-Dist: click>=8.0
Requires-Dist: fastembed>=0.3
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: networkx>=3.0
Requires-Dist: openai>=1.40
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tiktoken>=0.5
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-networkx>=3.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Henchman-AI

> Your AI Henchman for the Terminal - A Model-Agnostic AI Agent CLI

[![PyPI version](https://img.shields.io/pypi/v/henchman-ai.svg)](https://pypi.org/project/henchman-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/henchman-ai.svg)](https://pypi.org/project/henchman-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Henchman-AI is a powerful, terminal-based AI agent that supports multiple LLM providers (DeepSeek, OpenAI, Anthropic, Ollama, and more) through a unified interface. Inspired by gemini-cli, built for extensibility and production use.

## ✨ Features

- 🤝 **Multi-Agent Dev Team**: Orchestrate a team of specialists (Architect, Coder, Reviewer, Tester, etc.) to solve complex engineering tasks.
- 🔄 **Model-Agnostic**: Support any LLM provider through a unified abstraction layer
- 🐍 **Pythonic**: Leverages Python's async ecosystem and rich libraries for optimal performance
- 🔌 **Extensible**: Plugin system for tools, providers, and custom commands
- 🚀 **Production-Ready**: Proper error handling, comprehensive testing, and semantic versioning
- 🛠️ **Tool Integration**: Built-in support for file operations, web search, code execution, and more
- ⚡ **Fast & Efficient**: Async-first design with intelligent caching and rate limiting
- 🔒 **Secure**: Environment-based configuration and safe execution sandboxing

## 📦 Installation

### From PyPI (Recommended)
```bash
pip install henchman-ai
```

### From Source
```bash
git clone https://github.com/MGPowerlytics/henchman-ai.git
cd henchman-ai
pip install -e ".[dev]"
```

### With uv (Fastest)
```bash
uv pip install henchman-ai
```

## 🚀 Quick Start

1. **Set your API key** (choose your preferred provider):
   ```bash
   export DEEPSEEK_API_KEY="your-api-key-here"
   # or
   export OPENAI_API_KEY="your-api-key-here"
   # or
   export ANTHROPIC_API_KEY="your-api-key-here"
   ```

2. **Start the CLI**:
   ```bash
   henchman
   ```

3. **Or run with a prompt directly**:
   ```bash
   henchman --prompt "Explain this Python code" < example.py
   ```

## 📖 Usage Examples

### Basic Commands
```bash
# Show version
henchman --version

# Show help
henchman --help

# Interactive mode (default)
henchman

# Headless mode with prompt
henchman -p "Summarize the key points from README.md"

# Specify a provider
henchman --provider openai -p "Write a Python function to calculate fibonacci"

# Use a specific model
henchman --model gpt-4-turbo -p "Analyze this code for security issues"
```

### File Operations
```bash
# Read and analyze a file
henchman -p "Review this code for bugs" < script.py

# Process multiple files
cat *.py | henchman -p "Find common patterns in these files"

# Generate documentation
henchman -p "Create API documentation for this module" < module.py > docs.md
```

## ⚙️ Configuration

Henchman-AI uses hierarchical configuration (later settings override earlier ones):

1. **Default settings** (built-in sensible defaults)
2. **User settings**: `~/.henchman/settings.yaml`
3. **Workspace settings**: `.henchman/settings.yaml` (project-specific)
4. **Environment variables** (highest priority)

### Example `settings.yaml`
```yaml
# Provider configuration
providers:
  default: deepseek  # or openai, anthropic, ollama
  deepseek:
    model: deepseek-chat
    base_url: "https://api.deepseek.com"
    temperature: 0.7
  openai:
    model: gpt-4-turbo-preview
    organization: "org-xxx"

# Tool settings
tools:
  auto_accept_read: true
  shell_timeout: 60
  web_search_max_results: 5

# UI settings
ui:
  theme: "monokai"
  show_tokens: true
  streaming: true

# System settings
system:
  cache_enabled: true
  cache_ttl: 3600
  max_tokens: 4096
```

### Environment Variables
```bash
# Provider API keys
export DEEPSEEK_API_KEY="sk-xxx"
export OPENAI_API_KEY="sk-xxx"
export ANTHROPIC_API_KEY="sk-xxx"

# Configuration overrides
export HENCHMAN_DEFAULT_PROVIDER="openai"
export HENCHMAN_DEFAULT_MODEL="gpt-4"
export HENCHMAN_TEMPERATURE="0.5"
```

## 🔌 Supported Providers

| Provider | Models | Features |
|----------|--------|----------|
| **DeepSeek** | deepseek-chat, deepseek-coder | Free tier, Code completion |
| **OpenAI** | gpt-4, gpt-3.5-turbo, etc. | Function calling, JSON mode |
| **Anthropic** | claude-3-opus, claude-3-sonnet | Long context, Constitutional AI |
| **Ollama** | llama2, mistral, codellama | Local models, Custom models |
| **Custom** | Any OpenAI-compatible API | Self-hosted, Local inference |

## 🛠️ Development

### Setup Development Environment
```bash
# Clone and install
git clone https://github.com/MGPowerlytics/henchman-ai.git
cd henchman-ai
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

### Running Tests
```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=henchman --cov-report=html

# Run specific test categories
pytest tests/unit/ -v
pytest tests/integration/ -v
```

### Code Quality
```bash
# Linting
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/

# Security scanning
bandit -r src/
```

### Building and Publishing
```bash
# Build package
hatch build

# Test build
hatch run test

# Publish to PyPI (requires credentials)
hatch publish
```

## 📚 Documentation

### Online Documentation
For detailed documentation, see the [docs directory](docs/) in this repository:

- [Getting Started](docs/getting-started.md)
- [Configuration Guide](docs/configuration.md)
- [API Reference](docs/api.md)
- [Tool Development](docs/tools.md)
- [Provider Integration](docs/providers.md)
- [MCP Integration](docs/mcp.md)
- [Extensions](docs/extensions.md)

### Building Documentation Locally
You can build and view the documentation locally:

```bash
# Install documentation dependencies
pip install mkdocs mkdocs-material mkdocstrings[python]

# Build static HTML documentation
python scripts/build_docs.py

# Or serve documentation locally (live preview)
mkdocs serve
```

The documentation will be available at `http://localhost:8000` when served locally.

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 🐛 Reporting Issues

Found a bug or have a feature request? Please [open an issue](https://github.com/MGPowerlytics/henchman-ai/issues) on GitHub.

## 📄 License

Henchman-AI is released under the MIT License. See the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by [gemini-cli](https://github.com/google/gemini-cli)
- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Uses [Pydantic](https://docs.pydantic.dev/) for data validation
- Powered by the Python async ecosystem

---

**Happy coding with your AI Henchman!** 🦸‍♂️🤖