agentic 0.1.0 → 0.2.0

data/.architecture/decisions/adrs/ADR-012-task-output-handling.md

@@ -0,0 +1,205 @@
+# Task Output Handling
+
+## Overview
+
+This document specifies the architecture for handling task outputs within the Agentic framework, addressing how outputs are structured, processed, and utilized across the system.
+
+## Core Principles
+
+1. **Consistency**: Task outputs follow standardized formats for interoperability
+2. **Traceability**: Outputs maintain provenance information
+3. **Transformation**: Outputs can be transformed for different consumers
+4. **Verification**: Outputs include quality and confidence metrics
+5. **Persistence**: Outputs can be stored and retrieved as needed
+
+## Output Structure
+
+Task outputs should adhere to a consistent structure:
+
+```
+{
+  "result": {
+    // Domain-specific output content
+  },
+  "metadata": {
+    "task_id": "uuid",
+    "agent_id": "uuid",
+    "timestamp": "ISO8601",
+    "execution_time_ms": 1234,
+    "token_usage": {
+      "prompt": 123,
+      "completion": 456,
+      "total": 579
+    }
+  },
+  "verification": {
+    "confidence_score": 0.95,
+    "verification_results": [
+      {
+        "verifier": "schema_validation",
+        "passed": true,
+        "score": 1.0
+      },
+      {
+        "verifier": "content_quality",
+        "passed": true,
+        "score": 0.9
+      }
+    ]
+  }
+}
+```
+
+## Output Usage Patterns
+
+### 1. Sequential Task Chaining
+
+Outputs from one task serve as inputs to subsequent tasks, creating a workflow:
+
+```
+TaskA.output → TaskB.input → TaskB.output → TaskC.input
+```
+
+Implementation considerations:
+- Output transformation between tasks may be required
+- Schema validation ensures compatibility
+- Context/state must be preserved across transitions
+- Dependencies between tasks must be tracked
+
+### 2. Result Aggregation
+
+Multiple task outputs are combined to create a comprehensive response:
+
+```
+TaskA.output ─┐
+TaskB.output ─┼─→ Aggregator → Final Result
+TaskC.output ─┘
+```
+
+Implementation considerations:
+- Aggregation strategies vary by domain
+- Conflict resolution may be required
+- Quality metrics should influence weighting
+- Provenance must be maintained
+
+### 3. Verification Process
+
+Outputs undergo verification to ensure quality and correctness:
+
+```
+Task.output → Verification Hub → Verification Strategies → Confidence Score
+```
+
+Implementation considerations:
+- Multiple verification strategies applied in parallel
+- Weighted scoring based on strategy importance
+- Threshold-based decision making
+- Human intervention triggers based on confidence
+
+### 4. Learning System Integration
+
+Historical task outputs feed back into the learning system:
+
+```
+Task.output → ExecutionHistoryStore → PatternRecognizer → Strategy Optimization
+```
+
+Implementation considerations:
+- Anonymization of sensitive data
+- Performance correlation analysis
+- Success/failure pattern detection
+- Agent selection improvement
+
+### 5. External Integration
+
+Task outputs are transformed for external systems consumption:
+
+```
+Task.output → OutputTransformer → External API/UI/Database
+```
+
+Implementation considerations:
+- Format conversion for different consumers
+- Security and privacy filtering
+- Rate limiting and batching
+- Logging and auditing
+
+### 6. Feedback Loop
+
+Task outputs inform plan adaptation and refinement:
+
+```
+Task.output → AdaptationEngine → Plan Modification → New Tasks
+```
+
+Implementation considerations:
+- Detect needed refinements based on output quality
+- Generate additional tasks to improve results
+- Modify agent selection based on performance
+- Adjust expectations for downstream tasks
+
+## Component Responsibilities
+
+### Task Class
+
+- Generate structured output format
+- Track output provenance
+- Provide serialization support
+- Maintain output history (for retries)
+
+### PlanOrchestrator
+
+- Manage task output routing
+- Handle output transformations between tasks
+- Track overall plan output state
+- Aggregate results as appropriate
+
+### VerificationHub
+
+- Apply verification strategies to outputs
+- Calculate confidence scores
+- Trigger human intervention when needed
+- Add verification metadata to outputs
+
+### OutputTransformer (New Component)
+
+- Convert outputs between formats
+- Apply domain-specific transformations
+- Filter sensitive information
+- Optimize for target consumers
+
+### ExecutionHistoryStore
+
+- Persist task outputs with context
+- Index outputs for efficient retrieval
+- Support anonymization for learning
+- Provide query interface for pattern recognition
+
+## Implementation Approach
+
+1. **Start Small**: Begin with a basic structured output format
+2. **Add Metadata**: Incorporate execution metrics and provenance
+3. **Implement Verification**: Add verification results and confidence
+4. **Enable Transformation**: Create output transformation capabilities
+5. **Support Persistence**: Add storage and retrieval functionality
+
+## Development Priorities
+
+1. Define the output schema interface
+2. Implement basic output generation in Task
+3. Create output transformation utilities
+4. Develop verification integration
+5. Implement persistence layer
+6. Add learning system integration
+
+## Considerations for Future Extensions
+
+1. **Schema Evolution**: Support versioning of output schemas
+2. **Real-time Streaming**: Enable streaming outputs for long-running tasks
+3. **Compression**: Handle large outputs efficiently
+4. **Encryption**: Protect sensitive output data
+5. **Distributed Storage**: Scale output handling across environments
+
+## Conclusion
+
+A well-designed task output handling system is critical for the Agentic framework's effectiveness. By standardizing output formats, enabling various usage patterns, and supporting verification and learning, the system can deliver consistent, high-quality results while continuously improving over time.

data/.architecture/decisions/adrs/ADR-013-architecture-alignment.md

@@ -0,0 +1,211 @@
+# Architecture Alignment Analysis
+
+## Overview
+
+This document reviews all architectural documentation created for the Agentic framework to ensure alignment, cohesiveness, and focus on core goals. It identifies strengths, gaps, and recommendations for maintaining a unified architectural vision.
+
+## Document Inventory
+
+1. **ArchitectureConsiderations.md**: Core architectural vision and system layers
+2. **ArchitecturalFeatureBuilder.md**: Implementation guidelines for features
+3. **Task Output Handling**: Detailed architecture for task output processing
+4. **Task Input Handling**: Detailed architecture for task input processing
+5. **Prompt Generation**: Architecture for generating prompts
+6. **Self-Implementation Exercise**: Meta-exercise using Agentic to build itself
+
+## Core Goals Alignment
+
+All documentation consistently supports these core goals:
+
+1. **Domain Agnosticism**: Every document emphasizes building a framework that works across domains
+2. **Self-Improvement**: Learning capabilities are consistently included throughout
+3. **Extensibility**: Well-defined extension points appear in all documents
+4. **Verification**: Quality assurance is integrated at every level
+5. **Human Oversight**: Human intervention is carefully considered throughout
+
+## Strengths
+
+1. **Layered Architecture**: Clear separation of concerns across all documents
+2. **Consistent Design Patterns**: Registry, strategy, and observer patterns used consistently
+3. **Interface-First Approach**: All components define clear interfaces
+4. **Comprehensive Coverage**: All major aspects of the system are documented
+5. **Progressive Implementation**: Consistent phased approach to building features
+
+## Alignment Gaps
+
+1. **Terminology Inconsistencies**:
+   - "Feedback Loop" vs "Adaptation Engine" (same concept, different names)
+   - "Task Execution" vs "Task Performance" (same action, different terms)
+   - "Plugin" vs "Extension" (same concept, different terms)
+
+2. **Component Boundaries**:
+   - Some overlap between VerificationHub and AdaptationEngine responsibilities
+   - Unclear boundaries between TaskFactory and PlanOrchestrator
+   - Relationship between MetaLearningSystem and ExecutionHistoryStore needs clarification
+
+3. **Interface Definitions**:
+   - Some interfaces are well-defined (Task, Agent) while others are less detailed (PlanOrchestrator)
+   - Input/output transformation interfaces could be more specific
+
+4. **Implementation Priority**:
+   - Slight differences in implementation ordering between documents
+
+## Recommendations
+
+### 1. Terminology Standardization
+
+Create a glossary of terms to ensure consistency:
+
+| Term | Definition | Used For |
+|------|------------|----------|
+| Task Execution | The process of an agent performing a task | Core behavior of Task class |
+| Adaptation | The process of modifying behavior based on feedback | Functionality of AdaptationEngine |
+| Extension | A component that adds functionality to the system | Third-party additions to system |
+| Plugin | Specific type of extension that follows the plugin API | Extensions that use PluginManager |
+
+### 2. Component Responsibility Clarification
+
+| Component | Primary Responsibility | Secondary Responsibilities | NOT Responsible For |
+|-----------|------------------------|----------------------------|---------------------|
+| Task | Lifecycle management | Input/output handling, prompt building | Execution details, verification logic |
+| VerificationHub | Coordinating verification strategies | Confidence scoring | Adaptation decisions |
+| AdaptationEngine | Modifying plans based on verification | Feedback processing | Verification itself |
+| PlanOrchestrator | Coordinating task execution | Task dependency resolution | Task creation |
+| TaskFactory | Creating task instances | Task validation | Task execution |
+
+### 3. Interface Alignment
+
+Ensure these key interfaces are consistently defined across all documents:
+
+```ruby
+# Agent interface
+class Agent
+  def execute(prompt, context = nil)
+    # Execute and return output
+  end
+  
+  def get_capabilities
+    # Return agent capabilities
+  end
+end
+
+# Task interface
+class Task
+  def perform(agent)
+    # Execute task using agent
+  end
+  
+  def verify(context = nil)
+    # Verify task results
+  end
+  
+  def to_h
+    # Return serializable representation
+  end
+end
+
+# Verification Strategy interface
+module VerificationStrategy
+  def verify(task, context)
+    # Perform verification and return results
+  end
+  
+  def applicable?(task)
+    # Determine if strategy applies to task
+  end
+end
+```
+
+### 4. Implementation Priority Alignment
+
+Standardize the implementation sequence across all documents:
+
+1. Core Task and Agent implementation
+2. Basic input/output handling
+3. Prompt generation
+4. Verification integration
+5. Plan orchestration
+6. Learning system components
+7. Human interface
+8. Extension system
+
+### 5. Data Structure Alignment
+
+Ensure these key data structures are consistently defined:
+
+```ruby
+# Task Input Structure
+{
+  "parameters": { /* Domain-specific parameters */ },
+  "context": {
+    "plan_id": "uuid",
+    "goal": "description",
+    "previous_task_outputs": { /* References */ }
+  },
+  "constraints": { /* Limits and requirements */ },
+  "metadata": { /* Additional information */ }
+}
+
+# Task Output Structure
+{
+  "result": { /* Domain-specific output */ },
+  "metadata": {
+    "task_id": "uuid",
+    "agent_id": "uuid",
+    "timestamp": "ISO8601",
+    /* Additional metadata */
+  },
+  "verification": {
+    "confidence_score": 0.95,
+    "verification_results": [ /* Verification details */ ]
+  }
+}
+
+# Prompt Structure
+{
+  "system_instructions": "...",
+  "task_description": "...",
+  "context": "...",
+  "input_parameters": "...",
+  "output_requirements": "...",
+  "special_instructions": "..."
+}
+```
+
+## Document-Specific Recommendations
+
+### ArchitectureConsiderations.md
+
+- Add references to specialized architecture documents
+- Expand data flow section to include input/output transformation
+- Add component interaction diagrams
+
+### ArchitecturalFeatureBuilder.md
+
+- Add specific examples for each implementation phase
+- Include references to specialized architecture documents
+- Expand testing strategy section
+
+### Task Output/Input Handling
+
+- Align terminology with core architecture document
+- Ensure component responsibilities match overall architecture
+- Add more implementation examples
+
+### Prompt Generation
+
+- Clarify relationship with Task and Agent components
+- Ensure alignment with input handling architecture
+- Add more examples of different prompt types
+
+### Self-Implementation Exercise
+
+- Ensure all components mentioned match the core architecture
+- Align task types with other documentation
+- Add metrics for evaluating success
+
+## Conclusion
+
+The architectural documentation for Agentic forms a comprehensive and largely cohesive vision for the framework. With the standardizations recommended above, it will provide an even stronger foundation for implementation. The documentation effectively balances high-level architectural vision with detailed component design, creating a blueprint for a powerful, extensible, and self-improving agent orchestration framework.
+
+The architecture successfully achieves the core goals of domain agnosticism, extensibility, verification, learning capability, and human oversight, while providing practical guidance for implementation.

data/.architecture/decisions/adrs/ADR-014-agent-capability-registry.md

@@ -0,0 +1,80 @@
+# ADR-014: Agent Capability Registry
+
+## Status
+
+Accepted
+
+## Context
+
+As we develop the Agentic framework, we need a centralized system to manage, discover, and utilize agent capabilities. Capabilities are richer than simple tools, with versioning, dependencies, and composition possibilities. The system must support:
+
+1. Registration of capabilities with semantic versioning
+2. Discovery of capabilities based on name, version, or functionality
+3. Composition of capabilities into higher-order capabilities
+4. Runtime validation of capability inputs and outputs
+5. Management of capability providers (implementations)
+
+Previously, we had a more limited "tool" concept which lacked versioning, composition, and formal interface definitions. We need to evolve this concept while maintaining backward compatibility.
+
+## Decision
+
+We will implement an `AgentCapabilityRegistry` that serves as the central repository for all agent capabilities in the system. The registry will:
+
+1. Be implemented as a singleton to provide global access
+2. Maintain a collection of capability specifications and their providers
+3. Support semantic versioning for capability evolution
+4. Enable capability composition through dependency management
+5. Provide a rich API for capability discovery and filtering
+
+Key classes:
+
+- `CapabilitySpecification`: Defines the interface for a capability
+- `CapabilityProvider`: Implements a capability interface
+- `AgentCapabilityRegistry`: Manages capability specifications and providers
+
+The registry will provide these core operations:
+
+```ruby
+# Registration
+registry.register(specification, provider)
+
+# Discovery
+registry.get(name, version = nil)
+registry.list(filter = {})
+
+# Provider access
+registry.get_provider(name, version = nil)
+
+# Composition
+registry.compose(name, description, version, dependencies, implementation)
+```
+
+## Consequences
+
+### Positive
+
+1. Centralized management of capabilities improves discovery and reuse
+2. Semantic versioning enables capability evolution while maintaining compatibility
+3. Capability composition facilitates building complex capabilities from simpler ones
+4. Formal interface definitions improve capability documentation and usage
+5. Provider abstraction allows multiple implementations of the same capability
+
+### Negative
+
+1. Singleton pattern creates global state that may complicate testing
+2. Centralized registry could become a performance bottleneck at scale
+3. Version management adds complexity compared to simpler approaches
+4. Requires migration from previous tool-based approach
+
+### Neutral
+
+1. Requires agents to adopt capability-aware execution model
+2. Necessitates formal capability specification development
+
+## Implementation Notes
+
+The registry will be implemented as a singleton class with thread-safe operations. Capability specifications will include name, version, description, inputs, outputs, and dependencies. Providers will encapsulate the actual implementation logic.
+
+The registry will maintain an index of capabilities by name and version, allowing efficient lookups. It will also support finding the latest version of a capability when no specific version is requested.
+
+For backward compatibility, existing tools will be automatically wrapped as capabilities with appropriate adapters.

data/.architecture/decisions/adrs/ADR-015-persistent-agent-store.md

@@ -0,0 +1,100 @@
+# ADR-015: Persistent Agent Store
+
+## Status
+
+Accepted
+
+## Context
+
+To enable more efficient agent reuse and evolution, we need a mechanism to persistently store and retrieve agent configurations. This system should support:
+
+1. Storing complete agent configurations, including capabilities
+2. Retrieving agents by ID or name
+3. Versioning agent configurations as they evolve
+4. Filtering and searching for suitable agents based on capabilities or metadata
+5. Tracking agent provenance and usage history
+
+Without a persistent store, agents must be recreated from scratch for each task, even when similar agents have been previously assembled. This leads to inefficiency and missed opportunities for improvement through agent evolution.
+
+## Decision
+
+We will implement a `PersistentAgentStore` class that handles agent storage and retrieval. The store will:
+
+1. Use a file-based storage system with a configurable storage path
+2. Support semantic versioning for agent configurations
+3. Maintain an in-memory index for efficient lookup
+4. Store agent configurations as structured JSON
+5. Support rich filtering and querying capabilities
+
+Key operations:
+
+```ruby
+# Store an agent
+store.store(agent, name: "my_agent", metadata: { category: "research" })
+
+# Build an agent from stored configuration
+store.build_agent("my_agent")  # By name
+store.build_agent(agent_id)    # By ID
+store.build_agent(id, version: "1.2.0")  # Specific version
+
+# List and filter agents
+store.list_all()  # All agents
+store.all(filter: { capability: "web_search" })  # With specific capability
+store.all(filter: { metadata: { category: "research" } })  # With metadata
+
+# Get version history
+store.version_history(agent_id)
+
+# Delete agents
+store.delete(agent_id)
+store.delete(agent_id, version: "1.0.0")  # Specific version
+```
+
+We will use the following design:
+- File-based storage with one directory per agent
+- Each version stored as a separate JSON file
+- An index file for quick lookup without loading all agent files
+- Agent data will include capabilities, metadata, and configuration
+
+## Consequences
+
+### Positive
+
+1. Enables reuse of previously assembled agents for similar tasks
+2. Supports agent evolution through versioning
+3. Provides rich filtering for agent discovery
+4. Maintains complete agent provenance for auditing
+5. Simplifies integration with agent assembly system
+
+### Negative
+
+1. File-based storage has scalability limitations
+2. Limited transactional support compared to databases
+3. Requires additional synchronization in multi-process scenarios
+4. Increases code complexity with versioning logic
+
+### Neutral
+
+1. Requires filesystem access for storage
+2. Creates dependency on JSON serialization format
+3. May require migration strategies for major version changes
+
+## Implementation Notes
+
+The store will create a directory structure like:
+
+```
+storage_path/
+  index.json           # Main index with all agents
+  agent_id_1/
+    1.0.0.json         # First version
+    1.0.1.json         # Second version
+  agent_id_2/
+    1.0.0.json         # First version
+```
+
+The index will contain minimal information for quick lookups, while the full agent configuration will be stored in the version-specific files. The store will automatically rebuild the index if it becomes out of sync with the filesystem.
+
+For thread safety, file operations will use appropriate locking mechanisms. The store will gracefully handle partial or corrupted data through validation and error recovery.
+
+To support multiple storage backends in the future, the implementation will follow a repository pattern with a clear interface for storage operations.