rails-agent-stack 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83dde44cc5a68ee22c237736bd5992f64baf5b474e1ef7e3615244277988060f
+  data.tar.gz: 407a7cc7dc2fdde847babc4e948f38f7028d8121bb3142a9804058c366fcb58d
+SHA512:
+  metadata.gz: 520d19cb9bee5584270474f80b77518b99f81f4cec77c8d03603716dae2ef988007cf5b5474fb0150369aba473f6a00cfd1301259238fb8e267412bad36ff8e4
+  data.tar.gz: ccfacfe644d0facb1b2730b90c5877cecdde11c06b5d471a6ae5aa7d24cf48464a0aacae36e5ea5d362df8b1051e95702048d0a8bf42e2ed83c253968d833d71

data/.github/workflows/README.md

@@ -0,0 +1,16 @@
+# GitHub Actions
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | push/PR to `main` | RSpec + gem build |
+
+This repo is the **Ruby gem** (`rails-agent-stack`). It has **no Hetzner deploy** — customers install from GitHub:
+
+```ruby
+gem "rails-agent-stack", github: "Tiny-Bubble-Company/rails-agents"
+```
+
+Production sites deploy from sibling repos:
+
+- [`rails-agents-cloud`](https://github.com/Tiny-Bubble-Company/rails-agents-cloud) → rails-agent.com
+- [`rails-agents-ops`](https://github.com/Tiny-Bubble-Company/rails-agents-ops) → ops.rails-agent.com

data/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+# Gem repo — no Hetzner deploy. Cloud/ops deploy from their own Actions on push to main.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-rails-agents-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build gem
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build gem
+        run: gem build rails-agent-stack.gemspec

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+/tmp/
+/coverage/
+/.rspec_status
+*.gem
+.DS_Store

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+**Start here** when using Cursor, Claude Code, or another external coding agent with Rails Agent.
+
+Full onboarding guide: **[docs/AGENTS.md](docs/AGENTS.md)**
+
+Quick start:
+
+1. `bin/rails generate rails_agents:install` → open `/agents` and connect workspace  
+2. `bin/rails generate rails_agents:agent my_agent --type knowledge --database`  
+3. Attach BYOK credentials in cloud dashboard; reference as `credential: :company_openai` in `agent.rb`  
+4. `bundle exec rails-agents sync my_agent` → test/deploy/monitor in `/agents`
+
+Four taxonomy types: **Knowledge**, **Workflow**, **Operations**, **Monitoring**.
+
+Capabilities: **Tools**, **Skills**, **Packages** (Skills.sh / APM / Smithery), **Connectors**, **Knowledge**, plus workspace **Library** reuse.
+
+Run responses: prefer `result.output_text` (Markdown) and optional `result.output_data` — see [docs/AGENTS.md](docs/AGENTS.md#run-response-schema-integrate-into-product) and https://rails-agent.com/docs/run-response.

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `rails-agent-stack` will be documented in this file.
+
+## [0.2.0] - Unreleased
+
+### Changed
+
+- Documentation-first onboarding (AGENTS.md); removed Kip / chat-authoring positioning.
+- Four product-facing agent taxonomy types: Knowledge, Workflow, Operations, Monitoring.
+- BYOK model DSL: `model :name, provider:, credential:` with cloud credential references.
+- Generator `--type` and `--database` for database-connected Knowledge agents.
+- Company subscription + pass-through usage + 1% service fee pricing model.
+- Deprecated cloud pull bridge in embed UI; `rails-agents pull` retained for compatibility.
+
+### Added
+
+- `KnowledgeAgent`, `OperationsAgent`, and `MonitoringAgent` classes; the legacy output-focused class remains loadable for compatibility.
+- `docs/AGENTS.md` canonical guide for external coding agents.
+
+## [0.1.1] - 2026-08-02
+
+### Changed
+
+- Depend on published `open-wire` (`~> 0.1`) from RubyGems instead of a local path.
+- Re-release after yanked `0.1.0` on RubyGems.
+
+## [0.1.0] - 2026-07-18
+
+### Added
+
+- Initial release of the `rails-agent-stack` gem.
+- Mountable Rails Engine at `/agents` with cloud dashboard proxy UI.
+- `RailsAgents::Base` DSL — model, memory, knowledge, tools, skills, channels.
+- Cloud HTTP client (`Net::HTTP`) for runs, deploys, channels, knowledge sync, logs, traces, evals.
+- Thor CLI (`rails-agents`) — install, new, run, deploy, logs, traces, evals.
+- Generators — `rails_agents:install`, `rails_agents:agent`.
+- Configuration block with ENV defaults.
+- Example support agent under `examples/support/`.
+- RSpec coverage for Base, Client, and Configuration.

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+# open-wire comes from RubyGems via the gemspec (`~> 0.1`).
+# Override locally with: OPEN_WIRE_GEM_PATH=/path/to/open-wire/ruby bundle install
+if (path = ENV["OPEN_WIRE_GEM_PATH"]) && !path.empty? && File.directory?(path)
+  gem "open-wire", path: path
+end
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"
+gem "webmock", "~> 3.23"

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rails Agent
+
+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,228 @@
+<p align="center">
+  <a href="https://rails-agent.com">
+    <img src="https://rails-agent.com/og-image.jpg" alt="Rails Agent — fullstack AI agents for Ruby on Rails" width="720" />
+  </a>
+</p>
+
+<h1 align="center">Rails Agent</h1>
+
+<p align="center">
+  <strong>The most advanced agentic platform for Ruby on Rails.</strong><br />
+  Build Rails AI agents in your repo. Test, deploy, and monitor at <code>/agents</code>.
+</p>
+
+<p align="center">
+  <a href="https://rails-agent.com"><img src="https://img.shields.io/badge/rails--agent.com-docs-C2410C?style=flat-square" alt="Docs" /></a>
+  <a href="https://github.com/Tiny-Bubble-Company/rails-agents"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT" /></a>
+  <a href="https://rails-agent.com/docs/getting-started"><img src="https://img.shields.io/badge/Ruby-3.2%2B-CC342D?style=flat-square&logo=ruby&logoColor=white" alt="Ruby 3.2+" /></a>
+  <a href="https://rails-agent.com/docs/getting-started"><img src="https://img.shields.io/badge/Rails-7%2B-D30001?style=flat-square&logo=rubyonrails&logoColor=white" alt="Rails 7+" /></a>
+</p>
+
+<p align="center">
+  <a href="docs/AGENTS.md"><strong>AGENTS.md</strong></a>
+  ·
+  <a href="https://rails-agent.com/docs/getting-started">Getting started</a>
+  ·
+  <a href="https://rails-agent.com/docs/coding-agents">Coding agents</a>
+  ·
+  <a href="https://cloud.rails-agent.com">Cloud</a>
+</p>
+
+---
+
+## About
+
+[Rails Agent](https://rails-agent.com) is the fullstack **Rails agent framework** for production **Ruby on Rails agents**. Define instructions, tools, skills, packages, knowledge, channels, memory, and evals as files in your app — then use the mounted `/agents` dashboard to connect BYOK credentials, attach guardrails, ship channels, and observe cost.
+
+If you are searching for a **Rails AI agents** stack, an **ActiveAgent alternative**, or a **RubyLLM alternative**, Rails Agent is built for the full lifecycle: author in Git, run in the cloud, integrate responses into your product.
+
+**Website:** [rails-agent.com](https://rails-agent.com)
+
+---
+
+## Why Rails Agent (vs RubyLLM & ActiveAgent)
+
+Rails Agent is a better alternative to library-only LLM wrappers when you need agents that ship with your Rails app — not just chat completions.
+
+| | **Rails Agent** | RubyLLM | ActiveAgent |
+|--|-----------------|---------|-------------|
+| **Scope** | Fullstack agentic platform (build → deploy → monitor) | LLM client / chat helpers | Agent abstractions in Rails |
+| **Source of truth** | `app/agents/` directories in your repo | Application code calling the gem | Ruby classes / generators |
+| **Dashboard** | Mounted `/agents` (test, deploy, traces, cost) | — | Limited / app-owned |
+| **BYOK credentials** | Cloud-managed references (`credential: :company_openai`) | Env / config in app | App-managed |
+| **Build surface** | Instructions, tools, connectors, channels, skills, packages, knowledge, memory, guardrails | Prompts + API calls | Tools / prompts (varies) |
+| **Playbooks & Library** | Workspace reuse + proven scaffolds | — | — |
+| **Channels** | Open-Wire Slack / Teams, web, cron, API | — | App-wired |
+| **Ops** | Budget, guardrails, evals, Monitor | Caller responsibility | Caller responsibility |
+| **Best for** | Production **Rails AI agents** end-to-end | Thin LLM access | Lightweight agent objects |
+
+Positioning in one line: **most advanced agentic platform for Ruby on Rails** — git-native agents with cloud runtime, integrations, and production controls.
+
+---
+
+## Features
+
+### Build (agent tabs)
+
+| Capability | What you get |
+|------------|----------------|
+| **Instructions** | `prompt.md` system prompt — reviewed in Git |
+| **Tools** | Ruby methods over your ActiveRecord models |
+| **Connectors** | OAuth SaaS (Sheets, Notion, HubSpot, …) from the dashboard |
+| **Channels** | Slack & Microsoft Teams via **Open-Wire**, web chat, cron, API |
+| **Skills** | Composable multi-step behaviors |
+| **Packages** | Install from Skills.sh / Microsoft APM / Smithery |
+| **Knowledge** | Docs + database grounding for RAG-style answers |
+| **Memory** | Conversation memory (Mem0-backed), on by default |
+| **Guardrails** | Budget, model access, prompt injection, sensitive info |
+
+### Platform
+
+- **Playbooks** — proven scaffolds (instructions + tools + skills) you customize locally
+- **Library** — share tools, skills, packages, knowledge, and connectors across agents (`app/agents_library/` + `imports.yml`)
+- **Budget** — per-agent / policy spend limits alongside usage monitoring
+- **Monitor** — runs, traces, evals, and cost in `/agents`
+- **BYOK** — attach OpenAI, Anthropic, and other provider keys in cloud; reference them in Ruby with no secrets in Git
+- **Open-Wire** — Slack and Teams channel transport over `open-wire/1`
+- **Composio email** — email connectors for inbox workflows
+- **Evals** — golden cases under `evals/` before deploy
+- **Deploy** — `rails-agents sync` → `deploy` → production traffic
+- **Coding-agent docs** — Cursor, Codex, and Claude Code follow [AGENTS.md](docs/AGENTS.md) and [Coding agents](https://rails-agent.com/docs/coding-agents)
+
+---
+
+## Install
+
+```ruby
+# Gemfile
+gem "rails-agent-stack", github: "Tiny-Bubble-Company/rails-agents"
+```
+
+```bash
+bundle install
+bin/rails generate rails_agents:install
+bin/dev   # → http://localhost:3000/agents
+```
+
+Connect your company workspace at `/agents`, then scaffold a database Knowledge agent:
+
+```bash
+bin/rails generate rails_agents:agent store_assistant --type knowledge --database
+```
+
+**Zeitwerk:** fresh installs add `config/initializers/rails_agents_autoload.rb` so `app/agents/` and `app/agents_library/` are agent assets, not application namespaces.
+
+External coding agents (Cursor, Claude Code, Codex): start with **[docs/AGENTS.md](docs/AGENTS.md)**.
+
+---
+
+## Quick start
+
+```bash
+bundle exec rails-agents run store_assistant "Where is order ORD-DEMO-1001?"
+bundle exec rails-agents sync store_assistant
+bundle exec rails-agents deploy store_assistant
+bundle exec rails-agents logs store_assistant
+```
+
+```ruby
+class StoreAssistant < RailsAgents::KnowledgeAgent
+  model :gpt_5_mini, provider: :openai, credential: :company_openai
+  memory :conversation, provider: :mem0, recall: 5
+  knowledge_from "knowledge/**/*"
+
+  tool :lookup_order do |order_number:|
+    Order.find_by(number: order_number)&.as_json(only: %i[number status total_cents])
+  end
+end
+```
+
+`:company_openai` is a **cloud credential reference** — not a local env var. Enable managed memory from **Build → Memory**. Pass a stable `session_id` to `.run` so recall stays scoped per product user.
+
+---
+
+## Agent directory
+
+```
+app/agents/store_assistant/
+├── agent.rb            # RailsAgents::KnowledgeAgent subclass
+├── prompt.md           # System prompt
+├── imports.yml         # Optional workspace Library attachments
+├── tools/              # Optional extracted tools
+├── skills/             # Composable behaviors
+├── packages/           # Registry-installed capabilities
+├── memory.rb           # Memory config
+├── knowledge/          # RAG files
+├── connectors/         # External connection manifests
+├── channels/           # Slack, Teams, web, API, …
+└── evals/              # Smoke / regression cases
+
+app/agents_library/
+├── tools/
+├── skills/
+├── packages/
+├── knowledge/
+└── connectors/
+```
+
+Keep one-off work inside the agent. Move stable capabilities to `app/agents_library/` when another agent should reuse them, then reference via `imports.yml`. `rails-agents sync` includes imported Library files in the runtime bundle without duplicating shared source in Git.
+
+---
+
+## Agent taxonomy
+
+| Type | Main purpose | Example |
+|------|--------------|---------|
+| Knowledge | Understand and answer | Order support from Rails data |
+| Workflow | Execute predictable processes | Refund approval |
+| Operations | Coordinate unpredictable real-world work | Incident coordination |
+| Monitoring | Observe changes and respond | Inventory watcher |
+
+Generator: `--type knowledge|workflow|operations|monitoring` and `--database` for DB-connected Knowledge scaffolds.
+
+**Integrate responses:** every run returns `output_text` (Markdown), optional `output_data`, and typed `items` — same shape for every LLM. Guide: [rails-agent.com/docs/run-response](https://rails-agent.com/docs/run-response).
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/rails_agents.rb
+RailsAgents.configure do |config|
+  config.api_key = ENV["RAILS_AGENTS_API_KEY"]       # platform key
+  config.project_id = ENV["RAILS_AGENTS_PROJECT_ID"]
+end
+```
+
+Provider keys live in the cloud dashboard → Model credentials (BYOK). Never commit them.
+
+---
+
+## Pricing
+
+| | |
+|--|--|
+| **Subscription** | Fixed **company** plan (production workspaces) |
+| **Usage** | Provider + infrastructure at **pass-through cost** |
+| **Service fee** | **1%** on metered usage (transparent line item) |
+
+Details: [rails-agent.com/pricing](https://rails-agent.com/pricing)
+
+---
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Local path testing: sibling app `rails-agents-boilerplate`.
+
+---
+
+## License
+
+MIT — [MIT-LICENSE](MIT-LICENSE)
+
+[rails-agent.com](https://rails-agent.com) · [AGENTS.md](docs/AGENTS.md) · [Getting started](https://rails-agent.com/docs/getting-started)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec