agentic 0.1.0 → 0.2.0

data/README.md

@@ -1,64 +1,618 @@
 # Agentic
 
-A simple Ruby command-line tool to build and run AI Agents in a [plan-and-execute](https://blog.langchain.dev/planning-agents/#plan-and-execute) fashion.
+A Ruby gem for building and running AI agents in a [plan-and-execute](https://blog.langchain.dev/planning-agents/#plan-and-execute) fashion. Agentic provides a simple command-line tool and library to build, manage, deploy, and run purpose-driven AI agents using OpenAI's LLM API.
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add agentic
+```bash
+$ bundle add agentic
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install agentic
+```bash
+$ gem install agentic
+```
 
-# Agentic
+## Usage
 
-A simple Ruby command-line tool to build and run AI Agents in a [plan-and-execute](https://blog.langchain.dev/planning-agents/#plan-and-execute) fashion.
+### Command-Line Interface
 
-## Installation
+Agentic comes with a rich command-line interface featuring colored output, spinners for long-running tasks, and progress tracking:
 
-Install the gem and add to the application's Gemfile by executing:
+```bash
+# Display version information
+$ agentic version
 
-    $ bundle add agentic
+# Configuration Management
+$ agentic config init                               # Initialize configuration
+$ agentic config init --global                      # Initialize global configuration
+$ agentic config list                               # List all configuration settings
+$ agentic config get model                          # Get a specific configuration value
+$ agentic config set api_token=your_openai_api_key  # Set your OpenAI API token
+$ agentic config set model=gpt-4o-mini             # Configure the default model
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+# Plan Creation and Execution
+$ agentic plan "Generate a market research report on AI trends"          # Create a plan
+$ agentic plan "Write a blog post about Ruby" --save plan.json           # Save plan to file
+$ agentic plan "Research quantum computing" --output json                # Output in JSON format
+$ agentic plan "Analyze market trends" --model gpt-4o                    # Use a specific model
 
-    $ gem install agentic
+$ agentic execute --plan plan.json                  # Execute a saved plan
+$ agentic execute --async                           # Execute tasks asynchronously
+$ agentic execute --max-concurrency 5               # Limit concurrent tasks
 
-## Usage
+# Agent Management
+$ agentic agent list                                # List available agents
+$ agentic agent create "ResearchAgent" \            # Create a new agent
+    --role="Research Assistant" \
+    --purpose="Conduct thorough research" \
+    --capabilities=text_generation,web_search
+$ agentic agent show "ResearchAgent"                # Show agent details
+$ agentic agent build "ResearchAgent"               # Build an agent from storage
 
-To use the TaskPlanner:
+# Capability Management
+$ agentic capabilities list                         # List available capabilities
+$ agentic capabilities show text_generation         # Show capability details
+$ agentic capabilities search generation            # Search for capabilities
+```
 
-1. Require the gem:
-   ```ruby
-   require 'agentic'
+The CLI provides real-time feedback with spinners for long-running operations, colored status updates, and detailed progress tracking. It supports both global and project-specific configuration, allowing you to customize the behavior for different projects.
+
+### Programmatic API
+
+To use Agentic in your Ruby code:
+
+#### Basic Usage
+
+```ruby
+require 'agentic'
+
+# Configure your OpenAI API key
+Agentic.configure do |config|
+  config.access_token = 'your_openai_api_key'
+end
+
+# Create a TaskPlanner instance with a goal
+planner = Agentic::TaskPlanner.new("Write a blog post about Ruby on Rails")
+
+# Generate the plan
+plan = planner.plan
+
+# Display the plan
+puts plan.to_s
+
+# Or access the structured data
+plan.tasks.each do |task|
+  puts "Task: #{task.description}"
+  puts "Agent: #{task.agent.name}"
+end
+```
+
+#### Working with Agents
+
+```ruby
+# Create an agent with specific configuration
+agent = Agentic::Agent.build do |a|
+  a.name = "ResearchAgent"
+  a.role = "Research Assistant"
+  a.instructions = "Conduct thorough research on the given topic"
+end
+
+# Configure the LLM
+config = Agentic::LlmConfig.new(
+  model: "gpt-4o-mini",
+  temperature: 0.7
+)
+
+# Create a task
+task = Agentic::Task.new(
+  description: "Research the latest trends in Ruby on Rails",
+  agent_spec: {
+    "name" => "ResearchAgent",
+    "description" => "An agent that performs research",
+    "instructions" => "Research the given topic thoroughly"
+  }
+)
+
+# Execute the task with the agent
+result = task.perform(agent)
+
+# Check the result
+if result.successful?
+  puts "Task completed successfully!"
+  puts result.output
+else
+  puts "Task failed: #{result.failure.message}"
+end
+```
+
+#### Plan Orchestration
+
+```ruby
+# Create an orchestrator
+orchestrator = Agentic::PlanOrchestrator.new(
+  concurrency_limit: 5,
+  continue_on_failure: true
+)
+
+# Add tasks to the orchestrator
+tasks.each do |task|
+  orchestrator.add_task(task)
+end
+
+# Create an agent provider
+agent_provider = Agentic::DefaultAgentProvider.new
+
+# Execute the plan
+result = orchestrator.execute_plan(agent_provider)
+
+# Process the results
+if result.successful?
+  puts "Plan executed successfully!"
+else
+  puts "Plan execution had issues: #{result.status}"
+  result.results.each do |task_id, task_result|
+    if task_result.failed?
+      puts "Task #{task_id} failed: #{task_result.failure.message}"
+    end
+  end
+end
+```
+
+## Extension System
+
+Agentic includes a powerful Extension System to help integrate with external systems and customize the framework's behavior. The Extension System consists of three main components:
+
+### Domain Adapters
+
+Domain Adapters let you customize Agentic's behavior for specific domains like healthcare, finance, or legal:
+
+```ruby
+# Create a domain adapter for healthcare
+adapter = Agentic::Extension.domain_adapter("healthcare")
+
+# Add domain-specific knowledge
+adapter.add_knowledge(:terminology, {
+  terms: ["patient", "diagnosis", "treatment"],
+  specialty: "cardiology"
+})
+
+# Create a custom prompt adapter
+prompt_adapter = ->(prompt, context) {
+  specialty = context[:domain_knowledge][:terminology][:specialty]
+  "#{prompt} [Adapted for #{context[:domain]} #{specialty}]"
+}
+
+# Register the adapter
+adapter.register_adapter(:prompt, prompt_adapter)
+
+# Apply adaptation to a prompt
+adapted_prompt = adapter.adapt(:prompt, "Describe the symptoms")
+# => "Describe the symptoms [Adapted for healthcare cardiology]"
+```
+
+### Protocol Handlers
+
+Protocol Handlers standardize connections to external systems and APIs:
+
+```ruby
+# Get the protocol handler
+handler = Agentic::Extension.protocol_handler(
+  default_headers: { "User-Agent" => "AgenticApp/1.0" }
+)
+
+# Create and register a protocol implementation
+http_protocol = Object.new
+def http_protocol.send_request(endpoint, options)
+  # Implement HTTP request logic
+  { status: 200, body: "Response data" }
+end
+
+# Register the protocol
+handler.register_protocol(:http, http_protocol, { timeout: 30 })
+
+# Send a request
+response = handler.send_request(:http, "/api/data", {
+  method: "GET",
+  headers: { "Accept" => "application/json" }
+})
+```
+
+### Plugin Manager
+
+The Plugin Manager handles third-party extensions and their lifecycle:
+
+```ruby
+# Get the plugin manager
+manager = Agentic::Extension.plugin_manager
+
+# Register a plugin
+plugin = MyPlugin.new
+manager.register("my_plugin", plugin, { version: "1.0.0" })
+
+# Get and use a plugin
+if plugin = manager.get("my_plugin")
+  result = plugin.call(arg1, arg2)
+end
+
+# Disable a plugin
+manager.disable("my_plugin")
+```
+
+## Agent Specification and Task Definition
+
+Agentic provides structured representations for agents and tasks through several key value objects:
+
+### Agent Specification
+
+The AgentSpecification defines the requirements for an agent:
+
+```ruby
+# Create an agent specification
+agent_spec = Agentic::AgentSpecification.new(
+  name: "ResearchAgent",
+  description: "An agent that performs research",
+  instructions: "Research the given topic thoroughly"
+)
+
+# Convert to a hash representation
+hash = agent_spec.to_h
+
+# Create from a hash representation
+agent_spec_from_hash = Agentic::AgentSpecification.from_hash(hash)
+```
+
+### Task Definition
+
+The TaskDefinition defines a task to be performed by an agent:
+
+```ruby
+# Create a task definition
+task_def = Agentic::TaskDefinition.new(
+  description: "Research AI trends",
+  agent: agent_spec
+)
+
+# Convert to a hash representation
+hash = task_def.to_h
+
+# Create from a hash representation
+task_def_from_hash = Agentic::TaskDefinition.from_hash(hash)
+```
+
+### Execution Plan
+
+The ExecutionPlan represents a plan with tasks and expected answer format:
+
+```ruby
+# Create an expected answer format
+expected_answer = Agentic::ExpectedAnswerFormat.new(
+  format: "PDF",
+  sections: ["Summary", "Trends", "Conclusion"],
+  length: "10 pages"
+)
+
+# Create an execution plan
+plan = Agentic::ExecutionPlan.new([task_def], expected_answer)
+
+# Convert to a formatted string
+puts plan.to_s
+
+# Convert to a hash representation
+hash = plan.to_h
+```
+
+### Agent Configuration
+
+The AgentConfig provides a configuration object for agents:
+
+```ruby
+# Create an agent configuration
+config = Agentic::AgentConfig.new(
+  name: "ResearchAgent",
+  role: "Research Assistant",
+  backstory: "You are an expert researcher with decades of experience",
+  tools: ["web_search", "document_processor"],
+  llm_config: Agentic::LlmConfig.new(model: "gpt-4o-mini")
+)
+
+# Access configuration properties
+puts config.name
+puts config.role
+
+# Convert to a hash representation
+hash = config.to_h
+```
+
+## Agent Capabilities System
+
+Agentic features a powerful Capability System that enables dynamic agent composition, self-assembly, and persistence. The system allows agents to be constructed with precisely the capabilities they need for specific tasks, and to be stored for future reuse.
+
+### Capability Registry
+
+The capability registry manages capability specifications and providers:
+
+```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 the capability with the system
+Agentic.register_capability(text_gen_capability, text_gen_provider)
+```
+
+### Agent Assembly Engine
+
+The assembly engine dynamically constructs agents based on task requirements:
+
+```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)
+
+# The agent will automatically have capabilities like "text_generation"
+# based on the task requirements
+```
+
+### Agent Persistence
+
+Agents can be stored and retrieved for future use:
+
+```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 Composition
+
+Capabilities can be composed into higher-level capabilities:
+
+```ruby
+registry = Agentic.agent_capability_registry
+
+# Compose multiple capabilities into a new one
+registry.compose(
+  "comprehensive_report",
+  "Generates a comprehensive report with research and formatting",
+  "1.0.0",
+  [
+    { name: "text_generation", version: "1.0.0" },
+    { name: "data_analysis", version: "1.0.0" }
+  ],
+  ->(providers, inputs) {
+    # Implementation that uses both capabilities
+    analysis = providers[1].execute(data: inputs[:data])
+    report = providers[0].execute(prompt: "Generate a report on: #{analysis[:summary]}")
+    { report: report[:response], analysis: analysis }
+  }
+)
+
+# Use the composed capability
+agent.add_capability("comprehensive_report")
+result = agent.execute_capability("comprehensive_report", { data: { ... } })
+```
+
+## Learning System
+
+Agentic features a Learning System that enables agents to improve over time by capturing execution metrics, recognizing patterns, and optimizing strategies. The Learning System consists of three main components:
+
+### Execution History Store
+
+The ExecutionHistoryStore captures and stores execution metrics and performance data:
+
+```ruby
+# Create a history store
+history_store = Agentic::Learning::ExecutionHistoryStore.new(
+  storage_path: "~/.agentic/history",
+  anonymize: true,
+  retention_days: 30
+)
+
+# Record task execution metrics
+history_store.record_execution(
+  task_id: "task-123",
+  agent_type: "research_agent",
+  duration_ms: 1500,
+  success: true,
+  metrics: { tokens_used: 2000, quality_score: 0.85 }
+)
+
+# Query execution history
+research_tasks = history_store.get_history(agent_type: "research_agent", success: true)
+
+# Calculate metrics
+avg_tokens = history_store.get_metric(:tokens_used, { agent_type: "research_agent" }, :avg)
+```
+
+### Pattern Recognizer
+
+The PatternRecognizer analyzes execution history to identify patterns and optimization opportunities:
+
+```ruby
+# Create a pattern recognizer
+recognizer = Agentic::Learning::PatternRecognizer.new(
+  history_store: history_store,
+  min_sample_size: 10
+)
+
+# Analyze agent performance
+patterns = recognizer.analyze_agent_performance("research_agent")
+
+# Analyze correlations between properties
+correlation = recognizer.analyze_correlation(:duration_ms, :tokens_used)
+
+# Get optimization recommendations
+recommendations = recognizer.recommend_optimizations("research_agent")
+```
+
+### Strategy Optimizer
+
+The StrategyOptimizer generates improvements for prompts, parameters, and task sequences:
+
+```ruby
+# Create a strategy optimizer
+optimizer = Agentic::Learning::StrategyOptimizer.new(
+  pattern_recognizer: recognizer,
+  history_store: history_store,
+  llm_client: llm_client # Optional, for LLM-enhanced optimizations
+)
+
+# Optimize a prompt template
+improved_prompt = optimizer.optimize_prompt_template(
+  "Research the topic: {topic}",
+  "research_agent"
+)
+
+# Optimize LLM parameters
+improved_params = optimizer.optimize_llm_parameters(
+  { temperature: 0.7, max_tokens: 2000 },
+  "research_agent",
+  optimization_strategy: :balanced
+)
+
+# Generate performance report
+report = optimizer.generate_performance_report("research_agent")
+```
+
+### Integrating with Plan Orchestrator
+
+The Learning System can be automatically integrated with the PlanOrchestrator:
+
+```ruby
+# Create the learning system
+learning_system = Agentic::Learning.create(
+  storage_path: "~/.agentic/history",
+  llm_client: llm_client,
+  auto_optimize: false
+)
+
+# Create a plan orchestrator
+orchestrator = Agentic::PlanOrchestrator.new
+
+# Register the learning system with the orchestrator
+Agentic::Learning.register_with_orchestrator(orchestrator, learning_system)
+
+# The orchestrator will now automatically record execution metrics
+```
+
+## Configuration
+
+### Setting up the OpenAI API Key
+
+You can configure the OpenAI API key in several ways:
+
+1. Environment variable:
+   ```bash
+   export OPENAI_ACCESS_TOKEN="your_api_key"
+   ```
+
+2. Configuration file:
+   Create `.agentic.yml` in your project directory or home directory:
+   ```yaml
+   api_token: "your_api_key"
+   model: "gpt-4o-mini"
    ```
 
-2. Configure your OpenAI API key:
+3. In your Ruby code:
    ```ruby
    Agentic.configure do |config|
-     config.access_token = 'your_openai_api_key'
+     config.access_token = "your_api_key"
    end
    ```
 
-3. Create a TaskPlanner instance with a goal:
-   ```ruby
-   planner = Agentic::TaskPlanner.new("Write a blog post about Ruby on Rails")
-   ```
+### LLM Configuration
 
-4. Generate and display the plan:
-   ```ruby
-   plan = planner.plan
-   puts plan
-   ```
+You can customize the LLM behavior:
+
+```ruby
+config = Agentic::LlmConfig.new(
+  model: "gpt-4o-mini",
+  max_tokens: 500,
+  temperature: 0.7,
+  top_p: 1.0,
+  frequency_penalty: 0,
+  presence_penalty: 0
+)
+
+# Use in TaskPlanner
+planner = Agentic::TaskPlanner.new("Write a blog post", config)
 
-This will output a structured plan for accomplishing your goal, including tasks and expected output format.
+# Or with LlmClient directly
+client = Agentic::LlmClient.new(config)
+```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Running Tests
+
+Agentic includes a comprehensive test suite with both unit tests and integration tests. To run all tests:
+
+```bash
+rake spec
+```
+
+To run specific test categories:
+
+```bash
+# Run just integration tests
+rspec spec/integration/
+
+# Run a specific integration test file
+rspec spec/integration/plan_orchestrator_integration_spec.rb
+
+# Run with verbose output
+rspec spec/integration/ --format documentation
+```
+
+The integration tests cover real-world scenarios including:
+- Complex orchestration patterns with dependencies
+- Learning system's pattern recognition capabilities
+- Agent specification and task definition interactions
+- Timeout and retry behaviors
+- Error handling in complex scenarios
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
@@ -71,4 +625,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Agentic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/codenamev/agentic/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Agentic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/codenamev/agentic/blob/main/CODE_OF_CONDUCT.md).