spurline-core 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cae2c379d4f118c54c94f1d9e37936a4a7801117209ae048a7021bfdc8d912d8
+  data.tar.gz: 79b2dddbd5eb414c2370694d25f8b97e2ff8e275981e74ac946aed82e0f484a5
+SHA512:
+  metadata.gz: 5554bc94698551f59c07621d68f34fb72438ee2c47cd44a365e5b0124a98265cef1edb0f387ef7d4099b6208e435fb1861711270de0c03828eec348e4e69ac84
+  data.tar.gz: 52577fcd9a698e86128dbefde465173a75acd2b7f5d776e90e5507138adb29a50f17e04b0521bdee1afd0c49b373141d4c22e82cf4571e3df412fa8ec6a4d4b2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dylan Wilcox
+
+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

@@ -0,0 +1,177 @@
+# 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)
+
+```bash
+git clone git@github.com:dawilco/spurline.git
+cd spurline
+bundle install
+bundle exec rspec
+```
+
+## Quick Example
+
+```ruby
+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`:
+
+```bash
+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:
+
+```ruby
+# 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.
+
+```ruby
+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`:
+
+```ruby
+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](docs/guides/01_getting_started.md)
+- [Agent DSL](docs/guides/02_agent_dsl.md)
+- [Agent Lifecycle](docs/guides/03_agent_lifecycle.md)
+- [Streaming](docs/guides/04_streaming.md)
+- [Building Tools](docs/guides/05_building_tools.md)
+- [Security](docs/guides/07_security.md)
+- [Sessions and Memory](docs/guides/08_sessions_and_memory.md)
+- [Configuration](docs/guides/12_configuration.md)
+- [Guides Index](docs/guides/README.md)
+
+## Development Commands
+
+```bash
+bundle exec rspec
+bundle exec rspec spec/spurline/audit
+bundle exec ruby -Ilib your_script.rb
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/spur

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "spurline"
+
+Spurline::CLI::Router.run(ARGV)

data/lib/CLAUDE.md

@@ -0,0 +1,11 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3734 | 10:05 PM | 🔵 | Cartographer repository analysis system verified as complete and production-ready | ~1142 |
+</claude-mem-context>

data/lib/spurline/CLAUDE.md

@@ -0,0 +1,16 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3782 | 10:23 PM | 🔵 | Spurline session and state machine architecture analyzed for suspended sessions feature | ~700 |
+| #3734 | 10:05 PM | 🔵 | Cartographer repository analysis system verified as complete and production-ready | ~1142 |
+| #3733 | 10:04 PM | 🔵 | Cartographer repository analysis system verified complete and production-ready with all six analyzers | ~1347 |
+| #3677 | 9:11 PM | ✅ | Version bumped to 0.2.0 | ~215 |
+| #3664 | 8:45 PM | 🔵 | Spurline Milestone 1 implementation status audit completed | ~598 |
+| #3661 | 7:57 PM | 🔵 | Code quality review confirmed Plans 01-02 are production-ready with zero issues | ~791 |
+</claude-mem-context>

data/lib/spurline/adapters/CLAUDE.md

@@ -0,0 +1,12 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3631 | 6:00 PM | ⚖️ | Long-term memory architecture with pgvector and OpenAI embeddings | ~501 |
+| #3632 | " | ⚖️ | OpenAI adapter architecture with stop reason normalization and tool call accumulation | ~541 |
+</claude-mem-context>

data/lib/spurline/adapters/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    # Abstract base class for LLM adapters. Adapters translate between
+    # Spurline's internal representation and a specific LLM API.
+    #
+    # The primary interface is #stream (ADR-001). The scheduler parameter
+    # is the async seam (ADR-002).
+    class Base
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system:, tools:, config:, scheduler: Scheduler::Sync.new, &chunk_handler)
+        raise NotImplementedError, "#{self.class.name} must implement #stream"
+      end
+    end
+  end
+end

data/lib/spurline/adapters/claude.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+require "json"
+
+module Spurline
+  module Adapters
+    # Claude adapter using the official anthropic gem.
+    # Translates between Spurline's internal representation and the Claude API.
+    #
+    # This adapter streams responses and converts API events into
+    # Spurline::Streaming::Chunk objects.
+    class Claude < Base
+      DEFAULT_MODEL = "claude-sonnet-4-20250514"
+      DEFAULT_MAX_TOKENS = 4096
+
+      def initialize(api_key: nil, model: nil, max_tokens: nil)
+        @api_key = resolve_api_key(api_key)
+        @model = model || DEFAULT_MODEL
+        @max_tokens = max_tokens || DEFAULT_MAX_TOKENS
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system: nil, tools: [], config: {}, scheduler: Scheduler::Sync.new, &chunk_handler)
+        model = config[:model] || @model
+        max_tokens = config[:max_tokens] || @max_tokens
+        turn = config[:turn] || 1
+        pending_tool_input_snapshots = []
+
+        scheduler.run do
+          client = build_client
+
+          params = {
+            model: model,
+            max_tokens: max_tokens,
+            messages: format_messages(messages),
+          }
+
+          params[:system] = system if system && !system.empty?
+          params[:tools] = format_tools(tools) if tools && !tools.empty?
+          params[:tool_choice] = config[:tool_choice] if config[:tool_choice]
+
+          client.messages.stream(**params).each do |event|
+            handle_stream_event(
+              event,
+              turn: turn,
+              pending_tool_input_snapshots: pending_tool_input_snapshots,
+              &chunk_handler
+            )
+          end
+        end
+      end
+
+      private
+
+      def resolve_api_key(explicit_key)
+        candidates = [
+          explicit_key,
+          ENV.fetch("ANTHROPIC_API_KEY", nil),
+          Spurline.credentials["anthropic_api_key"],
+        ]
+        key = candidates.find { |value| present_string?(value) }
+        return key if key
+
+        raise Spurline::ConfigurationError,
+          "Missing Anthropic API key for adapter :claude. " \
+          "Set ANTHROPIC_API_KEY, add anthropic_api_key to Spurline.credentials, " \
+          "or pass api_key:."
+      end
+
+      def present_string?(value)
+        return false if value.nil?
+        return !value.strip.empty? if value.respond_to?(:strip)
+
+        true
+      end
+
+      def build_client
+        require "anthropic"
+        Anthropic::Client.new(api_key: @api_key)
+      rescue LoadError
+        raise Spurline::ConfigurationError,
+          "The 'anthropic' gem is required for adapter :claude. " \
+          "Add `gem \"anthropic\"` to your Gemfile."
+      end
+
+      def format_messages(messages)
+        messages.map do |msg|
+          content = msg[:content]
+
+          # Content blocks (tool_use, tool_result) pass through as-is
+          formatted_content = if content.is_a?(Array)
+            content
+          else
+            content.to_s
+          end
+
+          {
+            role: msg[:role] || "user",
+            content: formatted_content,
+          }
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |tool|
+          {
+            name: tool[:name].to_s,
+            description: tool[:description].to_s,
+            input_schema: tool[:input_schema] || {},
+          }
+        end
+      end
+
+      def handle_stream_event(event, turn:, pending_tool_input_snapshots:, &chunk_handler)
+        case event
+        when Anthropic::Streaming::TextEvent
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :text,
+              text: event.text,
+              turn: turn,
+            )
+          )
+        when Anthropic::Streaming::InputJsonEvent
+          snapshot = event.respond_to?(:snapshot) ? event.snapshot : nil
+          normalized = normalize_tool_arguments(snapshot)
+          pending_tool_input_snapshots << normalized unless normalized.empty?
+        when Anthropic::Streaming::ContentBlockStopEvent
+          content_block = event.content_block
+          return unless content_block && content_block.type.to_s == "tool_use"
+
+          tool_name = content_block.name.to_s
+          arguments = normalize_tool_arguments(content_block.input)
+          if arguments.empty? && pending_tool_input_snapshots.any?
+            arguments = pending_tool_input_snapshots.last
+          end
+          pending_tool_input_snapshots.clear
+
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :tool_start,
+              turn: turn,
+              metadata: {
+                tool_name: tool_name,
+                tool_use_id: content_block.id,
+                tool_call: {
+                  name: tool_name,
+                  arguments: arguments,
+                },
+              }
+            )
+          )
+        when Anthropic::Streaming::MessageStopEvent
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :done,
+              turn: turn,
+              metadata: { stop_reason: event.message.stop_reason.to_s }
+            )
+          )
+        end
+      end
+
+      def normalize_tool_arguments(raw_input)
+        case raw_input
+        when nil
+          {}
+        when Hash
+          raw_input
+        when String
+          parse_json_object(raw_input)
+        else
+          from_hash_like = extract_hash_like(raw_input)
+          return from_hash_like unless from_hash_like.empty?
+
+          json_candidate = raw_input.respond_to?(:to_json) ? raw_input.to_json : nil
+          parse_json_object(json_candidate)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def extract_hash_like(value)
+        if value.respond_to?(:to_h)
+          converted = value.to_h
+          return converted if converted.is_a?(Hash)
+        end
+
+        if value.respond_to?(:to_hash)
+          converted = value.to_hash
+          return converted if converted.is_a?(Hash)
+        end
+
+        {}
+      rescue StandardError
+        {}
+      end
+
+      def parse_json_object(raw_json)
+        return {} unless raw_json.is_a?(String) && !raw_json.strip.empty?
+
+        parsed = JSON.parse(raw_json)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/spurline/adapters/open_ai.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Spurline
+  module Adapters
+    # OpenAI adapter using the ruby-openai gem.
+    # Translates between Spurline's internal representation and the OpenAI API.
+    class OpenAI < Base
+      DEFAULT_MODEL = "gpt-4o"
+      DEFAULT_MAX_TOKENS = 4096
+
+      STOP_REASON_MAP = {
+        "stop" => "end_turn",
+        "tool_calls" => "tool_use",
+        "length" => "max_tokens",
+        "content_filter" => "content_filter",
+      }.freeze
+
+      def initialize(api_key: nil, model: nil, max_tokens: nil)
+        @api_key = resolve_api_key(api_key)
+        @model = model || DEFAULT_MODEL
+        @max_tokens = max_tokens || DEFAULT_MAX_TOKENS
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system: nil, tools: [], config: {}, scheduler: Scheduler::Sync.new, &chunk_handler)
+        model = config[:model] || @model
+        max_tokens = config[:max_tokens] || @max_tokens
+        turn = config[:turn] || 1
+        pending_tool_calls = {}
+
+        scheduler.run do
+          client = build_client
+
+          params = {
+            model: model,
+            max_tokens: max_tokens,
+            messages: format_messages(messages, system: system),
+            stream: proc do |chunk|
+              handle_stream_chunk(
+                chunk,
+                turn: turn,
+                pending_tool_calls: pending_tool_calls,
+                &chunk_handler
+              )
+            end,
+          }
+
+          params[:tools] = format_tools(tools) if tools && !tools.empty?
+
+          client.chat(parameters: params)
+          flush_pending_tool_calls!(pending_tool_calls, turn: turn, &chunk_handler)
+        end
+      end
+
+      private
+
+      def resolve_api_key(explicit_key)
+        candidates = [
+          explicit_key,
+          ENV.fetch("OPENAI_API_KEY", nil),
+          Spurline.credentials["openai_api_key"],
+        ]
+        key = candidates.find { |value| present_string?(value) }
+        return key if key
+
+        raise Spurline::ConfigurationError,
+          "Missing OpenAI API key for adapter :openai. " \
+          "Set OPENAI_API_KEY, add openai_api_key to Spurline.credentials, " \
+          "or pass api_key:."
+      end
+
+      def present_string?(value)
+        return false if value.nil?
+        return !value.strip.empty? if value.respond_to?(:strip)
+
+        true
+      end
+
+      def build_client
+        require "openai"
+        ::OpenAI::Client.new(access_token: @api_key)
+      rescue LoadError
+        raise Spurline::ConfigurationError,
+          "The 'ruby-openai' gem is required for adapter :openai. " \
+          "Add `gem \"ruby-openai\"` to your Gemfile."
+      end
+
+      # OpenAI expects the system prompt as a message in the message array.
+      def format_messages(messages, system: nil)
+        formatted = []
+        formatted << { role: "system", content: system } if present_string?(system)
+
+        messages.each do |message|
+          formatted << {
+            role: message[:role] || "user",
+            content: message[:content].to_s,
+          }
+        end
+
+        formatted
+      end
+
+      # OpenAI wraps tools in { type: "function", function: { ... } }.
+      def format_tools(tools)
+        tools.map do |tool|
+          {
+            type: "function",
+            function: {
+              name: tool[:name].to_s,
+              description: tool[:description].to_s,
+              parameters: tool[:input_schema] || {},
+            },
+          }
+        end
+      end
+
+      def handle_stream_chunk(chunk, turn:, pending_tool_calls:, &chunk_handler)
+        choice = first_choice(chunk)
+        return unless choice
+
+        delta = read_key(choice, "delta") || {}
+        finish_reason = read_key(choice, "finish_reason")
+
+        content = read_key(delta, "content")
+        if content
+          chunk_handler.call(
+            Streaming::Chunk.new(type: :text, text: content, turn: turn)
+          )
+        end
+
+        tool_calls = read_key(delta, "tool_calls")
+        accumulate_tool_call_deltas!(tool_calls, pending_tool_calls) if tool_calls
+
+        return unless finish_reason
+
+        chunk_handler.call(
+          Streaming::Chunk.new(
+            type: :done,
+            turn: turn,
+            metadata: { stop_reason: STOP_REASON_MAP[finish_reason] || finish_reason }
+          )
+        )
+      end
+
+      def first_choice(chunk)
+        choices = read_key(chunk, "choices")
+        return nil unless choices.is_a?(Array)
+
+        choices.first
+      end
+
+      def read_key(hash, key)
+        return nil unless hash.respond_to?(:[])
+
+        hash[key] || hash[key.to_sym]
+      end
+
+      def accumulate_tool_call_deltas!(tool_call_deltas, pending_tool_calls)
+        return unless tool_call_deltas.is_a?(Array)
+
+        tool_call_deltas.each do |tool_call_delta|
+          index = read_key(tool_call_delta, "index") || 0
+          pending_tool_calls[index] ||= { id: nil, name: "", arguments: "" }
+          tool_call = pending_tool_calls[index]
+
+          tool_call[:id] = read_key(tool_call_delta, "id") || tool_call[:id]
+          function_data = read_key(tool_call_delta, "function") || {}
+
+          name = read_key(function_data, "name")
+          tool_call[:name] = name if name
+
+          arguments_delta = read_key(function_data, "arguments")
+          tool_call[:arguments] += arguments_delta.to_s if arguments_delta
+        end
+      end
+
+      def flush_pending_tool_calls!(pending_tool_calls, turn:, &chunk_handler)
+        pending_tool_calls.keys.sort.each do |index|
+          tool_call = pending_tool_calls[index]
+          next if tool_call[:name].empty?
+
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :tool_start,
+              turn: turn,
+              metadata: {
+                tool_name: tool_call[:name],
+                tool_use_id: tool_call[:id],
+                tool_call: {
+                  name: tool_call[:name],
+                  arguments: parse_tool_arguments(tool_call[:arguments]),
+                },
+              }
+            )
+          )
+        end
+
+        pending_tool_calls.clear
+      end
+
+      def parse_tool_arguments(raw_json)
+        return {} unless raw_json.is_a?(String) && !raw_json.strip.empty?
+
+        parsed = JSON.parse(raw_json)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end