agentic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e110789346f794e5ca8b259bfec4fef822829854f6fa079ffa5ebb1f32c5547b
-  data.tar.gz: 0c4f3458d21a47e68b51326663abce0a1662ecc70c36adb615b5bab3b1a11357
+  metadata.gz: ebc5c754277ba41da6444fb8888e94cefc789c1616948c9f046fefeb585d0294
+  data.tar.gz: f01668889c945d6d21e7fe8df1906a5cf20ad4ece46c3c92823059dd822c43da
 SHA512:
-  metadata.gz: cfa927848cac32b8482e253f3e038be7bb85d69cc27ec25a5a0e883fd88beab91f0a44d16744e8eb9c198941d78ad34b1e058c92a8a7353e5b60b8fb31e49846
-  data.tar.gz: 0ab4180f1e7583bd7760a48c9b03bae74938219c6706b71f7cf7c8cf63e6059637030a4953076dd2e646ec1919f30d7ea1070b88a6640e5ce6af852d0587bcfc
+  metadata.gz: 4ba78360d0df76c6cbb7c3e69139a4257fa23fdfd38da32a256e128d187f48b6de327c79730b9573381e53cf50cf99773478725b81ff56afda1c9bd2af7e4ce1
+  data.tar.gz: e91cb20c369383161d617e82326e515d818f8c683636f763a3bedbb95126c366742813948cbdf61f6448192c430935af4ffe18ff2a9921b4b210582233989d76

data/.agentic.yml

@@ -0,0 +1,2 @@
+---
+model: gpt-4o-mini

data/.architecture/decisions/ArchitecturalFeatureBuilder.md

@@ -0,0 +1,136 @@
+# Architectural Feature Builder Guide
+
+This document consolidates the architectural design approach for the Agentic framework, providing a streamlined guide for feature implementation.
+
+## Architectural Philosophy
+
+Agentic is designed as a domain-agnostic, self-improving framework for AI agent orchestration following these principles:
+- Extensibility through well-defined interfaces
+- Progressive automation with human oversight
+- Learning capability through execution history
+- Separation of concerns with clearly defined responsibilities
+
+## Feature Implementation Process
+
+### 1. Design Phase
+
+When designing a new feature:
+
+1. **Reference Architecture**: Consult ArchitectureConsiderations.md for overall system design
+2. **Component Placement**: Identify which layer(s) the feature belongs to
+3. **Interface Definition**: Define clear interfaces before implementation
+4. **Dependency Management**: Minimize dependencies between components
+5. **Extension Points**: Identify where the feature should support extension
+
+### 2. Implementation Phase
+
+When implementing a feature:
+
+1. **Class Structure**:
+   - Define attributes with clear visibility (public/private)
+   - Implement lifecycle methods (initialization, execution, completion)
+   - Add observability hooks (logging, metrics)
+   - Include verification points
+
+2. **Communication Patterns**:
+   - Use event-driven communication where appropriate
+   - Implement clear state transitions
+   - Maintain immutability where possible
+   - Include support for serialization/deserialization
+
+3. **Service Integration**:
+   - Define clear boundaries between services
+   - Implement retry and error handling
+   - Support for asynchronous operation
+   - Include metrics collection
+
+### 3. Verification Phase
+
+When verifying a feature:
+
+1. **Automated Testing**:
+   - Unit tests for individual components
+   - Integration tests for component interaction
+   - System tests for end-to-end workflows
+
+2. **Manual Verification**:
+   - Identify human intervention points
+   - Verify error handling and recovery
+   - Assess performance characteristics
+   - Confirm extensibility
+
+## Task Class Design Example
+
+The Task class exemplifies the architectural approach:
+
+### Core Requirements
+
+1. **Functionality**:
+   - Represent a unit of work in the system
+   - Support execution by an agent
+   - Enable verification of results
+   - Track execution state and history
+
+2. **Communication**:
+   - Interface with agents for execution
+   - Communicate with verification systems
+   - Support dependency resolution
+   - Provide metrics for observability
+
+3. **Extensibility**:
+   - Support custom execution strategies
+   - Allow plugin-based verification
+   - Enable domain-specific behaviors
+   - Support various input/output formats
+
+### Implementation Considerations
+
+1. **State Management**:
+   - Maintain clear task lifecycle (pending, in_progress, completed, failed)
+   - Track timestamps for performance analysis
+   - Support retries with history
+   - Record verification results and confidence scores
+
+2. **Integration Points**:
+   - Agent execution interface
+   - Verification hub integration
+   - Metrics collection system
+   - Human intervention portal
+
+3. **Separation of Concerns**:
+   - Task should focus on state and lifecycle
+   - Execution details belong in agents
+   - Verification logic belongs in verifiers
+   - Dependency resolution in specialized resolvers
+
+## Feature Implementation Checklist
+
+For each new feature:
+
+- [ ] Design aligns with overall architecture
+- [ ] Clear separation of concerns
+- [ ] Well-defined interfaces
+- [ ] Appropriate error handling
+- [ ] Metrics and observability
+- [ ] Extension points identified
+- [ ] Human intervention points defined
+- [ ] Testing strategy established
+- [ ] Documentation prepared
+
+## Iteration Approach
+
+1. Start with a minimal implementation focused on core functionality
+2. Add verification and observability
+3. Enhance with extension points
+4. Refine based on testing and feedback
+5. Document thoroughly
+
+When iterating on architectural design:
+1. Update ArchitectureConsiderations.md with any changes
+2. Ensure backward compatibility or provide migration path
+3. Communicate changes to all stakeholders
+4. Update relevant tests and documentation
+
+## Conclusion
+
+This guide provides a structured approach to feature development within the Agentic framework. By following these guidelines, contributors can ensure their implementations align with the overall architectural vision while maintaining quality, extensibility, and consistency across the system.

data/.architecture/decisions/ArchitectureConsiderations.md

@@ -0,0 +1,200 @@
+# 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
+
+**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
+- 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
+
+## 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. Add human intervention portal
+
+For detailed design documentation on specific architectural decisions, see the `.architecture-review` 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
+
+## 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/.architecture/decisions/adr_001_observer_pattern_implementation.md

@@ -0,0 +1,196 @@
+# ADR 001: Observer Pattern Implementation
+
+## Status
+
+Proposed
+
+## Context
+
+The Agentic framework requires an event notification system to enable components to react to changes in Task state. We've designed the architecture to use the Observer pattern, initially intending to use Ruby's built-in `Observable` module from the standard library.
+
+However, as of Ruby 3.0, the `Observable` module has been extracted from the standard library into a separate gem: [observer](https://github.com/ruby/observer). This change necessitates a decision on how to implement the Observer pattern in our framework.
+
+## Decision Drivers
+
+1. **Dependency Management**: Minimizing unnecessary external dependencies
+2. **API Stability**: Ensuring a stable interface for observers
+3. **Performance**: Efficient notification for potentially large numbers of observers
+4. **Thread Safety**: Support for concurrent task execution
+5. **Maintainability**: Ease of understanding and maintaining the code
+6. **Flexibility**: Ability to extend or customize behavior as needed
+
+## Options Considered
+
+### 1. Use the 'observer' gem
+
+**Description**:
+- Add the 'observer' gem as a dependency
+- Continue using the `Observable` module as originally planned
+
+**Pros**:
+- Maintains compatibility with standard Ruby practices
+- Minimal implementation effort
+- Well-understood behavior
+- Maintained by the Ruby core team
+
+**Cons**:
+- Adds an external dependency to the project
+- Limited control over implementation details
+- Not thread-safe by default
+- Slightly less performance than a custom solution
+
+### 2. Implement a minimal custom observer pattern
+
+**Description**:
+- Create our own simple observer implementation within the framework
+- Focus on just the functionality we need
+
+**Pros**:
+- No external dependency
+- Complete control over implementation
+- Can be optimized for our specific use case
+- Can be made thread-safe from the start
+
+**Cons**:
+- Requires maintaining custom code
+- Need to ensure compatibility with standard observer patterns
+- Potential for bugs in our implementation
+
+### 3. Use the Wisper gem
+
+**Description**:
+- Add the 'wisper' gem as a dependency
+- Use its pub/sub implementation for event notifications
+
+**Pros**:
+- More modern pub/sub implementation
+- Additional features like global listeners, temporary subscriptions
+- Well maintained and widely used
+- Better separation between publishers and subscribers
+
+**Cons**:
+- More complex API than basic Observer pattern
+- Adds an external dependency
+- Potentially more than we need for our use case
+
+### 4. Event-driven architecture with custom dispatcher
+
+**Description**:
+- Implement a centralized event dispatcher system
+- Components register callbacks for specific event types
+
+**Pros**:
+- More flexible than traditional Observer pattern
+- Can support multiple event types and filtering
+- Centralized control over event propagation
+- Potentially better performance for many observers
+
+**Cons**:
+- More complex implementation
+- Different mental model than traditional Observer pattern
+- Requires more coordination between components
+
+## Decision
+
+We will implement a minimal custom observer pattern (Option 2) that closely mirrors the API of Ruby's Observable module. This decision balances our need to minimize dependencies while maintaining a familiar and straightforward API.
+
+The implementation will:
+
+1. Be thread-safe by default
+2. Support the familiar add_observer/delete_observer methods
+3. Use a more explicit notification mechanism with event types
+4. Include only what we need, no unnecessary features
+
+### Implementation
+
+```ruby
+module Agentic
+  module Observable
+    # Add an observer to this object
+    # @param observer [Object] The observer object
+    # @return [void]
+    def add_observer(observer)
+      @_observers ||= []
+      @_observers << observer unless @_observers.include?(observer)
+    end
+    
+    # Remove an observer from this object
+    # @param observer [Object] The observer object
+    # @return [void]
+    def delete_observer(observer)
+      @_observers&.delete(observer)
+    end
+    
+    # Remove all observers from this object
+    # @return [void]
+    def delete_observers
+      @_observers = []
+    end
+    
+    # Return the number of observers
+    # @return [Integer] The number of observers
+    def count_observers
+      @_observers ? @_observers.size : 0
+    end
+    
+    # Notify all observers of an event
+    # @param event_type [Symbol] The type of event
+    # @param *args Arguments to pass to the observers
+    # @return [void]
+    def notify_observers(event_type, *args)
+      return unless @_observers
+      
+      # Make a thread-safe copy of the observers array
+      observers = @_observers.dup
+      
+      observers.each do |observer|
+        if observer.respond_to?(:update)
+          observer.update(event_type, self, *args)
+        end
+      end
+    end
+  end
+end
+```
+
+## Consequences
+
+### Positive
+
+1. **No External Dependencies**: The framework will not require the 'observer' gem or any other external dependency for event notification.
+2. **Thread Safety**: The implementation will be thread-safe by default, better supporting concurrent task execution.
+3. **Explicit Event Types**: Using explicit event types in notifications provides more clarity than the generic notification in the standard Observable.
+4. **Familiar API**: Developers familiar with Ruby's Observable will find our API intuitive and easy to use.
+5. **Custom Control**: We have complete control over the implementation and can optimize or extend it as needed.
+
+### Negative
+
+1. **Custom Code Maintenance**: We'll need to maintain our own implementation, including testing and bug fixes.
+2. **Slight Deviation**: Our API will slightly deviate from the standard Observable module (explicit event types).
+3. **Potential Future Changes**: If Ruby's Observer gem becomes significantly more advanced, we might miss out on those improvements.
+
+### Neutral
+
+1. **Migration Path**: If needed, we can easily migrate to using the observer gem or another solution in the future with minimal changes to client code.
+2. **Documentation**: We'll need to clearly document our Observable module, but this is standard practice regardless of implementation choice.
+
+## Implementation Notes
+
+1. The Observable module should be included in the Agentic namespace to avoid conflicts.
+2. Thread safety is achieved by creating a copy of the observers array before iteration.
+3. The implementation should be tested for both single-threaded and multi-threaded scenarios.
+4. Documentation should clarify the slight differences from Ruby's standard Observable.
+
+## Alternative Paths
+
+If this implementation proves problematic in the future, we can:
+
+1. Switch to using the 'observer' gem with minimal code changes
+2. Adopt Wisper or another pub/sub gem if we need more advanced features
+3. Develop a more comprehensive event system if our needs become more complex
+
+## References
+
+- [Ruby Observer gem](https://github.com/ruby/observer)
+- [Wisper gem](https://github.com/krisleech/wisper)
+- [Observer Pattern on Wikipedia](https://en.wikipedia.org/wiki/Observer_pattern)