henchman-ai 0.1.8__tar.gz → 0.1.9__tar.gz

{henchman_ai-0.1.8 → henchman_ai-0.1.9}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.9] - 2026-01-28
+
+### Added
+
+- **Error Handling & Recovery**
+  - Added retry utilities with exponential backoff (`henchman.utils.retry`)
+  - NETWORK tools now automatically retry on transient failures (ConnectionError, TimeoutError, OSError)
+  - Configurable retry settings: `network_retries`, `retry_base_delay`, `retry_max_delay` in ToolSettings
+  - `RetryConfig` dataclass for fine-grained retry configuration
+  - `with_retry` decorator and `retry_async` function for custom retry logic
+
+- **Batch Operations**
+  - Added `execute_batch()` method to ToolRegistry for parallel tool execution
+  - Independent tool calls now execute concurrently using `asyncio.gather()`
+  - `BatchResult` dataclass with success/failure counts and individual results
+  - Batch execution continues even when some tools fail
+
 ## [0.1.8] - 2024-01-XX
 
 ### Fixed

{henchman_ai-0.1.8 → henchman_ai-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: henchman-ai
-Version: 0.1.8
+Version: 0.1.9
 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

henchman_ai-0.1.9/PROJECT_PLAN.md

@@ -0,0 +1,233 @@
+# Henchman-AI Tool Usage Improvement Project Plan
+
+## Overview
+This document outlines a comprehensive plan to enhance the tool usage capabilities of the Henchman-AI agent system. The goal is to make tool interactions more efficient, intelligent, and user-friendly.
+
+## Current State Analysis
+The current tool system provides basic file operations, shell commands, and web fetching capabilities. Tools are invoked individually with stateless interactions and minimal error recovery.
+
+## Improvement Categories
+
+### 1. Error Handling & Recovery ✅
+**Goal**: Make tool usage more resilient to failures
+**Implementation Plan**:
+- Add automatic retry logic with exponential backoff ✅
+- Implement fallback strategies for common failure modes
+- Add detailed error diagnostics and suggestions
+- Create error recovery templates for different tool types
+
+**Status**: Implemented - Retry utilities with exponential backoff for NETWORK tools
+**Priority**: High
+**Estimated Effort**: 2-3 weeks
+
+### 2. Tool Chaining & Pipelining
+**Goal**: Enable seamless data flow between tools
+**Implementation Plan**:
+- Design a pipeline DSL for tool composition
+- Implement output/input type matching system
+- Create pipeline execution engine
+- Add pipeline visualization and debugging
+
+**Priority**: High
+**Estimated Effort**: 3-4 weeks
+
+### 3. Context-Aware Tool Selection
+**Goal**: Intelligent tool recommendation based on context
+**Implementation Plan**:
+- Build tool usage pattern analyzer
+- Implement file type detection and appropriate tool mapping
+- Create context-aware tool suggestion engine
+- Add learning from user preferences
+
+**Priority**: Medium
+**Estimated Effort**: 2-3 weeks
+
+### 4. Batch Operations ✅
+**Goal**: Support efficient bulk operations
+**Implementation Plan**:
+- Design batch operation API ✅
+- Implement parallel execution for independent operations ✅
+- Add progress tracking for batch jobs
+- Create batch operation templates
+
+**Status**: Implemented - execute_batch() with asyncio.gather() for parallel execution
+**Priority**: Medium
+**Estimated Effort**: 2 weeks
+
+### 5. Interactive Preview Mode
+**Goal**: Safe editing with preview capabilities
+**Implementation Plan**:
+- Implement diff generation for file changes
+- Create preview interface for tool outputs
+- Add confirmation workflows for destructive operations
+- Design undo/redo capability
+
+**Priority**: Medium
+**Estimated Effort**: 2-3 weeks
+
+### 6. State Management
+**Goal**: Maintain context across tool interactions
+**Implementation Plan**:
+- Design session state management system
+- Implement tool usage history tracking
+- Create context persistence across turns
+- Add state visualization and management tools
+
+**Priority**: Low
+**Estimated Effort**: 3 weeks
+
+### 7. Tool Composition
+**Goal**: Create higher-level tools from basic ones
+**Implementation Plan**:
+- Design tool composition language
+- Implement tool template system
+- Create tool library with common compositions
+- Add tool composition sharing mechanism
+
+**Priority**: Medium
+**Estimated Effort**: 3 weeks
+
+### 8. Progress Feedback
+**Goal**: Provide real-time feedback for long operations
+**Implementation Plan**:
+- Implement progress tracking framework
+- Create progress visualization components
+- Add estimated time remaining calculations
+- Design interruptible operations
+
+**Priority**: Low
+**Estimated Effort**: 2 weeks
+
+### 9. Resource Management
+**Goal**: Efficient handling of large resources
+**Implementation Plan**:
+- Implement streaming file processing
+- Add memory usage monitoring and limits
+- Create resource cleanup mechanisms
+- Design pagination for large outputs
+
+**Priority**: Medium
+**Estimated Effort**: 2 weeks
+
+### 10. Tool Validation & Safety
+**Goal**: Prevent errors through validation
+**Implementation Plan**:
+- Create comprehensive parameter validation system
+- Implement pre-execution safety checks
+- Add tool-specific validation rules
+- Design validation feedback system
+
+**Priority**: High
+**Estimated Effort**: 2 weeks
+
+### 11. Learning from Usage Patterns
+**Goal**: Adaptive tool behavior based on usage
+**Implementation Plan**:
+- Implement usage pattern collection
+- Create pattern analysis engine
+- Design adaptive tool suggestions
+- Add user preference learning
+
+**Priority**: Low
+**Estimated Effort**: 4 weeks
+
+### 12. Cross-Tool Optimization
+**Goal**: Optimize sequences of tool calls
+**Implementation Plan**:
+- Implement tool call caching system
+- Create dependency analysis for tool sequences
+- Design optimization rules engine
+- Add performance monitoring
+
+**Priority**: Low
+**Estimated Effort**: 3 weeks
+
+### 13. Better Documentation Integration
+**Goal**: Inline help and examples
+**Implementation Plan**:
+- Enhance tool documentation system
+- Create interactive help with examples
+- Implement context-sensitive documentation
+- Add tool tutorial system
+
+**Priority**: Medium
+**Estimated Effort**: 2 weeks
+
+### 14. Tool Discovery & Suggestions
+**Goal**: Help users find the right tools
+**Implementation Plan**:
+- Create tool discovery interface
+- Implement intent-based tool matching
+- Add tool recommendation engine
+- Design tool exploration features
+
+**Priority**: Medium
+**Estimated Effort**: 2 weeks
+
+### 15. Permission & Safety Controls
+**Goal**: Configurable security boundaries
+**Implementation Plan**:
+- Design permission system architecture
+- Implement tool access controls
+- Create safety confirmation workflows
+- Add audit logging for sensitive operations
+
+**Priority**: High
+**Estimated Effort**: 3 weeks
+
+## Implementation Phases
+
+### Phase 1: Foundation (Weeks 1-6)
+1. Error Handling & Recovery
+2. Tool Validation & Safety
+3. Permission & Safety Controls
+
+### Phase 2: Intelligence (Weeks 7-12)
+1. Context-Aware Tool Selection
+2. Tool Discovery & Suggestions
+3. Better Documentation Integration
+
+### Phase 3: Efficiency (Weeks 13-18)
+1. Tool Chaining & Pipelining
+2. Batch Operations
+3. Resource Management
+
+### Phase 4: User Experience (Weeks 19-24)
+1. Interactive Preview Mode
+2. Progress Feedback
+3. Tool Composition
+
+### Phase 5: Advanced Features (Weeks 25-30)
+1. State Management
+2. Learning from Usage Patterns
+3. Cross-Tool Optimization
+
+## Success Metrics
+- 50% reduction in tool usage errors
+- 30% improvement in task completion time
+- 40% increase in user satisfaction scores
+- 25% reduction in manual tool selection
+
+## Risks & Mitigations
+1. **Performance Overhead**: Monitor and optimize critical paths
+2. **Complexity Creep**: Maintain backward compatibility
+3. **Security Concerns**: Implement thorough security reviews
+4. **User Adoption**: Provide gradual migration paths
+
+## Dependencies
+- Current tool system architecture
+- User feedback and usage patterns
+- Available development resources
+
+## Next Steps
+1. Review current tool implementation code
+2. Create detailed design documents for Phase 1
+3. Set up development environment and testing infrastructure
+4. Begin implementation of error handling improvements
+
+## Conclusion
+This comprehensive improvement plan will transform Henchman-AI's tool usage from basic command execution to an intelligent, efficient, and user-friendly system. The phased approach ensures manageable development while delivering continuous value to users.
+
+Last Updated: $(date)
+Project Lead: [To be assigned]
+Status: Planning Phase

henchman_ai-0.1.9/TOOL_CHAINING_DESIGN.md

@@ -0,0 +1,425 @@
+# Tool Chaining & Pipelining Design Document
+
+## Overview
+This document outlines the design for implementing tool chaining and pipelining capabilities in Henchman-AI. The goal is to enable seamless data flow between tools, allowing users to create complex workflows through simple pipeline syntax.
+
+## Current Limitations
+1. **Isolated Tool Calls**: Each tool operates independently with no data flow between calls
+2. **Manual Data Passing**: Users must manually extract and pass data between tools
+3. **No Composition**: Cannot create reusable tool combinations
+4. **Stateless Execution**: No context preservation between tool invocations
+
+## Design Goals
+1. **Intuitive Syntax**: Simple, readable pipeline syntax
+2. **Type Safety**: Automatic type checking between tool outputs and inputs
+3. **Error Propagation**: Clear error handling across pipeline stages
+4. **Performance**: Efficient execution with parallelization where possible
+5. **Debuggability**: Clear visibility into pipeline execution
+
+## Architecture
+
+### 1. Pipeline DSL (Domain Specific Language)
+```python
+# Example pipeline syntax
+pipeline = Pipeline(
+    read_file("data.txt") 
+    | grep("error") 
+    | write_file("errors.txt")
+)
+
+# Alternative syntax
+pipeline = read_file("data.txt") >> grep("error") >> write_file("errors.txt")
+```
+
+### 2. Tool Interface Extensions
+```python
+class ChainableTool(Tool):
+    """Base class for tools that can participate in chains."""
+    
+    @property
+    def output_type(self) -> Type:
+        """Type annotation for tool output."""
+        return str  # Default to string
+    
+    @property
+    def input_type(self) -> Type:
+        """Type annotation for tool input."""
+        return Any  # Default to accept anything
+    
+    def can_accept(self, output_type: Type) -> bool:
+        """Check if this tool can accept the given output type."""
+        return issubclass(output_type, self.input_type)
+```
+
+### 3. Pipeline Engine
+```python
+class PipelineEngine:
+    """Executes tool pipelines."""
+    
+    def execute(self, pipeline: Pipeline) -> PipelineResult:
+        """Execute a pipeline and return results."""
+        pass
+    
+    def validate(self, pipeline: Pipeline) -> ValidationResult:
+        """Validate pipeline structure and type compatibility."""
+        pass
+    
+    def optimize(self, pipeline: Pipeline) -> Pipeline:
+        """Optimize pipeline execution plan."""
+        pass
+```
+
+## Core Components
+
+### 1. Pipeline Definition
+```python
+@dataclass
+class Pipeline:
+    """Represents a sequence of tool operations."""
+    
+    stages: list[PipelineStage]
+    name: str = ""
+    description: str = ""
+    
+    def add_stage(self, stage: PipelineStage) -> "Pipeline":
+        """Add a stage to the pipeline."""
+        pass
+    
+    def validate(self) -> ValidationResult:
+        """Validate the entire pipeline."""
+        pass
+```
+
+### 2. Pipeline Stage
+```python
+@dataclass
+class PipelineStage:
+    """A single stage in a pipeline."""
+    
+    tool: ChainableTool
+    parameters: dict[str, Any]
+    input_source: InputSource  # Previous stage, file, or constant
+    output_dest: OutputDestination  # Next stage, file, or variable
+    
+    def execute(self, context: PipelineContext) -> StageResult:
+        """Execute this stage."""
+        pass
+```
+
+### 3. Type System
+```python
+class ToolType:
+    """Type system for tool inputs/outputs."""
+    
+    PRIMITIVE_TYPES = {
+        "string": str,
+        "integer": int,
+        "boolean": bool,
+        "array": list,
+        "object": dict,
+    }
+    
+    FILE_TYPES = {
+        "text_file": TextFile,
+        "binary_file": BinaryFile,
+        "directory": Directory,
+    }
+    
+    @classmethod
+    def infer_type(cls, value: Any) -> "ToolType":
+        """Infer type from value."""
+        pass
+    
+    @classmethod
+    def are_compatible(cls, source: "ToolType", target: "ToolType") -> bool:
+        """Check if types are compatible for chaining."""
+        pass
+```
+
+### 4. Execution Context
+```python
+@dataclass
+class PipelineContext:
+    """Context for pipeline execution."""
+    
+    variables: dict[str, Any]  # Pipeline variables
+    files: dict[str, Path]  # File references
+    stage_results: list[StageResult]  # Results from previous stages
+    execution_id: str  # Unique execution identifier
+    
+    def get_variable(self, name: str) -> Any:
+        """Get a pipeline variable."""
+        pass
+    
+    def set_variable(self, name: str, value: Any) -> None:
+        """Set a pipeline variable."""
+        pass
+```
+
+## Pipeline Syntax Examples
+
+### Example 1: Simple File Processing
+```python
+# Read file, search for pattern, write results
+pipeline = Pipeline(
+    name="error_extractor",
+    stages=[
+        Stage(read_file, {"path": "logs/app.log"}),
+        Stage(grep, {"pattern": "ERROR"}),
+        Stage(write_file, {"path": "errors.log"}),
+    ]
+)
+```
+
+### Example 2: Web Data Processing
+```python
+# Fetch data, extract information, save to file
+pipeline = (
+    web_fetch("https://api.example.com/data.json")
+    | grep("important_value")
+    | write_file("extracted.txt")
+)
+```
+
+### Example 3: Complex Workflow with Variables
+```python
+# Multi-step analysis with intermediate variables
+pipeline = Pipeline(
+    Stage(read_file, {"path": "data.csv"}, output_to="raw_data"),
+    Stage(shell, {"command": "wc -l"}, input_from="raw_data", output_to="line_count"),
+    Stage(write_file, {"path": "summary.txt", "content": "Lines: ${line_count}"}),
+)
+```
+
+### Example 4: Conditional Execution
+```python
+# Conditional pipeline based on file content
+pipeline = Pipeline(
+    read_file("config.yaml"),
+    If(
+        condition=grep("debug: true"),
+        then=pipeline1,
+        else=pipeline2
+    )
+)
+```
+
+## Implementation Phases
+
+### Phase 1: Foundation (Weeks 1-4)
+1. **Basic ChainableTool Interface**
+   - Extend existing Tool base class
+   - Add type annotations for inputs/outputs
+   - Create type compatibility checking
+
+2. **Simple Linear Pipelines**
+   - Implement sequential pipeline execution
+   - Basic error propagation
+   - Simple pipeline syntax
+
+### Phase 2: Advanced Features (Weeks 5-8)
+1. **Type System Enhancement**
+   - Comprehensive type inference
+   - Type conversion utilities
+   - Type validation at pipeline creation
+
+2. **Variable Support**
+   - Pipeline variable system
+   - Variable substitution in parameters
+   - Scope management
+
+### Phase 3: Optimization (Weeks 9-12)
+1. **Parallel Execution**
+   - Identify independent stages
+   - Implement parallel execution
+   - Resource management
+
+2. **Caching & Memoization**
+   - Stage result caching
+   - Input/output caching
+   - Cache invalidation
+
+### Phase 4: User Experience (Weeks 13-16)
+1. **Pipeline DSL**
+   - User-friendly syntax
+   - Pipeline visualization
+   - Interactive pipeline builder
+
+2. **Debugging Tools**
+   - Execution tracing
+   - Step-through debugging
+   - Pipeline state inspection
+
+## API Design
+
+### 1. Programmatic API
+```python
+# Create pipeline programmatically
+from henchman.tools.pipeline import Pipeline, Stage
+
+pipeline = Pipeline(
+    Stage(read_file_tool, {"path": "input.txt"}),
+    Stage(grep_tool, {"pattern": "search"}),
+    Stage(write_file_tool, {"path": "output.txt"}),
+)
+
+result = pipeline.execute()
+```
+
+### 2. DSL API
+```python
+# Use pipeline DSL
+from henchman.tools.pipeline import p
+
+result = p(
+    read_file("input.txt")
+    >> grep("search")
+    >> write_file("output.txt")
+).execute()
+```
+
+### 3. CLI Integration
+```bash
+# Command line pipeline execution
+henchman --pipeline "read_file input.txt | grep search | write_file output.txt"
+
+# Pipeline from file
+henchman --pipeline-file workflow.yaml
+```
+
+## Error Handling
+
+### 1. Stage-Level Errors
+```python
+class StageError(Exception):
+    """Error in a pipeline stage."""
+    
+    def __init__(self, stage: PipelineStage, error: Exception):
+        self.stage = stage
+        self.original_error = error
+        super().__init__(f"Stage {stage.name} failed: {error}")
+```
+
+### 2. Pipeline-Level Error Strategies
+```python
+class ErrorStrategy(Enum):
+    STOP_ON_ERROR = "stop"  # Default: Stop on first error
+    CONTINUE_ON_ERROR = "continue"  # Continue with next stage
+    RETRY_ON_ERROR = "retry"  # Retry failed stage
+    FALLBACK_ON_ERROR = "fallback"  # Use fallback pipeline
+```
+
+### 3. Error Recovery
+```python
+class PipelineRecovery:
+    """Handle pipeline errors and recovery."""
+    
+    def retry_stage(self, stage: PipelineStage, max_retries: int = 3) -> bool:
+        """Retry a failed stage."""
+        pass
+    
+    def fallback_pipeline(self, pipeline: Pipeline) -> Pipeline:
+        """Get fallback pipeline for error recovery."""
+        pass
+```
+
+## Performance Considerations
+
+### 1. Lazy Evaluation
+```python
+class LazyPipeline(Pipeline):
+    """Pipeline with lazy evaluation."""
+    
+    def execute(self) -> Generator[StageResult, None, None]:
+        """Execute pipeline lazily."""
+        for stage in self.stages:
+            yield stage.execute()
+```
+
+### 2. Parallel Execution
+```python
+class ParallelPipeline(Pipeline):
+    """Pipeline with parallel stage execution."""
+    
+    def execute_parallel(self, max_workers: int = 4) -> list[StageResult]:
+        """Execute independent stages in parallel."""
+        pass
+```
+
+### 3. Result Caching
+```python
+class CachedPipeline(Pipeline):
+    """Pipeline with result caching."""
+    
+    def __init__(self, cache_dir: Path = Path(".pipeline_cache")):
+        self.cache = PipelineCache(cache_dir)
+    
+    def execute(self, use_cache: bool = True) -> PipelineResult:
+        """Execute with optional caching."""
+        pass
+```
+
+## Security Considerations
+
+### 1. Pipeline Validation
+- Validate all tool parameters
+- Check file paths for safety
+- Limit resource usage
+- Sandbox execution where possible
+
+### 2. Permission Escalation Prevention
+- No automatic privilege escalation
+- User confirmation for sensitive operations
+- Audit logging for all pipeline executions
+
+### 3. Input Validation
+- Validate all external inputs
+- Sanitize file paths and URLs
+- Limit pipeline recursion depth
+
+## Testing Strategy
+
+### 1. Unit Tests
+- Individual tool chaining compatibility
+- Type system validation
+- Stage execution tests
+
+### 2. Integration Tests
+- Complete pipeline execution
+- Error handling scenarios
+- Performance benchmarks
+
+### 3. End-to-End Tests
+- Real-world workflow scenarios
+- User interaction tests
+- CLI integration tests
+
+## Migration Path
+
+### 1. Backward Compatibility
+- Existing tools remain unchanged
+- Optional chaining capability
+- Gradual migration of tools to ChainableTool
+
+### 2. Deprecation Strategy
+- Old API remains functional
+- Clear migration documentation
+- Automated migration tools
+
+## Success Metrics
+1. **Pipeline Creation Time**: Reduce by 50%
+2. **Error Rate**: Reduce pipeline errors by 40%
+3. **Execution Time**: Improve by 30% through optimization
+4. **User Satisfaction**: Increase based on user feedback
+
+## Next Steps
+1. **Week 1**: Design review and prototype
+2. **Week 2**: Implement ChainableTool base class
+3. **Week 3**: Create basic Pipeline engine
+4. **Week 4**: Test with simple use cases
+5. **Week 5**: Gather user feedback and iterate
+
+## Conclusion
+The tool chaining and pipelining system will transform Henchman-AI from a collection of individual tools into a powerful workflow automation platform. By providing intuitive syntax, robust error handling, and performance optimizations, users will be able to create complex data processing pipelines with minimal effort.
+
+This design provides a solid foundation for incremental implementation while maintaining backward compatibility and ensuring a smooth migration path for existing users.

{henchman_ai-0.1.8 → henchman_ai-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "henchman-ai"
-version = "0.1.8"
+version = "0.1.9"
 description = "A model-agnostic AI agent CLI - your AI henchman for the terminal"
 readme = "README.md"
 license = "MIT"