agentic 0.1.0 → 0.2.0

data/.architecture/implementation/agent_self_assembly_implementation.md

@@ -0,0 +1,267 @@
+# Agent Self-Assembly Implementation Summary
+
+## Overview
+
+This document summarizes the implementation of the agent self-assembly system in Agentic v0.2.0. The system enables agents to dynamically configure themselves based on task requirements and persist for future use.
+
+## Core Components
+
+### 1. Agent Capability Registry
+
+**Purpose**: Central repository for capability specifications and providers.
+
+**Key Features**:
+- Registration of capabilities with semantic versioning
+- Discovery of capabilities by name, version, or features
+- Composition of capabilities into higher-order capabilities
+- Provider management and resolution
+
+**Key Classes**:
+- `AgentCapabilityRegistry`: Singleton registry for all capabilities
+- `CapabilitySpecification`: Formal interface definition for capabilities
+- `CapabilityProvider`: Implementation of capability interfaces
+
+**Implementation Highlights**:
+- Singleton pattern with thread-safe operations
+- Version management with semantic versioning support
+- Support for capability composition through dependency resolution
+- Rich filtering API for capability discovery
+
+### 2. Persistent Agent Store
+
+**Purpose**: Stores and retrieves agent configurations persistently.
+
+**Key Features**:
+- Storage of complete agent configurations
+- Versioned agent configurations
+- Rich filtering and querying
+- Name and ID-based lookups
+
+**Key Classes**:
+- `PersistentAgentStore`: Main store implementation
+- Supporting classes for serialization and indexing
+
+**Implementation Highlights**:
+- File-based storage with configurable path
+- In-memory index for efficient lookups
+- Semantic versioning for agent evolution
+- Rich filtering API with multiple criteria
+
+### 3. Agent Assembly Engine
+
+**Purpose**: Analyzes tasks and assembles appropriate agents.
+
+**Key Features**:
+- Task requirement analysis
+- Capability selection via pluggable strategies
+- Agent building with selected capabilities
+- Integration with persistent store
+
+**Key Classes**:
+- `AgentAssemblyEngine`: Main engine implementation
+- `AgentCompositionStrategy`: Base strategy class
+- `DefaultCompositionStrategy`: Default implementation
+- `LlmAssistedCompositionStrategy`: LLM-enhanced implementation
+
+**Implementation Highlights**:
+- Multi-faceted requirement analysis
+- Strategy pattern for capability selection
+- Integration with agent store for reuse
+- Support for LLM-assisted capability selection
+
+### 4. Capability Optimizer
+
+**Purpose**: Improves capability implementations and compositions.
+
+**Key Features**:
+- Performance analysis of capabilities
+- Suggestion generation for improvements
+- Capability composition optimization
+- Integration with learning system
+
+**Key Classes**:
+- `CapabilityOptimizer`: Main optimizer implementation
+- Integration with `PatternRecognizer` and `ExecutionHistoryStore`
+
+**Implementation Highlights**:
+- Performance metric analysis
+- Heuristic and LLM-based optimization approaches
+- Caching system for optimization results
+- Integration with existing learning components
+
+### 5. CLI Integration
+
+**Purpose**: Command-line interface for capability and agent management.
+
+**Key Features**:
+- Listing and filtering capabilities
+- Viewing capability details
+- Searching for capabilities
+- Agent management commands
+
+**Key Classes**:
+- `CLI::Capabilities`: CLI commands for capabilities
+- `CLI::Agent`: Enhanced with capability-aware commands
+
+**Implementation Highlights**:
+- Rich formatting for capability display
+- Support for detailed capability information
+- Search functionality for capability discovery
+- Integration with agent assembly system
+
+## Implementation Details
+
+### Capability Registration
+
+```ruby
+# Define a capability specification
+text_gen_capability = Agentic::CapabilitySpecification.new(
+  name: "text_generation",
+  description: "Generates text based on a prompt",
+  version: "1.0.0",
+  inputs: {
+    prompt: { type: "string", required: true, description: "The prompt to generate text from" }
+  },
+  outputs: {
+    response: { type: "string", description: "The generated text" }
+  }
+)
+
+# Create a provider for the capability
+text_gen_provider = Agentic::CapabilityProvider.new(
+  capability: text_gen_capability,
+  implementation: ->(inputs) { { response: "Generated text for: #{inputs[:prompt]}" } }
+)
+
+# Register with the system
+Agentic.register_capability(text_gen_capability, text_gen_provider)
+```
+
+### Agent Assembly
+
+```ruby
+# Define a task
+task = Agentic::Task.new(
+  description: "Generate a report on AI trends",
+  agent_spec: Agentic::AgentSpecification.new(
+    name: "Report Generator",
+    description: "An agent that generates reports",
+    instructions: "Generate a comprehensive report on the topic"
+  ),
+  input: {
+    topic: "AI trends in 2023",
+    format: "markdown"
+  }
+)
+
+# Assemble an agent for the task
+agent = Agentic.assemble_agent(task, use_llm: true)
+
+# The agent will have capabilities like "text_generation"
+# based on the task requirements
+```
+
+### Agent Persistence
+
+```ruby
+# Store an agent for future use
+agent_id = Agentic.agent_store.store(agent, name: "report_generator")
+
+# Later, retrieve the agent by name
+stored_agent = Agentic.agent_store.build_agent("report_generator")
+
+# Or retrieve by ID
+stored_agent = Agentic.agent_store.build_agent(agent_id)
+
+# List all stored agents
+agents = Agentic.agent_store.all
+```
+
+### Capability Optimization
+
+```ruby
+# Create a capability optimizer
+optimizer = Agentic::Learning::CapabilityOptimizer.new(
+  pattern_recognizer: pattern_recognizer,
+  history_store: history_store,
+  registry: Agentic.agent_capability_registry
+)
+
+# Get optimization suggestions for a capability
+suggestions = optimizer.get_optimization_suggestions("text_generation")
+
+# Optimize capability composition for a task
+optimized = optimizer.optimize_capability_composition(task)
+```
+
+## Integration with Existing Systems
+
+### Learning System Integration
+
+The capability optimizer integrates with the existing learning system:
+- Uses `ExecutionHistoryStore` for performance data
+- Leverages `PatternRecognizer` for insight generation
+- Feeds optimization data back to the learning system
+
+### Agent Integration
+
+Agents have been enhanced to support capabilities:
+- The `Agent` class now has capability management methods
+- Agents can be assembled dynamically based on task requirements
+- Assembled agents can be stored and retrieved from the persistent store
+
+### Task System Integration
+
+The task system has been enhanced to support capability requirements:
+- Tasks can specify required capabilities
+- Task descriptions are analyzed for capability requirements
+- Task inputs can include capability hints
+
+## Testing Strategy
+
+The implementation includes comprehensive testing:
+
+1. **Unit Tests**:
+   - Tests for individual components
+   - Mock-based testing for external dependencies
+   - Edge case coverage
+
+2. **Integration Tests**:
+   - End-to-end workflow testing
+   - Real component interaction
+   - Performance validation
+
+3. **Time-Dependent Testing**:
+   - Uses `Timecop` for time-dependent operations
+   - Avoids actual sleeps for faster tests
+   - Validates versioning operations
+
+## Future Enhancements
+
+Planned enhancements for future versions:
+
+1. **Advanced Requirement Analysis**:
+   - Enhanced NLP for requirement extraction
+   - Learning-based requirement inference
+   - Context-aware capability selection
+
+2. **Alternative Storage Backends**:
+   - Database-backed agent storage
+   - Distributed storage for multi-environment setups
+   - Cloud storage integration
+
+3. **Enhanced Capability Management**:
+   - Capability approval workflows
+   - Capability usage analytics
+   - Capability marketplace concepts
+
+4. **Advanced Optimization**:
+   - Automated capability improvement
+   - A/B testing for capability variants
+   - Performance-based routing
+
+## Conclusion
+
+The agent self-assembly system represents a significant enhancement to the Agentic framework. It enables dynamic agent construction based on task requirements, persistent storage of agent configurations, and ongoing optimization through integration with the learning system.
+
+The implementation follows object-oriented principles, uses appropriate design patterns, and integrates seamlessly with existing systems. The system is designed for extensibility, with pluggable strategies, composable capabilities, and a flexible architecture.

data/.architecture/implementation/agent_self_assembly_summary.md

@@ -0,0 +1,138 @@
+# Agent Self-Assembly Implementation Summary
+
+## Overview
+
+The Agent Self-Assembly system enables agents to dynamically configure themselves based on task requirements and persist their configurations for future use. This implementation represents a significant advancement in the Agentic framework's ability to support adaptive, reusable agent architectures.
+
+## Key Components
+
+1. **Agent Capability Registry**
+   - Central registry for capability discovery and management
+   - Supports semantic versioning and compatibility checking
+   - Enables composition of capabilities into higher-level capabilities
+   - Implemented in `agent_capability_registry.rb`
+
+2. **Capability Specification & Provider**
+   - Clear separation between capability interface (specification) and implementation (provider)
+   - Structured input and output definitions with validation
+   - Explicit dependency declarations
+   - Implemented in `capability_specification.rb` and `capability_provider.rb`
+
+3. **Agent Assembly Engine**
+   - Analyzes task requirements to determine needed capabilities
+   - Selects appropriate capabilities using pluggable strategies
+   - Builds agents with selected capabilities
+   - Integrates with persistent storage for reuse
+   - Implemented in `agent_assembly_engine.rb`
+
+4. **Persistent Agent Store**
+   - Stores and retrieves agent configurations
+   - Supports versioning of agent configurations
+   - Provides filtering and search capabilities
+   - Implements serialization and deserialization of agents
+   - Implemented in `persistent_agent_store.rb`
+
+5. **CLI Integration**
+   - Commands for managing capabilities (`agentic capabilities`)
+   - Commands for managing agents (`agentic agent`)
+   - Interactive feedback on operations
+
+## Design Decisions
+
+1. **Capability vs. Tool Terminology**
+   - Maintained distinction between simple tools and rich capabilities
+   - Capabilities provide richer metadata, versioning, and composition
+   - Tools align with external standards like Model Context Protocol (MCP)
+   - See `capability_tools_distinction.md` for detailed rationale
+
+2. **Semantic Versioning**
+   - Capability versions follow semantic versioning (major.minor.patch)
+   - Compatibility checking based on major version match and minor version >=
+   - Ensures predictable behavior when combining capabilities
+
+3. **Composition Model**
+   - Capabilities can be composed into higher-level capabilities
+   - Explicit dependency declarations prevent missing dependencies
+   - Composition function handles integration of individual capabilities
+
+4. **Storage Strategy**
+   - File-based storage for agent configurations
+   - Indexed for fast retrieval
+   - Versioning support for tracking agent evolution
+   - Metadata for searchability and filtering
+
+5. **Strategy Pattern**
+   - Pluggable strategies for capability selection
+   - Default strategy based on requirement importance and explicit mentions
+   - Support for LLM-assisted capability selection (planned)
+   - Easy to extend with domain-specific strategies
+
+## Implementation Details
+
+### Core Abstractions
+
+- **CapabilitySpecification**: Defines the interface of a capability
+- **CapabilityProvider**: Implements the functionality of a capability
+- **AgentCapabilityRegistry**: Manages registration and discovery of capabilities
+- **AgentAssemblyEngine**: Analyzes tasks and assembles appropriate agents
+- **PersistentAgentStore**: Handles storage and retrieval of agent configurations
+- **AgentCompositionStrategy**: Interface for capability selection strategies
+
+### Key Workflows
+
+1. **Capability Registration**
+   - Define a capability specification with interface details
+   - Create a provider with implementation logic
+   - Register both in the registry
+
+2. **Agent Assembly**
+   - Analyze task requirements
+   - Check for existing suitable agents in storage
+   - If not found, select capabilities based on requirements
+   - Build a new agent with selected capabilities
+   - Optionally store for future reuse
+
+3. **Agent Persistence**
+   - Store agent configurations with metadata
+   - Retrieve agents by ID or name
+   - Build agents from stored configurations
+   - Manage agent versions
+
+## Future Enhancements
+
+1. **LLM-Assisted Capability Selection**
+   - Use LLMs to analyze task requirements more intelligently
+   - Implement more sophisticated matching algorithms
+
+2. **Learning Integration**
+   - Track performance of capabilities and assembled agents
+   - Optimize selection strategies based on historical performance
+   - Suggest capability improvements based on usage patterns
+
+3. **Richer Composition Models**
+   - Support for more complex composition patterns
+   - Pipeline and graph-based capability composition
+   - Runtime adaptation of composition based on execution context
+
+4. **Web-Based Capability Marketplace**
+   - Discover and share capabilities across projects
+   - Rating and review system for capabilities
+   - Versioned capability packages
+
+5. **Extended CLI**
+   - Interactive capability and agent builders
+   - Visualization of capability dependencies
+   - Performance metrics and recommendations
+
+## Documentation
+
+- **ADR-014**: Agent Capability Registry
+- **ADR-015**: Persistent Agent Store
+- **ADR-016**: Agent Assembly Engine
+- **ArchitecturalRecalibration**: Agent Self-Assembly
+- **API Documentation**: `docs/agent_capabilities_api.md`
+- **Terminology Guidance**: `capability_tools_distinction.md`
+
+## Version Impact
+
+This implementation is part of Agentic version 0.2.0, representing a major enhancement to the framework's capabilities for building adaptive, reusable agent architectures.

data/.architecture/members.yml

@@ -0,0 +1,187 @@
+# Architecture Review Members
+# Each member represents a specialized perspective for architectural reviews
+
+members:
+  - id: systems_architect
+    name: "Alex Rivera"
+    title: "Systems Architect"
+    specialties: 
+      - "distributed systems"
+      - "service architecture"
+      - "scalability patterns"
+    disciplines:
+      - "system design"
+      - "infrastructure modeling"
+      - "load distribution"
+    skillsets:
+      - "high-level architecture planning"
+      - "system decomposition"
+      - "technical roadmapping"
+    domains:
+      - "overall system coherence"
+      - "architectural principles"
+      - "technical governance"
+    perspective: "Focuses on how components work together as a cohesive system and analyzes big-picture architectural concerns."
+
+  - id: domain_expert
+    name: "Jamie Chen"
+    title: "AI Agent Domain Expert"
+    specialties:
+      - "agent orchestration patterns"
+      - "task composition and decomposition"
+      - "plan-and-execute paradigms"
+      - "multi-agent coordination"
+    disciplines:
+      - "agent behavior modeling"
+      - "task workflow design"
+      - "capability composition"
+      - "agent interaction patterns"
+    skillsets:
+      - "designing agent communication protocols"
+      - "modeling complex task dependencies"
+      - "defining agent capability boundaries"
+      - "orchestrating autonomous agent behaviors"
+    domains:
+      - "agent lifecycle management"
+      - "task execution semantics"
+      - "inter-agent coordination"
+      - "capability registry design"
+    perspective: "Evaluates how well the architecture serves AI agent orchestration needs, task composition patterns, and agent coordination requirements."
+
+  - id: security_specialist
+    name: "Morgan Taylor"
+    title: "AI Security Specialist"
+    specialties:
+      - "AI system threat modeling"
+      - "LLM security patterns"
+      - "agent execution sandboxing"
+      - "prompt injection prevention"
+    disciplines:
+      - "AI-specific security analysis"
+      - "agent behavior risk assessment"
+      - "LLM vulnerability identification"
+      - "capability access control"
+    skillsets:
+      - "securing AI agent interactions"
+      - "evaluating LLM API security"
+      - "designing safe agent execution environments"
+      - "preventing malicious agent behaviors"
+    domains:
+      - "agent execution security"
+      - "LLM interaction safety"
+      - "capability access control"
+      - "agent communication security"
+    perspective: "Reviews the architecture from an AI security perspective, focusing on agent execution safety, LLM interaction security, and preventing malicious agent behaviors."
+
+  - id: maintainability_expert
+    name: "Sam Rodriguez"
+    title: "Maintainability Expert"
+    specialties:
+      - "code quality"
+      - "refactoring"
+      - "technical debt"
+    disciplines:
+      - "code organization"
+      - "complexity analysis"
+      - "maintainability metrics"
+    skillsets:
+      - "identifying maintenance bottlenecks"
+      - "assessing technical debt"
+      - "simplifying complex structures"
+    domains:
+      - "code maintainability"
+      - "architectural clarity"
+      - "evolutionary design"
+    perspective: "Evaluates how well the architecture facilitates long-term maintenance, evolution, and developer understanding."
+
+  - id: performance_specialist
+    name: "Jordan Lee"
+    title: "AI Performance Specialist"
+    specialties:
+      - "LLM API optimization"
+      - "agent execution efficiency"
+      - "parallel task processing"
+      - "token usage optimization"
+    disciplines:
+      - "AI system performance analysis"
+      - "agent execution bottleneck identification"
+      - "LLM cost optimization"
+      - "concurrent agent coordination"
+    skillsets:
+      - "optimizing LLM API usage patterns"
+      - "designing efficient agent workflows"
+      - "minimizing execution latency"
+      - "balancing cost vs. performance trade-offs"
+    domains:
+      - "agent execution performance"
+      - "LLM API efficiency"
+      - "task orchestration throughput"
+      - "resource utilization optimization"
+    perspective: "Focuses on AI-specific performance implications, including LLM API costs, agent execution efficiency, and optimal resource utilization for agent orchestration."
+    
+  - id: ai_engineer
+    name: "Taylor Kim"
+    title: "Agent Systems Engineer"
+    specialties:
+      - "agentic framework development"
+      - "plan-and-execute architectures"
+      - "agent self-assembly systems"
+      - "capability plugin architectures"
+      - "agent learning and adaptation"
+    disciplines:
+      - "agent framework engineering"
+      - "extensible capability design"
+      - "agent lifecycle management"
+      - "learning system integration"
+      - "plugin architecture development"
+    skillsets:
+      - "building extensible agent frameworks"
+      - "designing capability composition systems"
+      - "implementing agent self-improvement"
+      - "creating robust agent execution environments"
+      - "developing agent observability tools"
+    domains:
+      - "agent framework architecture"
+      - "capability extensibility"
+      - "agent learning systems"
+      - "execution reliability"
+      - "developer experience for agent builders"
+    perspective: "Evaluates the architecture from an agent framework developer's perspective, focusing on extensibility, capability composition, learning integration, and creating robust foundations for agent-based applications."
+
+  - id: ruby_ecosystem_expert
+    name: "Riley Park"
+    title: "Ruby Ecosystem Expert"
+    specialties:
+      - "Ruby gem development"
+      - "Ruby design patterns"
+      - "Rails-style conventions"
+      - "Ruby metaprogramming"
+    disciplines:
+      - "Ruby library architecture"
+      - "gem packaging and distribution"
+      - "Ruby API design"
+      - "testing with RSpec and VCR"
+    skillsets:
+      - "designing idiomatic Ruby APIs"
+      - "implementing Ruby DSLs"
+      - "organizing Ruby gem structure"
+      - "optimizing Ruby performance patterns"
+    domains:
+      - "Ruby gem ecosystem integration"
+      - "developer ergonomics"
+      - "Ruby community standards"
+      - "gem maintenance and evolution"
+    perspective: "Evaluates the architecture from a Ruby ecosystem perspective, ensuring idiomatic Ruby design, proper gem structure, and alignment with Ruby community conventions and best practices."
+
+review_process:
+  individual_phase:
+    description: "Each member reviews the architecture independently, focusing on their area of expertise."
+    deliverable: "Individual member review section in the review document."
+  
+  collaborative_phase:
+    description: "Members confer to discuss findings, resolve conflicting perspectives, and prioritize recommendations."
+    deliverable: "Consolidated findings and balanced recommendations."
+  
+  final_report_phase:
+    description: "Produce a comprehensive architectural review that balances all perspectives."
+    deliverable: "Final architectural review document with actionable recommendations."