sus-fixtures-agent-context 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c9d4dad22be9729608f3805460e81bdc828f8d3f96b4152d681b83266e71abf5
+  data.tar.gz: 29d3f5f5d024240d95629f4bf29904905c1ee31cffc32d3eb693902d204a13f4
+SHA512:
+  metadata.gz: 533ff26c37f929daad81155ce92ca7054008a1e1012537b79a82a047ade05d63989a63bd3279cb1acb50c26ad451bca83e7f40016d51da204dee85e119bf860d
+  data.tar.gz: a486b1e28a8833b8dd7df9af87c81238ee0d3072bb1ece0e9a604d50cd9c6f9fe63f00ff7ab0b081fab83fd571a7f35ad2e1007cf98ce06022a95480e1774242

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+u.byg��?+)�M�G��/��Lb��X'?U�e����7���O������{�01Wh[�b1���f=�yE��1�EV�bq
+b��
@k�V��Q�to�������

data/agent.md

@@ -0,0 +1,51 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Usage Guide](.context/agent-context/usage.md)
+
+`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` ...
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, docume...
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate A...
+
+#### [Setting Up RBS Types and Steep Type Checking for Ruby Gems](.context/decode/types.md)
+
+This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace m...
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.

data/context/getting-started.md

@@ -0,0 +1,31 @@
+# Getting Started
+
+This guide explains how to use the `sus-fixtures-agent-context` gem to test agent contexts.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+bundle add sus-fixtures-agent-context
+```
+
+You will need a locally accessible Ollama server to use this gem, as it relies on the `Async::Ollama` client to interact with agents. Make sure you have Ollama installed and running.
+
+## Testing Agent Contexts
+
+This gem provides a convenient way to test whether a given context is sufficient for an agent to perform a task. It uses the `Async::Ollama` client to interact with agents. So you will need to have an Ollama server running and accessible.
+
+```ruby
+include Sus::Fixtures::Agent::Context
+
+it "can use the with_agent_context fixture" do
+	# The path is relative to the working directory by default.
+	with_agent_context("context/getting-started.md") do |session|
+		response = session.call("Write an expectation that checks if an `array` contains an `item`.")
+		expect(response).to be ==~ /expect\(array\).to be(:include?, item\)/
+	end
+end
+```
+
+It is recommended that you put these tests in `test/.agent/context` directory, and they must be run explicitly with `sus test/.agent/context`. By default, `sus` will not recurse into directories starting with a dot, so this is an acceptable way to organize your tests.

data/context/github-actions.md

@@ -0,0 +1,59 @@
+# GitHub Actions
+
+This guide explains how to integrate the `sus-fixtures-agent-context` gem with GitHub Actions for testing agent contexts.
+
+## Workflow
+
+In order to use this gem in GitHub Actions, you can set up a workflow that includes the Ollama server. Here is an example of how to configure your `.github/workflows/test.yml`:
+
+```yaml
+name: Test Agent Context
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Agent Context
+    runs-on: ${{matrix.os}}-latest
+    continue-on-error: ${{matrix.experimental}}
+    
+    services:
+      ollama:
+        image: ollama/ollama
+        ports:
+          - 11434:11434
+    
+    strategy:
+      matrix:
+        os:
+          - ubuntu
+        
+        ruby:
+          - "3.4"
+        
+        experimental: [false]
+        
+        include:
+          - os: ubuntu
+            ruby: head
+            experimental: true
+    
+    steps:
+    - uses: actions/checkout@v4
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{matrix.ruby}}
+        bundler-cache: true
+    
+    - name: Pull Model
+      run: bundle exec bake async:ollama:pull
+    
+    - name: Run tests
+      timeout-minutes: 30
+      run: bundle exec sus test/.agent/context
+```
+
+Note that the timeout is set to 30 mintues to allow sufficient time for the Ollama server to start and for the tests to run.

data/lib/sus/fixtures/agent/context/session.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/ollama"
+require "async/ollama/conversation"
+
+module Sus
+	module Fixtures
+		module Agent
+			module Context
+				# Manages a conversation session with an agent, loading context and handling prompts.
+				class Session
+					# @constant [String] The system prompt used to instruct the agent on how to use the provided context.
+					CONTEXT_PROMPT = <<~PROMPT
+						You are a documentation-aware assistant tasked with answering questions strictly based on the provided context.
+						
+						The context you are given is the sole source of truth. It defines how the system behaves, what features exist, and how they are used.
+						
+						- Do not rely on your prior training or general knowledge.
+						- If the answer cannot be inferred from the context, say: “The context does not contain enough information to answer this.”
+						- Do not speculate, assume, or generalize beyond what is written in the context.
+						
+						Your responses should be clear, concise, and strictly grounded in the information provided. Prioritize accuracy over completeness or fluency.
+					PROMPT
+					
+					# Initializes a new session for agent context interaction.
+					# @option :temperatuire [Float] The temperature for the agent's responses (default is 0.0 for deterministic responses).
+					# @option :model [String] The model to use for the agent (default is "llama3.1").
+					def initialize(**options)
+						# Remove as much non-determinism as possible:
+						options[:temperature] = 0.0
+						
+						@client = ::Async::Ollama::Client.open
+						@conversation = ::Async::Ollama::Conversation.new(@client, **options)
+					end
+					
+					# @attribute [::Async::Ollama::Conversation] The conversation object for this session.
+					attr :conversation
+					
+					# Sends a prompt to the agent and returns the response.
+					# @parameter prompt [String] The prompt to send to the agent.
+					# @returns [String] The agent's response.
+					def call(prompt)
+						chat = @conversation.call(prompt)
+						
+						return chat.response
+					end
+					
+					# Loads a context file and appends it to the conversation as a system message.
+					# @parameter path [String] The path to the context file.
+					def load_context_path(path)
+						::File.read(path).tap do |content|
+							@conversation.messages << {
+								role: "system",
+								content: CONTEXT_PROMPT + "\n\n--- The context follows:\n\n" + content
+							}
+						end
+					end
+					
+					# Closes the underlying client connection.
+					def close
+						@client.close if @client
+					end
+				end
+			end
+		end
+	end
+end

data/lib/sus/fixtures/agent/context/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Sus
+	module Fixtures
+		module Agent
+			module Context
+				VERSION = "0.1.0"
+			end
+		end
+	end
+end

data/lib/sus/fixtures/agent/context.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "context/session"
+
+# @namespace
+module Sus
+	# @namespace
+	module Fixtures
+		# @namespace
+		module Agent
+			# @namespace
+			module Context
+				include Sus::Fixtures::Async::SchedulerContext
+				
+				# @constant [String] The default path to the agent context file.
+				AGENT_PATH = "agent.md"
+				
+				# @returns [Integer] the default timeout for agent-based tests, in seconds.
+				def timeout
+					# 10 minutes - we don't expect tests to actually take this long, but sometimes Ollama has to load models which can take an exceptionally long time depending on the model size and hardware.
+					60*10
+				end
+				
+				# Yields a session with the agent context loaded from the given path or the default {AGENT_PATH}.
+				# Ensures the session is closed after the block.
+				# @parameter path [String | nil] The path to the context file to load.
+				# @parameter options [Hash] Additional options for the session.
+				# @yields {|session| ...} Yields the session with the loaded context.
+				# 	@parameter session [Session] The session with the loaded context.
+				def with_agent_context(path = nil, **options, &block)
+					session = Session.new(**options)
+					
+					if path
+						session.load_context_path(path)
+					end
+					
+					yield session
+				ensure
+					session&.close
+				end
+			end
+		end
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+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,37 @@
+# Sus::Fixtures::Agent::Context
+
+Provides convenient fixtures for testing whether a given context is sufficient for an agent to performn a task.
+
+[![Development Status](https://github.com/socketry/sus-fixtures-agent-context/workflows/Test/badge.svg)](https://github.com/socketry/sus-fixtures-agent-context/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/sus-fixtures-async/) for more details.
+
+  - [Getting Started](https://socketry.github.io/sus-fixtures-async/guides/getting-started/index) - This guide explains how to use the `sus-fixtures-agent-context` gem to test agent contexts.
+
+  - [GitHub Actions](https://socketry.github.io/sus-fixtures-async/guides/github-actions/index) - This guide explains how to integrate the `sus-fixtures-agent-context` gem with GitHub Actions for testing agent contexts.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/sus-fixtures-async/releases/index) for all releases.
+
+### v0.1.0
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v0.1.0

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: sus-fixtures-agent-context
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async-ollama
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: sus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- agent.md
+- context/getting-started.md
+- context/github-actions.md
+- lib/sus/fixtures/agent/context.rb
+- lib/sus/fixtures/agent/context/session.rb
+- lib/sus/fixtures/agent/context/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/sus-fixtures-async
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/sus-fixtures-async/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/sus-fixtures-async.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Test fixtures for running in Async.
+test_files: []