Spurline

Spurline is a Ruby framework for building production-grade AI agents.

It is opinionated, streaming-first, and security-oriented by default:

• all content is trust-typed (:system, :operator, :user, :external)
• tool output is treated as untrusted external data
• prompt-injection and PII controls are built into the call pipeline
• sessions and audit logs are first-class framework concepts

Status

Spurline is under active development. The core framework is usable and tested, with docs in docs/guides.

Recent hardening shipped:

• secret redaction for tool-call arguments in audit log, session turns, and stream metadata
• three-tier tool secret management (agent overrides, runtime vault, encrypted credentials, ENV fallback)
• structured replay audit events (:llm_request, :llm_response, :tool_call, :tool_result)
• configurable in-memory audit retention (audit_max_entries)
• stubbed integration coverage for guardrails, PII pipeline, SQLite round-trip/concurrency, memory overflow, streaming enumerator tool loops, and audit completeness
• adapter spurs via Spurline::Spur.adapters (for example spurline-local registering :ollama)

Bundled Spurs

Spurline ships the framework as spurline-core and includes bundled reference spur gems under spurs/:

• spurline-web-search: web search tools powered by Brave Search (spurs/spurline-web-search)
• spurline-deploy: supervised deployment planning and execution with safety gates (spurs/spurline-deploy)

spurline-deploy provides four tools:

• generate_deploy_plan (idempotent by repo_path, target, strategy)
• validate_deploy_prereqs (scoped prereq validation)
• execute_deploy_step (always confirmation-gated, dry-run by default)
• rollback_deploy (confirmation-gated rollback with optional auto-detect target version)

Requirements

• Ruby >= 3.2
• Bundler

Install (Framework Development)

git clone git@github.com:dawilco/spurline.git
cd spurline
bundle install
bundle exec rspec

Quick Example

require "spurline"
require "spurline/testing"
include Spurline::Testing

class HelloAgent < Spurline::Agent
  use_model :stub

  persona(:default) do
    system_prompt "You are a concise assistant."
  end
end

agent = HelloAgent.new(user: "dev")
agent.use_stub_adapter(responses: [
  stub_text("Hello from Spurline")
])

agent.run("Say hi") { |chunk| print chunk.text if chunk.text? }

CLI

Spurline ships spur:

bundle exec spur help
bundle exec spur new my_app
bundle exec spur generate agent researcher
bundle exec spur generate tool web_scraper
bundle exec spur check
bundle exec spur console

spur new now includes a project README.md, .env.example, and a starter spec/agents/assistant_agent_spec.rb.

Bundled Spurs

Spurline ships bundled spur gems under spurs/:

• spurline-web-search — Brave-powered web search (:web_search)
• spurline-test — test framework detection, execution, and parsing (:detect_test_framework, :run_tests, :parse_test_output)
• spurline-review — PR diff analysis and GitHub review comment tooling (:fetch_pr_diff, :analyze_diff, :summarize_findings, :post_review_comment)

During local development you can wire a spur gem via path:

# Gemfile
gem "spurline-test", path: "spurs/spurline-test"

Built-in Model Aliases

Use these directly with use_model:

• :claude_sonnet
• :claude_opus
• :claude_haiku
• :openai_gpt4o
• :openai_gpt4o_mini
• :openai_o3_mini
• :stub

Adapter aliases can also come from spurs. For example, requiring spurline/local registers :ollama.

Local Inference (Ollama)

spurline-local adds a local adapter backed by the Ollama HTTP API.

require "spurline"
require "spurline/local"

class LocalAgent < Spurline::Agent
  use_model :ollama, model: "llama3.2:latest"

  persona(:default) do
    system_prompt "You are a helpful local assistant."
  end
end

You can pass adapter kwargs directly through use_model:

class RemoteOllamaAgent < Spurline::Agent
  use_model :ollama, host: "10.0.0.1", port: 8080, model: "codellama:7b"
end

use_model kwargs are forwarded to the adapter constructor.

Core Concepts

• Spurline::Agent: public API and lifecycle
• Spurline::Tools::Base: tool contract and schema
• Spurline::Security::ContextPipeline: injection + PII + rendering gates
• Spurline::Session::Session: persistence/resumption boundary
• Spurline::Audit::Log: structured trace of LLM/tool execution

Documentation

• Getting Started
• Agent DSL
• Agent Lifecycle
• Streaming
• Building Tools
• Security
• Sessions and Memory
• Configuration
• Guides Index

Development Commands

bundle exec rspec
bundle exec rspec spec/spurline/audit
bundle exec ruby -Ilib your_script.rb

License

MIT. See LICENSE.