silas 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6fb5d6a2e04f91a4bc0ac0569a37da43017f6adae7209148878a2cb8ac41a66
-  data.tar.gz: 9d8ed143aac8d96d264a10ed3cf87c8ecee1ed838ba01ca67075a4a9a07e3b09
+  metadata.gz: 7a34eec0f8444f42ef91b1db155bc2786c28ce0de5ed345d9e63b39af9b29756
+  data.tar.gz: 94c9b0464629b6f23eab8f4811e5dd63cdec63d480388cf01c8b0b9111a43376
 SHA512:
-  metadata.gz: e01f7110a093b91b30af1c08d4d8167aaaa24861812702c10ba5078f952e7eea4ddb5851e484f6cb2815d171271de9a45d8b7cc275e3d59dcaa2541ad9731628
-  data.tar.gz: c84142c165b45db56d5761a64a62993e7332a2209593ff1c59afd58723beafc5e2bd2c14f1495fbb8963d664a69469f28829dece7d6e973e8a5e123963ca526b
+  metadata.gz: 62c5e530ccc6cfbc3cbfa7b1388b72e53545172acc054b7565930eef56541f8e839846435435585db3fcc3161d40994345b0da5e24fcdc0de1710988efc7ab35
+  data.tar.gz: e8c83c1733efd76810fe2d0cd5e5e57c8b1d929d1a5556d685e376c704108c550494f07e6eb332d6968e458f1bfbb85b5fc024016d1f951dfb1d6a351b6b4683

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.6.2 (2026-07-26)
+
+The providers guide and the remaining community files.
+
+### Added
+
+- **`docs/providers.md` — Providers & gateways.** How a model id picks a
+  provider (and why Silas stamps the resolved provider on every step row),
+  the OpenRouter recipe — one key, 300+ models, slash-form ids, with cost
+  lines and `compact_at` following the registry entry for the route you
+  actually run — plus OpenAI-compatible gateways (LiteLLM, Vercel AI
+  Gateway) via `openai_api_base`/`openrouter_api_base`, the
+  Bedrock/Vertex/Azure key map, local runtimes with the honest
+  cost-unavailable story, and `around_model_call` for failover. Every
+  mechanical claim verified against ruby_llm 1.16 source and a live
+  resolution run; Vercel endpoint details from their docs as of 2026-07-07.
+  Ships in the gem; linked from the configuration reference, the README,
+  and the installer's `ruby_llm.rb` initializer comment.
+- **`CODE_OF_CONDUCT.md`** (Contributor Covenant 2.1), linked from
+  CONTRIBUTING and the README.
+- **A pull request template** mirroring CONTRIBUTING's actual gates: both
+  stores, RuboCop, the chaos gate when the loop is touched, the
+  templates-smoke run when generators change, and a durability-notes
+  section for replay-path changes.
+
+### Fixed
+
+- README's status line claimed 0.5.x.
+
 ## 0.6.1 (2026-07-26)
 
 Two live-inbox fixes found by driving real apps, a security hardening pass,

data/README.md

@@ -100,9 +100,11 @@ release): [guarantees](https://danielstpaul.github.io/silas/guarantees).
 
 ## Status
 
-Early (0.5.x) and moving fast. Requires Rails >= 8.1 (Active Job
+Early (0.6.x) and moving fast. Requires Rails >= 8.1 (Active Job
 Continuations) and Solid Queue >= 1.2; any model provider
-[RubyLLM](https://rubyllm.com) supports.
+[RubyLLM](https://rubyllm.com) supports — Anthropic direct, OpenRouter,
+OpenAI-compatible gateways, local runtimes
+([providers guide](https://github.com/danielstpaul/silas/blob/main/docs/providers.md)).
 
 ## Community
 
@@ -113,7 +115,9 @@ Questions, ideas, and bug reports →
 
 See [CONTRIBUTING.md](https://github.com/danielstpaul/silas/blob/main/CONTRIBUTING.md)
 — including the short list of things Silas deliberately doesn't do, and the
-chaos gate that protects the durability contract.
+chaos gate that protects the durability contract. Everyone interacting here
+is expected to follow the
+[code of conduct](https://github.com/danielstpaul/silas/blob/main/CODE_OF_CONDUCT.md).
 
 ## Security
 

data/docs/configuration.md

@@ -18,6 +18,10 @@ end
 | `around_model_call` | `nil` | Wrap every model call — e.g. `->(ctx, &call) { RubyLLM::Resilience.chain(:anthropic) { call.() } }`. |
 | `queue_name` | `:default` | Active Job queue for agent turns. |
 
+Which provider serves a turn is decided by the model id — OpenRouter,
+OpenAI-compatible gateways, Bedrock/Vertex/Azure, and local runtimes are all
+recipes in [providers](providers.md).
+
 ## The loop
 
 | Option | Default | Meaning |

data/docs/providers.md

@@ -0,0 +1,171 @@
+# Providers & gateways
+
+Silas has exactly one inference seam: the `:ruby_llm` adapter. Every model
+call goes through [RubyLLM](https://rubyllm.com), so every provider RubyLLM
+speaks — Anthropic, OpenAI, Gemini, Bedrock, Vertex AI, Azure, Mistral,
+DeepSeek, Perplexity, xAI, OpenRouter, local runtimes — is available to your
+agents with zero Silas-specific glue. Keys live in
+`config/initializers/ruby_llm.rb`; **which provider serves a turn is decided
+by the model id**. Nothing in `app/agent/` changes when the provider does.
+
+## How a model id picks a provider
+
+RubyLLM ships a model registry (1,100+ entries, refreshed upstream from
+[models.dev](https://models.dev)). Silas resolves the agent's `model:` — from
+`agent.yml`, falling back to `config.default_model` — against that registry;
+the matching entry names the provider, and the adapter builds that provider's
+client. The same entry supplies the numbers Silas runs on, per
+(model, provider):
+
+- **pricing** — the cost lines in the inbox and the `max_cost` budget;
+- **context window** — the `compact_at` compaction threshold.
+
+So switching provider is switching model id. A model the registry doesn't
+know fails fast at the first step with the fix in the error
+(`RubyLLM.models.refresh!`, or pick a registry model). And because a
+registry's tie-breaks can change across upgrades, Silas stamps the resolved
+provider on every step row — historical cost lines price against the
+(model, provider) that actually served them, forever.
+
+## Direct providers
+
+The installer's `config/initializers/ruby_llm.rb` maps environment keys in —
+RubyLLM never reads provider keys from the environment by itself:
+
+```ruby
+RubyLLM.configure do |c|
+  c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+end
+```
+
+Every provider follows the same pattern (`openai_api_key`,
+`gemini_api_key`, …— the full list is in
+[RubyLLM's configuration docs](https://rubyllm.com/configuration/)). For
+cloud-platform shops the "enterprise gateway" is usually just the native
+provider:
+
+| Platform | Keys |
+|---|---|
+| AWS Bedrock | `bedrock_api_key`, `bedrock_secret_key`, `bedrock_region` (+ optional `bedrock_session_token`) |
+| GCP Vertex AI | `vertexai_project_id`, `vertexai_location` (+ optional `vertexai_service_account_key`) |
+| Azure OpenAI | `azure_api_base`, `azure_api_key` (or `azure_ai_auth_token`) |
+
+Verify any of this with `bin/rails silas:doctor` — it reports which providers
+have credentials configured and resolves your default model with its price:
+
+```
+ ✓ provider credentials — anthropic
+ ✓ model claude-sonnet-4-5 — anthropic · $3/$15 per MTok
+```
+
+## OpenRouter: one key, 300+ models
+
+[OpenRouter](https://openrouter.ai) is a first-class RubyLLM provider, and
+the registry ships its catalog (341 models as of ruby_llm 1.16) — one key
+buys your agents Claude, GPT, Gemini, Llama, DeepSeek and the rest, billed
+in one place.
+
+```ruby
+# config/initializers/ruby_llm.rb
+RubyLLM.configure do |c|
+  c.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+end
+```
+
+Routed models use slash-form ids — `creator/model`, exactly as OpenRouter
+lists them:
+
+```yaml
+# app/agent/agent.yml
+model: anthropic/claude-sonnet-4.5   # via OpenRouter
+```
+
+or globally:
+
+```ruby
+Silas.configure do |c|
+  c.default_model = "anthropic/claude-sonnet-4.5"
+end
+```
+
+The two id families never collide: `claude-sonnet-4-5` is Anthropic direct,
+`anthropic/claude-sonnet-4.5` is the same model via OpenRouter, and each
+resolves to its own registry entry. That per-route entry is the one your
+cost lines and compaction thresholds follow — the route you run, not the
+origin provider. Concretely, in the shipped registry the direct entry lists
+a 200K context window while OpenRouter's route lists 1M, so `compact_at`
+triggers where the route actually overflows.
+
+`silas:doctor` confirms the whole chain:
+
+```
+ ✓ provider credentials — openrouter
+ ✓ model anthropic/claude-sonnet-4.5 — openrouter · $3/$15 per MTok
+```
+
+## OpenAI-compatible gateways
+
+Self-hosted and enterprise gateways (LiteLLM, Vercel AI Gateway, an internal
+proxy) mostly speak the OpenAI chat-completions dialect. Two shapes:
+
+**The gateway serves OpenAI model ids** (`gpt-5.2`, …) — point the OpenAI
+provider at it:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openai_api_key  = ENV["GATEWAY_API_KEY"]
+  c.openai_api_base = "https://gateway.internal/v1"
+end
+```
+
+**The gateway serves models.dev slash ids** (`anthropic/claude-sonnet-4.5`,
+…, as Vercel's AI Gateway does) — repoint the OpenRouter provider, which
+already speaks plain chat-completions against exactly those ids:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openrouter_api_key  = ENV["AI_GATEWAY_API_KEY"]
+  c.openrouter_api_base = "https://ai-gateway.vercel.sh/v1"
+end
+```
+
+Either way the model id must still resolve in the registry — the registry
+entry is where Silas gets pricing and the context window, and a gateway
+that bills differently can be corrected per model with the
+`config.model_prices` override ([configuration](configuration.md)).
+
+Two gateway footnotes, both cheap to check with one real turn:
+
+- RubyLLM renders system messages as role `developer` (OpenAI's current
+  dialect) through these providers. OpenRouter normalises it; if your
+  gateway insists on `system`, set `c.openai_use_system_role = true`.
+- Streaming must pass through as SSE. If the operator inbox shows a turn
+  completing without live text, the gateway buffered the stream.
+
+## Local runtimes
+
+Ollama and GPUStack are RubyLLM providers too (`ollama_api_base`,
+`gpustack_api_base`/`gpustack_api_key`). Local models aren't in the shipped
+registry, so refresh it after configuring — `RubyLLM.models.refresh!` asks
+every configured provider for its live model list and merges the results —
+then use the id it lists. Local models carry no registry pricing: the inbox
+shows their token counts with "cost unavailable", and a `max_cost` budget
+can't bind (only priced tokens count toward it) — list the model in
+`config.model_prices` to restore both.
+
+## Failover and wrapping
+
+Provider outages, rate-limit retries and model failover belong at the
+inference seam, not in your tools. `config.around_model_call` wraps every
+model call the loop makes:
+
+```ruby
+Silas.configure do |c|
+  c.around_model_call = ->(ctx, &call) do
+    RubyLLM::Resilience.chain(:anthropic) { call.() }
+  end
+end
+```
+
+Whatever runs inside still lands in the same durable step — a failover
+retry that succeeds is recorded exactly like a first-try success.

data/lib/generators/silas/install/templates/ruby_llm.rb

@@ -3,7 +3,9 @@
 #
 #   export ANTHROPIC_API_KEY=sk-ant-...
 #
-# Any provider RubyLLM supports works the same way (openai_api_key, etc.).
+# Any provider RubyLLM supports works the same way (openai_api_key, etc.) —
+# OpenRouter, OpenAI-compatible gateways, and local runtimes are covered in
+# the Silas guide docs/providers.md (shipped in the gem: `bundle show silas`).
 RubyLLM.configure do |c|
   # Silas never uses RubyLLM's acts_as_* ActiveRecord mixins (it owns its own
   # durable schema), so opt into the new API to silence the legacy deprecation

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.6.1"
+  VERSION = "0.6.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Daniel St Paul
@@ -177,6 +177,7 @@ files:
 - docs/guarantees.md
 - docs/inbox-and-api.md
 - docs/memory.md
+- docs/providers.md
 - docs/sandbox.md
 - docs/tools.md
 - docs/tutorial.md