agentic 0.1.0 → 0.2.0

data/.architecture/decisions/adrs/ADR-006-extension-system.md

@@ -0,0 +1,273 @@
+# Extension System Design
+
+## Purpose and Scope
+
+The Extension System provides mechanisms for adapting the Agentic framework to different domains and use cases. It enables third-party extensions, domain-specific adaptations, and standardized external system connections, allowing the framework to be customized while maintaining a consistent core architecture.
+
+## Design Principles
+
+1. **Interface-based contracts**: All extensions conform to well-defined interfaces
+2. **Composition over inheritance**: Extensions are composed with core components rather than inheriting from them
+3. **Versioned APIs**: Extension interfaces are versioned to ensure stability
+4. **Minimal assumptions**: The system makes minimal assumptions about extension implementations
+5. **Progressive enhancement**: Core functionality works without extensions, which provide enhanced capabilities
+
+## Architecture
+
+The Extension System consists of three main components:
+
+1. **PluginManager**: Handles third-party extension loading and lifecycle
+2. **DomainAdapter**: Provides domain-specific knowledge and adaptation
+3. **ProtocolHandler**: Standardizes connections to external systems
+
+These components work together to provide a comprehensive extension mechanism while maintaining system integrity and consistency.
+
+### PluginManager
+
+The PluginManager coordinates third-party extension loading, registration, and lifecycle management:
+
+```ruby
+module Agentic
+  module Extension
+    class PluginManager
+      def initialize(options = {})
+        # Configuration and registry initialization
+      end
+      
+      def register(name, plugin, metadata = {})
+        # Register plugin if it conforms to contract
+      end
+      
+      def enable(name)
+        # Enable a registered plugin
+      end
+      
+      def disable(name)
+        # Disable a registered plugin
+      end
+      
+      def get(name)
+        # Retrieve a registered plugin
+      end
+      
+      def list(only_enabled: false)
+        # List registered plugins
+      end
+    end
+  end
+end
+```
+
+Key features:
+- Plugin discovery and auto-loading
+- Plugin validation against contracts
+- Enable/disable functionality
+- Metadata storage for versioning and attribution
+- Event hooks for plugin lifecycle events
+
+### DomainAdapter
+
+The DomainAdapter integrates domain-specific knowledge into the framework:
+
+```ruby
+module Agentic
+  module Extension
+    class DomainAdapter
+      def initialize(domain, options = {})
+        # Domain configuration
+      end
+      
+      def register_adapter(component, adapter)
+        # Register adapter for a component
+      end
+      
+      def add_knowledge(key, knowledge)
+        # Add domain-specific knowledge
+      end
+      
+      def adapt(component, target, context = {})
+        # Apply adaptation to target
+      end
+    end
+  end
+end
+```
+
+Key features:
+- Component-specific adaptations (prompts, tasks, verification)
+- Domain knowledge repository
+- Context-aware adaptation
+- Fallback to original behavior when adaptation fails
+
+### ProtocolHandler
+
+The ProtocolHandler standardizes connections to external systems:
+
+```ruby
+module Agentic
+  module Extension
+    class ProtocolHandler
+      def initialize(options = {})
+        # Protocol configuration
+      end
+      
+      def register_protocol(protocol_name, implementation, config = {})
+        # Register protocol implementation
+      end
+      
+      def send_request(protocol_name, endpoint, options = {})
+        # Send request using protocol
+      end
+    end
+  end
+end
+```
+
+Key features:
+- Protocol implementation registry
+- Unified request interface
+- Protocol-specific configuration
+- Default request settings
+
+## Integration Points
+
+### Core System Integration
+
+The Extension System integrates with core Agentic components at several points:
+
+1. **Agent Configuration**: Plugins can extend agent capabilities
+2. **Task Execution**: Domain adapters can customize task handling
+3. **Verification**: Domain-specific verification rules can be applied
+4. **External Communication**: ProtocolHandler provides standardized communication
+
+### Third-Party Integration
+
+Third-party extensions integrate through well-defined contracts:
+
+1. **Plugin Contract**: Requirements for valid plugins
+2. **Adapter Contract**: Interface for domain adaptations
+3. **Protocol Contract**: Requirements for protocol implementations
+
+## Extensibility Patterns
+
+1. **Registration Pattern**: Components register with managers
+2. **Strategy Pattern**: Interchangeable strategies for adaptation
+3. **Decorator Pattern**: Adapters wrap core components
+4. **Repository Pattern**: Knowledge storage and retrieval
+
+## Example Use Cases
+
+### Domain-Specific Adaptation
+
+```ruby
+# Create a healthcare domain adapter
+healthcare = Agentic::Extension::DomainAdapter.new("healthcare")
+
+# Add domain knowledge
+healthcare.add_knowledge(:terminology, {
+  terms: ["patient", "diagnosis", "treatment"],
+  relationships: {"diagnosis" => ["treatment"]}
+})
+
+# Register prompt adapter
+healthcare.register_adapter(:prompt, lambda do |prompt, context|
+  # Enhance prompt with healthcare-specific instructions
+  prompt + "\n\nUse healthcare terminology and follow HIPAA guidelines."
+end)
+
+# Use in task execution
+adapted_prompt = healthcare.adapt(:prompt, original_prompt)
+```
+
+### External System Integration
+
+```ruby
+# Create protocol handler
+protocols = Agentic::Extension::ProtocolHandler.new
+
+# Register HTTP protocol
+protocols.register_protocol(:http, HTTPClient.new, {
+  base_url: "https://api.example.com",
+  timeout: 30
+})
+
+# Register GraphQL protocol
+protocols.register_protocol(:graphql, GraphQLClient.new, {
+  endpoint: "https://api.example.com/graphql",
+  schema: "schema.graphql"
+})
+
+# Use protocols uniformly
+user_data = protocols.send_request(:http, "/users/123")
+query_result = protocols.send_request(:graphql, "", {
+  query: "{ user(id: 123) { name email } }"
+})
+```
+
+## Security Considerations
+
+1. **Plugin Isolation**: Plugins are validated and can be disabled if problematic
+2. **Sandboxing**: Implementation details determine the level of isolation
+3. **Permissions**: The framework should enforce capability-based access
+4. **Verification**: Adaptations should be verified for consistency
+
+## Future Extensions
+
+1. **Plugin Marketplace**: Central repository for sharing plugins
+2. **Dependency Resolution**: Automatic resolution of plugin dependencies
+3. **Versioned Plugins**: Support for multiple versions of the same plugin
+4. **Plugin Configuration UI**: User interface for plugin configuration
+5. **Plugin Telemetry**: Usage and performance metrics for plugins
+
+## Implementation Details
+
+The Extension System has been fully implemented with the following components:
+
+### Extension Module
+
+A central entry point for accessing extension components:
+
+```ruby
+module Agentic
+  module Extension
+    class << self
+      # Get or create a plugin manager instance
+      def plugin_manager(options = {})
+        @plugin_manager ||= PluginManager.new(options)
+      end
+
+      # Get or create a protocol handler instance
+      def protocol_handler(options = {})
+        @protocol_handler ||= ProtocolHandler.new(options)
+      end
+
+      # Create a domain adapter for a specific domain
+      def domain_adapter(domain, options = {})
+        DomainAdapter.new(domain, options)
+      end
+    end
+  end
+end
+```
+
+### Plugin Infrastructure
+
+The system includes a plugins directory at the root of the project for auto-discovery of plugins, with a README.md explaining how to create and use plugins:
+
+```
+/plugins/
+├── README.md
+└── my_plugin.rb
+```
+
+### Testing
+
+The Extension System is fully tested with comprehensive unit tests for each component:
+
+- `spec/agentic/extension/domain_adapter_spec.rb`
+- `spec/agentic/extension/protocol_handler_spec.rb`
+- `spec/agentic/extension/plugin_manager_spec.rb`
+
+## Conclusion
+
+The Extension System provides a flexible, maintainable approach to extending the Agentic framework for different domains and use cases. By following established design patterns and maintaining clear contract boundaries, it enables rich extensibility while preserving system integrity. The implementation is complete, well-tested, and ready for use in production environments.

data/.architecture/decisions/adrs/ADR-007-learning-system.md

@@ -0,0 +1,156 @@
+# Learning System Architecture
+
+## Purpose
+
+The Learning System enables Agentic to improve over time by capturing execution metrics, identifying patterns and optimization opportunities, and automatically adjusting strategies based on historical performance.
+
+## Key Components
+
+### ExecutionHistoryStore
+
+**Purpose**: Captures, stores, and retrieves execution metrics and performance data.
+
+**Responsibilities**:
+- Recording task and plan execution data
+- Storing metrics in a structured format
+- Providing query capabilities for historical analysis
+- Managing data retention policies
+- Anonymizing sensitive data
+
+**Interfaces**:
+- `record_execution(execution_data)`: Records a new execution in the history store
+- `get_history(filters)`: Retrieves execution history based on filter criteria
+- `get_metric(metric_name, filters, aggregation)`: Retrieves aggregated metrics
+- `cleanup_old_records()`: Deletes records older than retention period
+
+**Design Considerations**:
+- Uses a file-based storage system organized by date for efficient retrieval
+- Implements in-memory caching for frequently accessed records
+- Supports anonymization of sensitive data
+- Provides configurable retention policies
+- Uses a structured schema for execution records
+
+### PatternRecognizer
+
+**Purpose**: Analyzes execution history to identify patterns, trends, and optimization opportunities.
+
+**Responsibilities**:
+- Analyzing agent performance metrics
+- Identifying success/failure correlations
+- Detecting performance trends
+- Recognizing recurring failure patterns
+- Recommending optimization strategies
+
+**Interfaces**:
+- `analyze_agent_performance(agent_type, options)`: Analyzes performance for a specific agent
+- `analyze_correlation(task_property, performance_metric)`: Identifies correlations between properties
+- `recommend_optimizations(agent_type)`: Recommends optimization strategies
+
+**Design Considerations**:
+- Uses statistical methods to detect significant patterns
+- Implements caching for computationally expensive analyses
+- Provides confidence levels for identified patterns
+- Supports different analysis time windows
+- Uses a minimum sample size to ensure statistical validity
+
+### StrategyOptimizer
+
+**Purpose**: Improves execution strategies based on patterns identified in historical performance.
+
+**Responsibilities**:
+- Optimizing prompt templates
+- Adjusting LLM parameters
+- Optimizing task sequences
+- Applying learned optimizations
+- Generating performance reports
+
+**Interfaces**:
+- `optimize_prompt_template(original_template, agent_type, options)`: Optimizes a prompt template
+- `optimize_llm_parameters(original_params, agent_type, options)`: Optimizes LLM parameters
+- `optimize_task_sequence(original_sequence, plan_type, options)`: Optimizes task sequences
+- `apply_optimizations(target, registry)`: Applies optimizations to a registry
+- `generate_performance_report(agent_type)`: Generates a performance report
+
+**Design Considerations**:
+- Supports LLM-based and heuristic optimization strategies
+- Implements optimization caching with configurable intervals
+- Provides configurable optimization aggressiveness
+- Calculates confidence scores for optimizations
+- Maintains explanations for optimization decisions
+
+## Integration Points
+
+### PlanOrchestrator Integration
+
+The Learning System integrates with the PlanOrchestrator through event handlers:
+
+- `task_completed`: Records individual task executions
+- `plan_completed`: Records overall plan execution and task relationships
+
+The registration is facilitated by the `register_with_orchestrator` method which configures the necessary event handlers.
+
+### LLM Client Integration
+
+The StrategyOptimizer can leverage the LLM client to generate optimized prompts and parameters based on performance data. This integration is optional, and the optimizer falls back to heuristic approaches when no LLM client is available.
+
+## Data Flow
+
+1. **Execution History Capture**:
+   ```
+   Task/Plan Execution → ExecutionHistoryStore → Structured Record Storage
+   ```
+
+2. **Pattern Analysis**:
+   ```
+   ExecutionHistoryStore → PatternRecognizer → Pattern Identification → Optimization Recommendations
+   ```
+
+3. **Strategy Optimization**:
+   ```
+   PatternRecognizer + Historical Data → StrategyOptimizer → Improved Strategies
+   ```
+
+4. **Feedback Loop**:
+   ```
+   Improved Strategies → Task/Plan Execution → New Performance Data → Further Optimization
+   ```
+
+## Security and Privacy Considerations
+
+1. **Data Anonymization**: Sensitive task content and contextual information should be anonymized before storage.
+
+2. **Data Retention**: Historical data should be subject to configurable retention policies.
+
+3. **Storage Security**: Storage location for execution history should be secured and access-controlled.
+
+4. **Optimization Controls**: Automatic strategy optimization should be controlled and limited to prevent rapid fluctuations or regressions.
+
+## Extension Points
+
+1. **Additional Analyzers**: The PatternRecognizer can be extended with specialized analyzers for specific metrics or domains.
+
+2. **Custom Optimizers**: The StrategyOptimizer can be extended with domain-specific optimization strategies.
+
+3. **Storage Backends**: The ExecutionHistoryStore can be extended to support different storage backends (e.g., databases, cloud storage).
+
+4. **Visualization Integrations**: The performance reporting can be extended to integrate with visualization tools.
+
+## Future Considerations
+
+1. **Distributed Learning**: Support for aggregating performance data across multiple instances.
+
+2. **A/B Testing Framework**: Structured approach to testing strategy optimizations.
+
+3. **Transfer Learning**: Applying insights from one agent type to another.
+
+4. **Continuous Monitoring**: Real-time alerting for performance degradation.
+
+5. **Explainable Optimizations**: Enhanced explainability for optimization decisions.
+
+## Implementation Strategy
+
+1. **Phase 1**: Implement basic history capture and storage mechanisms
+2. **Phase 2**: Implement pattern recognition with statistical analysis
+3. **Phase 3**: Implement heuristic-based strategy optimization
+4. **Phase 4**: Implement LLM-based optimization capabilities
+5. **Phase 5**: Implement advanced features (A/B testing, transfer learning)