activeagent 0.2.3 → 0.2.4.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f659cf9684d31461a83a4ac64084506f2cff11ef3f4c8ea819025a05a0c9f65
-  data.tar.gz: c48520b380b7774bfd910511424dc8cbfddba469c20d2cd74e6f7c2e508515b5
+  metadata.gz: 184241f5e4ba55a57a90127a92fe89893991e6b71afa1338f7f3ac4f321bc0b2
+  data.tar.gz: 268aee27278446080510e914eb826144c7d2e27b2e5707fc86be79c3264441c8
 SHA512:
-  metadata.gz: 92f8faef24f551503ae65a9645b4ec86d5ceee547f6cc0438f2df5e114295fc7a325171bf34172d63d52a37b2486661cc99cd8d4048e7d6225c8220db4c73685
-  data.tar.gz: 19f01fe1bdad7d6a216908a6088b3e66d766582f5ec71e76e8e02557f10c56e7fbbcdfbd9d6bdbffcb4f03fcb4c454ddb532e56ea3fea38a195da8c319a6c01b
+  metadata.gz: bb8cee4ce3dfc23379004df4b5ead15e5de241cad72ddf30f0fda09a70ebd5a07150a9de08581fc5e7b0de7d6cf02e44e097c26ebb054efcecd117989c7787a5
+  data.tar.gz: 59fefa71afbd284233b03ed80a4b86c4b9050f246dd6246d592d5ae5acdeda8d16be5bbc682dc0dbab235605052b878310a5d9ed421735eba20aebd9baf229b8

data/README.md

@@ -1,43 +1,142 @@
-# Active Agent: README.md
-
 # Active Agent
 
-## Agent
+## Install
 
-Create agents that take instructions, prompts, and perform actions
+### Gemfile
+`gem 'activeagent', require: 'active_agent'`
 
-### Generation Provider
+### CLI
+`gem install activeagent`
 
-```ruby  
-class SupportAgent < ActiveAgent::Base  
-  generate_with :openai, model: ‘gpt-o3-mini’,  temperature: 0.7  
-end  
+### Rails Generator
+After installing the gem, run the Rails installation generator:
+
+```bash
+$ rails generate active_agent:install
 ```
 
-`generate_with` sets the generation provider’s completion generation model and parameters.
+This will create:
+```
+create  config/initializers/active_agent.rb
+create  config/active_agent.yml
+create  app/agents/application_agent.rb
+create  app/agents
+```
 
-`completion_response = SupportAgent.prompt(‘Help me!’).generate_now`
+- An initializer that uses default configurations 
+```ruby
+# config/initializers/active_agent.rb
+ActiveAgent.load_configuration(Rails.root.join('config', 'active_agent.yml'))
+```
+- A YAML configuration file for provider settings, such as OpenAI and might include environment-specific configurations:
+```yaml
+# config/active_agent.yml
+development:
+  openai:
+    service: "OpenAI"
+    api_key: <%= Rails.application.credentials.dig(:openai, :api_key) %>
+    model: "gpt-3.5-turbo"
+    temperature: 0.7
+
+production:
+  openai:
+    service: "OpenAI"
+    api_key: <%= Rails.application.credentials.dig(:openai, :api_key) %>
+    model: "gpt-3.5-turbo"
+    temperature: 0.7
 
-```ruby  
-class SupportAgent < ActiveAgent::Base  
-  generate_with :openai, model: ‘gpt-o3-mini’,  temperature: 0.7  
-  embed_with :openai, model: ‘text-embedding-3-small’  
-end  
 ```
+- A base application agent class
+```ruby
+# app/agents/application_agent.rb
+class ApplicationAgent < ActiveAgent::Base
+  layout 'agent'
+
+  def prompt
+    super { |format| format.text { render plain: params[:message] } }
+  end
+```
+- The agents directory structure
 
-`embed_with` sets the generation provider’s embedding generation model and parameters.
+## Agent
+Create agents that take instructions, prompts, and perform actions
 
-`embedding_response = SupportAgent.prompt(‘Help me!’).embed_now`
+### Rails Generator
+To use the Rails Active Agent generator to create a new agent and the associated views for the requested action prompts:
 
-### Instructions
+```bash
+$ rails generate active_agent:agent travel search book plans 
+```
+This will create:
+```
+create  app/agents/travel_agent.rb
+create  app/views/agents/travel/search.text.erb
+create  app/views/agents/travel/book.text.erb
+create  app/views/agents/travel/plans.text.erb
+```
+
+The generator creates:
+- An agent class inheriting from ApplicationAgent
+- Text template views for each action
+- Action methods in the agent class for processing prompts
+
+### Agent Actions
+```ruby
+class TravelAgent < ApplicationAgent
+  def search
+    
+    prompt { |format| format.text { render plain: "Searching for travel options" } }
+  end
+
+  def book
+    prompt { |format| format.text { render plain: "Booking travel plans" } }
+  end
+
+  def plans
+    prompt { |format| format.text { render plain: "Making travel plans" } }
+  end
+end
+```
+
+## Action Prompt
 
-Instructions are system prompts that predefine the agent’s intention.
+Action Prompt provides the structured interface for composing AI interactions through messages, actions/tools, and conversation context. [Read more about Action Prompt](lib/active_agent/action_prompt/README.md)
 
-### Prompt
+```ruby
+agent.prompt(message: "Find hotels in Paris", 
+      actions: [{name: "search", params: {query: "hotels paris"}}])
+```
+
+The prompt interface manages:
+- Message content and roles (system/user/assistant)
+- Action/tool definitions and requests
+- Headers and context tracking
+- Content types and multipart handling
+
+### Generation Provider 
+
+Generation Provider defines how prompts are sent to AI services for completion and embedding generation. [Read more about Generation Providers](lib/active_agent/generation_provider/README.md)
 
-Action Prompt allows Active Agents to render plain text and HTML prompt templates. Calling generate on a prompt will send the prompt to the agent’s Generation Provider.
+```ruby
+class VacationAgent < ActiveAgent::Base
+  # Try not to get too model-rous with the parameters!
+  generate_with :openai, 
+  model: "gpt-4",
+  temperature: 0.7
+
+  # Embed yourself in the joy of vector search
+  embed_with :openai,
+  model: "text-embedding-ada-002" 
+end
+```
 
-`SupportAgent.prompt(“What does CRUD and REST mean?”)`
+Providers handle:
+- API client configuration
+- Prompt/completion generation
+- Stream processing
+- Embedding generation  
+- Context management
+- Error handling
 
 ### Queue Generation
 
@@ -49,7 +148,7 @@ Active Agents can define methods that are autoloaded as callable tools. These ac
 
 ## Actions
 
-```  
+```ruby
 def get_cat_image_base64  
   uri = URI("https://cataas.com/cat")  
   response = Net::HTTP.get_response(uri)
@@ -86,4 +185,4 @@ end
 
 response = SupportAgent.prompt(‘show me a picture of a cat’).generate_now
 
-response.message
+response.message

data/lib/active_agent/action_prompt/README.md

@@ -1,44 +1,111 @@
 # Active Agent: Action Prompt
 
-ActionPrompt provides a structured way to create and manage prompts and tools for AI interactions. It includes several support classes to handle different aspects of prompt creation and management. The Base class implements an AbstractController to perform actions that render prompts..
+Action Prompt provides a structured way to create and manage prompts for AI interactions. It enables composing messages, handling actions/tools, and managing conversation context through several key components.
 
-## Main Components
+Action Prompt manages the overall prompt structure including:
 
-Module - for including in your agent classes to provide prompt functionality.
-Base class - for creating and managing prompts in ActiveAgent.
-Tool class - for representing the tool object sent to the Agent's generation provider.
-Message - class for representing a single message within a prompt.
-Prompt - class for representing a the context of a prompt, including messages, actions, and other attributes.
+- Messages list with system/user/assistant roles
+- Action/tool definitions
+- Headers and context tracking
+- Content type and encoding 
+- Multipart message handling
 
-### ActionPrompt::Base
-
-The base class is used to create and manage prompts in Active Agent. It provides the core functionality for creating and managing contexts woth prompts, tools, and messages.
-
-#### Core Methods
-`prompt` - Creates a new prompt object with the given attributes.
+```ruby
+prompt = ActionPrompt::Prompt.new(
+  instructions: "System guidance",
+  message: "User input",
+  actions: [tool_definition, action_schema],
+  context: messages
+)
+```
 
+## ActionPrompt::Message 
 
-### ActionPrompt::Tool
+Represents individual messages with:
 
-### ActionPrompt::Message
+### Content and Role
+```ruby
+message = ActionPrompt::Message.new(
+  content: "Search for a hotel",
+  role: :user
+)
+```
 
-Represents a single message within a prompt.
+- Content stores the actual message text
+- Role defines the message sender type (system/user/assistant/function/tool)
+- Messages form interactions between roles in a Context
 
-### ActionPrompt::Prompt
+### Action Requests and Responses
+```ruby
+message = ActionPrompt::Message.new(
+  content: "Search for a hotel",
+  role: :tool,
+  requested_actions: [{name: "search", params: {query: "hotel"}}]
+)
+```
+
+- Tracks if message requests actions/tools
+- Maintains list of requested_actions
+- Action responses include function call results
+- Handles tool execution state
+
+### Content Type and Encoding
+- Default content_type is "text/plain"
+- Supports multiple content types for rich messages
+- Default charset is UTF-8
+- Handles content encoding/decoding
+
+### Role Validation
+- Enforces valid roles via VALID_ROLES constant
+- Validates on message creation
+- Raises ArgumentError for invalid roles
+- Supported roles: system, assistant, user, tool, function
 
-Manages the overall structure of a prompt, including multiple messages, actions, and other attributes.
+```ruby
+message = ActionPrompt::Message.new(
+  content: "Hello",
+  role: :user,
+  content_type: "text/plain",
+  charset: "UTF-8"
+)
+```
 
 ### ActionPrompt::Action
 
-Represents an action that represents the tool object sent to the Agent's generation provider can be associated with a prompt or message.
+Defines callable tools/functions:
 
-## Usage
+- Name and parameters schema
+- Validation and type checking
+- Response handling
+- Action execution
 
-To use ActionPrompt in your agent, include the module in your agent class:
+## Usage with Base Agents
 
 ```ruby
-class MyAgent
-  include ActiveAgent::ActionPrompt
-  
-  # Your agent code here
+class MyAgent < ActiveAgent::Base
+  # Define available actions
+  def action_schemas
+    [
+      {name: "search", params: {query: :string}}
+    ]
+  end
+
+  # Handle action responses
+  def perform_action(action) 
+    case action.name
+    when "search"
+      search_service.query(action.params[:query])
+    end
+  end
 end
+```
+
+The Base agent integrates with ActionPrompt to:
+
+1. Create prompts with context
+2. Register available actions
+3. Process action requests
+4. Handle responses and update context
+5. Manage the conversation flow
+
+See Base.rb for full agent integration details.

data/lib/active_agent/action_prompt/message.rb

@@ -3,20 +3,27 @@ module ActiveAgent
     class Message
       VALID_ROLES = %w[system assistant user tool function].freeze
 
-      attr_accessor :content, :role, :name, :action_requested, :requested_actions
+      attr_accessor :content, :role, :name, :action_requested, :requested_actions, :content_type, :charset
 
       def initialize(attributes = {})
+        @action_requested = @requested_actions.any?  
+        @agent_class = attributes[:agent_class]       
+        @charset = attributes[:charset] || "UTF-8"
         @content = attributes[:content] || ""
-        @role = attributes[:role] || :user
+        @content_type = attributes[:content_type] || "text/plain"
         @name = attributes[:name]
-        @agent_class = attributes[:agent_class]
+        @role = attributes[:role] || :user
         @requested_actions = attributes[:requested_actions] || []
-        @action_requested = @requested_actions.any?
         validate_role
       end
 
       def to_h
-        hash = {role: role, content: content}
+        hash = {
+          role: role, 
+          content: content,
+          content_type: content_type,
+          charset: charset
+        }
         hash[:name] = name if name
         hash[:action_requested] = requested_actions.any?
         hash[:requested_actions] = requested_actions if requested_actions.any?

data/lib/active_agent/base.rb

@@ -448,11 +448,15 @@ module ActiveAgent
     end
 
     def insert_part(container, response, charset)
-      response[:charset] ||= charset
-      prompt = ActiveAgent::ActionPrompt::Prompt.new(response)
+      prompt = ActiveAgent::ActionPrompt::Prompt.new
+      message = ActiveAgent::ActionPrompt::Message.new(
+        content: response[:body],
+        content_type: response[:content_type],
+        charset: charset
+      )
+      prompt.message = message
       container.add_part(prompt)
     end
-
     # This and #instrument_name is for caching instrument
     def instrument_payload(key)
       {

data/lib/active_agent/generation_provider/README.md

@@ -1,17 +1,72 @@
 # Active Agent: Generation Provider
 
-This README provides information about the base generation provider class and the generation provider module interfaces in the ActiveAgent library.
+This README provides information about the generation provider interfaces and implementations in the ActiveAgent library.
 
 ## Main Components
 
-Base class - for creating and configuring generation providers.
-Module - for including in your agent classes to provide generation provider functionality.
+- Base class - Abstract class for implementing generation providers
+- OpenAI Provider - Reference implementation using OpenAI's API
+- Response class - Standardized response wrapper
+- Module - For including generation provider functionality in agents
 
-### ActiveAgent::GenerationProvider::Base
+## Core Concepts
 
-The main class for creating and configuring generation providers. It provides the core functionality for creating and managing generation providers.
+### Base Provider Class
 
-#### Core Methods
+The `ActiveAgent::GenerationProvider::Base` class defines the core interface that all providers must implement:
 
-##### initialize(options = {})
-Creates a new generation provider object with the given options.
+```ruby
+def generate(prompt)
+  raise NotImplementedError
+end
+```
+
+### OpenAI Provider Implementation
+
+The OpenAI provider shows how to implement a concrete generation provider:
+
+- Handles authentication and client setup
+- Implements prompt/completion generation
+- Supports streaming responses
+- Handles embeddings generation
+- Manages context updates
+- Processes tool/action calls
+
+### Provider Features
+
+- Configuration - Providers accept config options for API keys, models, etc
+- Streaming - Optional streaming support for realtime responses
+- Action handling - Support for function/tool calling
+- Error handling - Standardized error handling via GenerationProviderError
+- Context management - Tracks conversation context and message history
+
+### Response Handling
+
+The Response class wraps provider responses with a consistent interface:
+
+```ruby
+Response.new(
+  prompt: prompt,    # Original prompt
+  message: message,  # Generated response
+  raw_response: raw  # Provider-specific response
+)
+```
+
+## Usage Example
+
+```ruby
+# Configure provider
+provider = ActiveAgent::GenerationProvider::OpenAIProvider.new(
+  "api_key" => ENV["OPENAI_API_KEY"],
+  "model" => "gpt-4"
+)
+
+# Generate completion
+response = provider.generate(prompt)
+
+# Access response
+response.message.content    # Generated text
+response.raw_response      # Raw provider response
+```
+
+See the OpenAI provider implementation for a complete reference example.

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "0.2.3"
+  VERSION = "0.2.4.rc1"
 end

data/lib/generators/active_agent/templates/application_agent.rb.tt

@@ -1,5 +1,9 @@
 <% module_namespacing do -%>
 class ApplicationAgent < ActiveAgent::Base
   layout 'agent'
+
+  def prompt
+    super { |format| format.text { render plain: params[:message] } }
+  end
 end
 <% end %>

data/lib/generators/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/active_agent.rb"
+      end
+
+      def create_configuration
+        template "active_agent.yml", "config/active_agent.yml"
+      end
+
+      def create_application_agent
+        template "application_agent.rb", "app/agents/application_agent.rb"
+      end
+
+      def create_agents_directory
+        empty_directory "app/agents"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/templates/active_agent.yml

@@ -0,0 +1,34 @@
+default: &default
+  openai: &openai_default
+    access_token: <%= ENV['OPENAI_ACCESS_TOKEN'] %>
+    organization_id: <%= ENV['OPENAI_ORGANIZATION_ID'] %>
+    default_model: gpt-4
+    default_embedding_model: text-embedding-3-small
+    default_temperature: 0.7
+    request_timeout: 60
+    
+  anthropic: &anthropic_default
+    access_token: <%= ENV['ANTHROPIC_ACCESS_TOKEN'] %>
+    default_model: claude-3-sonnet
+    default_temperature: 0.7
+    request_timeout: 60
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+  test_mode: true
+  mock_responses: true
+
+production:
+  <<: *default
+  openai:
+    <<: *openai_default
+    request_timeout: 120
+  anthropic:
+    <<: *anthropic_default
+    request_timeout: 120
+
+staging:
+  <<: *production

data/lib/generators/templates/initializer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Configure ActiveAgent
+ActiveAgent.configure do |config|
+  # Load configuration from config/active_agent.yml
+  config.load_configuration Rails.root.join("config", "active_agent.yml")
+
+  # Configure default provider settings
+  config.default_provider = :openai
+  
+  # Configure default generation settings
+  config.default_generation_settings = {
+    temperature: 0.7,
+    top_p: 1.0,
+    frequency_penalty: 0.0,
+    presence_penalty: 0.0
+  }
+
+  # Configure default embedding settings
+  config.default_embedding_settings = {
+    dimensions: 1536
+  }
+
+  # Configure test mode - when true, will use mock responses
+  config.test_mode = Rails.env.test?
+
+  # Configure logging
+  config.logger = Rails.logger
+  config.log_level = Rails.env.production? ? :info : :debug
+
+  # Configure cache
+  config.cache = Rails.cache
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activeagent
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4.rc1
 platform: ruby
 authors:
 - Justin Bowen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-20 00:00:00.000000000 Z
+date: 2025-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -130,8 +130,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-description: The AI Agent framework to make Rails the best framework for AI application
-  development.
+description: A simple way to perform long running LLM background jobs and streaming
+  responses
 email: jusbowen@gmail.com
 executables: []
 extensions: []
@@ -180,13 +180,13 @@ files:
 - lib/generators/active_agent/templates/agent_spec.rb.tt
 - lib/generators/active_agent/templates/agent_test.rb.tt
 - lib/generators/active_agent/templates/application_agent.rb.tt
-homepage:
+- lib/generators/install_generator.rb
+- lib/generators/templates/active_agent.yml
+- lib/generators/templates/initializer.rb
+homepage: https://rubygems.org/gems/activeagent
 licenses:
 - MIT
-metadata:
-  homepage_uri: https://activeagents.ai
-  source_code_uri: https://github.com/activeagents/activeagent
-  bug_tracker_uri: https://github.com/activeagents/activeagent/issues
+metadata: {}
 post_install_message:
 rdoc_options: []
 require_paths: