agentic 0.1.0 → 0.2.0

data/.architecture/decisions/adrs/ADR-002-system-boundaries.md

@@ -0,0 +1,162 @@
+# ADR-002: Implementation of System Boundaries
+
+## Status
+
+Draft
+
+## Context
+
+The architectural review of version 0.2.0 identified that the boundaries between different subsystems (planning, execution, learning) in the Agentic codebase could be more explicit. Currently, there is direct coupling between these subsystems, which:
+
+1. Makes it difficult to understand the interfaces between major components
+2. Limits the ability to replace or extend individual subsystems
+3. Creates potential for unintended side effects when modifying one subsystem
+4. Increases cognitive load for developers working with the codebase
+5. Makes testing more challenging as subsystems cannot be easily isolated
+
+As the codebase continues to grow, these issues will become more pronounced and limit the system's evolvability.
+
+## Decision Drivers
+
+* Modularity: Enable independent development and evolution of subsystems
+* Comprehensibility: Make system boundaries clear for new developers
+* Testability: Allow subsystems to be tested in isolation
+* Extensibility: Support plugging in alternative implementations for subsystems
+* Maintainability: Reduce coupling between conceptually separate parts of the system
+* Evolution: Enable subsystems to evolve at different rates
+
+## Decision
+
+Implement explicit boundaries between the major subsystems in Agentic by:
+
+1. Defining clear interfaces between the planning, execution, and learning subsystems
+2. Introducing anti-corruption layers where needed to maintain domain consistency
+3. Using dependency inversion to reduce direct coupling
+4. Implementing explicit contracts for cross-subsystem communication
+
+**Architectural Components Affected:**
+* TaskPlanner (interface extraction and implementation)
+* PlanOrchestrator (interface extraction and implementation)
+* Learning system (interface extraction and implementation)
+* Verification system (interface extraction and implementation)
+* Cross-cutting concerns (logging, configuration, error handling)
+
+**Interface Changes:**
+* New interfaces for major subsystems:
+  - IPlanningSystem
+  - IExecutionSystem
+  - ILearningSystem
+  - IVerificationSystem
+* Domain event interfaces for cross-subsystem communication
+* Factory methods for creating subsystem implementations
+
+## Consequences
+
+### Positive
+
+* Clearer system structure with well-defined boundaries
+* Improved ability to work on subsystems independently
+* Better testability through proper isolation
+* Easier to swap implementations for specific subsystems
+* Reduced coupling between conceptually separate parts
+* More deliberate cross-subsystem communication
+
+### Negative
+
+* Additional interfaces increase initial complexity
+* Potential for over-engineering if boundaries are too rigid
+* Initial development overhead to refactor existing code
+* Slight performance overhead from additional abstraction layers
+* Migration challenges for existing code
+
+### Neutral
+
+* Shift in development approach requiring more upfront design
+* Need for documentation about subsystem interactions
+* Potential need for adapter implementations during transition
+
+## Implementation
+
+**Phase 1: Interface Definition**
+* Define interfaces for all major subsystems
+* Document interaction patterns between subsystems
+* Create domain event system for cross-boundary communication
+* Add initial validation tests for interfaces
+
+**Phase 2: Implementation Refactoring**
+* Refactor existing implementations to follow the new interfaces
+* Create anti-corruption layers where needed
+* Update factories to work with interfaces instead of concrete classes
+* Keep backward compatibility through adapter patterns
+
+**Phase 3: Boundary Enforcement**
+* Add static analysis tools to enforce architectural boundaries
+* Create visualizations of subsystem interactions
+* Implement metrics for measuring coupling between subsystems
+* Update documentation with architectural diagrams and guidelines
+
+## Alternatives Considered
+
+### Alternative 1: Looser boundaries with documentation only
+
+**Pros:**
+* Less initial refactoring work
+* More flexibility for cross-subsystem optimizations
+* Less ceremony for developers working across boundaries
+
+**Cons:**
+* Relies on discipline rather than structure
+* Boundaries may erode over time
+* Harder to maintain as the system grows
+* Limited enforcement of architectural intentions
+
+### Alternative 2: Microservice-like boundaries with separate packages
+
+**Pros:**
+* Strongest enforcement of boundaries
+* Maximum independence for subsystem teams
+* Clearest separation of concerns
+* Forces explicit API design
+
+**Cons:**
+* Excessive overhead for a library
+* Potential performance impact from stricter isolation
+* More complex deployment and integration
+* May feel over-engineered for the current scale
+
+### Alternative 3: Boundary enforcement through aspect-oriented programming
+
+**Pros:**
+* Could maintain boundaries without extensive refactoring
+* Potentially more flexible boundary definitions
+* Less invasive to existing code
+
+**Cons:**
+* Adds complexity through AOP mechanisms
+* Less explicit in the code itself
+* Potentially harder to understand for new developers
+* Limited tools in Ruby for this approach
+
+## Validation
+
+**Acceptance Criteria:**
+- [ ] All subsystem interactions occur through defined interfaces
+- [ ] No direct dependencies between implementation classes across subsystems
+- [ ] Each subsystem can be tested in isolation with mocked dependencies
+- [ ] Static analysis tools can verify boundary compliance
+- [ ] Performance overhead is acceptable (<5% in benchmark tests)
+- [ ] Documentation clearly explains subsystem boundaries and interactions
+
+**Testing Approach:**
+* Unit tests for individual subsystems with mocked dependencies
+* Integration tests for subsystem interactions
+* Static analysis to verify boundary compliance
+* Performance benchmarks comparing before and after implementations
+* Documentation review by developers not involved in the implementation
+
+## References
+
+* [Architectural Review 0.2.0](../../../.architecture/reviews/0-2-0.md)
+* [Implementation Roadmap](../../../.architecture/recalibration/implementation_roadmap_0-2-0.md)
+* [Domain-Driven Design concepts](https://www.martinfowler.com/bliki/BoundedContext.html)
+* [Clean Architecture principles](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

data/.architecture/decisions/adrs/ADR-003-content-safety.md

@@ -0,0 +1,158 @@
+# ADR-003: Content Safety Filtering Approach
+
+## Status
+
+Draft
+
+## Context
+
+The architectural review of version 0.2.0 identified that the Agentic gem currently lacks protection against harmful or inappropriate content being generated or requested. As AI agents can potentially generate or be prompted with unsafe content, this poses several risks:
+
+1. Safety risks from generating harmful instructions or content
+2. Reputational risks for users of the library
+3. Potential violations of API provider terms of service
+4. Lack of controls to prevent misuse
+5. Inconsistent handling of unsafe content across the system
+
+As AI capabilities continue to advance, content safety becomes increasingly important for any production AI system.
+
+## Decision Drivers
+
+* Safety: Prevent generation of harmful content and instructions
+* Compliance: Ensure compliance with API provider policies
+* Configurability: Allow users to adapt filtering to their specific needs
+* Performance: Minimize impact on system performance
+* Transparency: Make filtering decisions transparent to users
+* Consistency: Apply safety measures consistently across the system
+
+## Decision
+
+Implement a comprehensive content safety filtering system with:
+
+1. Input filtering before sending to LLMs
+2. Output filtering after receiving LLM responses
+3. Configurable filtering levels and rules
+4. Transparent logging of filtering decisions
+5. Override mechanisms for trusted contexts
+
+**Architectural Components Affected:**
+* LlmClient (modified to apply filtering)
+* ContentSafetyFilter (new component)
+* Agent (modified to apply filtering to instructions)
+* Configuration (extended to include safety settings)
+
+**Interface Changes:**
+* New ContentSafetyFilter class with methods for:
+  - Checking input safety
+  - Checking output safety
+  - Configuring filtering rules
+  - Logging filtering decisions
+* Configuration extensions for safety settings
+
+## Consequences
+
+### Positive
+
+* Reduced risk of generating or processing harmful content
+* Better compliance with API provider policies
+* More control for users over content safety
+* Consistent handling of content safety across the system
+* Transparent safety decisions with appropriate logging
+
+### Negative
+
+* Additional processing overhead for all LLM interactions
+* Potential for false positives blocking legitimate content
+* Complexity of handling edge cases in content filtering
+* Need for regular updates to filtering rules as threats evolve
+
+### Neutral
+
+* Shift in responsibility for content safety to the library
+* Need for documentation about safety capabilities and limitations
+* Potential need for domain-specific customizations
+
+## Implementation
+
+**Phase 1: Basic Filtering**
+* Create ContentSafetyFilter class with basic pattern-based filtering
+* Integrate with LlmClient for input and output filtering
+* Add configuration options for enabling/disabling filtering
+* Implement logging for filtering decisions
+
+**Phase 2: Enhanced Filtering**
+* Add support for different filtering levels (minimal, standard, strict)
+* Implement domain-specific filtering rules
+* Create override mechanisms for trusted contexts
+* Add detection for more subtle safety issues
+
+**Phase 3: Advanced Capabilities**
+* Implement embeddings-based filtering for semantic safety issues
+* Add support for custom filtering rules
+* Create tools for analyzing and improving filtering accuracy
+* Implement content sanitization (as opposed to just blocking)
+
+## Alternatives Considered
+
+### Alternative 1: Rely on API provider safety measures
+
+**Pros:**
+* Less development effort
+* No performance overhead in our library
+* Leverage specialized expertise of API providers
+
+**Cons:**
+* Inconsistent handling across different providers
+* Limited control over filtering behavior
+* No protection for inputs before they reach API providers
+* Potential compliance gaps with some providers
+
+### Alternative 2: Third-party content moderation service
+
+**Pros:**
+* Leverage specialized moderation expertise
+* Regular updates to detection capabilities
+* Potentially higher accuracy than internal solution
+
+**Cons:**
+* External dependency for critical functionality
+* Additional latency from API calls
+* Potential cost implications
+* Privacy concerns with sending data to third parties
+
+### Alternative 3: Client-side responsibility only
+
+**Pros:**
+* Simplicity in library implementation
+* No performance overhead within the library
+* Maximum flexibility for library users
+
+**Cons:**
+* Inconsistent safety measures across implementations
+* Higher burden on library users
+* No protection by default
+* Potential reputation risks if misused
+
+## Validation
+
+**Acceptance Criteria:**
+- [ ] Content filtering can detect common categories of unsafe content
+- [ ] False positive rate is below acceptable threshold (target: <5%)
+- [ ] Performance impact is acceptable (target: <50ms per interaction)
+- [ ] Filtering can be configured at different levels
+- [ ] Override mechanisms work correctly for trusted contexts
+- [ ] Filtering decisions are properly logged
+
+**Testing Approach:**
+* Unit tests with various input patterns including edge cases
+* Performance benchmarks for filtering overhead
+* Integration tests with LlmClient
+* Validation with synthetic (safe) examples of problematic patterns
+* User testing of configuration options
+
+## References
+
+* [Architectural Review 0.2.0](../../../.architecture/reviews/0-2-0.md)
+* [Implementation Roadmap](../../../.architecture/recalibration/implementation_roadmap_0-2-0.md)
+* [OpenAI Moderation API](https://platform.openai.com/docs/guides/moderation)
+* [AI content safety best practices](https://www.responsible.ai/resources/content-safety)

data/.architecture/decisions/adrs/ADR-004-agent-permissions.md

@@ -0,0 +1,161 @@
+# ADR-004: Agent Permission Model
+
+## Status
+
+Draft
+
+## Context
+
+The architectural review of version 0.2.0 identified that the Agentic gem lacks a clear mechanism to restrict what capabilities agents have access to. This presents several challenges:
+
+1. No granular control over agent actions, creating potential security risks
+2. Inability to enforce least-privilege principles for agents
+3. Difficulty implementing role-based agent systems with proper security boundaries
+4. Limited auditing capabilities for agent actions and permissions
+5. No formal way to express agent capability requirements
+
+As AI agents become more powerful and deployed in more sensitive contexts, controlling their capabilities becomes increasingly important for security and compliance.
+
+## Decision Drivers
+
+* Security: Implement principle of least privilege for agents
+* Flexibility: Support diverse permission models for different use cases
+* Usability: Make permission system intuitive for developers
+* Auditability: Enable tracking of permissions and access attempts
+* Performance: Minimize overhead from permission checks
+* Integration: Work seamlessly with existing agent models
+
+## Decision
+
+Implement a comprehensive agent permission system with:
+
+1. Explicit permission definitions with granular capabilities
+2. Permission registry for centralized management
+3. Capability checking at agent execution time
+4. Permission inheritance and composition
+5. Audit logging for permission checks and violations
+
+**Architectural Components Affected:**
+* Agent (modified to include and check permissions)
+* Permission (new component)
+* PermissionRegistry (new component)
+* AgentSpecification (modified to include permission requirements)
+* Task (modified to specify required permissions)
+
+**Interface Changes:**
+* New Permission class to represent individual capabilities
+* PermissionRegistry for managing system permissions
+* Agent interface extensions for capability checking:
+  - `can?(capability_name)` method
+  - `require_capability(capability_name)` method
+* Configuration options for permission management
+
+## Consequences
+
+### Positive
+
+* Improved security through controlled agent capabilities
+* Support for role-based agent authorization
+* Better auditability of agent actions and permissions
+* Clear expression of capability requirements
+* Foundation for more complex security models
+
+### Negative
+
+* Additional complexity in agent configuration
+* Potential friction in development if permissions are too restrictive
+* Performance overhead from permission checking
+* Migration challenges for existing agent implementations
+
+### Neutral
+
+* Shift toward more explicit capability management
+* Need for documentation about permission models
+* Potential need for helper methods to simplify common patterns
+
+## Implementation
+
+**Phase 1: Core Permission Model**
+* Create Permission class for representing capabilities
+* Implement PermissionRegistry for centralized management
+* Extend Agent to support permission checking
+* Add basic audit logging for permission decisions
+
+**Phase 2: Enhanced Permission Features**
+* Implement permission inheritance and composition
+* Create permission sets for common agent roles
+* Add configuration options for permission management
+* Enhance audit logging with more context
+
+**Phase 3: Advanced Security Model**
+* Implement context-sensitive permissions
+* Add dynamic permission granting/revocation
+* Create tools for analyzing permission usage
+* Implement permission-based sandbox execution
+
+## Alternatives Considered
+
+### Alternative 1: Capability-based security model
+
+**Pros:**
+* More object-oriented approach with capabilities as objects
+* Can be more secure with proper unforgeable capabilities
+* More flexible composition of capabilities
+
+**Cons:**
+* More complex implementation
+* Less familiar to most developers
+* Potentially higher performance overhead
+* More challenging to audit centrally
+
+### Alternative 2: Role-based access control only
+
+**Pros:**
+* Simpler implementation
+* More familiar to developers from other systems
+* Easier to reason about at a high level
+* Potentially lower overhead
+
+**Cons:**
+* Less granular control than capability-based approach
+* More rigid permission structure
+* Harder to implement dynamic permissions
+* Less aligned with agent-oriented design
+
+### Alternative 3: Attribute-based access control
+
+**Pros:**
+* More flexible for complex permission scenarios
+* Better support for context-sensitive permissions
+* More expressive permission model
+
+**Cons:**
+* Significantly more complex to implement
+* Higher performance overhead
+* Steeper learning curve for users
+* More difficult to reason about permissions
+
+## Validation
+
+**Acceptance Criteria:**
+- [ ] Agents can be restricted to specific capabilities
+- [ ] Permission checks prevent unauthorized actions
+- [ ] Permissions can be composed and inherited
+- [ ] Permission checks have acceptable performance overhead (<1ms)
+- [ ] Audit logs capture all permission decisions
+- [ ] Permission model integrates with existing agent concepts
+
+**Testing Approach:**
+* Unit tests for permission checks under various scenarios
+* Performance benchmarks for permission overhead
+* Integration tests with agent execution
+* Security-focused tests to verify proper enforcement
+* User testing of permission configuration
+
+## References
+
+* [Architectural Review 0.2.0](../../../.architecture/reviews/0-2-0.md)
+* [Implementation Roadmap](../../../.architecture/recalibration/implementation_roadmap_0-2-0.md)
+* [Principle of Least Privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
+* [Capability-based security](https://en.wikipedia.org/wiki/Capability-based_security)
+* [Role-based access control](https://en.wikipedia.org/wiki/Role-based_access_control)

data/.architecture/decisions/adrs/ADR-005-adaptation-engine.md

@@ -0,0 +1,127 @@
+# Adaptation Engine Design
+
+## Purpose and Scope
+
+The Adaptation Engine component is a core part of the Verification Layer, responsible for implementing feedback-driven adjustments to improve agent and task performance over time. It analyzes task outcomes, verification results, and human feedback to suggest or automatically apply adaptations to various system components.
+
+## Design Principles
+
+1. **Feedback-driven**: All adaptations are based on explicit feedback from execution, verification, or human input
+2. **Component-oriented**: Each system component (agents, tasks, prompts) can have specific adaptation strategies
+3. **Progressive autonomy**: Supports both manual review of suggestions and automatic application of adaptations
+4. **Historical awareness**: Maintains history of adaptations for analysis and continuous improvement
+5. **Threshold-based actions**: Uses confidence scores to determine when adaptation is needed
+
+## Architecture
+
+### Class Structure
+
+The `AdaptationEngine` is designed as a registry of adaptation strategies that can be applied to different components based on feedback:
+
+```ruby
+module Agentic
+  class AdaptationEngine
+    def initialize(options = {})
+      # Configuration settings
+      # Adaptation registry
+      # Feedback history
+    end
+    
+    def register_adaptation_strategy(component, strategy)
+      # Register a callable strategy for a component
+    end
+    
+    def process_feedback(feedback)
+      # Process feedback and determine if adaptation is needed
+    end
+    
+    def apply_adaptation(feedback)
+      # Apply registered strategy to adapt the component
+    end
+    
+    def adaptation_history(component = nil)
+      # Retrieve adaptation history
+    end
+  end
+end
+```
+
+### Interfaces
+
+#### Feedback Format
+
+Feedback is structured as a hash containing:
+- `:component`: Symbol identifying the component (e.g., `:agent`, `:task`, `:prompt`)
+- `:target`: The instance to adapt
+- `:metrics`: Performance metrics (including `:confidence` score)
+- `:outcome`: Success/failure indicator
+- `:suggestion`: Optional suggested improvement
+
+#### Adaptation Strategy Interface
+
+Adaptation strategies are implemented as callables (Procs or lambdas) that:
+1. Accept a feedback hash
+2. Perform adaptation on the target
+3. Return a result hash with adaptation details
+
+### Integration Points
+
+1. **Verification Hub**: Provides feedback based on verification results
+2. **Task Execution**: Reports outcomes for adaptation consideration
+3. **Human Interface**: Allows manual feedback to drive adaptation
+4. **Learning System**: Provides pattern-based suggestions for adaptations
+
+## Key Behaviors
+
+### Adaptation Threshold
+
+The engine uses a configurable threshold to determine when adaptation is needed:
+- Confidence scores below threshold trigger adaptation consideration
+- Threshold can be adjusted based on domain requirements and risk tolerance
+
+### Auto-Adaptation
+
+Two operating modes are supported:
+1. **Manual review**: Adaptations are suggested but require confirmation
+2. **Automatic application**: Adaptations are applied immediately when needed
+
+### Adaptation Registry
+
+Components register specific adaptation strategies:
+- Different strategies for different component types
+- Strategy registration at runtime allows for extensibility
+- Domain-specific strategies can be registered as needed
+
+### History Tracking
+
+All feedback and adaptations are tracked:
+- Provides audit trail of system improvements
+- Enables analysis of adaptation effectiveness
+- Supports learning for future adaptation strategies
+
+## Implementation Considerations
+
+1. **Error Handling**: Adaptations could potentially create regression issues, so robust error handling is essential
+2. **Persistence**: Consider whether adaptation history should be persisted across sessions
+3. **Metrics**: Define standard metrics for measuring adaptation effectiveness
+4. **Strategy Composition**: Allow complex adaptations through composition of simpler strategies
+5. **Validation**: Ensure adaptations maintain system consistency and don't violate constraints
+
+## Future Extensions
+
+1. **Adaptation Chains**: Support sequences of adaptations with dependencies
+2. **Meta-Adaptation**: Adapt the adaptation strategies themselves based on effectiveness
+3. **A/B Testing**: Compare different adaptation strategies for effectiveness
+4. **Domain-Specific Adapters**: Create specialized adaptation libraries for different domains
+5. **Collaborative Adaptation**: Allow multiple agents to contribute to adaptation decisions
+
+## Security and Safety
+
+1. **Adaptation Limits**: Set boundaries on what can be changed through adaptation
+2. **Rollback Capability**: Ability to revert problematic adaptations
+3. **Approval Workflows**: Multi-stage approval for critical adaptations
+4. **Isolation**: Ensure adaptations can't compromise system integrity
+
+## Conclusion
+
+The Adaptation Engine provides a flexible, extensible mechanism for improving system performance through feedback-driven adjustments. By applying targeted adaptations based on execution outcomes, verification results, and human feedback, the system can continuously improve its effectiveness in achieving user goals.