activeagent 0.6.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a07262fb92e03b08ab0abaad0cf2c9b6575a4aa1f6988899c9d0b2d9b081589c
-  data.tar.gz: '0619435e72d1a4e368c330956aa1295059c98c94a4c885e02b7781e82ba56260'
+  metadata.gz: 330c02d2e1ac16e72413f22401dbc6899f652b794d34090b0f499a37b901fbaf
+  data.tar.gz: a492f5c88db1f217fe47f9de1477f195c6b150b5dc5ce5791c66fe0f63b0b028
 SHA512:
-  metadata.gz: 3c7277d51950db30434643a67379467886cf40e2a100e4ada54556b88cafd4a92e314e02f06d2a94572b686c7064a28d1da94c3176e207452611b3d340d7d455
-  data.tar.gz: e14ae5c030fe0ce4b7c47915f4728dfa9474b7a465695ab9c0e2cb244136eb024bf8c1f6657b2178282091c98af4171b549927f55a38d195023d9d4f540979e1
+  metadata.gz: d8dac6789ba1f3685c24d711aace46ad5b681e9c795a975e61f07ee3c7d9a9bc44c2fd0568fabcabd739df5efd13b222c5fa6e954384bacb8bbcfdaaab0d7182
+  data.tar.gz: 8a0f61b2b5a9375c8f1b090bca29af077384079ba008622a1a510d8190acdff034c7f6b8065c1c752a2cee00dabd35d00f017db28954aacc17386fb06be63d50

data/CHANGELOG.md

@@ -5,6 +5,244 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2025-11-21
+
+Major refactor with breaking changes. Complete provider rewrite. New modular architecture.
+
+**Requirements:** Ruby 3.1+, Rails 7.0+/8.0+/8.1+
+
+### Breaking Changes
+
+#### 1. Update Provider Gems
+
+```ruby
+# Gemfile - Remove unofficial gems
+gem "ruby-openai"
+gem "ruby-anthropic"
+
+# Add official provider SDKs
+gem "openai"      # Official OpenAI SDK
+gem "anthropic"   # Official Anthropic SDK
+```
+
+Run `bundle install` after updating.
+
+#### 2. Update Base Class
+
+```ruby
+# Before
+class MyAgent < ActiveAgent::ActionPrompt::Base
+end
+
+# After
+class MyAgent < ActiveAgent::Base
+end
+```
+
+#### 3. Configure Providers
+
+```ruby
+# Before - options wrapped in options key
+class MyAgent < ActiveAgent::Base
+  def chat
+    prompt(message: "Hello", options: { temperature: 0.7 })
+  end
+end
+
+# After - options passed directly (at class or call level)
+class MyAgent < ActiveAgent::Base
+  generate_with :openai, model: "gpt-4o-mini", temperature: 0.7
+
+  def chat
+    prompt("Hello")  # Uses class-level config
+  end
+
+  def chat_creative
+    prompt("Hello", temperature: 1.0)  # Override per-call
+  end
+end
+```
+
+#### 4. Update Custom Providers (if any)
+
+```ruby
+# Before
+module ActiveAgent::GenerationProvider
+  class CustomProvider < Base
+  end
+end
+
+# After
+module ActiveAgent::Providers
+  class CustomProvider < BaseProvider
+  end
+end
+```
+
+#### 5. Update Generator Commands
+
+```bash
+# Before
+rails g active_agent MyAgent action
+
+# After
+rails g active_agent:agent MyAgent action
+```
+
+#### 6. Remove Framework Retry Config
+
+```ruby
+# Remove from config/initializers/activeagent.rb
+ActiveAgent.configure do |config|
+  config.retries = true
+  config.retries_count = 5
+end
+
+# Use provider-specific settings in config/active_agent.yml
+openai:
+  service: "OpenAI"
+  max_retries: 5
+  timeout: 600.0
+```
+
+Template paths:
+- `app/views/agents/{agent}/instructions.md` (no `.erb` extension by default for instructions)
+- `app/views/agents/{agent}/{action}.md.erb`
+
+### Added
+
+**Mock Provider for Testing**
+```ruby
+class MyAgent < ActiveAgent::Base
+  generate_with :mock
+end
+
+response = MyAgent.prompt("Test").generate_now
+# Returns predictable responses without API calls
+```
+
+**Mixed Provider Support**
+```ruby
+class MyAgent < ActiveAgent::Base
+  generate_with :openai, model: "gpt-4o-mini"
+  embed_with :anthropic, model: "claude-3-5-sonnet-20241022"
+end
+```
+
+**Prompt Previews**
+```ruby
+preview = MyAgent.prompt("Hello").prompt_preview
+# Shows instructions, messages, tools before execution
+```
+
+**Callback Lifecycle**
+- `before_generation`, `after_generation`, `around_generation`
+- `before_prompt`, `after_prompt`, `around_prompt`
+- `before_embed`, `after_embed`, `around_embed`
+- `on_stream_open`, `on_stream`, `on_stream_close`
+- Rails-style callback control: `prepend_*`, `skip_*`, `append_*`
+
+**Multi-Input Embeddings**
+```ruby
+response = MyAgent.embed(inputs: ["Text 1", "Text 2"]).embed_now
+vectors = response.data.map { |d| d[:embedding] }
+```
+
+**Normalized Usage Statistics**
+```ruby
+response = MyAgent.prompt("Hello").generate_now
+
+# Works across all providers
+response.usage.input_tokens
+response.usage.output_tokens
+response.usage.total_tokens
+
+# Provider-specific fields when available
+response.usage.cached_tokens      # OpenAI, Anthropic
+response.usage.reasoning_tokens   # OpenAI o1 models
+response.usage.service_tier       # Anthropic
+```
+
+**Enhanced Instrumentation for APM Integration**
+- Unified event structure: `prompt.active_agent` and `embed.active_agent` (top-level) plus `prompt.provider.active_agent` and `embed.provider.active_agent` (per-API-call)
+- Event payloads include comprehensive data for monitoring tools (New Relic, DataDog, etc.):
+  - Request parameters: `model`, `temperature`, `max_tokens`, `top_p`, `stream`, `message_count`, `has_tools`
+  - Usage data: `input_tokens`, `output_tokens`, `total_tokens`, `cached_tokens`, `reasoning_tokens`, `audio_tokens`, `cache_creation_tokens` (critical for cost tracking)
+  - Response metadata: `finish_reason`, `response_model`, `response_id`, `embedding_count`
+- Top-level events report cumulative usage across all API calls in multi-turn conversations
+- Provider-level events report per-call usage for granular tracking
+
+**Multi-Turn Usage Tracking**
+- `response.usage` now returns cumulative token counts across all API calls during tool calling
+- New `response.usages` array contains individual usage objects from each API call
+- `Usage` objects support addition: `usage1 + usage2` for combining statistics
+
+**Provider Enhancements**
+- OpenAI Responses API: `api: :responses` or `api: :chat`
+- Anthropic JSON object mode with automatic extraction
+- OpenRouter: quantization, provider preferences, web search
+- Flexible naming: `:openai` or `:open_ai`, `:openrouter` or `:open_router`
+
+**Rails 8.1 Support**
+
+**Comprehensive Documentation**
+- VitePress site at docs.activeagents.ai
+- All examples tested and validated
+
+### Changed
+
+**Provider Architecture**
+- Unified `BaseProvider` interface across all providers
+- Retry logic moved to provider SDKs (automatic exponential backoff)
+- Migrated to official SDKs: `openai` gem and `anthropic` gem
+- Type-safe options with per-provider definitions
+
+**Configuration**
+- Options configurable at class level, instance level, or per-call
+- Simplified parameter handling pattern
+
+**Requirements**
+- Ruby 3.1+ (previously 3.0+)
+
+**Testing**
+- Reorganized by feature and provider integration
+- All documentation examples validated
+
+### Fixed
+
+**Providers**
+- OpenAI streaming with functions/tools
+- Ollama streaming support
+- Anthropic tool choice modes (`any` and `tool`)
+- OpenRouter model fallback and parameter naming
+- Provider gem loading errors
+
+**Framework**
+- Streaming lifecycle with function/tool calls
+- Multi-tool and multi-turn conversation handling
+- Options mutation during generation
+- Template rendering without blocks
+- Schema generator key symbolization
+- Rails 8.0 and 8.1 compatibility
+- Usage extraction across OpenAI/Anthropic response formats
+
+### Removed
+
+**Namespaces**
+- `ActiveAgent::ActionPrompt` → use `ActiveAgent::Base`
+- `ActiveAgent::GenerationProvider` → use `ActiveAgent::Providers`
+
+**Configuration**
+- `ActiveAgent.configuration.retries` → use provider `max_retries`
+- `ActiveAgent.configuration.retries_count` → use provider `max_retries`
+- `ActiveAgent.configuration.retries_on` → handled by provider SDKs
+
+**Modules**
+- `ActiveAgent::QueuedGeneration` → `Queueing` concern
+- `ActiveAgent::Rescuable` → `Rescue` concern
+- `ActiveAgent::Sanitizers` → moved to concerns
+- `ActiveAgent::PromptHelper` → moved to concerns
+
 ## [0.3.2] - 2025-04-15
 
 ### Added
@@ -13,5 +251,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enhance streaming to support tool calls during stream. Previously, streaming mode blocked tool call execution.
 - Fix layout rendering bug when no block is passed and views now render correctly without requiring a block.
 
-### Removed 
-- Generation Provider module and Action Prompt READMEs have been removed, but will be updated along with the main README in the next release.
+### Removed
+- Generation Provider module and Action Prompt READMEs have been removed, but will be updated along with the main README in the next release.

data/README.md

@@ -29,16 +29,16 @@ Add the generation provider gem you want to use:
 
 ```bash
 # OpenAI
-bundle add ruby-openai
+bundle add openai
 
 # Anthropic
-bundle add ruby-anthropic
+bundle add anthropic
 
 # Ollama (uses OpenAI-compatible API)
-bundle add ruby-openai
+bundle add openai
 
 # OpenRouter (uses OpenAI-compatible API)
-bundle add ruby-openai
+bundle add openai
 ```
 
 ### Setup
@@ -51,8 +51,7 @@ rails generate active_agent:install
 
 This creates:
 - `config/active_agent.yml`: Configuration file for generation providers
-- `app/agents`: Directory for your agent classes
-- `app/views/agent_*`: Directory for agent prompt/view templates
+- `app/agents/application_agent.rb`: Base agent class
 
 ### Quick Example
 
@@ -60,19 +59,16 @@ Define an application agent:
 
 ```ruby
 class ApplicationAgent < ActiveAgent::Base
-  generate_with :openai, 
-    instructions: "You are a helpful assistant.",
-    model: "gpt-4o-mini",
-    temperature: 0.7
+  generate_with :openai, model: "gpt-4o-mini"
 end
 ```
 
 Use your agent:
 
 ```ruby
-message = "Test Application Agent"
-prompt = ApplicationAgent.with(message: message).prompt_context
-response = prompt.generate_now
+response = ApplicationAgent.prompt(message: "Hello, world!").generate_now
+puts response.message
+# => "Hello! How can I help you today?"
 ```
 
 ### Your First Agent
@@ -112,20 +108,17 @@ Configure generation providers in `config/active_agent.yml`:
 development:
   openai:
     service: "OpenAI"
-    api_key: <%= Rails.application.credentials.dig(:openai, :api_key) %>
+    access_token: <%= Rails.application.credentials.dig(:openai, :access_token) %>
     model: "gpt-4o-mini"
-    embeddings_model: "text-embedding-3-small"
 
   anthropic:
     service: "Anthropic"
-    api_key: <%= Rails.application.credentials.dig(:anthropic, :api_key) %>
-    model: "claude-3-5-sonnet"
+    access_token: <%= Rails.application.credentials.dig(:anthropic, :access_token) %>
+    model: "claude-sonnet-4.5"
 
   ollama:
     service: "Ollama"
     model: "llama3.2"
-    embeddings_model: "nomic-embed-text"
-    host: "http://localhost:11434"
 ```
 
 ## Features
@@ -146,9 +139,8 @@ Extract structured data from images, PDFs, and text:
 
 ```ruby
 prompt = DataExtractionAgent.with(
-  output_schema: :chart_schema,
   image_path: Rails.root.join("sales_chart.png")
-).parse_content
+).parse_content.generate_now
 ```
 
 ### Translation
@@ -156,7 +148,7 @@ Translate text between languages:
 
 ```ruby
 response = TranslationAgent.with(
-  message: "Hi, I'm Justin", 
+  message: "Hi, I'm Justin",
   locale: "japanese"
 ).translate.generate_now
 ```
@@ -166,8 +158,7 @@ Agents can use tools to perform actions:
 
 ```ruby
 # Agent with tool support
-message = "Show me a cat"
-prompt = SupportAgent.with(message: message).prompt_context
+prompt = SupportAgent.prompt(message: "Show me a cat")
 response = prompt.generate_now
 # Response includes tool call results
 ```