red64-cli 0.1.0 → 0.3.0

package/framework/stacks/rails/implement-ai-llm-with-rubyllm.md

@@ -0,0 +1,342 @@
+# AI/LLM Implementation with ruby_llm
+
+Project memory for implementing AI-powered features using the ruby_llm gem in MediaPulse.
+
+---
+
+## Overview
+
+MediaPulse uses the `ruby_llm` gem as a unified interface for multi-provider LLM access. The architecture separates concerns into configuration, client factory, and domain-specific services.
+
+---
+
+## Architecture Layers
+
+### 1. Configuration (`config/initializers/ruby_llm.rb`)
+Global setup for ruby_llm gem with API keys and defaults.
+
+```ruby
+# Pattern: Configure in initializer, credentials from Rails.credentials
+RubyLLM.configure do |config|
+  config.anthropic_api_key = Rails.application.credentials.dig(:anthropic, :api_key)
+  config.openai_api_key = Rails.application.credentials.dig(:openai, :api_key)
+  config.default_model = "claude-sonnet-4-20250514"
+  config.max_retries = 3
+  config.retry_interval = 0.5
+  config.retry_backoff_factor = 2
+  config.request_timeout = 120
+end
+```
+
+### 2. Client Factory (`app/services/llm_client_factory.rb`)
+Provider abstraction with task-specific model selection.
+
+```ruby
+# Pattern: Factory methods for different use cases
+LlmClientFactory.extraction_client  # Claude Haiku - fast, cost-effective
+LlmClientFactory.generation_client  # Claude Sonnet - creative, quality
+```
+
+### 3. Service Layer (`app/services/llm_service.rb`)
+Unified interface for AI operations with error mapping.
+
+```ruby
+# Pattern: Domain methods with consistent return types
+LlmService.generate_ideas(prompt:, system_prompt:, model:)
+LlmService.generate_content(prompt:, system_prompt:, model:)
+LlmService.stream(prompt:, system_prompt:, model:, &block)
+```
+
+---
+
+## Model Selection Strategy
+
+| Use Case | Model | Rationale |
+|----------|-------|-----------|
+| **Extraction** (semantic, entities) | Claude Haiku | Fast, cost-effective for structured extraction |
+| **Generation** (ideas, content) | Claude Sonnet | Higher quality for creative tasks |
+| **Embeddings** | OpenAI text-embedding-3-small | Cost-effective vector generation |
+
+```ruby
+# Constants for model IDs (avoid magic strings)
+HAIKU_MODEL = "claude-haiku-3-5-20241022"
+SONNET_MODEL = "claude-sonnet-4-20250514"
+```
+
+---
+
+## Response Handling Pattern
+
+Use immutable Data objects for LLM responses:
+
+```ruby
+# Pattern: Immutable value objects for responses
+LlmResponse = Data.define(:content, :model, :input_tokens, :output_tokens)
+
+# Usage in service
+def build_response(response)
+  LlmResponse.new(
+    content: response.content,
+    model: response.model_id,
+    input_tokens: response.input_tokens,
+    output_tokens: response.output_tokens
+  )
+end
+```
+
+---
+
+## Prompt Engineering Patterns
+
+### System Prompts
+Define persona and output format constraints:
+
+```ruby
+# Pattern: Constants for reusable system prompts
+SYSTEM_PROMPT = <<~PROMPT
+  You are an expert content strategist. Analyze the provided source material and generate
+  compelling content ideas. For each idea, provide:
+  1. A clear, engaging title
+  2. A brief summary (2-3 sentences)
+  3. The source indices that support this idea
+
+  Return your response as JSON array with objects containing: title, summary, source_indices
+PROMPT
+```
+
+### JSON Output Requests
+Request structured output with explicit format:
+
+```ruby
+# Pattern: Explicit JSON schema in prompt
+def build_prompt(content, source_type)
+  <<~PROMPT
+    Analyze the following #{source_type} content and extract semantic information.
+
+    Return a JSON object with exactly these fields:
+    - summary: A 2-3 sentence summary
+    - entities: Array of objects with "name" and "type" keys
+    - claims: Array of strings representing key assertions
+    - confidence: A number between 0.0 and 1.0
+
+    Respond with ONLY valid JSON, no markdown formatting or explanation.
+
+    CONTENT:
+    #{content}
+  PROMPT
+end
+```
+
+### Content Truncation
+Handle token limits gracefully:
+
+```ruby
+# Pattern: Truncate before sending to LLM
+MAX_CONTENT_TOKENS = 8000
+CHARS_PER_TOKEN = 4
+
+def truncate_content(content)
+  max_chars = MAX_CONTENT_TOKENS * CHARS_PER_TOKEN
+  return content if content.length <= max_chars
+  content[0, max_chars] + "\n\n[Content truncated for processing]"
+end
+```
+
+---
+
+## JSON Response Parsing
+
+LLMs may wrap JSON in markdown code fences:
+
+```ruby
+# Pattern: Extract JSON from potential markdown wrapping
+def extract_json(content)
+  content = content.strip
+  if content.start_with?("```")
+    content = content.sub(/\A```\w*\n?/, "")
+    content = content.sub(/\n?```\z/, "")
+  end
+  content.strip
+end
+
+# Pattern: Graceful fallback for parsing failures
+def parse_response(response_content)
+  json_content = extract_json(response_content)
+  parsed = JSON.parse(json_content)
+  return {} unless parsed.is_a?(Hash)
+  parsed.transform_keys(&:to_sym)
+rescue JSON::ParserError => e
+  Rails.logger.warn("Failed to parse JSON response: #{e.message}")
+  {}
+end
+```
+
+---
+
+## Error Handling
+
+### Error Hierarchy
+Map ruby_llm errors to domain-specific errors:
+
+```ruby
+# Pattern: Custom error hierarchy
+class LlmService
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+  class ApiError < Error; end
+end
+
+# Pattern: Map provider errors to domain errors
+rescue RubyLLM::UnauthorizedError => e
+  raise AuthenticationError, e.message
+rescue RubyLLM::RateLimitError => e
+  raise RateLimitError, e.message
+rescue RubyLLM::ConfigurationError => e
+  raise ConfigurationError, e.message
+rescue RubyLLM::Error => e
+  raise ApiError, e.message
+```
+
+### Validation Before API Calls
+
+```ruby
+# Pattern: Fail fast with clear messages
+def validate_api_key!
+  api_key = Rails.application.credentials.dig(:anthropic, :api_key)
+  return if api_key.present?
+
+  raise ConfigurationError,
+    "Anthropic API key not configured. Add to credentials: anthropic.api_key"
+end
+```
+
+---
+
+## Testing LLM Services
+
+### Mocking ruby_llm Calls
+
+```ruby
+# Pattern: Stub RubyLLM.chat for unit tests
+test "generate_ideas returns LlmResponse" do
+  mock_response = Minitest::Mock.new
+  mock_response.expect :content, "Generated content"
+  mock_response.expect :model_id, "claude-sonnet-4-20250514"
+  mock_response.expect :input_tokens, 150
+  mock_response.expect :output_tokens, 200
+
+  mock_chat = Minitest::Mock.new
+  mock_chat.expect :with_instructions, mock_chat, [String]
+  mock_chat.expect :ask, mock_response, [String]
+
+  RubyLLM.stub :chat, mock_chat do
+    result = LlmService.generate_ideas(prompt: "Test", system_prompt: "Expert")
+    assert_instance_of LlmResponse, result
+  end
+end
+```
+
+### Stubbing Credentials in Tests
+
+```ruby
+# Pattern: Stub credentials for test isolation
+def stub_anthropic_api_key
+  credentials_mock = Class.new do
+    def dig(*keys)
+      keys == [:anthropic, :api_key] ? "test-api-key" : nil
+    end
+  end.new
+  Rails.application.instance_variable_set(:@credentials, credentials_mock)
+end
+
+def reset_credentials_stub
+  Rails.application.instance_variable_set(:@credentials, nil)
+end
+```
+
+### Testing Error Mapping
+
+```ruby
+# Pattern: Verify error mapping with mock errors
+test "maps RubyLLM::RateLimitError to RateLimitError" do
+  error_response = OpenStruct.new(body: "Rate limit exceeded")
+  mock_chat = Minitest::Mock.new
+  mock_chat.expect :ask, nil do
+    raise RubyLLM::RateLimitError.new(error_response)
+  end
+
+  RubyLLM.stub :chat, mock_chat do
+    assert_raises(LlmService::RateLimitError) do
+      LlmService.generate_ideas(prompt: "Test")
+    end
+  end
+end
+```
+
+---
+
+## Credential Management
+
+Store API keys in Rails encrypted credentials:
+
+```bash
+# Edit credentials
+bin/rails credentials:edit
+
+# Structure
+anthropic:
+  api_key: sk-ant-...
+openai:
+  api_key: sk-...
+```
+
+Access pattern:
+```ruby
+Rails.application.credentials.dig(:anthropic, :api_key)
+```
+
+---
+
+## Domain-Specific Services
+
+Create focused services for specific AI tasks:
+
+| Service | Purpose | Model |
+|---------|---------|-------|
+| `SemanticProcessing::SemanticExtractor` | Extract entities, claims, topics | Haiku |
+| `IdeaGenerationService` | Generate content ideas from sources | Sonnet |
+| `ContentGenerationService` | Create platform-specific content | Sonnet |
+| `EmbeddingService` | Vector embeddings for similarity | OpenAI |
+
+Each follows the pattern:
+- Class method `call` for invocation
+- Dependency injection for testability
+- Result objects for outcomes
+- Error propagation to caller
+
+---
+
+## Quick Reference
+
+### Creating a New LLM Service
+
+1. Define class in `app/services/`
+2. Use `LlmClientFactory` for client (extraction or generation)
+3. Build prompt with explicit JSON schema
+4. Parse response with JSON extraction helper
+5. Return immutable result object
+6. Map errors to domain-specific types
+
+### Adding Tests
+
+1. Stub `RubyLLM.chat` with mock
+2. Stub credentials if validating API keys
+3. Test success path with mock responses
+4. Test error paths with raised exceptions
+5. Verify response structure and types
+
+---
+
+_Focus on patterns, not exhaustive API documentation. See ruby_llm gem docs for full API reference._

package/framework/stacks/rails/rails.md

@@ -0,0 +1,301 @@
+# Ruby on Rails Conventions
+
+Project memory for Rails 8.1 patterns and conventions in MediaPulse.
+
+---
+
+## Framework Stack
+
+### Core Technologies
+- **Rails 8.1** with `config.load_defaults 8.1`
+- **Hotwire**: Turbo + Stimulus for reactive UI without heavy JavaScript
+- **Propshaft**: Modern asset pipeline (not Sprockets)
+- **Importmap**: ESM-based JavaScript, no bundler required
+- **Solid Queue**: Database-backed job processing (replaces Sidekiq/Redis)
+- **Solid Cache**: Database-backed caching
+- **Kamal**: Docker-based deployment
+
+### Database
+- **SQLite3** for development (production-ready with proper config)
+- Separate databases for queue, cache, and cable (see `db/*_schema.rb`)
+
+---
+
+## Application Architecture
+
+### MVC Patterns
+
+**Models** (`app/models/`)
+- Inherit from `ApplicationRecord` (abstract base class)
+- Keep models focused on data and associations
+- Use validations, scopes, and callbacks appropriately
+- Extract complex business logic to service objects
+
+```ruby
+# Pattern: Lean models with clear responsibilities
+class Content < ApplicationRecord
+  belongs_to :user
+  has_many :versions, dependent: :destroy
+
+  validates :title, presence: true
+  validates :status, inclusion: { in: %w[draft published] }
+
+  scope :published, -> { where(status: "published") }
+  scope :by_user, ->(user) { where(user: user) }
+end
+```
+
+**Controllers** (`app/controllers/`)
+- Inherit from `ApplicationController`
+- Use `allow_browser versions: :modern` (Rails 8.1 default)
+- Keep actions thin, delegate to models/services
+- Use strong parameters for all user input
+
+```ruby
+# Pattern: RESTful actions with strong parameters
+class ContentsController < ApplicationController
+  def create
+    @content = Current.user.contents.build(content_params)
+    if @content.save
+      redirect_to @content, notice: "Created successfully"
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def content_params
+    params.require(:content).permit(:title, :body, :status)
+  end
+end
+```
+
+**Views** (`app/views/`)
+- Use Hotwire/Turbo for dynamic updates
+- Prefer partials for reusable components
+- Use Stimulus controllers for JavaScript behavior
+
+---
+
+## Business Logic Patterns
+
+### Service Objects
+Place complex operations in `app/services/`. Use when logic spans multiple models or involves external services.
+
+```ruby
+# app/services/content_generator.rb
+class ContentGenerator
+  def initialize(user:, prompt:)
+    @user = user
+    @prompt = prompt
+  end
+
+  def call
+    # Complex AI generation logic
+    Result.new(success: true, content: generated_content)
+  end
+
+  private
+
+  attr_reader :user, :prompt
+end
+```
+
+### Query Objects
+For complex queries, use `app/queries/` or model scopes.
+
+```ruby
+# Pattern: Chainable scopes over query objects for simple cases
+Content.published.by_user(user).where("created_at > ?", 1.week.ago)
+```
+
+---
+
+## Background Jobs
+
+### Solid Queue Conventions
+- Jobs inherit from `ApplicationJob`
+- Configure adapter in production: `config.active_job.queue_adapter = :solid_queue`
+- Use appropriate queue names for priority
+
+```ruby
+# app/jobs/generate_content_job.rb
+class GenerateContentJob < ApplicationJob
+  queue_as :default
+
+  retry_on StandardError, wait: :polynomially_longer, attempts: 3
+  discard_on ActiveJob::DeserializationError
+
+  def perform(content_id)
+    content = Content.find(content_id)
+    ContentGenerator.new(content: content).call
+  end
+end
+```
+
+---
+
+## API Patterns
+
+### JSON Responses
+Use Jbuilder for JSON APIs. Keep API logic in dedicated controllers.
+
+```ruby
+# app/controllers/api/v1/base_controller.rb
+module Api
+  module V1
+    class BaseController < ApplicationController
+      skip_before_action :verify_authenticity_token
+      before_action :authenticate_api_request
+    end
+  end
+end
+```
+
+### Turbo Streams
+For real-time updates within the app, prefer Turbo Streams over custom APIs.
+
+```ruby
+# Pattern: Broadcast updates via Turbo
+respond_to do |format|
+  format.html { redirect_to @content }
+  format.turbo_stream
+end
+```
+
+---
+
+## Database Conventions
+
+### Migrations
+- Use descriptive, timestamped migration names
+- Always include `null: false` for required fields
+- Add indexes for foreign keys and frequently queried columns
+- Use `references` with `foreign_key: true`
+
+```ruby
+# Pattern: Complete migration with constraints
+class CreateContents < ActiveRecord::Migration[8.1]
+  def change
+    create_table :contents do |t|
+      t.references :user, null: false, foreign_key: true
+      t.string :title, null: false
+      t.text :body
+      t.string :status, null: false, default: "draft"
+      t.timestamps
+    end
+
+    add_index :contents, [:user_id, :status]
+  end
+end
+```
+
+### Schema
+- Schema file is `db/schema.rb` (default)
+- Separate schema files for queue/cache/cable databases
+
+---
+
+## Testing Approach
+
+### Minitest (Default)
+- Tests in `test/` directory
+- Use fixtures for test data
+- Parallel test execution enabled
+
+```ruby
+# Pattern: Model test with fixtures
+class ContentTest < ActiveSupport::TestCase
+  test "validates title presence" do
+    content = Content.new(title: nil)
+    assert_not content.valid?
+    assert_includes content.errors[:title], "can't be blank"
+  end
+end
+```
+
+### System Tests
+- Use Capybara with Selenium
+- Test user flows end-to-end
+
+```ruby
+# test/system/contents_test.rb
+class ContentsTest < ApplicationSystemTestCase
+  test "creating a content" do
+    visit new_content_path
+    fill_in "Title", with: "Test Content"
+    click_on "Create"
+    assert_text "Created successfully"
+  end
+end
+```
+
+---
+
+## Security Practices
+
+### Built-in Protections
+- CSRF protection enabled by default
+- Strong parameters required
+- Parameter filtering for sensitive data (see `filter_parameter_logging.rb`)
+
+### Credentials
+- Use `bin/rails credentials:edit` for secrets
+- Never commit unencrypted secrets
+- Access via `Rails.application.credentials.dig(:key, :subkey)`
+
+### Security Tools
+- **Brakeman**: Static security analysis (`bundle exec brakeman`)
+- **bundler-audit**: Gem vulnerability scanning
+
+---
+
+## Code Style
+
+### Rubocop Configuration
+- Using `rubocop-rails-omakase` (Rails default style)
+- Run with `bundle exec rubocop`
+
+### Naming Conventions
+- Models: singular, CamelCase (`Content`, `UserProfile`)
+- Controllers: plural, CamelCase + Controller (`ContentsController`)
+- Tables: plural, snake_case (`contents`, `user_profiles`)
+- Jobs: descriptive + Job (`GenerateContentJob`)
+- Services: action-oriented (`ContentGenerator`, `WorkflowExecutor`)
+
+---
+
+## Performance
+
+### Caching
+- Fragment caching with Solid Cache in production
+- Use `cache` helper in views for expensive partials
+- Russian doll caching with `touch: true` on associations
+
+### N+1 Prevention
+- Use `includes` for eager loading
+- Monitor with bullet gem in development (optional)
+
+```ruby
+# Pattern: Eager load associations
+Content.includes(:user, :versions).published
+```
+
+---
+
+## Directory Conventions
+
+```
+app/
+  controllers/     # Request handling
+  models/          # ActiveRecord models
+  views/           # ERB templates + Turbo Streams
+  jobs/            # Background jobs (Solid Queue)
+  services/        # Business logic (create as needed)
+  helpers/         # View helpers
+  javascript/      # Stimulus controllers
+  mailers/         # Email delivery
+```
+
+Extend with `app/services/`, `app/queries/` as complexity grows.