solid_agent 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52f173d6c45fc416105fb4a93760dc7aacc81061b75bada9820fce835e9652dd
-  data.tar.gz: '07348df42b87220dea84691d61a11cac6e6576cebbcbe2272c702a0bed6f539c'
+  metadata.gz: 2b204dd708358a41a24ed81cb3e27a76c83b97bd6b69fb098eeaf9a3c54d4ddd
+  data.tar.gz: 3ee800cb2936615ee7ac57072da8a26c6152bf73e92088c8853a8cbcdd3b4a6b
 SHA512:
-  metadata.gz: ffd6386b0d71a95df1ac198c9590bbf337bf7e1a37ccc19e17eb57afbbcf544260fe7e2e552ba8470d4091d636a5b7b074aa5e7745d9d17021af839704b81f46
-  data.tar.gz: bcb89c355432829006b38157c727c271b4b63c86aa09a67d14611b16896f515406dfbf5d84f45c1b2b53a9e4adae6d4cfa250397271f3bb0f8e029f15417d5b4
+  metadata.gz: 4a9d1c5133162f5ebd32fe1cf90ac999cd9b0f0f9c64396eb4e59ef9b60ca3d871e79c5d6e83fe50a830bfbbea6677837ff5ad0e0ca8e32277b885c577d63e9c
+  data.tar.gz: 6e3d799d6cb5321f10455d2a954cb24d2c41a0768c88489a86eb24f6bfe84f5b4ae25fffc614e60f0edfd05c517dc6dfef66c79c078e125d9ed275fa581e27a9

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- **`SolidAgent::Records::*` — behavior for the agent-configuration records.**
+  `Agent`, `AgentVersion`, `AgentTemplate`, `AgentRun` and `Ownable` ship as
+  concerns; the model classes stay host-owned in `app/models`. Every
+  cross-model reference resolves through `SolidAgent.agent_class` and its
+  siblings at call time, so the gem never names `Agent` as a constant and never
+  constantizes during load. The concerns are required eagerly, which is safe
+  because nothing in them touches an ActiveRecord API until a host model
+  includes one — `require "solid_agent"` in a process with no ActiveRecord
+  defines the modules and loads nothing else.
+
+  This folds the ActiveAgents platform's drifted model copies back onto the
+  gem, as tracked in activeagent's `docs/framework/v2-extraction-roadmap.md`.
+
+- **`SolidAgent.run_executor`** — the seam for executing an agent record.
+  Building an agent class from stored provider/model/instructions is
+  execution, which belongs to activeagent and the host, so the gem defines the
+  contract and the host fills it. The default raises with instructions rather
+  than returning mock data.
+
+- **`SolidAgent.records_installed?`** — answers false both when the model
+  constant is missing and when its migration has not run, so a consumer that
+  must degrade (activeagent's dashboard being the motivating one) can check
+  once instead of failing late.
+
+- **Record test harness** (`test/records/`, `rake test:records`) running
+  against a real ActiveRecord on sqlite `:memory:`. The unit harness mocks
+  `ActiveRecord::Base`, which would put a fake under the real one, so the two
+  cannot share a process. `rake` runs both.
+
+- **`CHANGELOG.md`**, which the gemspec already advertised.
+
+### Fixed
+
+- `SolidAgent.context_class`, `message_class` and `generation_class` had no
+  consumers while the shipped initializer template told hosts to set them, so
+  uncommenting it did nothing. `HasContext#infer_class_names` now reads them.
+
+- Sibling class-name derivation chained
+  `delete_suffix("Context").delete_suffix("Session")`, reducing
+  `SessionContext` to `""` and yielding a bare `Message`/`Generation` pair that
+  collided across every context in an app. Extracted to
+  `SolidAgent::ModelNaming`, which strips at most one suffix and is now the
+  single place that knows the rule — the context generator derived the same
+  names independently, which is how they drifted.
+
+- `require "solid_agent"` outside Rails raised `NameError` on
+  `ActiveSupport::Concern`; the gem assumed a host had already loaded
+  ActiveSupport for it. It now requires the pieces it calls. The unit
+  harness's hand-rolled String inflections went with it — they were defined
+  *after* `require "solid_agent"` and had been shadowing ActiveSupport's, so
+  the suite was exercising a toy `camelize` while production ran the real one.
+
+### Changed
+
+- `activemodel` is now a declared dependency. `AgentManifest` has always been
+  an ActiveModel; it arrived transitively through `activerecord`, and a require
+  deserves a declaration.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Active Agents AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,13 +1,41 @@
+<p align="center">
+  <img src="assets/solid_agent.png" alt="SolidAgent" width="200">
+</p>
+
 # SolidAgent
 
-SolidAgent extends the [ActiveAgent](https://github.com/activeagents/activeagent) framework with enterprise-grade features for building robust AI agents in Rails applications. It provides three core concerns that add database-backed persistence, declarative tool schemas, and real-time streaming capabilities to your agents.
+[![Gem Version](https://img.shields.io/gem/v/solid_agent?logo=rubygems&color=CC342D)](https://rubygems.org/gems/solid_agent)
+[![Downloads](https://img.shields.io/gem/dt/solid_agent?label=downloads)](https://rubygems.org/gems/solid_agent)
+[![CI](https://github.com/activeagents/solid_agent/actions/workflows/ci.yml/badge.svg)](https://github.com/activeagents/solid_agent/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-docs.activeagents.ai%2Fsolid__agent-2563eb)](https://docs.activeagents.ai/solid_agent)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-CC342D)](https://www.ruby-lang.org)
+[![ActiveAgent](https://img.shields.io/badge/activeagent-%3E%3D%201.0-D30001)](https://github.com/activeagents/activeagent)
+[![License](https://img.shields.io/github/license/activeagents/solid_agent)](LICENSE)
+
+SolidAgent extends the [ActiveAgent](https://github.com/activeagents/activeagent) framework with database-backed persistence for everything an agent does in a Rails application: conversations, generations, tool/MCP interactions, reasoning, and long-term memory.
+
+**[Documentation](https://docs.activeagents.ai/solid_agent)** ·
+**[Examples](examples)** ·
+**[`.agent.md` spec](docs/agent-md-spec.md)**
 
 ## Features
 
-- **HasContext** - Database-backed prompt context management for maintaining conversation history and agent state
+Agent-side concerns:
+
+- **HasContext** - Database-backed prompt context management for maintaining conversation history and agent state, including the full tool/MCP interaction stream
+- **HasMemory** - An agent-curated summary list the model reads/writes via `save_memory`/`recall_memory` function-calling tools; scoped to a subject record so agents hand off to each other through shared memory
 - **HasTools** - Declarative, schema-based tool definitions compatible with LLM function-calling APIs
+- **HasReasons** - Capture and inspect extended-thinking/reasoning output across a generation
 - **StreamsToolUpdates** - Real-time UI feedback during tool execution via ActionCable
 
+Model-side and standalone:
+
+- **Reasonable** - Persist reasoning content/tokens/metadata on your generation records
+- **AgentRun** - Durable run records (installed by the generator): lifecycle status, append-only progress events for live UIs, token/duration accounting, and instruction-fingerprint cohorts for comparing configuration changes
+- **ToolCache** - Cache tool/MCP/service results by `(tool, normalized args)` with TTL, backed by `Rails.cache`; error results are never cached and replays are tagged `cached: true`
+- **ModelPricing** - Token-count → estimated USD cost, using RubyLLM's model registry when available with a static pattern-table fallback
+- **AgentManifest** - Load, validate, export, and build agent classes from portable manifests (`.agent.md`, dotprompt, CrewAI)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,20 +50,16 @@ And then execute:
 $ bundle install
 ```
 
-Or install it yourself as:
-
-```bash
-$ gem install solid_agent
-```
-
 ## Usage
 
 ### Quick Start
 
-Generate a new agent with context support:
+Install the persistence tables and models (`AgentContext`, `AgentMessage`, `AgentGeneration`, `AgentMemory`, `AgentMemoryEntry`, `AgentRun`), then generate an agent with context support:
 
 ```bash
-$ rails generate solid_agent:agent WritingAssistant --context --context_name conversation --contextable user
+$ rails generate solid_agent:install
+$ rails db:migrate
+$ rails generate solid_agent:agent WritingAssistant --context --context_name conversation --contextual user
 ```
 
 ### HasContext - Persistent Conversation History
@@ -46,12 +70,14 @@ Add database-backed context management to your agents:
 class WritingAssistantAgent < ApplicationAgent
   include SolidAgent::HasContext
 
-  has_context :conversation, contextable: :user
+  has_context :conversation, class_name: "AgentContext", contextual: :user
 
   def improve
-    load_conversation(contextable: current_user)
-    add_conversation_user_message(params[:message])
-    prompt messages: conversation_messages
+    load_conversation(contextable: params[:user])  # contextable is the polymorphic association
+
+    prompt messages: conversation_messages + [
+      { role: "user", content: params[:message] }
+    ]
   end
 end
 ```
@@ -63,6 +89,42 @@ This generates helper methods like:
 - `add_conversation_assistant_message(content)` - Add an AI response
 - `conversation_result` - Get the last assistant message
 
+With `auto_save` on (the default), the last prompt message is persisted as
+the user turn and the response as the assistant turn, both after the
+provider call — so reach for `add_conversation_user_message` only with
+`auto_save: false`, or the turn is stored twice.
+
+> **Naming a context also names its models.** `has_context :conversation`
+> infers `Conversation`, `ConversationMessage` and `ConversationGeneration`,
+> not the `AgentContext` family the installer wrote — hence `class_name:`
+> above, which infers `AgentMessage` and `AgentGeneration` alongside it.
+> Unnamed `has_context` resolves to those models directly; for genuinely
+> separate tables per context, run
+> `rails generate solid_agent:context conversation`.
+
+> **Note:** contexts are persisted under `self.class.name` — agents built
+> with anonymous `Class.new(...)` must define a class name or context
+> creation will fail the `agent_name` presence validation.
+
+#### Telemetry trace correlation
+
+Every persisted generation records a `trace_id` and a provenance snapshot
+(agent/prompt/context checksums). Thread a distributed trace id — for
+example an `ActiveAgent::Telemetry` trace — through prompt options and it
+lands on the `agent_generations` row, joining conversation records to
+telemetry traces:
+
+```ruby
+def improve
+  prompt_options[:trace_id] = my_telemetry_trace_id
+  load_conversation(contextable: current_user)
+  prompt messages: conversation_messages
+end
+```
+
+Query with `AgentGeneration.with_trace(trace_id)` or
+`AgentContext.with_trace(trace_id)`.
+
 ### HasTools - Declarative Tool Schemas
 
 Define tools inline with a clean DSL:
@@ -103,28 +165,157 @@ class BrowserAgent < ApplicationAgent
 end
 ```
 
+### HasMemory - Agent-Curated Long-Term Memory
+
+Give an agent a durable summary list it decides when to read and write, scoped to a subject record rather than the agent class — so different agents operating on the same subject share memory, with `source_agent` provenance on every entry:
+
+```ruby
+class SupportAgent < ApplicationAgent
+  include SolidAgent::HasContext
+  include SolidAgent::HasMemory
+
+  has_context contextual: :user
+  has_memory # scope: "default", class_name: "AgentMemory"
+
+  def assist
+    load_context(contextable: params[:user])
+    prompt messages: context_messages, tools: memory_tool_definitions
+  end
+end
+```
+
+The model calls `save_memory(content:, category:)` and `recall_memory(category:, limit:)` as ordinary function-calling tools. `SolidAgent::HasMemory.tool_definitions` exposes the same schemas module-level for non-agent executors (platform services, MCP servers). Inject `agent.memory.to_prompt` into instructions to prime a handoff.
+
+### ToolCache - Cached Tool Results
+
+```ruby
+result = SolidAgent::ToolCache.fetch(tool: "fetch_url", args: { url: url }, ttl: 300) do
+  expensive_call(url)
+end
+result[:cached] # => true on a replay
+```
+
+Error-shaped results (`{ error: ... }`) are never cached, so transient failures don't stick; cache keys are stable across argument ordering and symbol/string keys.
+
+### AgentRun - Durable Run Records
+
+Executors record each agent execution as an `AgentRun`: lifecycle (`start!`/`complete!`/`fail!`/`cancel!`), correlation with contexts, generations, and telemetry via `trace_id`, and an append-only progress-event stream a UI can poll mid-run:
+
+```ruby
+run = AgentRun.create!(runnable: document, agent_name: "SupportAgent", input_prompt: message)
+run.record_instructions(agent.instructions) # cohort fingerprint ("calm-heron")
+run.start!
+run.append_event(kind: "tool", label: "fetch_url", eid: "e1", status: "started")
+# ... execute ...
+run.append_event(kind: "tool", label: "fetch_url", eid: "e1", status: "done", duration_ms: 120)
+run.complete!(output: response.message.content, input_tokens: usage.input_tokens, output_tokens: usage.output_tokens)
+```
+
+`AgentRun#instructions_codename` names each instruction cohort deterministically (`SolidAgent::RunFingerprint`), so comparing "what changed between these two batches of runs" reads as `calm-heron` vs `misty-atoll` instead of hex digests.
+
+### ModelPricing - Estimated Spend
+
+```ruby
+SolidAgent::ModelPricing.estimate(model: "claude-sonnet-5", input_tokens: 12_000, output_tokens: 800)
+# => 0.048 (USD, estimated)
+```
+
+The generated `AgentGeneration#estimated_cost` uses this automatically. Rates come from RubyLLM's registry when that gem is present, else a static pattern table.
+
 ### Generators
 
 ```bash
+# Install persistence tables + models (contexts, messages, generations, memories)
+$ rails generate solid_agent:install
+
 # Generate a new agent
 $ rails generate solid_agent:agent MyAgent
 
-# Generate with context support
+# Generate with context support. --context_name emits
+# `has_context :session`, which resolves Session/SessionMessage/
+# SessionGeneration — pair it with the context generator below, or drop the
+# option to use the installed AgentContext models.
 $ rails generate solid_agent:agent MyAgent --context --context_name session
 
 # Generate a tool template
 $ rails generate solid_agent:tool search MyAgent --parameters query:string:required
 
-# Generate context models
+# Generate custom-named context models
 $ rails generate solid_agent:context conversation
+
+# Add reasoning columns to a generation model
+$ rails generate solid_agent:reasons AgentGeneration
+
+# Scaffold an agent manifest (.agent.md)
+$ rails generate solid_agent:manifest research
 ```
 
+## Examples
+
+The [`examples/`](examples) directory has a worked example per concern —
+agent classes, views, controllers and console walkthroughs laid out the way
+they'd sit in a Rails app:
+
+| Example | Concerns |
+|---------|----------|
+| [persistent_conversation](examples/persistent_conversation) | `HasContext` |
+| [memory_handoff](examples/memory_handoff) | `HasMemory` |
+| [tool_streaming](examples/tool_streaming) | `HasTools`, `StreamsToolUpdates`, `ToolCache` |
+| [reasoning](examples/reasoning) | `HasReasons`, `Reasonable` |
+| [run_tracking](examples/run_tracking) | `AgentRun`, `RunFingerprint`, `ModelPricing` |
+| [manifests](examples/manifests) | `AgentManifest` |
+
+The narrated versions live at
+[docs.activeagents.ai/solid_agent](https://docs.activeagents.ai/solid_agent).
+
+## Example Apps
+
+See SolidAgent in action:
+
+- [Fizzy](https://github.com/tonsoffun/fizzy) - AI-enhanced Kanban tracking tool with writing, research, and file analysis agents
+- [Writebook](https://github.com/tonsoffun/writebook) - Collaborative writing platform with integrated AI writing assistance, research, and document analysis
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-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).
+```bash
+bundle exec rake test
+```
+
+### Testing against ActiveAgent
+
+This suite runs against mocks — deliberately, so it stays fast and
+dependency-free — which means it can pass while these concerns no longer
+compose with the framework they extend. ActiveAgent carries a dummy Rails
+app and a cross-repo suite for exactly that. Point it at your working tree:
+
+```bash
+git clone https://github.com/activeagents/activeagent ../activeagent
+cd ../activeagent
+
+SOLID_AGENT_PATH=../solid_agent \
+  BUNDLE_GEMFILE=gemfiles/solid_agent_main.gemfile \
+  SOLID_AGENT_STRICT=1 \
+  bin/test test/integration/solid_agent/*_test.rb \
+           actionagent/test/agent_execution_service_test.rb
+```
+
+`SOLID_AGENT_STRICT=1` fails on anything the suite would otherwise skip for
+a missing API — here the resolved gem *is* your checkout, so a skip means
+something was removed. CI runs this on every pull request against
+ActiveAgent's main branch and its latest release, and again nightly. See
+[Releasing & Cross-Repo Testing](https://docs.activeagents.ai/contributing/releasing).
+
+### Releasing
+
+Releases publish from a `v*` tag through
+[.github/workflows/release.yml](.github/workflows/release.yml) using RubyGems
+trusted publishing, gated on CI including the cross-repo suite. Bump
+`SolidAgent::VERSION`, tag, push. This gem depends on `activeagent` and
+`actionagent` depends on this gem, so anything requiring a new framework API
+waits for that release to land on RubyGems first.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/solid_agent.
+Bug reports and pull requests are welcome on GitHub at https://github.com/activeagents/solid_agent.

data/Rakefile

@@ -3,10 +3,30 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+# Two suites, two processes. Rake::TestTask forks one Ruby per task, which is
+# the point: these harnesses cannot share a process.
+#
+# * test/ (unit) hand-rolls stand-ins for Rails and ActiveModel so the concerns
+#   run with no Rails and no database.
+# * test/records/ boots a real ActiveRecord on sqlite :memory:. Loading it into
+#   the unit process would put a genuine ActiveRecord::Base underneath the mock
+#   one, and the two disagree about everything.
+#
+# Splitting them is what keeps both harnesses honest — and what makes a failure
+# name the harness it happened in.
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/records/**/*_test.rb")
 end
 
-task default: :test
+namespace :test do
+  desc "Run the record concerns against a real ActiveRecord on sqlite"
+  Rake::TestTask.new(:records) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/records/**/*_test.rb"]
+  end
+end
+
+task default: [ :test, "test:records" ]