agent_c 2.71828

data/docs/cost-reporting.md

@@ -0,0 +1,86 @@
+# Cost Reporting
+
+Note: You probably want to make a `Batch`. See the [main README](../README.md)
+
+## Overview
+
+AgentC automatically tracks all LLM interactions in a SQLite database, allowing you to generate detailed cost reports.
+
+## Generating Reports
+
+Track your LLM usage and costs:
+
+```ruby
+# See the [configuration](./session-configuration.md) for session args
+session = AgentC::Session.new(...)
+
+# Generate a cost report for all projects
+AgentC::Costs::Report.call(agent_store: session.agent_store)
+
+# For a specific project
+AgentC::Costs::Report.call(
+  agent_store: session.agent_store,
+  project: 'my_project'
+)
+
+# For a specific run
+AgentC::Costs::Report.call(
+  agent_store: session.agent_store,
+  project: 'my_project',
+  run_id: 1234567890
+)
+
+# Or use the session's cost method for current project/run
+puts "Project cost: $#{session.cost.project}"
+puts "Run cost: $#{session.cost.run}"
+```
+
+## What's Included
+
+The report includes:
+- Input/output token counts
+- Cache hit rates
+- Per-interaction costs
+- Total spending
+- Pricing for both normal and long-context models
+
+## Report Format
+
+The cost report displays information organized by project and run:
+
+```
+Project: my_project
+Run ID: 1234567890
+
+Interaction 1 (2024-01-15 10:30:00)
+  Input tokens: 1,250
+  Output tokens: 450
+  Cached tokens: 800
+  Cost: $0.0234
+
+Interaction 2 (2024-01-15 10:35:00)
+  Input tokens: 2,100
+  Output tokens: 680
+  Cached tokens: 1,500
+  Cost: $0.0356
+
+Total Cost: $0.0590
+```
+
+## Cost Optimization Tips
+
+1. **Use cached prompts** - System prompts that rarely change can be cached, significantly reducing costs
+2. **Choose appropriate models** - Use lighter models (Haiku) for simple tasks, heavier models (Sonnet/Opus) for complex ones
+3. **Batch operations** - Group similar tasks together to maximize cache hits
+4. **Monitor costs regularly** - Run cost reports after each pipeline run to identify expensive operations
+
+## Database Schema
+
+All queries are persisted in SQLite with:
+- Full conversation history
+- Token usage metrics
+- Timestamps and metadata
+- Tool calls and responses
+- Project and run ID associations
+
+This allows for detailed analysis and debugging of AI interactions over time.

data/docs/pipeline-tips-and-tricks.md

@@ -0,0 +1,71 @@
+# Pipeline Tips and Tricks
+
+This document contains useful patterns and techniques for working with AgentC pipelines.
+
+## Custom I18n Attributes
+
+By default, when using i18n interpolation in your prompts, AgentC will use `record.attributes` to provide values for interpolation. However, you can customize this behavior by implementing an `i18n_attributes` method on your record.
+
+### Use Case
+
+This is useful when:
+- You want to interpolate values that aren't stored as attributes on the record
+- You need to compute or format values specifically for prompts
+- You want to limit which attributes are exposed to i18n interpolation
+- You need to provide different data than what's in the database
+
+### Example
+
+```ruby
+class MyStore < VersionedStore::Base
+  include AgentC::Store
+
+  record(:my_record) do
+    schema do |t|
+      t.string(:file_path)
+      t.text(:file_contents)
+    end
+
+    # Override the default i18n_attributes
+    def i18n_attributes
+      {
+        file_name: File.basename(file_path),
+        file_extension: File.extname(file_path),
+        lines_count: file_contents&.lines&.count || 0
+      }
+    end
+  end
+end
+```
+
+Now in your prompts, you can interpolate these computed values:
+
+```yaml
+en:
+  analyze_file:
+    prompt: "Analyze %{file_name} which has %{lines_count} lines and is a %{file_extension} file"
+```
+
+### How It Works
+
+When you use `agent_step` with i18n (either via `prompt_key` or the shorthand syntax), AgentC checks if your record responds to `i18n_attributes`. If it does, that method's return value is used for interpolation. Otherwise, it falls back to `record.attributes`.
+
+This works with both explicit prompt keys:
+
+```ruby
+agent_step(
+  :my_step,
+  prompt_key: "my_step.prompt",
+  cached_prompt_keys: ["my_step.cached"]
+)
+```
+
+And with the shorthand syntax:
+
+```ruby
+agent_step(:my_step)
+```
+
+### Return Value
+
+The `i18n_attributes` method should return a Hash with symbol or string keys. These keys will be used for interpolation in your i18n strings.

data/docs/session-configuration.md

@@ -0,0 +1,274 @@
+# Session Configuration
+
+Note: You probably want to make a `Batch`. See the [main README](../README.md)
+
+This describes how to create a Session object if you just want to chat with Claude through AgentC.
+
+## Overview
+
+AgentC uses a session-based configuration approach that provides isolated configuration with no global state. Each session maintains its own configuration and RubyLLM context, making it ideal for:
+- Testing (no configuration pollution between tests)
+- Multiple concurrent configurations in the same process
+- Better dependency injection and code organization
+
+## Basic Session Configuration
+
+```ruby
+session = Session.new(
+  # all chats with claude are saved to a sqlite db.
+  # this is separate than your Store's db because
+  # why throw anything away. Can be useful for
+  # debugging why Claude did what it did
+  agent_db_path: "/path/to/your/claude/db.sqlite",
+  logger: Logger.new("/dev/null"), # probably use the same logger for everything...
+  i18n_path: "/path/to/your/prompts.yml",
+
+  # as you debug your pipeline, you'll probably run it
+  # many times. We tag all Claude chat records with a
+  # project so you can track costs.
+  project: "SomeProject",
+
+  # only available for Bedrock...
+  ruby_llm: {
+    bedrock_api_key: ENV.fetch("AWS_ACCESS_KEY_ID"),
+    bedrock_secret_key: ENV.fetch("AWS_SECRET_ACCESS_KEY"),
+    bedrock_session_token: ENV.fetch("AWS_SESSION_TOKEN"),
+    bedrock_region: ENV.fetch("AWS_REGION", "us-west-2"),
+    default_model: ENV.fetch("LLM_MODEL", "us.anthropic.claude-sonnet-4-5-20250929-v1:0")
+  }
+)
+
+# Create chats from the session
+chat = session.chat
+response = chat.ask("What is Ruby?")
+
+# Or use the prompt method for one-off requests
+result = session.prompt(
+  prompt: "What is Ruby?",
+  schema: -> { string(:answer) }
+)
+```
+
+## Configuration Options
+
+All session parameters are optional except where noted. If database-related features are needed, `agent_db_path` and `project` become required.
+
+### agent_db_path
+
+Path to the SQLite database file where all LLM interactions will be stored.
+
+```ruby
+session = Session.new(
+  agent_db_path: 'tmp/db/agent.sqlite3'
+)
+```
+
+The database is automatically created if it doesn't exist. All conversations, token usage, and costs are persisted here. Required if using database features (cost tracking, persistence).
+
+### project (required with agent_db_path)
+
+A string identifier for your project. Used to organize and filter cost reports.
+
+```ruby
+session = Session.new(
+  agent_db_path: 'tmp/db/agent.sqlite3',
+  project: 'my_project'
+)
+```
+
+Required when `agent_db_path` is provided.
+
+### workspace_dir
+
+The working directory for file-based tools. Tools like `read_file`, `edit_file`, and `dir_glob` operate relative to this directory.
+
+```ruby
+session = Session.new(
+  workspace_dir: Dir.pwd
+)
+```
+
+Defaults to `Dir.pwd` if not specified.
+
+### run_id
+
+An optional identifier to group related queries. Useful for tracking multiple pipeline runs or sessions.
+
+```ruby
+session = Session.new(
+  run_id: Time.now.to_i
+)
+```
+
+Auto-generated if not provided when `agent_db_path` is configured.
+
+### logger
+
+Custom logger for debugging:
+
+```ruby
+session = Session.new(
+  logger: Logger.new($stdout)
+)
+```
+
+### i18n_path
+
+Path to custom I18n translations file for prompts:
+
+```ruby
+session = Session.new(
+  i18n_path: 'config/locales/prompts.yml'
+)
+```
+
+This is particularly useful when using `agent_step` in Pipeline definitions, where prompts and schemas can be loaded from i18n YAML files.
+
+### max_spend_project
+
+Maximum project cost threshold in dollars. Raises `AgentC::Errors::AbortCostExceeded` when exceeded:
+
+```ruby
+session = Session.new(
+  agent_db_path: 'tmp/db/agent.sqlite3',
+  project: 'my_project',
+  max_spend_project: 10.0  # Abort if project costs exceed $10
+)
+```
+
+### max_spend_run
+
+Maximum run cost threshold in dollars. Raises `AgentC::Errors::AbortCostExceeded` when exceeded:
+
+```ruby
+session = Session.new(
+  agent_db_path: 'tmp/db/agent.sqlite3',
+  project: 'my_project',
+  run_id: 'run_123',
+  max_spend_run: 5.0  # Abort if this run costs exceed $5
+)
+```
+
+### ruby_llm
+
+RubyLLM configuration hash. Each session has its own isolated RubyLLM context:
+
+```ruby
+session = Session.new(
+  ruby_llm: {
+    bedrock_api_key: ENV['AWS_ACCESS_KEY_ID'],
+    bedrock_secret_key: ENV['AWS_SECRET_ACCESS_KEY'],
+    bedrock_region: 'us-west-2',
+    default_model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0'
+  }
+)
+```
+
+Available RubyLLM options:
+- `bedrock_api_key` - AWS access key
+- `bedrock_secret_key` - AWS secret key
+- `bedrock_session_token` - Optional AWS session token
+- `bedrock_region` - AWS region (e.g., 'us-west-2')
+- `default_model` - Model ID to use
+
+### extra_tools
+
+A hash mapping tool names (symbols) to custom tool classes or instances. This allows you to add custom tools beyond the built-in AgentC tools.
+
+```ruby
+session = Session.new(
+  extra_tools: {
+    my_tool: MyCustomTool,           # Class will be initialized
+    another_tool: MyOtherTool.new    # Instance used directly
+  }
+)
+```
+
+When a tool class is provided, AgentC will instantiate it with `workspace_dir:` and `env:` keyword arguments:
+
+```ruby
+# AgentC will call:
+# MyCustomTool.new(workspace_dir: session.workspace_dir, env: session.env)
+```
+
+When a tool instance is provided, it will be used as-is without initialization.
+
+Custom tools must implement the tool interface expected by RubyLLM. See the [Custom Tools documentation](custom-tools.md) for details on implementing custom tools.
+
+## Complete Example
+
+```ruby
+require 'agent_c'
+require 'logger'
+
+# Create a fully configured session
+session = Session.new(
+  # Database and project
+  agent_db_path: 'tmp/db/agent.sqlite3',
+  project: 'document_processor',
+  run_id: Time.now.to_i,
+
+  # Working directory and i18n
+  workspace_dir: Dir.pwd,
+  i18n_path: 'config/locales/agent_prompts.yml',
+
+  # Logging
+  logger: Logger.new($stdout, level: Logger::INFO),
+
+  # Cost controls
+  max_spend_project: 100.0,
+  max_spend_run: 10.0,
+
+  # RubyLLM configuration
+  ruby_llm: {
+    bedrock_api_key: ENV['AWS_ACCESS_KEY_ID'],
+    bedrock_secret_key: ENV['AWS_SECRET_ACCESS_KEY'],
+    bedrock_region: 'us-west-2',
+    default_model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0'
+  },
+
+  # Custom tools (optional)
+  extra_tools: {
+    custom_search: MySearchTool,
+    api_client: MyApiClient.new(api_key: ENV['API_KEY'])
+  }
+)
+
+# Create chats from the session
+chat = session.chat(tools: [:read_file, :edit_file])
+response = chat.ask("What is Ruby?")
+
+# Or use the prompt method for one-off requests
+result = session.prompt(
+  prompt: "Summarize this file",
+  schema: -> { string(:summary) },
+  tools: [:read_file]
+)
+```
+
+## Environment-Specific Configuration
+
+```ruby
+session = Session.new(
+  agent_db_path: ENV['RACK_ENV'] == 'production' ?
+    '/var/db/agent_production.sqlite3' :
+    'tmp/db/agent_development.sqlite3',
+  project: ENV['PROJECT_NAME'] || 'default_project',
+  workspace_dir: Dir.pwd,
+  logger: Logger.new($stdout, level: ENV['LOG_LEVEL'] || 'INFO'),
+  ruby_llm: {
+    bedrock_region: ENV['AWS_REGION'] || 'us-west-2',
+    default_model: ENV['LLM_MODEL'] || 'us.anthropic.claude-sonnet-4-5-20250929-v1:0'
+  }
+)
+```
+
+## AWS Credentials
+
+AgentC uses AWS Bedrock for LLM access. Ensure your AWS credentials are configured via:
+
+- Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`)
+- AWS credentials file (`~/.aws/credentials`)
+- IAM role (when running on EC2/ECS)
+
+No additional configuration is needed in AgentC for AWS credentials.