lumen-llm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68399d42a44e4e0cfbdce9d294278dbe2a0aaa17d91795c0c8dc5faf0e3be502
+  data.tar.gz: 31d3eb2f3b8280fc97c35775587534f4cc6716cc7ddc788bfbc38d0c59e0f972
+SHA512:
+  metadata.gz: 38ae5b9ee3f02ff592a74df1e88ceef5815ac5ecdbf3243e756dc24623311343abc499accea0d0d6625d9b048b3dec077b166a7efe5c653701b46516b18cff77
+  data.tar.gz: 530d17a9d585f593f2369074900b994239c64eb204b86d34936bfb5625a6dc0fe0f988bba45edafceff4d054a4fcf671b2dc198edaf085628446e3ff0d596ab5

data/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+This repo contains the `lumen-llm` Ruby gem.
+
+## Ground Rules
+
+- Keep runtime dependencies at zero.
+- Keep Ruby syntax compatible with Ruby 2.3.
+- Keep Rails support optional and compatible with Rails 4+.
+- Use `LumenLLM::` as the canonical public namespace.
+- Keep `Lumen::` as a compatibility alias.
+- Do not add agent loops, tool calls, streaming, persistence, provider SDKs, or schema validation in v1.
+
+## Development Commands
+
+```sh
+bin/setup
+bin/test
+ruby -Ilib:test test/runner_test.rb
+bin/debug-template examples/templates/translator.yml examples/inputs/translator.json
+gem build lumen-llm.gemspec
+```
+
+## Testing Expectations
+
+- Use Minitest.
+- Keep the Minitest development dependency below `5.16` while Ruby 2.3 is supported.
+- Do not make real network calls in tests.
+- Prefer fake providers, fake transports, and in-memory stores.
+- Test public behavior instead of private implementation.
+- Run `bin/test` before handing off changes.
+
+## Compatibility Checklist
+
+Before changing code, check that the change:
+
+- avoids Ruby 2.4+ only syntax unless the support floor changes;
+- does not assume Rails constants exist;
+- does not assume ActiveSupport helpers exist;
+- does not assume Redis is installed;
+- does not require OpenRouter credentials in tests.
+
+## Skills
+
+Agent-facing skills live in `skills/`. Each skill must be a self-contained directory with a `SKILL.md` file containing YAML frontmatter with `name` and `description`.

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public gem extraction.
+- Provides YAML templates, single-call OpenRouter chat, JSON/text parsing, optional stores, and Rails integration.
+

data/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Thanks for helping improve `lumen-llm`.
+
+## Development
+
+Set up the project:
+
+```sh
+bin/setup
+```
+
+Run the test suite:
+
+```sh
+bin/test
+bundle exec rake test
+```
+
+Check template rendering:
+
+```sh
+bin/debug-template examples/templates/translator.yml examples/inputs/translator.json
+```
+
+Check gem packaging:
+
+```sh
+gem build --strict --output /tmp/lumen-llm-0.1.0.gem lumen-llm.gemspec
+```
+
+## Compatibility Rules
+
+- Keep runtime dependencies at zero.
+- Keep Ruby syntax compatible with Ruby 2.3.
+- Keep Rails support optional and compatible with Rails 4+.
+- Use `LumenLLM::` as the canonical public namespace.
+- Keep `Lumen::` as a compatibility alias.
+- Do not add agent loops, tool calls, streaming, persistence, provider SDKs, or schema validation in v1.
+
+## Tests
+
+- Use Minitest.
+- Do not make real network calls in tests.
+- Prefer fake providers, fake transports, and in-memory stores.
+- Test public behavior instead of private implementation.
+
+## Releases
+
+Only maintainers publish releases. Normal pushes and pull requests run CI only. RubyGems releases are triggered by `v*` tags through GitHub Actions and RubyGems Trusted Publishing.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Dong Xu
+
+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,203 @@
+# lumen-llm
+
+[![CI](https://github.com/uxgnod/lumen-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/uxgnod/lumen-llm/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/lumen-llm.svg)](https://rubygems.org/gems/lumen-llm)
+
+`lumen-llm` is a tiny Ruby LLM prompt runner for old Ruby and Rails apps.
+
+It provides the small set of features extracted from Lumen:
+
+- YAML prompt templates
+- simple `{{variable}}` interpolation
+- single-call OpenRouter chat completions
+- JSON or text response parsing
+- optional cache and usage stores
+- optional Rails 4+ defaults
+
+It intentionally does not provide agents, tool calls, streaming, vector search, provider SDKs, persistence, or schema validation.
+
+## Requirements
+
+- Ruby `>= 2.3`
+- Rails `>= 4` is optional
+- No runtime gem dependencies
+
+HTTP uses Ruby stdlib `net/http`. JSON, YAML, logger, URI, digest, and date are also stdlib.
+
+Ruby 2.3 and 2.4 are end-of-life runtimes. This gem supports them for legacy Rails apps, but new applications should use a maintained Ruby when possible.
+
+## Installation
+
+Install directly:
+
+```sh
+gem install lumen-llm
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "lumen-llm"
+```
+
+Then:
+
+```ruby
+require "lumen_llm"
+```
+
+## Configuration
+
+For a plain Ruby app:
+
+```ruby
+LumenLLM.configure do |config|
+  config.template_path = File.expand_path("lumen_templates", __dir__)
+  config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  config.openrouter_referer = "https://example.com"
+  config.openrouter_title = "MyApp"
+end
+```
+
+For Rails 4+:
+
+```ruby
+# config/initializers/lumen_llm.rb
+LumenLLM.configure do |config|
+  config.template_path = Rails.root.join("lumen_templates").to_s
+  config.logger = Rails.logger
+  config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  config.openrouter_referer = "https://www.example.com"
+  config.openrouter_title = "MyRailsApp"
+end
+```
+
+The Railtie sets `template_path` and `logger` defaults when Rails is present, but explicit configuration is recommended.
+
+## Templates
+
+Create `lumen_templates/translator.yml`:
+
+```yaml
+key: translator
+model: openai/gpt-5-mini
+provider: openrouter
+output_type: json
+
+system_prompt: |
+  You are a professional localization assistant.
+  Return only valid JSON. Do not use markdown.
+
+user_prompt: |
+  Translate "{{source_text}}" into these target languages:
+  {{target_languages_json}}
+
+  Return a JSON object using the same language codes as keys.
+```
+
+Run it:
+
+```ruby
+result = LumenLLM.run(
+  "translator",
+  input: {
+    source_text: "Save changes",
+    target_languages_json: { "de" => "German", "fr" => "French" }.to_json
+  }
+)
+
+puts result["de"]
+```
+
+## Compatibility Alias
+
+The canonical namespace is `LumenLLM`.
+
+For migrations from the original Rails-internal Lumen library, this gem also exposes:
+
+```ruby
+Lumen.run("translator", input: { ... })
+Lumen::TemplateLoader.load("translator")
+Lumen::Runner.new(template: template, input: input)
+```
+
+## Stores
+
+By default, `lumen-llm` uses `LumenLLM::Stores::NullStore`, which does not cache or record stats.
+
+Use memory store in tests or simple scripts:
+
+```ruby
+LumenLLM.configure do |config|
+  config.store = LumenLLM::Stores::MemoryStore.new
+end
+```
+
+Use Redis by passing an existing Redis-like client:
+
+```ruby
+redis = Redis.new(url: ENV["REDIS_URL"])
+
+LumenLLM.configure do |config|
+  config.store = LumenLLM::Stores::RedisStore.new(redis)
+end
+```
+
+`lumen-llm` does not depend on the `redis` gem. Your app owns that dependency.
+
+## Force Refresh
+
+```ruby
+LumenLLM.run("translator", input: input, force: true)
+```
+
+`force: true` bypasses the configured cache for that call.
+
+## Development Workflow
+
+```sh
+bin/setup
+bin/test
+bundle exec rake test
+bin/debug-template examples/templates/translator.yml examples/inputs/translator.json
+gem build --strict --output /tmp/lumen-llm-0.1.0.gem lumen-llm.gemspec
+```
+
+The test suite uses Minitest and no real network calls.
+Minitest is capped below `5.16` because newer Minitest releases require Ruby 2.6+.
+
+## Contributing
+
+Bug reports and small pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes, especially the Ruby 2.3 compatibility rules and the no-runtime-dependency constraint.
+
+## Security
+
+Please do not report security vulnerabilities in public issues. See [SECURITY.md](SECURITY.md) for the private reporting process.
+
+## Agent Skills
+
+The `skills/` directory contains Agent Skills compatible with the open `SKILL.md` format:
+
+- `skills/lumen-llm-setup`
+- `skills/lumen-llm-template-authoring`
+- `skills/lumen-llm-debugging`
+
+They help coding agents install, configure, test, and debug this gem without guessing project conventions.
+
+## Release
+
+Maintainers release through GitHub Actions and RubyGems Trusted Publishing.
+Normal pushes and pull requests only run checks; only `v*` tags trigger the release workflow.
+
+Build locally before tagging:
+
+```sh
+gem build --strict --output /tmp/lumen-llm-0.1.0.gem lumen-llm.gemspec
+```
+
+After CI passes and RubyGems trusted publishing is configured, publish by pushing a version tag:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```

data/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest released version of `lumen-llm`.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a security vulnerability.
+
+Email `uxgnod@gmail.com` with:
+
+- a description of the issue;
+- affected versions, if known;
+- reproduction steps or proof-of-concept details;
+- any suggested mitigation.
+
+We will acknowledge the report, investigate privately, and publish a fixed release when needed.
+
+## Security Notes
+
+`lumen-llm` intentionally keeps runtime dependencies at zero and does not include provider SDKs, persistence, agent loops, tool calls, or streaming in v1. Tests must not make real network calls or require OpenRouter credentials.

data/examples/inputs/translator.json

@@ -0,0 +1,5 @@
+{
+  "source_text": "Save changes",
+  "target_languages_json": "{\"de\":\"German\",\"fr\":\"French\",\"es\":\"Spanish\"}"
+}
+

data/examples/templates/translator.yml

@@ -0,0 +1,19 @@
+key: translator
+model: openai/gpt-5-mini
+provider: openrouter
+output_type: json
+
+system_prompt: |
+  You are a professional localization assistant for software products.
+  Translate short UI copy naturally and concisely.
+  Preserve placeholders, numbers, HTML tags, and product names.
+  Return only valid JSON. Do not use markdown.
+
+user_prompt: |
+  Translate the following source text into the target languages.
+
+  Source text: "{{source_text}}"
+  Target languages: {{target_languages_json}}
+
+  Return a JSON object using the exact same language codes from target languages as keys.
+

data/lib/lumen.rb

@@ -0,0 +1,2 @@
+require "lumen_llm"
+

data/lib/lumen_llm/configuration.rb

@@ -0,0 +1,39 @@
+require "logger"
+
+module LumenLLM
+  class Configuration
+    attr_accessor :template_path,
+                  :openrouter_api_key,
+                  :openrouter_referer,
+                  :openrouter_title,
+                  :store,
+                  :provider_registry,
+                  :cache_ttl,
+                  :http_open_timeout,
+                  :http_read_timeout
+
+    attr_writer :logger
+
+    def initialize
+      @template_path = nil
+      @logger = nil
+      @openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+      @openrouter_referer = ENV["OPENROUTER_REFERER"] || "https://example.com"
+      @openrouter_title = ENV["OPENROUTER_TITLE"] || "lumen-llm"
+      @store = nil
+      @provider_registry = nil
+      @cache_ttl = 3600
+      @http_open_timeout = 10
+      @http_read_timeout = 60
+    end
+
+    def logger
+      @logger ||= Logger.new($stderr)
+    end
+
+    def logger_configured?
+      !@logger.nil?
+    end
+  end
+end
+

data/lib/lumen_llm/errors.rb

@@ -0,0 +1,8 @@
+module LumenLLM
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class TemplateNotFoundError < Error; end
+  class ParserError < Error; end
+  class ProviderError < Error; end
+end
+

data/lib/lumen_llm/parser.rb

@@ -0,0 +1,13 @@
+module LumenLLM
+  module Parser
+    def self.extract(provider:, raw:, output_type:)
+      case provider.to_s
+      when "openrouter"
+        Providers::OpenRouter::Parser.extract(raw, output_type)
+      else
+        raise ParserError, "No parser defined for provider: #{provider}"
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/provider_registry.rb

@@ -0,0 +1,19 @@
+module LumenLLM
+  class ProviderRegistry
+    def initialize
+      @providers = {}
+    end
+
+    def register(name, provider = nil, &block)
+      @providers[name.to_s] = block || provider
+    end
+
+    def fetch(name)
+      provider = @providers[name.to_s]
+      raise ConfigurationError, "Unknown LLM provider: #{name}" unless provider
+
+      provider.respond_to?(:call) ? provider.call : provider
+    end
+  end
+end
+

data/lib/lumen_llm/providers/open_router/client.rb

@@ -0,0 +1,79 @@
+require "json"
+require "net/http"
+require "uri"
+
+module LumenLLM
+  module Providers
+    module OpenRouter
+      class Client
+        ENDPOINT = "https://openrouter.ai/api/v1/chat/completions"
+
+        def initialize(api_key: nil, referer: nil, title: nil, transport: nil, open_timeout: nil, read_timeout: nil)
+          config = LumenLLM.configuration
+          @api_key = api_key || config.openrouter_api_key || ENV["OPENROUTER_API_KEY"]
+          @referer = referer || config.openrouter_referer
+          @title = title || config.openrouter_title
+          @transport = transport || NetHTTPTransport.new
+          @open_timeout = open_timeout || config.http_open_timeout
+          @read_timeout = read_timeout || config.http_read_timeout
+        end
+
+        def chat(messages, model:)
+          raise ConfigurationError, "OpenRouter API key is not configured" if blank?(@api_key)
+
+          body = {
+            :model => model,
+            :messages => messages
+          }
+
+          response = @transport.request(
+            URI.parse(ENDPOINT),
+            headers,
+            body.to_json,
+            @open_timeout,
+            @read_timeout
+          )
+
+          unless success?(response)
+            raise ProviderError, "OpenRouter API Error: #{response.code} - #{response.body}"
+          end
+
+          JSON.parse(response.body)
+        end
+
+        private
+
+        def headers
+          {
+            "Authorization" => "Bearer #{@api_key}",
+            "Content-Type" => "application/json",
+            "HTTP-Referer" => @referer,
+            "X-Title" => @title
+          }
+        end
+
+        def success?(response)
+          response.code.to_i >= 200 && response.code.to_i < 300
+        end
+
+        def blank?(value)
+          value.nil? || value.to_s.strip == ""
+        end
+      end
+
+      class NetHTTPTransport
+        def request(uri, headers, body, open_timeout, read_timeout)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+
+          request = Net::HTTP::Post.new(uri.request_uri, headers)
+          request.body = body
+          http.request(request)
+        end
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/providers/open_router/parser.rb

@@ -0,0 +1,28 @@
+require "json"
+
+module LumenLLM
+  module Providers
+    module OpenRouter
+      class Parser
+        def self.extract(raw, output_type = "text")
+          content = raw.dig("choices", 0, "message", "content")
+          raise ParserError, "Missing content in response." unless content
+
+          clean = content.gsub(/```json|```/, "").strip
+
+          case output_type.to_s
+          when "json"
+            begin
+              JSON.parse(clean)
+            rescue JSON::ParserError
+              raise ParserError, "Invalid JSON output:\n#{clean}"
+            end
+          else
+            clean
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/railtie.rb

@@ -0,0 +1,15 @@
+require "lumen_llm"
+
+if defined?(Rails::Railtie)
+  module LumenLLM
+    class Railtie < Rails::Railtie
+      initializer "lumen_llm.configure" do |app|
+        LumenLLM.configure do |config|
+          config.template_path ||= app.root.join("lumen_templates").to_s
+          config.logger = Rails.logger unless config.logger_configured?
+        end
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/runner.rb

@@ -0,0 +1,50 @@
+require "digest/sha1"
+require "json"
+
+module LumenLLM
+  class Runner
+    def initialize(template:, input:, store: nil, provider_registry: nil)
+      @template = template
+      @input = input
+      @store = store || LumenLLM.configuration.store || Stores::NullStore.new
+      @provider_registry = provider_registry || LumenLLM.configuration.provider_registry || LumenLLM.provider_registry
+    end
+
+    def run(force: false)
+      cache_key = "lumen:#{@template.key}:#{Digest::SHA1.hexdigest(@input.to_json)}"
+
+      raw = if force
+        log("[LumenLLM::Runner] FORCE REFRESH: #{cache_key}")
+        generate
+      else
+        @store.cache(cache_key, :ttl => LumenLLM.configuration.cache_ttl) { generate }
+      end
+
+      Parser.extract(
+        provider: @template.provider,
+        raw: raw,
+        output_type: @template.output_type
+      )
+    end
+
+    private
+
+    def generate
+      payload = @template.render(@input)
+      response = @provider_registry.fetch(payload[:provider]).chat(payload[:messages], model: payload[:model])
+      track_stats(@template.key, response)
+      response
+    end
+
+    def track_stats(key, response)
+      usage = response["usage"] || {}
+      @store.incr_stat("prompt_tokens:#{key}", usage["prompt_tokens"]) if usage["prompt_tokens"]
+      @store.incr_stat("completion_tokens:#{key}", usage["completion_tokens"]) if usage["completion_tokens"]
+      @store.track_usage(key, response["model"], usage)
+    end
+
+    def log(message)
+      LumenLLM.configuration.logger.info(message)
+    end
+  end
+end

data/lib/lumen_llm/stores/memory_store.rb

@@ -0,0 +1,52 @@
+require "date"
+
+module LumenLLM
+  module Stores
+    class MemoryStore
+      def initialize
+        @values = {}
+        @stats = Hash.new(0)
+      end
+
+      def cache(key, _options = {})
+        return @values[key] if @values.key?(key)
+
+        @values[key] = yield
+      end
+
+      def incr_stat(metric, amount = 1)
+        @stats["stats:#{metric}"] += amount.to_i
+      end
+
+      def stat(key)
+        @stats["stats:#{key}"].to_i
+      end
+
+      def all_stats(pattern = "stats:*")
+        prefix = pattern.sub(/\*$/, "")
+        result = {}
+        @stats.each do |key, value|
+          result[key] = value if key.index(prefix) == 0
+        end
+        result
+      end
+
+      def track_usage(template_key, model, usage)
+        date = Date.today.strftime("%Y-%m-%d")
+        [
+          "usage:total",
+          "usage:#{template_key}",
+          "usage:model:#{model}",
+          "usage:#{template_key}:model:#{model}",
+          "usage:date:#{date}",
+          "usage:#{template_key}:date:#{date}"
+        ].each do |prefix|
+          incr_stat("#{prefix}:prompt_tokens", usage["prompt_tokens"])
+          incr_stat("#{prefix}:completion_tokens", usage["completion_tokens"])
+          incr_stat("#{prefix}:total_tokens", usage["total_tokens"])
+        end
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/stores/null_store.rb

@@ -0,0 +1,24 @@
+module LumenLLM
+  module Stores
+    class NullStore
+      def cache(_key, _options = {})
+        yield
+      end
+
+      def incr_stat(_metric, _amount = 1)
+      end
+
+      def stat(_key)
+        0
+      end
+
+      def all_stats(_pattern = "stats:*")
+        {}
+      end
+
+      def track_usage(_template_key, _model, _usage)
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/stores/redis_store.rb

@@ -0,0 +1,55 @@
+require "json"
+require "date"
+
+module LumenLLM
+  module Stores
+    class RedisStore
+      def initialize(redis)
+        @redis = redis
+      end
+
+      def cache(key, options = {})
+        ttl = options[:ttl] || 3600
+        value = @redis.get(key)
+        return JSON.parse(value) if value
+
+        result = yield
+        @redis.setex(key, ttl, result.to_json)
+        result
+      end
+
+      def incr_stat(metric, amount = 1)
+        @redis.incrby("stats:#{metric}", amount.to_i)
+      end
+
+      def stat(key)
+        @redis.get("stats:#{key}").to_i
+      end
+
+      def all_stats(pattern = "stats:*")
+        result = {}
+        @redis.keys(pattern).each do |key|
+          result[key] = @redis.get(key).to_i
+        end
+        result
+      end
+
+      def track_usage(template_key, model, usage)
+        date = Date.today.strftime("%Y-%m-%d")
+        [
+          "usage:total",
+          "usage:#{template_key}",
+          "usage:model:#{model}",
+          "usage:#{template_key}:model:#{model}",
+          "usage:date:#{date}",
+          "usage:#{template_key}:date:#{date}"
+        ].each do |prefix|
+          incr_stat("#{prefix}:prompt_tokens", usage["prompt_tokens"])
+          incr_stat("#{prefix}:completion_tokens", usage["completion_tokens"])
+          incr_stat("#{prefix}:total_tokens", usage["total_tokens"])
+        end
+      end
+    end
+  end
+end
+

data/lib/lumen_llm/template.rb

@@ -0,0 +1,36 @@
+module LumenLLM
+  class Template
+    attr_reader :key, :system_prompt, :user_prompt, :model, :provider, :output_type
+
+    def initialize(key:, system_prompt:, user_prompt:, model:, provider: :openrouter, output_type: :json)
+      @key = key.to_s
+      @system_prompt = system_prompt.to_s
+      @user_prompt = user_prompt.to_s
+      @model = model.to_s
+      @provider = provider.to_s
+      @output_type = output_type.to_s
+    end
+
+    def render(input)
+      {
+        :provider => provider,
+        :model => model,
+        :messages => [
+          { :role => "system", :content => interpolate(system_prompt, input) },
+          { :role => "user", :content => interpolate(user_prompt, input) }
+        ]
+      }
+    end
+
+    private
+
+    def interpolate(str, input)
+      rendered = str.dup
+      input.each do |key, value|
+        rendered = rendered.gsub("{{#{key}}}", value.to_s)
+      end
+      rendered
+    end
+  end
+end
+

data/lib/lumen_llm/template_loader.rb

@@ -0,0 +1,36 @@
+require "yaml"
+
+module LumenLLM
+  class TemplateLoader
+    def self.load(key, path: nil)
+      new(path || LumenLLM.configuration.template_path).load(key)
+    end
+
+    def initialize(path)
+      @path = path
+    end
+
+    def load(key)
+      raise ConfigurationError, "template_path is not configured" if blank?(@path)
+
+      template_file = File.join(@path.to_s, "#{key}.yml")
+      raise TemplateNotFoundError, "Template not found: #{key}" unless File.exist?(template_file)
+
+      config = YAML.load_file(template_file)
+      Template.new(
+        key: config["key"] || key,
+        system_prompt: config["system_prompt"],
+        user_prompt: config["user_prompt"],
+        model: config["model"],
+        provider: config["provider"] || "openrouter",
+        output_type: config["output_type"] || "text"
+      )
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.to_s.strip == ""
+    end
+  end
+end

data/lib/lumen_llm/version.rb

@@ -0,0 +1,4 @@
+module LumenLLM
+  VERSION = "0.1.0"
+end
+

data/lib/lumen_llm.rb

@@ -0,0 +1,57 @@
+require "lumen_llm/version"
+require "lumen_llm/errors"
+require "lumen_llm/configuration"
+require "lumen_llm/template"
+require "lumen_llm/template_loader"
+require "lumen_llm/provider_registry"
+require "lumen_llm/stores/null_store"
+require "lumen_llm/stores/memory_store"
+require "lumen_llm/stores/redis_store"
+require "lumen_llm/providers/open_router/client"
+require "lumen_llm/providers/open_router/parser"
+require "lumen_llm/parser"
+require "lumen_llm/runner"
+
+module LumenLLM
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @provider_registry = nil
+    end
+
+    def provider_registry
+      @provider_registry ||= default_provider_registry
+    end
+
+    def run(template_key, input: {}, force: false, store: nil, provider_registry: nil)
+      template = TemplateLoader.load(template_key)
+      Runner.new(
+        template: template,
+        input: input,
+        store: store,
+        provider_registry: provider_registry
+      ).run(force: force)
+    end
+
+    private
+
+    def default_provider_registry
+      registry = ProviderRegistry.new
+      registry.register("openrouter") { Providers::OpenRouter::Client.new }
+      registry
+    end
+  end
+end
+
+Lumen = LumenLLM unless defined?(::Lumen)
+
+require "lumen_llm/railtie" if defined?(Rails)

data/skills/lumen-llm-debugging/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: lumen-llm-debugging
+description: Use when debugging lumen-llm failures involving template loading, OpenRouter requests, JSON parsing, cache behavior, or Rails integration.
+---
+
+# lumen-llm Debugging
+
+Use this skill when a user reports a failing `LumenLLM.run` call.
+
+## Checklist
+
+1. Confirm the template path and template key.
+2. Render the template locally with `bin/debug-template`.
+3. Check `OPENROUTER_API_KEY` or explicit `config.openrouter_api_key`.
+4. Confirm the model name is available through OpenRouter.
+5. If JSON parsing fails, inspect the raw response content for markdown fences or explanations.
+6. If cache seems stale, retry with `force: true`.
+7. If Rails integration fails, require `lumen_llm` and inspect the initializer.
+
+## Useful Commands
+
+```sh
+bin/test
+bin/debug-template examples/templates/translator.yml examples/inputs/translator.json
+ruby -Ilib -e 'require "lumen_llm"; p LumenLLM.configuration'
+```
+
+## Common Causes
+
+- Missing template path.
+- Template filename does not match the key passed to `LumenLLM.run`.
+- The model returned non-JSON while `output_type: json` was set.
+- Redis was assumed to exist but no store was configured.
+- Rails app used `Settings.openrouter`; migrate to explicit `LumenLLM.configure`.
+

data/skills/lumen-llm-setup/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: lumen-llm-setup
+description: Use when installing, configuring, or migrating the lumen-llm Ruby gem in a Ruby or Rails app, especially Rails 4/5 apps that need a lightweight OpenRouter LLM runner.
+---
+
+# lumen-llm Setup
+
+Use this skill when a user asks to add `lumen-llm`, migrate from an internal `Lumen` module, or configure OpenRouter credentials.
+
+## Workflow
+
+1. Inspect the app Ruby and Rails versions before editing.
+2. Add `gem "lumen-llm"` to the Gemfile.
+3. Add `require "lumen_llm"` only when the app does not use Bundler autorequire.
+4. For Rails, create `config/initializers/lumen_llm.rb`.
+5. Configure `template_path`, `logger`, `openrouter_api_key`, `openrouter_referer`, and `openrouter_title`.
+6. Choose a store:
+   - no store for default no-cache behavior;
+   - `MemoryStore` for local scripts and tests;
+   - `RedisStore` with an app-owned Redis client for production cache/stats.
+7. Add a template under `lumen_templates/`.
+8. Verify with a fake provider or a single manual OpenRouter call.
+
+## Rails Initializer Pattern
+
+```ruby
+LumenLLM.configure do |config|
+  config.template_path = Rails.root.join("lumen_templates").to_s
+  config.logger = Rails.logger
+  config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+  config.openrouter_referer = "https://www.example.com"
+  config.openrouter_title = "MyRailsApp"
+end
+```
+
+## Migration Notes
+
+- Prefer new calls as `LumenLLM.run(...)`.
+- Existing `Lumen.run(...)`, `Lumen::TemplateLoader`, and `Lumen::Runner` are supported through the compatibility alias.
+- Do not depend on app-specific `Settings`; pass values through `LumenLLM.configure`.
+

data/skills/lumen-llm-template-authoring/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: lumen-llm-template-authoring
+description: Use when creating or reviewing lumen-llm YAML prompt templates, especially templates that require JSON output and Ruby 2.3/Rails 4 compatibility.
+---
+
+# lumen-llm Template Authoring
+
+Use this skill when writing templates under `lumen_templates/` or `examples/templates/`.
+
+## Template Shape
+
+```yaml
+key: translator
+model: openai/gpt-5-mini
+provider: openrouter
+output_type: json
+
+system_prompt: |
+  Return only valid JSON.
+
+user_prompt: |
+  Input: {{input_json}}
+```
+
+## Rules
+
+- Use `{{variable_name}}` placeholders.
+- Pass structured data as JSON strings from Ruby.
+- Set `output_type: json` only when the model is instructed to return raw JSON.
+- Tell the model not to wrap JSON in markdown.
+- Preserve placeholders and product names when translating UI copy.
+- Keep templates app-specific; the gem should only ship generic examples.
+
+## Test Pattern
+
+Use `LumenLLM::TemplateLoader.load` to load the template and `template.render(input)` to verify the rendered messages. Use a fake provider for full runner tests.
+

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: lumen-llm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dong Xu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+- !ruby/object:Gem::Dependency
+  name: mutex_m
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+description: lumen-llm provides YAML prompt templates, single-call OpenRouter chat
+  completion, JSON/text parsing, optional cache stores, and Rails 4+ integration without
+  runtime gem dependencies.
+email:
+- uxgnod@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- SECURITY.md
+- examples/inputs/translator.json
+- examples/templates/translator.yml
+- lib/lumen.rb
+- lib/lumen_llm.rb
+- lib/lumen_llm/configuration.rb
+- lib/lumen_llm/errors.rb
+- lib/lumen_llm/parser.rb
+- lib/lumen_llm/provider_registry.rb
+- lib/lumen_llm/providers/open_router/client.rb
+- lib/lumen_llm/providers/open_router/parser.rb
+- lib/lumen_llm/railtie.rb
+- lib/lumen_llm/runner.rb
+- lib/lumen_llm/stores/memory_store.rb
+- lib/lumen_llm/stores/null_store.rb
+- lib/lumen_llm/stores/redis_store.rb
+- lib/lumen_llm/template.rb
+- lib/lumen_llm/template_loader.rb
+- lib/lumen_llm/version.rb
+- skills/lumen-llm-debugging/SKILL.md
+- skills/lumen-llm-setup/SKILL.md
+- skills/lumen-llm-template-authoring/SKILL.md
+homepage: https://github.com/uxgnod/lumen-llm
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/uxgnod/lumen-llm
+  changelog_uri: https://github.com/uxgnod/lumen-llm/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/uxgnod/lumen-llm/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A tiny Ruby/Rails-friendly LLM prompt runner for OpenRouter.
+test_files: []