locallingo 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 931aa3bf94ee48a2021c8ec6f5de047e593f2f94bc5ba01e20b48bd1b2e96d3c
-  data.tar.gz: fcbab1174c9dbefb317fdae26a0c0a763f4a3b8026b19f8fe8f08a54d222f8fb
+  metadata.gz: ff4c0e72d7b3eb6d699b7cff03d8e2b8a61efb8a1c94c16cc906f2843b4dc53c
+  data.tar.gz: c4419498f0f7de3b334efab4c89471eb3a6a27da543992b5171aa3b67760c3d6
 SHA512:
-  metadata.gz: 9bc87c498dcc47fbda209f58005ce265f09ef5432107bbced4f9185e32ae51873b6aae014f7f11f650cd4905328169cb32e8f477c9ab1d310f2b4692da350ce8
-  data.tar.gz: 65f2c9cbf024baa4cb89202da61fff2d4feb0de544c2ea85371525714e83a322ac93f065ae08239e67f562d0158b0ddf01acd199e9d9060614f3c02afa8f37a5
+  metadata.gz: 7820e2f62b6784ae546cd7521303e434a0319099f1ac69fa7471aff9cb786ff3b844f1200ae711eab36df7e058b31742f03de231c5bd95d460889c1027209628
+  data.tar.gz: b727c0b6f89916f328f3c2b00831263d779b7a7139f478571d7b2e9015326ef8841873da7e72ddd6f963e7f0009dafe9cc4630c1d6883d091bb165672d70fc67

data/CHANGELOG.md

@@ -7,6 +7,13 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Added
+- `Locallingo.configure { |c| c.anthropic_api_key = ... }` — gem-level provider
+  credentials as Strings or lazy callables, for apps whose keys don't live in
+  ENV (Rails credentials, app config objects, vaults). Precedence:
+  `Locallingo.configure` → host `RubyLLM.configure` → ENV.
+- `.locallingo.rb` setup file: the CLI loads it from the project root before
+  dispatch, so standalone `lingo` runs can configure credentials without
+  booting Rails.
 - Initial extraction from the `bin/translate` toolchain into a standalone gem.
 - `lingo` CLI with subcommands: `status`, `translate`, `validate`, `quality`,
   `fix-quality`, `accept-edits`, `hash`, `sync`. Legacy `--flag` forms still work

data/README.md

@@ -32,8 +32,21 @@ group :development do
 end
 ```
 
-RubyLLM reads provider credentials from ENV (e.g. `OPENAI_API_KEY`,
-`ANTHROPIC_API_KEY`). Locallingo never stores keys.
+Provider credentials come from ENV (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
+or from Ruby, for apps whose keys live elsewhere (Rails credentials, an app
+config object, a vault):
+
+```ruby
+Locallingo.configure do |config|
+  config.anthropic_api_key = "sk-ant-..."            # a String…
+  config.openai_api_key = -> { AppConf.openai_key }  # …or a lazy callable
+end
+```
+
+Put that in a `.locallingo.rb` file next to `.locallingo.yml` and the `lingo`
+CLI loads it on start — no Rails boot required. A key set via
+`Locallingo.configure` wins over one set through `RubyLLM.configure`, which
+wins over ENV. Locallingo never stores keys itself.
 
 ## Configuration
 

data/lib/locallingo/cli.rb

@@ -16,6 +16,11 @@ module Locallingo
   class CLI
     CLI_NAME = "lingo"
 
+    # Optional Ruby setup file loaded before dispatch — the hook for apps to
+    # configure credentials (via Locallingo.configure or RubyLLM.configure)
+    # without booting Rails.
+    SETUP_FILENAME = ".locallingo.rb"
+
     # subcommand => the legacy flag it replaces
     COMMANDS = {
       "status" => "--status",
@@ -52,6 +57,7 @@ module Locallingo
     def run
       command = resolve_command
       options = parse_options!
+      load_setup_file
       config = Locallingo.configuration(root_path: Dir.pwd, package: options[:package])
       dispatch(command, config, options)
     rescue Locallingo::Error => e
@@ -61,6 +67,13 @@ module Locallingo
 
     private
 
+    # An absent file is fine; errors in the file propagate loudly. `load` (not
+    # require) so repeated in-process invocations re-execute it.
+    def load_setup_file
+      path = File.join(Dir.pwd, SETUP_FILENAME)
+      load path if File.file?(path)
+    end
+
     # Determine the subcommand, translating a leading legacy flag (with a
     # deprecation notice) and defaulting to `status`.
     def resolve_command

data/lib/locallingo/providers/ruby_llm.rb

@@ -31,14 +31,14 @@ module Locallingo
         @provider = provider.to_sym
       end
 
-      # True when credentials for the configured provider are present in ENV.
-      # Unknown providers are assumed configured (RubyLLM may source the key
-      # elsewhere) rather than blocking.
+      # True when a key for the configured provider is found in any source
+      # (Locallingo settings, host RubyLLM config, ENV). Unknown providers are
+      # assumed configured (RubyLLM may source the key elsewhere) rather than
+      # blocking.
       def credentials?
-        env = CREDENTIAL_ENV[provider]
-        return true unless env
+        return true unless CREDENTIAL_ENV.key?(provider)
 
-        !ENV.fetch(env, "").to_s.strip.empty?
+        !resolved_api_key.nil?
       end
 
       # Raise a precise error when the provider has no credentials.
@@ -46,8 +46,10 @@ module Locallingo
         return if credentials?
 
         raise MissingCredentialsError,
-              "No credentials for provider #{provider.inspect} " \
-              "(expected #{CREDENTIAL_ENV[provider]} in ENV)"
+              "No credentials for provider #{provider.inspect}. " \
+              "Set #{CREDENTIAL_ENV[provider]} in ENV, call " \
+              "Locallingo.configure { |c| c.#{provider}_api_key = ... }, or add a " \
+              ".locallingo.rb setup file at the project root (loaded by the CLI)."
       end
 
       # Send +instructions+ (system prompt) + +payload+ (user message, JSON) to
@@ -70,20 +72,55 @@ module Locallingo
 
       # RubyLLM does not read provider API keys from ENV on its own, so a
       # standalone CLI run (no Rails initializer to call RubyLLM.configure)
-      # would raise "Missing configuration for <provider>". Fill the
-      # provider's key from ENV — unless the host app already configured
-      # one, which always wins.
+      # would raise "Missing configuration for <provider>". Push the resolved
+      # key into RubyLLM's config: an explicit `Locallingo.configure` key wins
+      # (re-resolved every chat so callables stay live), then a key the host
+      # app already set, then the ENV fallback.
       def configure_credentials!
-        env = CREDENTIAL_ENV[provider]
-        return unless env
+        return unless CREDENTIAL_ENV.key?(provider)
 
-        setting = "#{provider}_api_key"
         config = ::RubyLLM.config
+        setting = key_setting
         return unless config.respond_to?(setting) && config.respond_to?("#{setting}=")
-        return unless config.public_send(setting).to_s.strip.empty?
 
-        key = ENV.fetch(env, "")
-        config.public_send("#{setting}=", key) unless key.strip.empty?
+        key = settings_api_key
+        return if key.nil? && !presence(config.public_send(setting)).nil?
+
+        key ||= env_api_key
+        config.public_send("#{setting}=", key) unless key.nil?
+      end
+
+      # Key resolution across sources, in precedence order. Used by
+      # #credentials? as a fail-fast check before any network call.
+      def resolved_api_key
+        settings_api_key || host_configured_api_key || env_api_key
+      end
+
+      def settings_api_key
+        Locallingo.settings.api_key_for(provider)
+      end
+
+      # A key the host app set via RubyLLM.configure — only inspected when
+      # ruby_llm is already loaded (we never require it just to peek).
+      def host_configured_api_key
+        return nil unless defined?(::RubyLLM)
+
+        config = ::RubyLLM.config
+        return nil unless config.respond_to?(key_setting)
+
+        presence(config.public_send(key_setting))
+      end
+
+      def env_api_key
+        env = CREDENTIAL_ENV[provider]
+        env ? presence(ENV.fetch(env, "")) : nil
+      end
+
+      def key_setting = "#{provider}_api_key"
+
+      def presence(value)
+        key = value.to_s.strip
+        key.empty? ? nil : key
       end
     end
   end

data/lib/locallingo/settings.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Locallingo
+  # Code-level gem settings, configured via `Locallingo.configure`. Distinct
+  # from Locallingo::Configuration, which loads the `.locallingo.yml` project
+  # file — Settings holds what must never live in YAML: provider credentials.
+  #
+  #   Locallingo.configure do |config|
+  #     config.anthropic_api_key = ENV.fetch("MY_KEY")          # a String…
+  #     config.openai_api_key = -> { Vault.read("openai_key") } # …or a callable
+  #   end
+  #
+  # Callables are resolved lazily on every use (never memoized), so keys can
+  # come from sources that aren't ready at configure time or that rotate.
+  class Settings
+    PROVIDERS = %i[openai anthropic gemini deepseek openrouter].freeze
+
+    attr_accessor(*PROVIDERS.map { |name| :"#{name}_api_key" })
+
+    # The usable key for +provider+: callables are called, results stripped,
+    # and blank or unknown-provider values come back as nil.
+    def api_key_for(provider)
+      return nil unless PROVIDERS.include?(provider.to_sym)
+
+      value = public_send("#{provider}_api_key")
+      value = value.call if value.respond_to?(:call)
+      key = value.to_s.strip
+      key.empty? ? nil : key
+    end
+  end
+end

data/lib/locallingo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Locallingo
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/locallingo.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "locallingo/version"
+require_relative "locallingo/settings"
 require_relative "locallingo/configuration"
 require_relative "locallingo/json_extraction"
 require_relative "locallingo/key_flattener"
@@ -35,4 +36,21 @@ module Locallingo
   def self.configuration(root_path: Dir.pwd, package: nil)
     Configuration.load(root_path:, package:)
   end
+
+  # Code-level settings (provider credentials) — see Locallingo::Settings.
+  def self.settings
+    @settings ||= Settings.new
+  end
+
+  # Configure the gem from Ruby — the credentials path for apps whose keys
+  # don't live in ENV (call it from a Rails initializer or a `.locallingo.rb`
+  # setup file next to `.locallingo.yml`; the CLI loads the latter on start).
+  def self.configure
+    yield settings
+    settings
+  end
+
+  def self.reset_settings!
+    @settings = nil
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: locallingo
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -81,6 +81,7 @@ files:
 - lib/locallingo/quality_checker.rb
 - lib/locallingo/reporter.rb
 - lib/locallingo/rubocop.rb
+- lib/locallingo/settings.rb
 - lib/locallingo/state_store.rb
 - lib/locallingo/validators/duplicate_values.rb
 - lib/locallingo/validators/manual_edits.rb