agentic 0.1.0 → 0.2.0

data/ArchitectureConsiderations.md

@@ -0,0 +1,229 @@
+# Architecture Considerations for Agentic
+
+## Core Architecture Vision
+
+Agentic aims to be a domain-agnostic, self-improving framework for AI agent orchestration using a plan-and-execute paradigm. This document outlines the architectural considerations for creating a robust, extensible system.
+
+## System Layers
+
+### 1. Foundation Layer
+
+**Purpose**: Provides core abstractions and fundamental capabilities.
+
+**Components**:
+- **AgentRegistry**: Central registry for managing different agent types
+- **CapabilityManager**: Handles extensible agent abilities and tools
+- **MetaLearningSystem**: Enables cross-execution improvements and adaptation
+- **StreamingObservabilityHub**: Central coordinator for real-time event streaming and observability
+
+**Design Principles**:
+- Dependency injection for all components
+- Registry pattern for plugin management
+- Abstract interfaces for all core functionalities
+
+### 2. Runtime Layer
+
+**Purpose**: Manages the execution of tasks and plans.
+
+**Components**:
+- **TaskFactory**: Creates task instances from specifications
+- **PlanOrchestrator**: Manages workflow execution
+- **ExecutionContext**: Maintains state during execution
+- **Task**: Represents individual units of work
+  - Properties: id, description, agent_spec, input, output, status
+  - Behaviors: initialization, performance, verification
+- **TaskResult**: Encapsulates the outcome of task execution
+  - Properties: task_id, success, output, failure
+  - Behaviors: result inspection, serialization
+- **TaskFailure**: Captures detailed failure information
+  - Properties: message, type, timestamp, context
+  - Behaviors: error contextualization, serialization
+
+**Design Principles**:
+- State management through immutable objects
+- Event-driven communication between components
+- Transaction-like semantics for task execution
+- Observable pattern for task state notification
+- Streaming observability for real-time insights
+- Result-oriented failure handling
+
+### 3. Verification Layer
+
+**Purpose**: Ensures quality and correctness of execution.
+
+**Components**:
+- **VerificationHub**: Coordinates verification strategies
+- **CriticFramework**: Provides multi-perspective evaluation
+- **AdaptationEngine**: Implements feedback-driven adjustments
+- **Verification Strategies**:
+  - Schema validation
+  - LLM-based evaluation
+  - Quantitative metrics analysis
+  - Goal alignment checking
+
+**Design Principles**:
+- Strategy pattern for verification methods
+- Observer pattern for reporting and monitoring
+- Progressive verification with escalation paths
+
+### 4. Extension System
+
+**Purpose**: Enables adaptation to different domains and use cases.
+
+**Components**:
+- **PluginManager**: Handles third-party extensions, registration, and lifecycle
+  - Plugin discovery and auto-loading
+  - Enable/disable functionality
+  - Metadata tracking for version management
+  - Event hooks for plugin lifecycle events
+- **DomainAdapter**: Integrates domain-specific knowledge
+  - Context-aware adaptation of prompts, tasks, and verification
+  - Domain knowledge repository
+  - Custom adapters for different components
+  - Pluggable adaptation strategies
+- **ProtocolHandler**: Standardizes external system connections
+  - Uniform interface for different communication protocols
+  - Configuration management
+  - Request/response standardization
+  - Error handling and logging
+
+**Design Principles**:
+- Interface-based contracts for extensions
+- Composition over inheritance
+- Versioned APIs for stability
+- Progressive enhancement of functionality
+- Defensive programming with graceful degradation
+- Standardized logging and error reporting
+
+## Learning System
+
+**Purpose**: Enables the system to improve over time.
+
+**Components**:
+- **ExecutionHistoryStore**: Captures performance data
+- **PatternRecognizer**: Identifies optimization opportunities
+- **StrategyOptimizer**: Improves execution strategies
+
+**Design Principles**:
+- Anonymized telemetry collection
+- Incremental learning with stability guarantees
+- Performance benchmarking against baselines
+
+## Observability System
+
+**Purpose**: Provides real-time insights into system execution and behavior.
+
+**Components**:
+- **StreamingObservabilityHub**: Central coordinator for all observability events
+- **ObservabilityStream**: Generic streaming interface supporting multiple backends (console, file, WebSocket, memory)
+- **StreamProcessor**: Event filtering, transformation, and routing capabilities
+- **MetricsAggregator**: Real-time metrics calculation and windowed aggregation
+- **Enhanced Observable Pattern**: Streaming-aware extension of existing Observable pattern
+
+**Design Principles**:
+- Non-blocking streaming to prevent execution delays
+- Pluggable stream backends for different use cases
+- Configurable event filtering and transformation
+- Thread-safe concurrent stream processing
+- Backwards compatible with existing Observable behavior
+
+**Stream Types**:
+- **Task Execution Streams**: Intermediate steps, progress updates, and performance metrics
+- **Agent Assembly Streams**: Capability analysis, selection reasoning, and construction steps
+- **Plan Building Streams**: Goal analysis, task generation, and dependency resolution
+- **Orchestration Streams**: Scheduling decisions, resource allocation, and execution coordination
+- **LLM Interaction Streams**: Token usage, response times, and content flow
+
+## Human Interface
+
+**Purpose**: Facilitates human oversight and intervention.
+
+**Components**:
+- **InterventionPortal**: Manages human input requests/responses
+- **ExplanationEngine**: Provides transparency into system decisions
+- **ConfigurationInterface**: Enables system customization
+
+**Design Principles**:
+- Progressive automation of common interventions
+- Clear explanation of system reasoning
+- Configurable confidence thresholds
+
+## Critical Human Intervention Points
+
+1. **Ethical Boundaries**: Human approval for ethically sensitive tasks
+2. **Domain Expertise Gaps**: Specialized knowledge provision
+3. **Novel Situation Handling**: Guidance for unprecedented scenarios
+4. **Success Criteria Definition**: Establishing nuanced evaluation metrics
+5. **Error Recovery**: Intervention when automatic recovery fails
+6. **Agent Selection Validation**: Confirming appropriate agent assignments
+7. **Resource Authorization**: Approving access to restricted resources
+8. **Strategic Direction**: High-level course correction
+9. **Confidence Thresholds**: Proceeding despite uncertainty
+10. **Final Output Validation**: Approving complete solutions
+
+## Implementation Strategy
+
+1. **Layered Development**:
+   - Start with core execution components
+   - Add verification layer
+   - Implement learning capabilities
+   - Enhance human interface
+
+2. **Progressive Automation**:
+   - Begin with high human oversight
+   - Track intervention patterns
+   - Gradually automate common interventions
+   - Build intervention knowledge base
+
+3. **Extensibility First**:
+   - Define clear extension points
+   - Create minimal implementations
+   - Document interfaces thoroughly
+   - Provide example extensions
+
+4. **Continuous Verification**:
+   - Implement metrics collection early
+   - Establish performance baselines
+   - Create automated verification
+   - Build regression test suite
+
+## Data Flow
+
+```
+Goal → TaskPlanner → Tasks → PlanOrchestrator
+  ↓
+Agent Selection → Task Execution → Verification
+  ↓
+Feedback Loop → Task Adaptation → Final Output
+```
+
+With verification points at each transition and potential human intervention based on confidence thresholds.
+
+## Next Steps
+
+1. ✅ Implement the Task class with result-oriented failure handling
+2. ✅ Implement TaskResult and TaskFailure supporting classes
+3. ✅ Add Observable pattern for task state notification
+4. ✅ Create PlanOrchestrator for task execution with Async
+5. ✅ Implement verification hub and basic verification strategies
+6. ✅ Implement AdaptationEngine for feedback-driven adjustments
+7. ✅ Implement Extension System components (PluginManager, DomainAdapter, ProtocolHandler)
+8. ✅ Implement Learning System components (ExecutionHistoryStore, PatternRecognizer, StrategyOptimizer)
+9. ✅ Implement metrics collection
+10. 🚧 Implement Streaming Observability System (StreamingObservabilityHub, ObservabilityStream, enhanced Observable pattern)
+11. Add human intervention portal
+
+For detailed design documentation on specific architectural decisions, see the @.architecture/decisions/adrs directory, which contains in-depth analysis of:
+- Task Input Handling
+- Task Output Handling
+- Task Failure Handling
+- Prompt Generation
+- Task Observable Pattern
+- Adaptation Engine
+- Extension System
+- Learning System
+- Streaming Observability
+
+## Conclusion
+
+This architecture provides a flexible, extensible framework for AI agent orchestration that can adapt to different domains while maintaining quality through verification and human oversight. The system is designed to improve over time through learning from execution history and human feedback.

data/CHANGELOG.md

@@ -1,5 +1,60 @@
-## [Unreleased]
+## [0.2.0] - 2025-05-29
+
+### Added
+- Agent Self-Assembly System for dynamic agent construction
+  - AgentCapabilityRegistry for managing capability specifications and providers
+  - PersistentAgentStore for saving and retrieving agent configurations
+  - AgentAssemblyEngine for analyzing tasks and assembling appropriate agents
+  - CapabilityOptimizer for improving capability implementations
+  - LLM-assisted capability selection strategy
+- Capability System with rich specification and versioning
+  - Clear distinction between capabilities and tools
+  - Semantic versioning for capability evolution
+  - Capability composition for building complex capabilities
+  - Dependency management for capabilities
+- CLI commands for capability and agent management
+  - Listing and filtering capabilities
+  - Viewing capability details
+  - Searching for capabilities
+  - Agent creation and management
+- Example capabilities for common tasks
+- Integration with learning system for capability optimization
+- Comprehensive integration tests for agent assembly workflow
+- Documentation for capability API and agent self-assembly
+- Comprehensive CLI implementation with subcommands for plan, execute, agent, and config
+- Real-time feedback with progress bars, spinners, and colorized output
+- Per-user and per-project configuration support
+- Enhanced LLM error and refusal handling with categorization
+- First-class configuration objects for LLM, retry handling, and orchestration
+- Value objects for task definitions, agent specifications, and execution results
+- Expanded test coverage for core components
+
+### Improved
+- Test coverage across all major features
+- Documentation for integration testing
+- Stability in edge cases like timeouts and partial failures
+- Metrics collection for learning system analysis
+- Agent reusability through persistent storage
+- Decoupled data from presentation throughout the codebase
+- Improved error handling with specific error types and recovery strategies
+- Enhanced documentation with CLI examples and API snippets
+
+## [0.1.0] - 2024-06-27
+
+### Added
+- Comprehensive CLI implementation with subcommands for plan, execute, agent, and config
+- Real-time feedback with progress bars, spinners, and colorized output
+- Per-user and per-project configuration support
+- Enhanced LLM error and refusal handling with categorization
+- First-class configuration objects for LLM, retry handling, and orchestration
+- Value objects for task definitions, agent specifications, and execution results
+- Expanded test coverage for core components
+
+### Changed
+- Decoupled data from presentation throughout the codebase
+- Improved error handling with specific error types and recovery strategies
+- Enhanced documentation with CLI examples and API snippets
 
 ## [0.1.0] - 2024-06-27
 
-- Initial release
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Agentic is a Ruby gem for building and running AI agents in a plan-and-execute fashion. It provides a simple command-line tool and library to build, manage, deploy, and run purpose-driven AI agents, using OpenAI's LLM API.
+
+## Architecture Documentation
+
+This project follows a rigorous architectural design approach inspired by the [ai-software-architect](https://github.com/codenamev/ai-software-architect) framework. Before implementing new features or making significant changes:
+
+1. **Consult Architectural Documents**:
+   - @ArchitectureConsiderations.md - Core architectural vision and system layers
+   - @ArchitecturalFeatureBuilder.md - Feature implementation guidelines and checklist
+   - @.architecture/ folder (when available) - Detailed architectural decision records and reviews
+
+2. **Follow Architectural Design Process**:
+   - Design Phase: Reference existing architecture, identify component placement, define interfaces
+   - Implementation Phase: Follow established patterns, maintain separation of concerns
+   - Verification Phase: Implement comprehensive testing and manual verification
+
+3. **Architectural Principles**:
+   - Domain-agnostic, self-improving framework design
+   - Progressive automation with human oversight
+   - Learning capability through execution history
+   - Extensibility through well-defined interfaces
+   - Clear separation of concerns across system layers
+
+## Key Commands
+
+### Setup and Installation
+
+```bash
+# Install dependencies
+bin/setup
+
+# Install the gem locally
+bundle exec rake install
+```
+
+### Testing and Linting
+
+```bash
+# Run the test suite
+bundle exec rake spec
+
+# Run a specific test file
+bundle exec rspec spec/path/to/file_spec.rb
+
+# Run a specific test
+bundle exec rspec spec/path/to/file_spec.rb:LINE_NUMBER
+
+# Run linting (StandardRB)
+bundle exec rake standard
+
+# Run both tests and linting (default task)
+bundle exec rake
+
+# Autofix linter issues with StandardRB
+standardrb --fix
+```
+
+### Release
+
+```bash
+# Release a new version (after updating version.rb)
+bundle exec rake release
+```
+
+## Development Guidelines
+
+You are an experienced Ruby on Rails developer, very accurate for details. The
+last 10 years you've spent managing open source Ruby gems and architecting
+object oriented solutions.
+
+You must keep your answers very short, concise, simple and informative.
+
+### Architectural Rigor
+
+Before implementing any feature:
+1. **Review Architecture**: Consult `ArchitectureConsiderations.md` and `ArchitecturalFeatureBuilder.md`
+2. **System Layer Identification**: Determine which architectural layer(s) your feature affects:
+   - Foundation Layer (core abstractions, registries)
+   - Runtime Layer (task execution, orchestration)
+   - Verification Layer (quality assurance, validation)
+   - Extension System (plugins, domain adapters)
+3. **Interface Design**: Define clear interfaces following established patterns
+4. **Implementation Checklist**: Use the checklist in `ArchitecturalFeatureBuilder.md`
+
+### Code Standards
+
+1. Prepend all Ruby commands with "bundle exec"
+2. Use the project's .rubocop.yml for formatting of all Ruby code.
+3. Use YARD comments for properly documenting all generated Ruby code.
+4. **Testing with VCR**: The project uses VCR to record and replay HTTP interactions for tests. When adding new API interactions, ensure that they are properly recorded in cassettes.
+5. **Structured Outputs**: When working with LLM responses, use the StructuredOutputs module to define schemas and validate responses.
+6. **Factory Pattern**: Follow the established factory pattern when extending or creating new agents.
+7. **API Key Handling**: Never hardcode API keys. Use the configuration system or environment variables.
+8. **Ruby Style**: The project follows StandardRB conventions. Ensure your code passes `rake standard`.
+9. **Documentation**: Document new classes and methods using YARD-style comments.
+
+### Architectural Decision Documentation
+
+When making significant architectural decisions:
+1. Document rationale in relevant architectural files
+2. Update @ArchitectureConsiderations.md if system design changes
+3. Consider creating @.architecture/decisions/adrs/ entries for major decisions
+4. Ensure decisions align with multi-perspective review principles (systems, domain, security, performance, maintainability)
+
+(Rest of the document remains the same as the previous content)

data/CONTRIBUTING.md

@@ -0,0 +1,286 @@
+# Contributing to Agentic
+
+Thank you for your interest in contributing to Agentic! This guide will help you get started with contributing to our AI agent orchestration framework.
+
+## Quick Start
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/agentic.git
+   cd agentic
+   ```
+3. **Set up development environment**:
+   ```bash
+   bin/setup
+   ```
+4. **Run tests** to ensure everything works:
+   ```bash
+   bundle exec rake
+   ```
+
+## Development Guidelines
+
+### Code Standards
+
+- **Ruby Style**: Follow [StandardRB](https://github.com/testdouble/standard) conventions
+- **Testing**: Use RSpec for tests, aim for >90% coverage on new code
+- **Documentation**: Use YARD comments for all public APIs
+- **Commit Messages**: Follow [Conventional Commits](https://www.conventionalcommits.org/)
+
+### Before You Code
+
+1. **Check existing issues** and discussions
+2. **Open an issue** for significant changes to discuss approach
+3. **Review architectural documentation**:
+   - `ArchitectureConsiderations.md` - Overall system design
+   - `ArchitecturalFeatureBuilder.md` - Implementation guidelines
+   - `.architecture/principles.md` - Core architectural principles
+
+### Architectural Guidelines
+
+**Before implementing any feature**:
+
+1. **Review Architecture**: Consult architectural documentation
+2. **System Layer Identification**: Determine which layer(s) your feature affects:
+   - Foundation Layer (core abstractions, registries)
+   - Runtime Layer (task execution, orchestration)
+   - Verification Layer (quality assurance, validation)
+   - Extension System (plugins, domain adapters)
+3. **Interface Design**: Define clear interfaces following established patterns
+4. **Implementation Checklist**: Use the checklist in `ArchitecturalFeatureBuilder.md`
+
+### Code Workflow
+
+1. **Create a feature branch** from main:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Write tests first** (TDD approach encouraged):
+   ```bash
+   bundle exec rspec spec/path/to/new_feature_spec.rb
+   ```
+
+3. **Implement your feature** following our patterns:
+   - Use dependency injection
+   - Follow the Observable pattern for state changes
+   - Implement proper error handling with detailed context
+   - Add comprehensive logging
+
+4. **Run the full test suite**:
+   ```bash
+   bundle exec rake
+   ```
+
+5. **Check code style**:
+   ```bash
+   bundle exec rake standard
+   # Auto-fix style issues:
+   standardrb --fix
+   ```
+
+6. **Update documentation** as needed
+
+## Testing Guidelines
+
+### Test Structure
+
+- **Unit Tests**: Test individual classes and methods
+- **Integration Tests**: Test component interactions
+- **Feature Tests**: Test end-to-end workflows
+
+### VCR Cassettes
+
+The project uses VCR to record HTTP interactions. When adding new API calls:
+
+1. **Record cassettes** during initial test runs
+2. **Commit cassettes** with your changes
+3. **Use descriptive cassette names** that relate to the test scenario
+
+### Test Examples
+
+```ruby
+# spec/agentic/your_feature_spec.rb
+require 'spec_helper'
+
+RSpec.describe Agentic::YourFeature do
+  describe '#method_name' do
+    it 'does something useful' do
+      # Arrange
+      feature = described_class.new
+
+      # Act
+      result = feature.method_name
+
+      # Assert
+      expect(result).to be_successful
+    end
+  end
+end
+```
+
+## Making Changes
+
+### Types of Changes
+
+- **Bug Fix**: Fix incorrect behavior
+- **Enhancement**: Improve existing functionality
+- **New Feature**: Add new capability
+- **Breaking Change**: Modify public API (requires special care)
+
+### For New Features
+
+1. **Create an ADR** (Architectural Decision Record) for significant features:
+   ```bash
+   cp .architecture/templates/adr.md .architecture/decisions/adrs/ADR-XXX-your-feature.md
+   ```
+
+2. **Follow the feature implementation process** from `ArchitecturalFeatureBuilder.md`
+
+3. **Add comprehensive tests** including edge cases
+
+4. **Update documentation** including README if needed
+
+### For Breaking Changes
+
+1. **Discuss in an issue first** - breaking changes require community input
+2. **Follow semantic versioning** - breaking changes increment major version
+3. **Provide migration guide** in CHANGELOG.md
+4. **Deprecate before removing** when possible
+
+## Pull Request Process
+
+### Before Submitting
+
+- [ ] All tests pass: `bundle exec rake`
+- [ ] Code follows style guide: `bundle exec rake standard`
+- [ ] Documentation is updated
+- [ ] CHANGELOG.md is updated (for user-facing changes)
+- [ ] Commit messages follow conventional format
+
+### PR Description Template
+
+```markdown
+## Summary
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] Enhancement
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] All tests pass locally
+
+## Documentation
+- [ ] Code comments updated
+- [ ] README updated (if needed)
+- [ ] CHANGELOG updated (if needed)
+- [ ] ADR created (for significant changes)
+
+## Additional Notes
+Any additional context or considerations
+```
+
+### Review Process
+
+1. **Automated checks** must pass (CI, linting, tests)
+2. **Code review** by maintainers
+3. **Architectural review** for significant changes
+4. **Documentation review** for user-facing changes
+
+## Release Process
+
+### Version Strategy
+
+- **Patch** (0.0.X): Bug fixes, documentation
+- **Minor** (0.X.0): New features, non-breaking enhancements
+- **Major** (X.0.0): Breaking changes
+
+### Release Steps
+
+1. Update `lib/agentic/version.rb`
+2. Update `CHANGELOG.md`
+3. Create release PR
+4. Tag and release via `bundle exec rake release`
+
+## Community Guidelines
+
+### Communication
+
+- **Be respectful** and inclusive
+- **Ask questions** when you're unsure
+- **Share knowledge** and help others
+- **Give constructive feedback** in reviews
+
+### Getting Help
+
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions and general discussion
+- **Code Comments**: Implementation-specific questions
+
+## Advanced Topics
+
+### Extension Development
+
+If you're developing plugins or extensions:
+
+1. **Review extension patterns** in `lib/agentic/extension/`
+2. **Follow plugin interfaces** defined in extension system
+3. **Add comprehensive tests** for extension points
+4. **Document extension API** changes
+
+### Performance Considerations
+
+- **Profile before optimizing** using Ruby profiling tools
+- **Consider LLM API costs** in design decisions
+- **Test performance impact** of changes
+- **Use caching appropriately** following established patterns
+
+### Security Considerations
+
+- **Review security implications** of changes
+- **Follow secure coding practices**
+- **Consider content filtering** for user inputs
+- **Implement appropriate permissions** for new capabilities
+
+## Development Tools
+
+### Useful Commands
+
+```bash
+# Run specific tests
+bundle exec rspec spec/path/to/file_spec.rb
+
+# Run tests with coverage
+COVERAGE=true bundle exec rspec
+
+# Generate documentation
+bundle exec yard doc
+
+# Interactive console with gem loaded
+bundle exec rake console
+```
+
+### IDE Setup
+
+The project includes configuration for:
+- **VS Code**: `.vscode/` directory with recommended extensions
+- **RuboCop**: For linting integration
+- **YARD**: For documentation generation
+
+## Questions?
+
+If you have questions not covered in this guide:
+
+1. **Check existing documentation** in the repository
+2. **Search GitHub issues** for similar questions
+3. **Open a GitHub Discussion** for general questions
+4. **Open a GitHub Issue** for specific bugs or feature requests
+
+Thank you for contributing to Agentic! 🚀