solid_agent 0.0.0 → 0.2.0

data/examples/README.md

@@ -0,0 +1,60 @@
+# SolidAgent Examples
+
+Runnable, copy-pasteable examples for every SolidAgent concern. Each
+directory mirrors the layout of a Rails app, so the files can be dropped
+into `app/` as-is and the paths tell you where they belong.
+
+Every example assumes the persistence tables and models are installed:
+
+```bash
+bundle add solid_agent
+rails generate solid_agent:install
+rails db:migrate
+```
+
+That generates `AgentContext`, `AgentMessage`, `AgentGeneration`,
+`AgentMemory`, `AgentMemoryEntry` and `AgentRun` into `app/models/`, so they
+are yours to edit — SolidAgent's concerns talk to them through a duck-typed
+contract, not through hard-coded class names.
+
+The narrative walkthrough of these examples lives at
+[docs.activeagents.ai/solid_agent/examples](https://docs.activeagents.ai/solid_agent/examples).
+
+| Example | Concerns | What it shows |
+|---------|----------|---------------|
+| [persistent_conversation](persistent_conversation) | `HasContext` | A support agent whose conversation survives the request, replayed from the database on every turn |
+| [memory_handoff](memory_handoff) | `HasMemory` | Two agents sharing agent-curated notes about the same subject record |
+| [tool_streaming](tool_streaming) | `HasTools`, `StreamsToolUpdates`, `ToolCache` | Declarative tool schemas, live "what is it doing" updates over ActionCable, cached tool results |
+| [reasoning](reasoning) | `HasReasons`, `Reasonable` | Capturing extended-thinking output and persisting it on generation records |
+| [run_tracking](run_tracking) | `AgentRun`, `RunFingerprint`, `ModelPricing` | Durable run records, an append-only progress stream a UI can poll, cohorts and cost |
+| [manifests](manifests) | `AgentManifest` | Defining an agent in a portable `.agent.md` file and loading it as a class |
+
+## Running the examples
+
+The `usage.rb` file in each directory is the console script — the part you
+would paste into `rails console` (or call from a controller/job) once the
+agent files are in place. They are written to be read top to bottom rather
+than executed blind: they hit a provider and write rows.
+
+Prefer to try one without spending tokens? Point the agent at the mock
+provider first:
+
+```ruby
+class SupportAgent < ApplicationAgent
+  generate_with :mock, model: "mock-gpt-4o-mini"
+end
+```
+
+Persistence, memory, runs and the tool cache all behave identically — only
+the model response changes.
+
+## Related documentation
+
+- [SolidAgent overview](https://docs.activeagents.ai/solid_agent)
+- [Conversation context](https://docs.activeagents.ai/solid_agent/context)
+- [Long-term memory](https://docs.activeagents.ai/solid_agent/memory)
+- [Tools, streaming and caching](https://docs.activeagents.ai/solid_agent/tools)
+- [Reasoning](https://docs.activeagents.ai/solid_agent/reasoning)
+- [Runs, cohorts and cost](https://docs.activeagents.ai/solid_agent/runs)
+- [Agent manifests](https://docs.activeagents.ai/solid_agent/manifests)
+- [`.agent.md` specification](../docs/agent-md-spec.md)

data/examples/manifests/changelog_writer.agent.md

@@ -0,0 +1,81 @@
+---
+name: changelog-writer
+version: 1.0.0
+description: Turns a range of merged pull requests into a release changelog
+author: activeagents
+license: MIT
+tags:
+  - writing
+  - release
+
+model: anthropic/claude-sonnet-4-20250514
+config:
+  temperature: 0.3
+  max_tokens: 2048
+
+input:
+  schema:
+    repository: "string, The repository the release belongs to"
+    from?: "string, Git ref the release starts at"
+    to?: "string, Git ref the release ends at"
+    audience?: "string(users, operators, contributors), Who the changelog is written for"
+
+output:
+  format: json
+  schema:
+    type: object
+    properties:
+      headline:
+        type: string
+      entries:
+        type: array
+        items:
+          type: object
+          properties:
+            title:
+              type: string
+            category:
+              type: string
+      breaking:
+        type: array
+        items:
+          type: string
+
+tools:
+  - name: list_merged_pulls
+    description: List pull requests merged between two refs
+    inputSchema:
+      type: object
+      properties:
+        repository:
+          type: string
+        from:
+          type: string
+        to:
+          type: string
+      required:
+        - repository
+
+activeagent:
+  class_name: ChangelogWriterAgent
+  concerns:
+    - has_tools: [list_merged_pulls]
+---
+
+# Changelog Writer
+
+You write release changelogs from merged pull requests.
+
+## Instructions
+
+1. Call `list_merged_pulls` for the requested range.
+2. Group the changes into Added, Changed, Fixed and Removed.
+3. Write one line per change, in the present tense, describing what a
+   reader can now do differently — not which files moved.
+4. List anything that breaks an existing setup under `breaking`, with the
+   migration step spelled out.
+5. Leave a category out entirely rather than padding it.
+
+## Template
+
+Write the changelog for {{ repository }} covering {{ from | default: "the last release" }} to {{ to | default: "HEAD" }}, for an audience of {{ audience | default: "users" }}.

data/examples/manifests/usage.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Portable agent manifests — rails console walkthrough.
+#
+# A manifest is an agent definition that lives in a file instead of a class:
+# frontmatter for the model, tools, input/output schemas and framework
+# extensions, Markdown for the instructions. It can be reviewed in a pull
+# request, shipped to another framework, or loaded into a running app.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/manifests
+# Format spec: https://github.com/activeagents/solid_agent/blob/main/docs/agent-md-spec.md
+
+path = "examples/manifests/changelog_writer.agent.md"
+
+# --- Read ---------------------------------------------------------------
+
+manifest = SolidAgent::AgentManifest.parse(path)
+manifest.name           # => "changelog-writer"
+manifest.model          # => "anthropic/claude-sonnet-4-20250514"
+manifest.tools.map(&:name)
+manifest.instructions   # the Markdown body
+manifest.fingerprint    # stable digest — the version an agent ran under
+
+# `load` takes anything: a path, a URL, a JSON/YAML string, or a Hash.
+SolidAgent::AgentManifest.load("https://example.com/agents/support.agent.md")
+SolidAgent::AgentManifest.load({ name: "quick", model: "openai/gpt-4o-mini" })
+
+# --- Validate -----------------------------------------------------------
+
+SolidAgent::AgentManifest.validate(path)          # => [] when valid
+SolidAgent::AgentManifest.valid?(path)            # => true
+SolidAgent::AgentManifest.validate(path, strict: true)
+SolidAgent::AgentManifest.validate!(path)         # raises ValidationError
+
+# Worth wiring into CI, so a broken manifest fails the build rather than a
+# request:
+Dir["config/agents/**/*.agent.md"].flat_map { |f| SolidAgent::AgentManifest.validate(f) }
+
+# --- Build --------------------------------------------------------------
+
+# Build an agent class from the manifest. The class arrives configured but
+# not finished: it inherits from ApplicationAgent, includes the concerns
+# the manifest asked for, carries the manifest's tool schemas, and keeps
+# the model, provider and instructions as class attributes.
+klass = SolidAgent::AgentManifest.load_agent(path, class_name: "ChangelogWriterAgent")
+
+klass._manifest_provider      # => "anthropic"
+klass._manifest_model         # => "claude-sonnet-4-20250514"
+klass._manifest_instructions  # the Markdown body
+klass._manifest               # the Manifest itself, fingerprint included
+klass.new.tools.map { |t| t[:name] } # => ["list_merged_pulls"]
+
+# `activeagent.class_name` in the frontmatter names the constant, so
+# passing class_name: here is only needed to override it. Name it either
+# way when persisting context — contexts are keyed by class name, and an
+# anonymous class has none.
+
+# What the manifest does not carry is behaviour: actions and tool bodies
+# are still Ruby. Reopen the class and supply them.
+#
+#   class ChangelogWriterAgent
+#     generate_with _manifest_provider.to_sym, model: _manifest_model
+#
+#     def write
+#       prompt instructions: _manifest_instructions,
+#              message: params[:message],
+#              tools: tools
+#     end
+#
+#     # Declared tools raise NotImplementedError until you define them.
+#     def list_merged_pulls(repository:, from: nil, to: nil)
+#       GitHub.merged_pulls(repository, from: from, to: to)
+#     end
+#   end
+#
+#   ChangelogWriterAgent.with(message: "Release 1.2.0").write.generate_now
+
+# --- Convert ------------------------------------------------------------
+
+SolidAgent::AgentManifest.parser_formats    # what can be read
+SolidAgent::AgentManifest.exporter_formats  # what can be written
+
+# Import someone else's definition...
+SolidAgent::AgentManifest.parse("agents.yaml")            # CrewAI
+SolidAgent::AgentManifest.parse("basic.prompt")           # Google Dotprompt
+SolidAgent::AgentManifest.parse("copilot.prompt.md")      # GitHub Copilot
+
+# ...and export yours for them.
+SolidAgent::AgentManifest.export(manifest, :dotprompt)
+SolidAgent::AgentManifest.convert(path, :crewai, "tmp/agents.yaml")
+
+# --- Provenance ---------------------------------------------------------
+
+# What an agent ran under, checksummed — pairs with the provenance
+# HasContext records on every generation.
+SolidAgent::AgentManifest.provenance(manifest)

data/examples/memory_handoff/app/agents/researcher_agent.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# First half of a hand-off: an agent that researches a project and writes
+# what it learned to long-term memory.
+#
+# Memory is scoped to (subject record, scope name) — not to the agent class
+# — so anything this agent saves is readable by any other agent working on
+# the same project. `save_memory` and `recall_memory` are ordinary
+# function-calling tools, so the model decides when to write and when to
+# read; you only decide what the subject is.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/memory
+class ResearcherAgent < ApplicationAgent
+  include SolidAgent::HasMemory
+
+  generate_with :openai, model: "gpt-4o-mini"
+
+  # scope: "default", class_name: "AgentMemory" unless you say otherwise.
+  # Use a scope to give one subject independent memory streams
+  # (has_memory scope: "competitive_research").
+  has_memory
+
+  def research
+    prompt(
+      message: "Research #{params[:project].name} and save what a writer would need to know.",
+      tools: memory_tool_definitions
+    )
+  end
+
+  # memory_subject defaults to params[:memorable], falling back to the
+  # HasContext contextable. Override it when the subject is somewhere else
+  # — here the project the run is about.
+  def memory_subject
+    params[:project]
+  end
+end

data/examples/memory_handoff/app/agents/writer_agent.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Second half of the hand-off: a different agent class, same subject.
+#
+# Two ways to pick up what ResearcherAgent left behind:
+#
+#   1. Give the model the recall tool and let it decide (below).
+#   2. Prime the instructions with `memory.to_prompt` so the notes are in
+#      context from the first token — cheaper, and the model can't forget
+#      to look. `draft_with_primed_memory` does that.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/memory
+class WriterAgent < ApplicationAgent
+  include SolidAgent::HasMemory
+
+  generate_with :openai, model: "gpt-4o-mini"
+
+  has_memory
+
+  def draft
+    prompt(
+      message: "Draft the launch post for #{params[:project].name}.",
+      tools: memory_tool_definitions
+    )
+  end
+
+  def draft_with_primed_memory
+    prompt(
+      instructions: [
+        "You are a product writer.",
+        memory&.to_prompt
+      ].compact.join("\n\n"),
+      message: "Draft the launch post for #{params[:project].name}.",
+      tools: memory_tool_definitions
+    )
+  end
+
+  def memory_subject
+    params[:project]
+  end
+end

data/examples/memory_handoff/usage.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Memory hand-off between two agents — rails console walkthrough.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/memory
+
+project = Project.find(1)
+
+# The researcher calls save_memory as it works. Each note records which
+# agent class wrote it.
+ResearcherAgent.with(project: project).research.generate_now
+
+memory = AgentMemory.for(project)
+memory.recall(limit: 5).map { |e| [ e.source_agent, e.category, e.content ] }
+# => [["ResearcherAgent", "fact", "Ships on the 14th; pricing unchanged"], ...]
+
+# A different agent class, later — possibly a different request, job, or
+# deploy — picks the same subject up and reads those notes back.
+WriterAgent.with(project: project).draft.generate_now
+
+# Or hand the notes over without spending a tool call, by putting them in
+# the instructions:
+memory.to_prompt
+# => "Memory notes for this subject:\n- Ships on the 14th... (ResearcherAgent)"
+
+WriterAgent.with(project: project).draft_with_primed_memory.generate_now
+
+# Scopes keep unrelated streams apart on the same subject:
+AgentMemory.for(project, scope: "competitive_research").remember(
+  "Competitor X ships a similar feature in Q3",
+  source_agent: "MarketAgent",
+  category: "fact"
+)
+
+# Categories filter recall; entries come back newest first.
+memory.recall(category: "handoff", limit: 10)
+
+# Curation is ordinary Active Record — nothing here is append-only by
+# force, so prune when a note goes stale.
+memory.entries.where(category: "task").find_each(&:destroy)
+
+# The same tool contract is available to non-agent executors (a platform
+# service, an MCP server) without including the concern:
+SolidAgent::HasMemory.tool_definitions.map { |t| t[:name] }
+# => ["save_memory", "recall_memory"]

data/examples/persistent_conversation/app/agents/support_agent.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# A support agent whose conversation outlives the request.
+#
+# `has_context :conversation, contextual: :user` persists the prompt, the
+# assistant's reply, and the tool exchange in between to the tables the
+# install generator created — agent_contexts, agent_messages and
+# agent_generations — keyed by the record passed as params[:user].
+#
+# The macro defines the methods used below (load_conversation,
+# conversation_messages, conversation_result, conversation_summary, ...).
+# Name the context something else and the methods rename with it.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/context
+class SupportAgent < ApplicationAgent
+  include SolidAgent::HasContext
+
+  generate_with :openai, model: "gpt-4o-mini"
+
+  # Naming a context also names the models it resolves: :conversation alone
+  # would look for Conversation / ConversationMessage / ConversationGeneration
+  # and raise NameError on the first request. class_name points it back at
+  # what `solid_agent:install` wrote (AgentMessage and AgentGeneration are
+  # inferred from it). Want separate tables instead? Run
+  # `rails generate solid_agent:context conversation` and drop class_name.
+  has_context :conversation, class_name: "AgentContext", contextual: :user
+
+  # Multi-turn: load the stored conversation, append this turn's question,
+  # and send the whole history as the prompt.
+  #
+  # Nothing here writes to the database. With auto_save on (the default),
+  # SolidAgent persists the last prompt message as the user turn and the
+  # response as the assistant turn, both after the provider call — so the
+  # next request replays this exchange. Add messages by hand only with
+  # `auto_save: false`, or the turn is stored twice.
+  #
+  # `contextual: :user` alone would create the context for you, but it runs
+  # after the prompt is built — a conversation has to be loaded *before*
+  # that to replay its messages, so load it explicitly here.
+  def answer
+    load_conversation(contextable: params[:user])
+
+    prompt messages: conversation_messages + [
+      { role: "user", content: params[:message] }
+    ]
+  end
+
+  # Contexts are keyed by (contextable, agent_name, action_name), so a
+  # second action gets its own row rather than appending to the chat
+  # history. To work against an existing conversation from a different
+  # entry point, load it by id instead of by contextable.
+  def summarize
+    load_conversation(context_id: params[:conversation_id])
+
+    prompt messages: conversation_messages + [
+      { role: "user", content: "Summarize this conversation in three bullet points." }
+    ]
+  end
+end

data/examples/persistent_conversation/app/controllers/support_conversations_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The web side of a persisted conversation: one POST per turn, and a show
+# action that renders the history straight out of the database — no session
+# state, no cache, nothing to warm up after a deploy.
+class SupportConversationsController < ApplicationController
+  def show
+    @conversation = AgentContext
+      .for_agent("SupportAgent")
+      .for_action("answer")
+      .find_by!(contextable: current_user)
+
+    @messages = @conversation.messages.chronological
+  end
+
+  def create
+    response = SupportAgent.with(
+      user: current_user,
+      message: params.require(:message)
+    ).answer.generate_now
+
+    render json: { reply: response.message.content }
+  end
+end

data/examples/persistent_conversation/app/views/agents/support/instructions.md.erb

@@ -0,0 +1,8 @@
+You are a support agent.
+
+Answer in two short paragraphs at most. When you do not know something, say
+so and name the next step the customer should take rather than guessing.
+
+<%# Instructions are always rendered from this template. The action
+    template (answer.md.erb) is only a fallback for the message — pass
+    `messages:` to prompt, as SupportAgent#answer does, and it is skipped. %>

data/examples/persistent_conversation/usage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Persistent conversation — rails console walkthrough.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/context
+
+user = User.first
+
+# Turn one. The context row, the user message and the assistant message are
+# all written during generate_now.
+SupportAgent.with(user: user, message: "My invoice is wrong").answer.generate_now
+
+# Turn two. The agent replays turn one from the database before asking.
+SupportAgent.with(user: user, message: "It's the VAT line").answer.generate_now
+
+conversation = AgentContext.for_agent("SupportAgent").find_by(contextable: user)
+
+conversation.messages.chronological.map { |m| [ m.role, m.content ] }
+# => [["user", "My invoice is wrong"],
+#     ["assistant", "..."],
+#     ["user", "It's the VAT line"],
+#     ["assistant", "..."]]
+
+conversation.total_tokens        # cumulative across both turns
+conversation.generations.count   # => 2, one row per provider call
+
+# Every generation carries what produced it: model, finish reason, token
+# split, duration, raw provider payload, and a provenance snapshot of the
+# agent/prompt/context checksums at the time.
+generation = conversation.generations.last
+generation.model                 # => "gpt-4o-mini"
+generation.total_tokens
+generation.estimated_cost        # => USD estimate via SolidAgent::ModelPricing
+generation.provenance["agent_checksum"]
+
+# Thread a distributed trace id through prompt_options and the generation
+# joins up with your telemetry:
+#
+#   def answer
+#     prompt_options[:trace_id] = Current.trace_id
+#     ...
+#   end
+#
+AgentGeneration.with_trace("some-trace-id")
+AgentContext.with_trace("some-trace-id")
+
+# Reading a conversation back for a UI is plain Active Record — the
+# generated models are yours, scopes included.
+conversation.messages.assistant_messages.last&.content
+AgentContext.for_agent("SupportAgent").recent.limit(10)
+user.agent_contexts if user.respond_to?(:agent_contexts) # add the has_many yourself

data/examples/reasoning/app/agents/analysis_agent.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Capturing extended thinking.
+#
+# Models that expose reasoning (Claude's extended thinking, OpenAI's
+# reasoning models) return it alongside the answer. HasReasons collects it
+# on the agent instance and, with `persist: true`, writes it onto the
+# generation record so it survives the request — as long as that model
+# includes SolidAgent::Reasonable and has the columns:
+#
+#   rails generate solid_agent:reasons AgentGeneration
+#   rails db:migrate
+#
+# Reasoning is model output about its own process: treat it as sensitive.
+# `redact_on_persist: true` keeps the token counts and drops the text.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/reasoning
+class AnalysisAgent < ApplicationAgent
+  include SolidAgent::HasContext
+  include SolidAgent::HasReasons
+
+  generate_with :anthropic, model: "claude-sonnet-5"
+
+  # Reasoning is read off the response, so it has to be handed to
+  # capture_reasoning once the provider has answered. Declared *before*
+  # has_context on purpose: around callbacks nest in declaration order, so
+  # this one wraps HasContext's — and by the time it runs, the generation
+  # row that `persist: true` updates has been written.
+  around_generation :capture_generation_reasoning
+
+  has_context contextual: :document
+
+  has_reasons auto_capture: true,       # reasoning_prompt_options asks for thinking
+              persist: true,            # store on the generation record
+              budget_tokens: 10_000,    # default thinking budget
+              redact_on_persist: false  # true stores "[Redacted]" + tokens
+
+  def analyze
+    prompt(
+      message: "What risks does this contract create for the buyer?",
+      **reasoning_prompt_options # extended_thinking + budget from has_reasons
+    )
+  end
+
+  private
+
+  def capture_generation_reasoning
+    response = yield
+    capture_reasoning(response)
+    response
+  end
+end

data/examples/reasoning/usage.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Reasoning capture — rails console walkthrough.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/reasoning
+
+document = Document.find(1)
+
+AnalysisAgent.with(document: document).analyze.generate_now
+
+# Persisted (persist: true + SolidAgent::Reasonable on the model). This is
+# what survives the request:
+generation = AgentGeneration.recent.first
+generation.reasoning_content
+generation.reasoning_tokens
+generation.has_reasoning?
+generation.reasoning_summary(length: 120)
+generation.thinking?           # reasoning_tokens > 0 on the generated model
+
+# In-memory, on the agent instance that ran — reachable from inside an
+# action or a callback, not from the console after the fact:
+#
+#   def analyze
+#     prompt(...)
+#   end
+#
+#   def after_response
+#     reasons                  # => [SolidAgent::Reasonable::Reason, ...]
+#     last_reasoning&.content
+#     total_reasoning_tokens
+#     has_reasoning?
+#     reasoning_chain          # every non-redacted reason, joined
+#     reasoning_stats
+#     # => { count: 2, total_tokens: 450, total_thinking_time_ms: 1200,
+#     #      redacted_count: 0, models: ["claude-sonnet-5"] }
+#   end
+
+# Storing reasoning by hand — from a provider response, or as a note:
+generation.store_reasoning!(response)
+generation.store_reason!(
+  SolidAgent::Reasonable::Reason.new(content: "Chose the strict parser", tokens: 0)
+)
+
+# Reasoning columns on any generation-shaped model:
+#
+#   rails generate solid_agent:reasons MyGeneration \
+#     --content_column thinking_trace --tokens_column think_tokens
+#
+#   class MyGeneration < ApplicationRecord
+#     include SolidAgent::Reasonable
+#     reasonable_config column: :thinking_trace, tokens_column: :think_tokens
+#   end

data/examples/run_tracking/app/agents/report_agent.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# The agent the run records. Two details matter for run tracking:
+#
+# - the instructions are a constant, so the executor can fingerprint the
+#   exact text a run executed under (see DocumentAnalysisRun),
+# - the caller's trace id is threaded into prompt_options, so the
+#   generation row, the context row and the run all carry the same
+#   trace_id and can be joined with your telemetry.
+#
+# Docs: https://docs.activeagents.ai/solid_agent/runs
+class ReportAgent < ApplicationAgent
+  include SolidAgent::HasContext
+
+  INSTRUCTIONS = <<~TEXT.freeze
+    You are a document analyst. Answer only from the document you are given,
+    quote the clause you are relying on, and say plainly when the document
+    does not cover the question.
+  TEXT
+
+  generate_with :openai, model: "gpt-4o-mini"
+
+  has_context contextual: :document
+
+  def analyze
+    prompt_options[:trace_id] = params[:trace_id] if params[:trace_id]
+
+    prompt instructions: INSTRUCTIONS, message: params[:question]
+  end
+end