agentic 0.1.0 → 0.2.0

data/.architecture/decisions/adrs/ADR-008-prompt-generation.md

@@ -0,0 +1,325 @@
+# Prompt Generation Architecture
+
+## Overview
+
+This document specifies the architecture for prompt generation within the Agentic framework. Prompts serve as the critical interface between Tasks and Agents, translating structured data and instructions into a format that guides agent execution and shapes output quality.
+
+## Core Principles
+
+1. **Separation of Concerns**: Prompt generation logic should be separable from task execution
+2. **Templating**: Prompt structures should be templateable and versionable
+3. **Adaptability**: Prompts should adapt to different agent capabilities and domains
+4. **Context Integration**: Prompts should effectively incorporate relevant context
+5. **Quality Optimization**: Prompt design should optimize for output quality and consistency
+
+## Prompt Anatomy
+
+A well-structured prompt typically includes these elements:
+
+```
+[System Instructions]
+You are an agent with the role of {role} and purpose of {purpose}.
+{backstory}
+{constraints}
+
+[Task Description]
+Your task is to {description}.
+
+[Context]
+Here is the relevant information you need to complete this task:
+{context}
+
+[Input Parameters]
+The following input must be processed:
+{input_json}
+
+[Output Requirements]
+Provide your response in the following format:
+{output_schema}
+
+[Special Instructions]
+{special_instructions}
+```
+
+## Architectural Components
+
+### 1. PromptBuilder
+
+Central service responsible for constructing prompts from templates and data:
+
+```
+Task + PromptBuilder → Formatted Prompt
+```
+
+Responsibilities:
+- Apply prompt templates
+- Insert task-specific data
+- Format according to agent requirements
+- Optimize prompt structure
+
+### 2. PromptTemplate
+
+Defines the structure and content patterns for different prompt types:
+
+```ruby
+class PromptTemplate
+  attr_reader :id, :name, :template, :version
+  
+  def initialize(id:, name:, template:, version: "1.0")
+    @id = id
+    @name = name
+    @template = template
+    @version = version
+  end
+  
+  def render(data)
+    # Apply data to template
+  end
+end
+```
+
+Responsibilities:
+- Store prompt structure
+- Support variable interpolation
+- Enable versioning
+- Allow domain customization
+
+### 3. PromptRegistry
+
+Manages the collection of available prompt templates:
+
+```ruby
+class PromptRegistry
+  include Singleton
+  
+  def initialize
+    @templates = {}
+  end
+  
+  def register(template)
+    @templates[template.id] = template
+  end
+  
+  def get(id)
+    @templates[id]
+  end
+  
+  def find_by_task_type(task_type)
+    # Return appropriate template for task type
+  end
+end
+```
+
+Responsibilities:
+- Store available templates
+- Provide template lookup by ID
+- Support template discovery
+- Manage template versioning
+
+### 4. PromptOptimizer
+
+Improves prompt effectiveness based on historical performance:
+
+```
+Historical Prompts + Outcomes → PromptOptimizer → Improved Template
+```
+
+Responsibilities:
+- Analyze prompt effectiveness
+- Suggest improvements
+- Implement best practices
+- Adapt to agent capabilities
+
+## Prompt Generation Patterns
+
+### 1. Basic Template Application
+
+Simplest pattern applying task data to a template:
+
+```
+Task Data + Template → PromptBuilder → Formatted Prompt
+```
+
+Implementation considerations:
+- Variable interpolation
+- Formatting for readability
+- Handling missing data
+- Default values
+
+### 2. Contextual Enhancement
+
+Enriches prompts with relevant context:
+
+```
+Task Data + Context + Template → PromptBuilder → Enhanced Prompt
+```
+
+Implementation considerations:
+- Context prioritization
+- Relevance determination
+- Context summarization
+- Information ordering
+
+### 3. Agent-Specific Adaptation
+
+Tailors prompts to specific agent capabilities:
+
+```
+Task Data + Template + Agent Capabilities → PromptBuilder → Adapted Prompt
+```
+
+Implementation considerations:
+- Agent capability detection
+- Feature availability checking
+- Prompt complexity adjustment
+- Instruction specificity
+
+### 4. Dynamic Optimization
+
+Adjusts prompts based on real-time feedback:
+
+```
+Initial Prompt + Feedback → PromptOptimizer → Refined Prompt
+```
+
+Implementation considerations:
+- Incremental refinement
+- Feedback loop integration
+- Performance metrics evaluation
+- A/B testing
+
+## Responsibility Distribution
+
+### Task Class
+
+- Provide task data for prompt creation
+- Request prompt generation when needed
+- Pass prompt to agent during execution
+- Store prompt with execution record
+
+```ruby
+# In Task class
+def build_prompt
+  PromptBuilder.instance.build_for_task(self)
+end
+```
+
+### Agent Class
+
+- Consume formatted prompts
+- Provide capability information to prompt builder
+- Report prompt effectiveness
+
+```ruby
+# In Agent class
+def execute(prompt)
+  # Use prompt to guide execution
+end
+```
+
+### PromptBuilder
+
+- Central service for prompt construction
+- Apply templates to task data
+- Format prompts for specific agents
+- Implement optimization strategies
+
+```ruby
+# PromptBuilder implementation
+def build_for_task(task, agent_capabilities = {})
+  template = PromptRegistry.instance.find_by_task_type(task.type)
+  context = ContextManager.instance.get_context_for_task(task)
+  
+  template.render({
+    role: task.agent_spec["role"],
+    purpose: task.agent_spec["purpose"],
+    description: task.description,
+    context: format_context(context),
+    input_json: JSON.pretty_generate(task.input),
+    output_schema: task.output_schema&.to_json,
+    special_instructions: task.special_instructions
+  })
+end
+```
+
+## Template Management
+
+### 1. Template Storage
+
+Templates can be stored in:
+- Database records
+- YAML/JSON files
+- Code-based definitions
+
+Implementation considerations:
+- Searchability
+- Version control
+- Hot reloading
+- Environment-specific templates
+
+### 2. Template Authoring
+
+Templates can be authored by:
+- System developers
+- Domain experts
+- Automated systems
+
+Implementation considerations:
+- Authoring interface
+- Template validation
+- Best practice enforcement
+- Template testing
+
+### 3. Template Versioning
+
+Templates should support versioning:
+- Semantic versioning (Major.Minor.Patch)
+- Change tracking
+- Backward compatibility
+- Gradual rollout
+
+## Implementation Approach
+
+1. **Start Simple**: Begin with basic string templates
+2. **Add Structure**: Implement formal template objects
+3. **Create Registry**: Develop central template management
+4. **Enable Customization**: Support domain-specific templates
+5. **Implement Optimization**: Add performance-based improvements
+
+## Development Priorities
+
+1. Define PromptTemplate class
+2. Implement basic PromptBuilder
+3. Create PromptRegistry
+4. Integrate with Task class
+5. Develop optimization strategies
+6. Add template management tools
+
+## Integration with Other Components
+
+### Input Handling
+
+- Input data format affects prompt structure
+- Schema information guides input presentation
+
+### Output Handling
+
+- Output schema requirements must be clearly communicated in prompts
+- Output format instructions affect result quality
+
+### Verification
+
+- Prompt quality directly impacts verification success
+- Verification results can inform prompt improvements
+
+## Considerations for Future Extensions
+
+1. **Multi-modal Prompts**: Support for image, audio, or other media in prompts
+2. **Chain-of-Thought**: Structured prompting for complex reasoning
+3. **Few-Shot Learning**: Including examples in prompts
+4. **Interactive Prompts**: Prompts that evolve through agent interaction
+5. **Meta-Prompting**: Prompts that help agents create better prompts
+
+## Conclusion
+
+A well-designed prompt generation system is essential for effective agent execution. By separating prompt generation from task execution, implementing templating and optimization, and ensuring adaptability across domains and agent types, the Agentic framework can maximize agent effectiveness while maintaining consistency and quality.

data/.architecture/decisions/adrs/ADR-009-task-failure-handling.md

@@ -0,0 +1,353 @@
+# Task Failure Handling Architecture
+
+## Overview
+
+This document outlines the architectural design decision for handling task failures within the Agentic framework. It addresses limitations of exception-based failure handling and proposes a more robust approach compatible with complex execution scenarios.
+
+## Context
+
+Tasks in Agentic represent discrete units of work executed by agents. The initial design considered raising exceptions when task execution fails, which presents several challenges:
+
+- **Orchestration Complexity**: In multi-step or parallel execution scenarios, exceptions disrupt the entire orchestration flow
+- **Recovery Difficulty**: Exception-based approaches complicate retry mechanisms and graceful degradation
+- **Workflow Continuity**: Dependent tasks may be able to proceed with partial results or alternative paths
+- **Failure Analysis**: Immediate exception propagation may limit comprehensive failure tracking and analysis
+
+## Design Decision
+
+### Result-Oriented Failure Handling
+
+Rather than raising exceptions, task execution will use a result-oriented approach:
+
+1. **Task Result Object**: Introduce a TaskResult class to encapsulate execution outcomes
+2. **Status-Based Flow Control**: Use task status to indicate completion state
+3. **Error Preservation**: Store error details in the task object itself
+4. **Observable Failure**: Implement event-based notification for status changes
+
+### TaskResult Structure
+
+```ruby
+class TaskResult
+  attr_reader :success, :output, :error, :task_id
+  
+  def initialize(task_id:, success:, output: nil, error: nil)
+    @task_id = task_id
+    @success = success
+    @output = output
+    @error = error
+  end
+  
+  def successful?
+    @success
+  end
+  
+  def failed?
+    !@success
+  end
+end
+```
+
+### Task Status Lifecycle
+
+```
+  ┌─────────┐     ┌─────────────┐     ┌───────────┐
+  │ pending ├────►│ in_progress ├────►│ completed │
+  └─────────┘     └──────┬──────┘     └───────────┘
+                         │
+                         ▼
+                    ┌─────────┐      ┌──────────┐
+                    │ failed  ├─────►│ retrying │
+                    └─────┬───┘      └───┬──────┘
+                          │              │
+                          └──────────────┘
+```
+
+### Task Error Representation
+
+```ruby
+class TaskError
+  attr_reader :message, :type, :timestamp, :context
+  
+  def initialize(message:, type:, context: {})
+    @message = message
+    @type = type
+    @timestamp = Time.now
+    @context = context
+  end
+  
+  def to_h
+    {
+      message: @message,
+      type: @type,
+      timestamp: @timestamp.iso8601,
+      context: @context
+    }
+  end
+end
+```
+
+### Observable Failure Pattern
+
+```ruby
+module TaskObservable
+  def add_observer(observer)
+    @observers ||= []
+    @observers << observer
+  end
+  
+  def notify_status_change(old_status, new_status)
+    return unless @observers
+    
+    @observers.each do |observer|
+      observer.on_task_status_change(self, old_status, new_status)
+    end
+  end
+end
+```
+
+## Implementation Details
+
+### Task Class Modifications
+
+```ruby
+class Task
+  include TaskObservable
+  
+  attr_reader :id, :description, :agent_spec, :input, :output, :status, :error
+  
+  # ... existing initialization ...
+  
+  def perform(agent)
+    old_status = @status
+    @status = :in_progress
+    notify_status_change(old_status, @status)
+    
+    begin
+      @output = agent.execute(build_prompt)
+      old_status = @status
+      @status = :completed
+      notify_status_change(old_status, @status)
+      
+      TaskResult.new(
+        task_id: @id,
+        success: true,
+        output: @output
+      )
+    rescue StandardError => e
+      @error = TaskError.new(
+        message: e.message,
+        type: e.class.name,
+        context: {
+          backtrace: e.backtrace&.first(10),
+          agent_id: agent.id
+        }
+      )
+      
+      old_status = @status
+      @status = :failed
+      notify_status_change(old_status, @status)
+      
+      Agentic.logger.error("Task execution failed: #{e.message}")
+      
+      TaskResult.new(
+        task_id: @id,
+        success: false,
+        error: @error
+      )
+    end
+  end
+  
+  def retry(agent)
+    return unless @status == :failed
+    
+    old_status = @status
+    @status = :retrying
+    notify_status_change(old_status, @status)
+    
+    perform(agent)
+  end
+  
+  # ... other methods ...
+end
+```
+
+### PlanOrchestrator Usage
+
+```ruby
+class PlanOrchestrator
+  def execute_task(task, agent)
+    result = task.perform(agent)
+    
+    if result.successful?
+      # Process successful outcome
+      process_output(task, result.output)
+    else
+      # Handle failure based on policy
+      handle_task_failure(task, result.error)
+    end
+    
+    result
+  end
+  
+  def handle_task_failure(task, error)
+    case error.type
+    when "TimeoutError"
+      # Maybe retry with longer timeout
+      retry_with_extended_timeout(task)
+    when "AuthenticationError"
+      # Maybe request new credentials
+      request_authentication_update(task)
+    else
+      # Apply general failure policy
+      apply_failure_policy(task)
+    end
+  end
+  
+  # ... other methods ...
+end
+```
+
+## Failure Handling Strategies
+
+### Retry with Backoff
+
+For transient failures, implement exponential backoff:
+
+```ruby
+def retry_with_backoff(task, agent, max_attempts = 3)
+  attempts = 0
+  
+  while attempts < max_attempts
+    sleep_duration = 2 ** attempts
+    sleep(sleep_duration)
+    
+    attempts += 1
+    result = task.retry(agent)
+    
+    return result if result.successful?
+  end
+  
+  # Max retries exceeded
+  TaskResult.new(
+    task_id: task.id,
+    success: false,
+    error: TaskError.new(
+      message: "Max retry attempts exceeded",
+      type: "MaxRetriesExceededError",
+      context: { attempts: attempts }
+    )
+  )
+end
+```
+
+### Alternative Task Path
+
+When a task fails, try an alternative approach:
+
+```ruby
+def execute_with_fallback(primary_task, fallback_task, agent)
+  result = primary_task.perform(agent)
+  
+  if result.successful?
+    return result
+  end
+  
+  # Try fallback task instead
+  fallback_result = fallback_task.perform(agent)
+  
+  # Record relationship between tasks
+  primary_task.add_related_task(fallback_task.id, "fallback")
+  
+  fallback_result
+end
+```
+
+### Human Intervention
+
+For critical failures, request human assistance:
+
+```ruby
+def request_human_intervention(task, error)
+  intervention_request = HumanInterventionRequest.new(
+    task_id: task.id,
+    error: error,
+    suggested_actions: generate_intervention_suggestions(error),
+    priority: calculate_intervention_priority(task, error)
+  )
+  
+  InterventionPortal.instance.submit(intervention_request)
+  
+  # Return a pending result while waiting for human input
+  TaskResult.new(
+    task_id: task.id,
+    success: false,
+    error: TaskError.new(
+      message: "Awaiting human intervention",
+      type: "HumanInterventionRequiredError",
+      context: { intervention_id: intervention_request.id }
+    )
+  )
+end
+```
+
+## Benefits of This Approach
+
+1. **Enhanced Resilience**: System continues functioning despite individual task failures
+2. **Execution Flexibility**: Supports parallel, sequential, and conditional execution patterns
+3. **Better Diagnostics**: Comprehensive error context enables more effective debugging
+4. **Adaptable Recovery**: Multiple recovery strategies can be applied based on failure context
+5. **Operational Visibility**: Failure patterns can be analyzed across executions
+6. **Status Observability**: Other components can react to status changes through the observer pattern
+
+## Drawbacks and Mitigations
+
+1. **Increased Complexity**: More complex than simple exceptions
+   - Mitigation: Provide helper methods and clear documentation
+
+2. **Error Propagation**: May mask serious errors that should halt execution
+   - Mitigation: Include critical error classification with different handling
+
+3. **Memory Usage**: Storing error details consumes more memory
+   - Mitigation: Implement configurable error detail retention policies
+
+## Integration with Other Components
+
+### Verification Layer
+
+Task failure information feeds into verification:
+
+```ruby
+def verify_with_failure_awareness(task)
+  # Include failure history in verification context
+  verification_context = {
+    failure_history: task.failure_history,
+    current_error: task.error
+  }
+  
+  VerificationHub.instance.verify(task, verification_context)
+end
+```
+
+### Learning System
+
+Failures contribute to system learning:
+
+```ruby
+def record_failure_patterns(task, error)
+  ExecutionHistoryStore.instance.record_failure(
+    task_type: task.type,
+    error_type: error.type,
+    context: error.context,
+    resolution_strategy: task.resolution_strategy
+  )
+  
+  # Analyze failure patterns periodically
+  PatternRecognizer.instance.analyze_failures if should_analyze_patterns?
+end
+```
+
+## Conclusion
+
+This result-oriented approach to task failure handling offers significant advantages over exception-based designs, particularly for complex orchestration scenarios. It enables more resilient execution flows, flexible recovery strategies, and comprehensive failure analysis while maintaining system stability.
+
+By storing error information within the task and using status-based flow control, the system can better handle parallel execution, support sophisticated retry mechanisms, and provide rich diagnostics for both automated and human-assisted recovery.