agent_gateway 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3517469f438cc1b6f649f04a3efefd74dde4ba8a03fde7ba9453e7f26ec3036d
+  data.tar.gz: ba5c6952bdaff79502367cf2463e8bcf6fa2281169b091d831a0ca81b12cb0be
+SHA512:
+  metadata.gz: 9c5898a3d51db11fd25a2c159f14a3c856f67da2afa359d0c6c519a366342de2f0fd3f9811d4324281920ee3b2032ad9ac1106fd87a7d78e066725585e4d6fe8
+  data.tar.gz: 0577e6232671783e4c0595edb3807e840c95ed68ffa10b2401817068142a60e2e5fc5bf95110f970a30de4a822316e7aa63231697d588bbec1e05f6804efdbec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Waites
+
+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,137 @@
+![Agent Gateway](lando.jpeg)
+
+# Agent Gateway
+
+A mountable Rails engine that exposes a single authenticated JSON endpoint for AI agents to consume your app's data.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "agent_gateway"
+```
+
+Then mount the engine in `config/routes.rb`:
+
+```ruby
+mount AgentGateway::Engine => "/agent-gateway"
+```
+
+## Configuration
+
+Create an initializer `config/initializers/agent_gateway.rb`:
+
+```ruby
+AgentGateway.configure do |c|
+  c.app_name    = "MyApp"
+  c.auth_token  = ENV["AGENT_GATEWAY_TOKEN"]  # required — raises at boot if blank
+  c.path_secret = ENV["AGENT_GATEWAY_SECRET"] # auto-generated + logged if omitted
+  c.default_period = "7d"                     # 1d, 7d, 30d, 90d, 1y, all
+
+  c.expose :users, model: "User" do
+    count
+    latest 5
+    attributes :email, :name, :created_at
+    scope :active
+    date_column :created_at
+  end
+
+  c.expose :orders, model: "Order" do
+    count
+    sum :total
+    avg :total
+    latest 3
+    attributes :id, :total, :status, :created_at
+  end
+end
+```
+
+### DSL Reference
+
+| Method | Description |
+|--------|-------------|
+| `count` | Include record count |
+| `latest N` | Include N most recent records |
+| `attributes :col1, :col2` | Allowlist fields on latest records |
+| `sum :column` | Sum a numeric column (call multiple times for multiple columns) |
+| `avg :column` | Average a numeric column (call multiple times) |
+| `scope :name` | Apply a named scope to all queries |
+| `date_column :name` | Column used for period filtering (default: `created_at`) |
+
+## Endpoint
+
+```
+GET /<mount_path>/<path_secret>/briefing
+```
+
+### Authentication
+
+Two-layer auth:
+1. **Path secret** — wrong value returns `404` (endpoint appears nonexistent)
+2. **Bearer token** — wrong/missing value returns `401`
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  https://myapp.com/agent-gateway/$SECRET/briefing
+```
+
+### Query Parameters
+
+| Param | Description | Example |
+|-------|-------------|---------|
+| `period` | Time window: `1d`, `7d`, `30d`, `90d`, `1y`, `all` | `?period=30d` |
+| `resources` | Comma-separated resource keys to include | `?resources=users,orders` |
+| `latest` | Override latest count for all resources | `?latest=10` |
+
+### Response
+
+```json
+{
+  "app_name": "MyApp",
+  "generated_at": "2026-02-20T12:00:00Z",
+  "period": {
+    "from": "2026-02-13",
+    "to": "2026-02-20",
+    "days": 7
+  },
+  "data": {
+    "users": {
+      "count": 142,
+      "latest": [
+        { "email": "new@example.com", "name": "New User", "created_at": "2026-02-20" }
+      ]
+    },
+    "orders": {
+      "count": 89,
+      "sum": { "total": 12450.00 },
+      "avg": { "total": 139.89 },
+      "latest": [
+        { "id": 501, "total": "250.00", "status": "paid", "created_at": "2026-02-20" }
+      ]
+    }
+  }
+}
+```
+
+## Security Notes
+
+- `path_secret` is compared using `ActiveSupport::SecurityUtils.secure_compare` (timing-safe)
+- Bearer token is also compared with `secure_compare`
+- If no `path_secret` is configured, one is auto-generated and printed to STDOUT at boot
+- Missing `auth_token` raises at boot — the engine won't start without one
+
+## Using with AI Agents
+
+Point your AI agent at the briefing endpoint with the bearer token. The response is a single JSON payload designed for LLM consumption — structured, filterable, and concise.
+
+Example system prompt snippet:
+
+```
+Fetch app data from: GET https://myapp.com/agent-gateway/<secret>/briefing
+Header: Authorization: Bearer <token>
+```
+
+## License
+
+MIT

data/app/controllers/agent_gateway/briefings_controller.rb

@@ -0,0 +1,74 @@
+module AgentGateway
+  class BriefingsController < ActionController::API
+    before_action :verify_path_secret
+    before_action :authenticate_token
+
+    def show
+      resources = build_resources
+      period_info = build_period_info
+
+      render json: {
+        app_name: AgentGateway.configuration.app_name,
+        generated_at: Time.current.iso8601,
+        period: period_info,
+        data: resources
+      }
+    end
+
+    private
+
+    def verify_path_secret
+      unless ActiveSupport::SecurityUtils.secure_compare(
+        params[:path_secret].to_s,
+        AgentGateway.configuration.path_secret.to_s
+      )
+        head :not_found
+      end
+    end
+
+    def authenticate_token
+      token = request.headers["Authorization"].to_s.sub(/\ABearer\s+/, "")
+      unless ActiveSupport::SecurityUtils.secure_compare(token, AgentGateway.configuration.auth_token.to_s)
+        head :unauthorized
+      end
+    end
+
+    def build_resources
+      configs = AgentGateway.configuration.resources
+      requested = params[:resources]&.split(",")&.map(&:strip)&.map(&:to_sym)
+
+      selected = if requested
+        configs.slice(*requested)
+      else
+        configs
+      end
+
+      selected.each_with_object({}) do |(key, config), hash|
+        runner = QueryRunner.new(key, config, period: period_param, latest_override: latest_override)
+        hash[key] = runner.call
+      end
+    end
+
+    def build_period_info
+      days = resolve_display_period
+      if days
+        { from: days.days.ago.to_date.iso8601, to: Date.current.iso8601, days: days }
+      else
+        { from: nil, to: Date.current.iso8601, days: "all" }
+      end
+    end
+
+    def resolve_display_period
+      period_key = period_param || AgentGateway.configuration.default_period
+      QueryRunner::PERIODS.fetch(period_key) { QueryRunner::PERIODS.fetch(AgentGateway.configuration.default_period, 7) }
+    end
+
+    def period_param
+      params[:period].presence
+    end
+
+    def latest_override
+      params[:latest]&.to_i&.then { |n| n > 0 ? n : nil }
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,3 @@
+AgentGateway::Engine.routes.draw do
+  get ":path_secret/briefing", to: "briefings#show"
+end

data/lib/agent_gateway/configuration.rb

@@ -0,0 +1,35 @@
+module AgentGateway
+  class Configuration
+    attr_accessor :app_name, :path_secret, :auth_token, :default_period
+    attr_reader :resources
+
+    def initialize
+      @app_name = "App"
+      @path_secret = nil
+      @auth_token = nil
+      @default_period = "7d"
+      @resources = {}
+    end
+
+    def expose(key, model: nil, &block)
+      model_name = model || key.to_s.classify
+      config = ResourceConfig.new(model_name)
+      config.instance_eval(&block) if block
+      @resources[key.to_sym] = config
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/agent_gateway/engine.rb

@@ -0,0 +1,18 @@
+module AgentGateway
+  class Engine < ::Rails::Engine
+    isolate_namespace AgentGateway
+
+    config.after_initialize do
+      cfg = AgentGateway.configuration
+
+      if cfg.auth_token.nil? || cfg.auth_token.to_s.strip.empty?
+        raise "AgentGateway: auth_token must be configured. Set it via AgentGateway.configure { |c| c.auth_token = 'your-token' }"
+      end
+
+      if cfg.path_secret.nil? || cfg.path_secret.to_s.strip.empty?
+        cfg.path_secret = SecureRandom.uuid
+        puts "[AgentGateway] path_secret auto-generated: #{cfg.path_secret}"
+      end
+    end
+  end
+end

data/lib/agent_gateway/query_runner.rb

@@ -0,0 +1,81 @@
+module AgentGateway
+  class QueryRunner
+    PERIODS = {
+      "1d"  => 1,
+      "7d"  => 7,
+      "30d" => 30,
+      "90d" => 90,
+      "1y"  => 365,
+      "all" => nil
+    }.freeze
+
+    def initialize(resource_key, config, period: nil, latest_override: nil)
+      @resource_key = resource_key
+      @config = config
+      @period = period
+      @latest_override = latest_override
+    end
+
+    def call
+      model = @config.model_name.constantize
+      relation = base_relation(model)
+
+      result = {}
+      result[:count] = relation.count if @config.count_enabled?
+      result[:sum] = compute_sums(relation) unless @config.sum_columns.empty?
+      result[:avg] = compute_avgs(relation) unless @config.avg_columns.empty?
+      result[:latest] = fetch_latest(relation) if latest_count
+
+      result
+    rescue NameError
+      { error: "Model not found: #{@config.model_name}" }
+    end
+
+    private
+
+    def base_relation(model)
+      relation = @config.scope_name ? model.public_send(@config.scope_name) : model.all
+      apply_period_filter(relation)
+    end
+
+    def apply_period_filter(relation)
+      days = resolve_period
+      return relation unless days
+
+      date_col = @config.date_column_name
+      relation.where(date_col => days.days.ago..)
+    end
+
+    def resolve_period
+      period_key = @period || AgentGateway.configuration.default_period
+      return nil if period_key == "all"
+
+      PERIODS.fetch(period_key) { PERIODS.fetch(AgentGateway.configuration.default_period, 7) }
+    end
+
+    def compute_sums(relation)
+      @config.sum_columns.each_with_object({}) do |col, hash|
+        hash[col] = (relation.sum(col.to_sym) || 0).round(2)
+      end
+    end
+
+    def compute_avgs(relation)
+      @config.avg_columns.each_with_object({}) do |col, hash|
+        hash[col] = (relation.average(col.to_sym) || 0).to_f.round(2)
+      end
+    end
+
+    def latest_count
+      @latest_override || @config.latest_count
+    end
+
+    def fetch_latest(relation)
+      records = relation.order(created_at: :desc).limit(latest_count)
+      if @config.attributes_list.any?
+        records.map { |r| @config.attributes_list.each_with_object({}) { |a, h| h[a] = r.public_send(a) } }
+      else
+        records.map { |r| { "id" => r.id } }
+      end
+    end
+  end
+end

data/lib/agent_gateway/resource_config.rb

@@ -0,0 +1,72 @@
+module AgentGateway
+  class ResourceConfig
+    attr_reader :model_name
+
+    def initialize(model_name)
+      @model_name = model_name
+      @attributes_list = []
+      @count_enabled = false
+      @latest_count = nil
+      @sum_columns = []
+      @avg_columns = []
+      @scope_name = nil
+      @date_column_name = :created_at
+    end
+
+    def attributes(*attrs)
+      @attributes_list = attrs.map(&:to_s)
+    end
+
+    def attributes_list
+      @attributes_list
+    end
+
+    def count(enabled = true)
+      @count_enabled = enabled
+    end
+
+    def count_enabled?
+      @count_enabled
+    end
+
+    def latest(n)
+      @latest_count = n
+    end
+
+    def latest_count
+      @latest_count
+    end
+
+    def sum(column)
+      @sum_columns << column.to_s
+    end
+
+    def sum_columns
+      @sum_columns
+    end
+
+    def avg(column)
+      @avg_columns << column.to_s
+    end
+
+    def avg_columns
+      @avg_columns
+    end
+
+    def scope(name)
+      @scope_name = name
+    end
+
+    def scope_name
+      @scope_name
+    end
+
+    def date_column(name)
+      @date_column_name = name.to_sym
+    end
+
+    def date_column_name
+      @date_column_name
+    end
+  end
+end

data/lib/agent_gateway/version.rb

@@ -0,0 +1,3 @@
+module AgentGateway
+  VERSION = "0.1.0"
+end

data/lib/agent_gateway.rb

@@ -0,0 +1,5 @@
+require "agent_gateway/version"
+require "agent_gateway/resource_config"
+require "agent_gateway/configuration"
+require "agent_gateway/query_runner"
+require "agent_gateway/engine"

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: agent_gateway
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jesse Waites
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: A mountable Rails engine that provides a configured, authenticated JSON
+  briefing endpoint for AI agents to consume app data.
+email:
+- jesse@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/controllers/agent_gateway/briefings_controller.rb
+- config/routes.rb
+- lando.jpeg
+- lib/agent_gateway.rb
+- lib/agent_gateway/configuration.rb
+- lib/agent_gateway/engine.rb
+- lib/agent_gateway/query_runner.rb
+- lib/agent_gateway/resource_config.rb
+- lib/agent_gateway/version.rb
+homepage: https://github.com/jessewaites/agent_gateway
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Rails engine exposing app data as a single AI-agent-friendly JSON endpoint
+test_files: []