rasti-ai 3.0.1 → 3.2.0

data/AGENTS.md

@@ -4,27 +4,115 @@ Developer and agent reference. For usage examples see README.md.
 
 ## Architecture
 
+### Provider
+
+`Rasti::AI::Provider` is the entry point that makes provider and model a runtime value instead of a class reference. An instance holds the transport configuration (`api_key`, `usage_tracker`, `logger`, HTTP timeouts) plus the default `model`, and knows how to build the provider's `Client` and `Assistant`.
+
+The set of providers is **fixed** — there is no registry and third-party providers are not supported. Two frozen constants in the base class drive resolution:
+
+```ruby
+MODULES = {open_ai: 'OpenAI', gemini: 'Gemini', anthropic: 'Anthropic', open_router: 'OpenRouter', huawei_maas: 'HuaweiMaaS'}.freeze
+ALIASES = {openai: :open_ai, openrouter: :open_router, huawei: :huawei_maas}.freeze
+```
+
+`Provider.build(name, **options)` normalizes the name (`downcase.to_sym`), applies aliases, and resolves the class with `AI.const_get(MODULES[key])::Provider` — at call time, so there is no load-order constraint. Passing an existing `Provider` instance returns it untouched. Unknown names raise `Errors::UnknownProvider`.
+
+`client_class` / `assistant_class` are derived from `name` through `provider_module`, so `OpenRouter::Provider` (which inherits from `OpenAI::Provider`) gets `OpenRouter::Client` and `OpenRouter::Assistant` without overriding anything.
+
+#### Provider — methods to implement (7 total)
+
+Public — also consumed by the `Client`:
+
+```ruby
+def name                    # :open_ai — also used by provider_module
+def default_model           # from Rasti::AI config
+def default_api_key         # from Rasti::AI config
+def base_url                # e.g. 'https://api.anthropic.com/v1'
+def parse_usage(response)   # raw response => Usage or nil
+```
+
+Private — the request/response translation:
+
+```ruby
+def request(client:, messages:, system:, model:, json_schema:, thinking:)  # calls the client, returns raw response
+def encode_message(message) # {role:, content:} with generic roles => provider message
+def parse_content(response) # raw response => String
+```
+
+Plus a `THINKING_LEVELS` constant (see [Thinking levels](#thinking-levels)). OpenAI-compatible providers only override `name`, `default_model` and `default_api_key`.
+
+#### Public API
+
+- **`Provider#generate_text(prompt:/messages:, system:, model:, json_schema:, thinking:, client:)`** — one request, no tools, no loop. Normalizes generic-role messages, extracts `system` messages into the provider's system field, and returns a `Result`.
+- **`Provider#create_assistant(state:, system:, model:, tools:, mcp_servers:, json_schema:, thinking:, client:)`** — builds the provider-specific `Assistant`. `system:` is sugar for `state: AssistantState.new(context: ...)`; passing both raises `ArgumentError`.
+- **`Provider#build_client`** — the provider's `Client` with the instance's transport options.
+- **`Rasti::AI.provider`, `Rasti::AI.generate_text`, `Rasti::AI.create_assistant`** — thin module-level wrappers. They split transport options (used to build the provider) from call options (forwarded to the provider method).
+
+`model:` accepts `'provider:model'` (split on the first `:`), but only when `provider:` is not given explicitly. The provider falls back to `Rasti::AI.default_provider` (`ENV['AI_DEFAULT_PROVIDER']`); nil raises `ArgumentError`. `model` on a `Provider` is only its default — every call accepts a `model:` override.
+
+The private helpers `build_provider` and `split_provider_and_model` live in a `class << self` block with `private` inside it.
+
+### Result
+
+`Rasti::AI::Result` (a `Rasti::Model`) is the normalized output of `generate_text`:
+
+| Attribute | Content |
+|---|---|
+| `content` | The text the model returned, or the JSON string when `json_schema` is used |
+| `usage` | A `Usage` instance, from `Provider#parse_usage` |
+| `raw` | The untouched provider payload |
+
+`Provider#parse_usage` is public because the `Client` also calls it, from `track_usage`, on every response of the assistant's tool loop.
+
+`Assistant#call` still returns a plain `String` — unchanged for compatibility.
+
+### Generic roles
+
+`Rasti::AI::Roles` (`USER`, `ASSISTANT`, `SYSTEM`) is the provider-agnostic vocabulary used by `generate_text(messages:)`. Each `Provider#encode_message` translates it (Gemini maps `assistant` to its `model` role; `system` messages are pulled out of the array by `split_system` and passed through the provider's system field).
+
+The per-provider `Roles` modules still exist and are what the `Assistant` classes use. Inside `Rasti::AI::<Provider>::*`, a bare `Roles::USER` resolves to the provider's module by lexical scope — use the fully qualified `Rasti::AI::Roles::USER` for the generic one.
+
+> ⚠️ Do not reference a provider's `Roles` constants in a constant definition inside `<provider>/provider.rb`: `multi_require` loads `provider.rb` **before** `roles.rb` (alphabetical order). Resolve them inside method bodies instead (see `Gemini::Provider#encode_role`).
+
+#### Known duplication
+
+`Anthropic::Provider` reimplements the structured-output tool and its parsing, which also live in `Anthropic::Assistant` (Anthropic has no native `json_schema` support). Same for Gemini's `generation_config`. This is temporary: once the `Assistant` is rebuilt on top of `Provider#request`, both collapse into one. Keep them in sync until then.
+
 ### Template method pattern
 
 `Rasti::AI::Client` and `Rasti::AI::Assistant` are abstract base classes. Provider-specific subclasses implement a fixed set of methods; all shared logic (HTTP retries, tool caching, the request/response loop) lives in the base.
 
 #### Client — methods to implement
 
+Nothing is mandatory. A client only defines the provider's endpoint method (`chat_completions`, `messages`, `generate_content`) and, if the API needs credentials in the request, one of:
+
 ```ruby
-def default_api_key          # reads from Rasti::AI config
-def base_url                 # e.g. 'https://api.anthropic.com/v1'
-def parse_usage(response)    # returns a Usage instance or nil
-# optionally override:
 def build_request(uri)       # super + add auth headers
-def build_url(relative_url)  # super unless URL needs query params (e.g. Gemini key)
+def build_url(relative_url)  # super + query params (e.g. Gemini key)
 ```
 
+Everything else — API key, default model, base URL, usage parsing — lives in the `Provider`, and the client delegates (`provider` and `provider_module` come from the `ProviderAware` module, shared with `Assistant`):
+
+```ruby
+def default_api_key ; provider.default_api_key ; end
+def default_model   ; provider.default_model   ; end
+def base_url        ; provider.base_url        ; end
+def track_usage(response) ; ... provider.parse_usage(response) ... ; end
+```
+
+As a result `OpenRouter::Client` and `HuaweiMaaS::Client` have **empty bodies**. Keep them: they are the namespace marker that `Provider#client_class` and `ProviderAware#provider_module` resolve against, and they keep `Rasti::AI::<Provider>::Client.new` working as a documented entry point.
+
+`Provider#build_client` injects itself (`provider: self`). When a client is built standalone (`OpenAI::Client.new`) the private `provider` method lazily builds the provider of its own namespace, derived from the class name — so nothing breaks and no provider-specific config is duplicated.
+
+> ⚠️ In `Client#initialize`, the `provider:` keyword argument shadows the private `provider` method. That's why the fallback goes through `default_api_key` instead of calling `provider.default_api_key` inline.
+
+> ⚠️ The class-name derivation means an anonymous client subclass (`Class.new(OpenAI::Client)`) has no provider. Subclass explicitly if you need one in a test.
+
 The base `post` method handles JSON serialization, logging, retries on network errors and 5xx, and calls `track_usage` after each successful response.
 
-#### Assistant — methods to implement (12 total)
+#### Assistant — methods to implement (11 total)
 
 ```ruby
-def build_default_client           # Client.new
 def build_user_message(prompt)     # {role: ..., content: prompt}
 def build_assistant_message(content)
 def build_assistant_tool_calls_message(response)
@@ -40,6 +128,10 @@ def extract_tool_name(wrapped)     # string name from wrapped tool hash
 
 The base `call` loop: add user message → request completion → if tool calls: execute each, add results, loop → else: return content.
 
+The client is **not** a template method: the base `Assistant` gets it from its provider (`provider.build_client`), lazily, so nothing is built until the first request. As with `Client`, `Provider#create_assistant` injects `provider: self`, and direct instantiation (`Rasti::AI::OpenRouter::Assistant.new`) falls back to the namespace derivation.
+
+That leaves `OpenRouter::Assistant` and `HuaweiMaaS::Assistant` with **empty bodies** — like their clients, they survive as the documented public entry point per provider and as the namespace marker `Provider#assistant_class` resolves.
+
 #### Tool — optional base class
 
 Simple tool classes only need a `.form` class method and a `#call(params={})` instance method.
@@ -68,14 +160,31 @@ lib/
         roles.rb
         client.rb
         assistant.rb
+        provider.rb
       gemini/
         roles.rb
         client.rb
         assistant.rb
+        provider.rb
       anthropic/
         roles.rb
         client.rb
         assistant.rb
+        provider.rb
+      open_router/
+        roles.rb
+        client.rb
+        assistant.rb
+        provider.rb
+      huawei_maas/
+        roles.rb
+        client.rb
+        assistant.rb
+        provider.rb
+      provider.rb              # entry point: resolves provider/model, builds client + assistant, generate_text
+      provider_aware.rb        # shared lazy provider lookup by namespace (Client + Assistant)
+      result.rb                # normalized generate_text output (content, usage, raw)
+      roles.rb                 # generic roles (user, assistant, system)
       mcp/
         server.rb              # Rack middleware exposing tools via JSON-RPC 2.0
         tools_registry.rb      # per-request tool registry used by the middleware
@@ -100,6 +209,12 @@ spec/
   anthropic/
     client_spec.rb
     assistant_spec.rb
+  open_router/
+    client_spec.rb
+    assistant_spec.rb
+  huawei_maas/
+    client_spec.rb
+    assistant_spec.rb
   mcp/
     client_spec.rb
     server_spec.rb
@@ -125,6 +240,7 @@ spec/
 | | OpenAI | Gemini | Anthropic |
 |---|---|---|---|
 | Auth | `Authorization: Bearer {key}` | `?key=` query param | `x-api-key: {key}` + `anthropic-version: 2023-06-01` header |
+| Usage payload | `usage.prompt_tokens` / `completion_tokens` | `usageMetadata.promptTokenCount` / `candidatesTokenCount` | `usage.input_tokens` / `output_tokens` |
 | Endpoint | `POST /chat/completions` | `POST /models/{model}:generateContent` | `POST /messages` |
 | System prompt | message with `role: system` | top-level `system_instruction` | top-level `system` string |
 | `max_tokens` | optional | optional | **required** (default 4096 in client) |
@@ -140,6 +256,19 @@ spec/
 - Gemini: renames to `parameters`
 - Anthropic: renames to `input_schema`
 
+### OpenAI-compatible providers
+
+OpenRouter and Huawei MaaS speak the OpenAI chat completions protocol verbatim — same endpoint shape (`POST /chat/completions`), same request body, same response structure, same tool calling format, same Bearer token auth. They inherit from the OpenAI provider; their whole implementation is `name` / `default_model` / `default_api_key` / `base_url` on the provider. Their clients and assistants are empty subclasses.
+
+| | OpenRouter | Huawei MaaS |
+|---|---|---|
+| Base URL | `https://openrouter.ai/api/v1` | `https://api-ap-southeast-1.modelarts-maas.com/v2` |
+| Auth | `Authorization: Bearer {key}` | `Authorization: Bearer {key}` |
+| Config | `openrouter_api_key` / `openrouter_default_model` | `huawei_maas_api_key` / `huawei_maas_default_model` |
+| `provider` in Usage | `'open_router'` | `'huawei_maas'` |
+
+Thinking is inherited too: `reasoning_effort` is passed through as-is (same as OpenAI).
+
 
 ## Thinking levels
 
@@ -151,18 +280,23 @@ The base `Assistant` accepts `thinking: 'low' | 'medium' | 'high'` (validated on
 | `'medium'` | `'medium'` | `8_000` | `8_192` |
 | `'high'` | `'high'` | `16_000` | `24_576` |
 
+The `THINKING_LEVELS` table lives in each **`Provider`** class (it's provider metadata, not assistant behavior). `Assistant#thinking_config` reads it as `Provider::THINKING_LEVELS[thinking]` — resolved by lexical scope to the provider's own class. `Provider#thinking_config` also validates the level against the table's keys.
+
 For Gemini, `thinking_config` goes inside `generation_config` — the client doesn't need a new param. For OpenAI and Anthropic, it's a separate top-level param in the client method (`reasoning_effort:` and `thinking:` respectively).
 
+OpenRouter and Huawei MaaS inherit OpenAI's behavior: `thinking` is passed through as `reasoning_effort` with the same string values (`'low'`/`'medium'`/`'high'`). No `thinking_config` override is needed. Note that Huawei's models typically accept only `'high'` and `'max'` — `'high'` is the safe choice, and `'max'` is not expressible through the gem's universal levels.
+
 The loop does not change. Anthropic thinking blocks (`type: 'thinking'`) in responses are ignored by `parse_content` (looks for `type == 'text'`) and preserved automatically by `build_assistant_tool_calls_message` (passes full `response['content']` array).
 
 
 ## Adding a new provider
 
-Create three files under `lib/rasti/ai/<provider>/`:
+Create four files under `lib/rasti/ai/<provider>/`:
 
 1. **`roles.rb`** — string constants for role names
-2. **`client.rb`** — inherits `Rasti::AI::Client`, implements the main API method + private helpers
-3. **`assistant.rb`** — inherits `Rasti::AI::Assistant`, implements all 12 template methods
+2. **`client.rb`** — inherits `Rasti::AI::Client`, implements the main API method + auth
+3. **`assistant.rb`** — inherits `Rasti::AI::Assistant`, implements all 11 template methods
+4. **`provider.rb`** — inherits `Rasti::AI::Provider`, implements the 7 methods + `THINKING_LEVELS`
 
 Add to `lib/rasti/ai.rb`:
 ```ruby
@@ -170,6 +304,10 @@ attr_config :<provider>_api_key,       ENV['<PROVIDER>_API_KEY']
 attr_config :<provider>_default_model, ENV['<PROVIDER>_DEFAULT_MODEL']
 ```
 
+Add the provider to `MODULES` (and `ALIASES` if the name has a common alternative spelling) in `lib/rasti/ai/provider.rb`, and create a fourth file `provider.rb` implementing the 6 methods listed in [Provider](#provider).
+
+The client must expose a private `default_model` returning the configured default (all providers do) and a **public** `parse_usage`.
+
 If the new provider supports thinking, define a `THINKING_LEVELS` constant and a private `thinking_config` method (see existing providers). The base constructor already validates and exposes `thinking`.
 
 Add an entry to the `PROVIDERS` table in `tasks/assistant.rake` so the interactive task is also available for the new provider:
@@ -189,6 +327,18 @@ config.<provider>_api_key       = 'test_<provider>_api_key'
 config.<provider>_default_model = '<provider>-test'
 ```
 
+### OpenAI-compatible providers
+
+If the new provider speaks the OpenAI chat completions protocol (same endpoint, request body, response shape, tool calling, Bearer auth), inherit from `Rasti::AI::OpenAI::Client`, `Rasti::AI::OpenAI::Assistant` and `Rasti::AI::OpenAI::Provider` instead of the abstract bases:
+
+- **client** — empty body, just the subclass declaration
+- **assistant** — empty body, just the subclass declaration
+- **provider** — overrides `name`, `default_model`, `default_api_key` and `base_url`; inherits `request`, `encode_message`, `parse_content`, `parse_usage` and `THINKING_LEVELS`
+
+`Usage#provider` comes from `Provider#name`, so nothing else needs to know the provider's identity.
+
+See `open_router/` and `huawei_maas/` for reference implementations.
+
 ### ⚠️ multi_require load order
 
 `require_relative_pattern 'ai/**/*'` loads files alphabetically. If the new provider name sorts before `assistant` or `client` (e.g. `anthropic` < `assistant`), the subclass is loaded before the base class and raises `NameError`.
@@ -203,9 +353,14 @@ require_relative 'ai/tool'
 require_relative 'ai/tool_serializer'
 require_relative 'ai/client'
 require_relative 'ai/assistant'
+require_relative 'ai/open_ai/roles'
+require_relative 'ai/open_ai/client'
+require_relative 'ai/open_ai/assistant'
 require_relative_pattern 'ai/**/*'   # duplicates are skipped by Ruby's require
 ```
 
+The OpenAI provider is also explicitly required because OpenAI-compatible providers (OpenRouter, Huawei MaaS) inherit from it, and some of their directory names sort before `open_ai` alphabetically (e.g. `huawei_maas` < `open_ai`).
+
 If you add a provider whose name sorts before `client` alphabetically, the same mechanism protects it.
 
 
@@ -519,6 +674,8 @@ It's a simple class (not a `Tool` subclass) that returns a plain string — cove
   rake assistant:openai      # OPENAI_API_KEY
   rake assistant:gemini      # GEMINI_API_KEY
   rake assistant:anthropic   # ANTHROPIC_API_KEY
+  rake assistant:openrouter  # OPENROUTER_API_KEY
+  rake assistant:huawei_maas # HUAWEI_MAAS_API_KEY
   ```
   Each task validates the key, writes logs to `log/<provider>.log`, connects to the [Pipeworx](https://pipeworx.io) public weather MCP server, and starts a `You:` / `Assistant:` prompt loop (`exit` or `Ctrl+C` to quit). The model can be overridden with the matching env variable (e.g. `OPENAI_DEFAULT_MODEL=gpt-4o`).
 

data/README.md

@@ -45,6 +45,17 @@ Rasti::AI.configure do |config|
   config.anthropic_api_key = 'sk-ant-12345' # Default ENV['ANTHROPIC_API_KEY']
   config.anthropic_default_model = 'claude-opus-4-5' # Default ENV['ANTHROPIC_DEFAULT_MODEL']
 
+  # OpenRouter
+  config.openrouter_api_key = 'sk-or-12345' # Default ENV['OPENROUTER_API_KEY']
+  config.openrouter_default_model = 'openai/gpt-4o-mini' # Default ENV['OPENROUTER_DEFAULT_MODEL']
+
+  # Huawei MaaS
+  config.huawei_maas_api_key = 'sk-maas-12345' # Default ENV['HUAWEI_MAAS_API_KEY']
+  config.huawei_maas_default_model = 'DeepSeek-V3' # Default ENV['HUAWEI_MAAS_DEFAULT_MODEL']
+
+  # Default provider used by Rasti::AI.create_assistant and Rasti::AI.generate_text
+  config.default_provider = :open_ai # Default ENV['AI_DEFAULT_PROVIDER']
+
   # Usage tracking
   config.usage_tracker = ->(usage) { puts "#{usage.provider}: #{usage.input_tokens} in / #{usage.output_tokens} out" }
 end
@@ -55,13 +66,139 @@ end
 - **OpenAI** - `Rasti::AI::OpenAI::Assistant`
 - **Gemini** - `Rasti::AI::Gemini::Assistant`
 - **Anthropic** - `Rasti::AI::Anthropic::Assistant`
+- **OpenRouter** - `Rasti::AI::OpenRouter::Assistant`
+- **Huawei MaaS** - `Rasti::AI::HuaweiMaaS::Assistant`
+
+All providers share the same interface. The examples below use OpenAI, but apply equally to any provider by replacing `OpenAI` with the provider name.
+
+OpenRouter and Huawei MaaS are [OpenAI-compatible](https://platform.openai.com/docs/api-reference/chat) APIs — they use the same chat completions format, tool calling, and Bearer token auth. Their clients and assistants inherit from the OpenAI provider, so everything in the examples below works identically.
+
+### Choosing provider and model at runtime
+
+Instead of referencing a provider-specific class, the provider can be a parameter or come from the configuration. This makes swapping models a config change instead of a code change.
 
-All providers share the same interface. The examples below use OpenAI, but apply equally to Gemini or Anthropic by replacing `OpenAI` with the provider name.
+```ruby
+# One-shot text generation
+result = Rasti::AI.generate_text prompt: 'who is the best player', provider: :open_ai
+
+result.content # => 'The best player is Lionel Messi'
+result.usage   # => Rasti::AI::Usage
+result.raw     # => raw provider response
+
+# Provider and model
+Rasti::AI.generate_text prompt: 'who is the best player', provider: :anthropic, model: 'claude-sonnet-4-5'
+
+# Both in a single string — handy for ENV vars
+Rasti::AI.generate_text prompt: 'who is the best player', model: ENV['AI_MODEL'] # 'gemini:gemini-2.0-flash'
+
+# Provider from configuration (Rasti::AI.default_provider)
+Rasti::AI.generate_text prompt: 'who is the best player'
+```
+
+The response is normalized across providers: `content` is the text the model returned (or the JSON string when `json_schema:` is used), `usage` is a `Rasti::AI::Usage`, and `raw` is the untouched provider payload as an escape hatch.
+
+Instead of a single `prompt:`, a conversation can be passed with `messages:` using generic roles — each provider translates them to its own format (`assistant` becomes `model` on Gemini, `system` becomes `system_instruction`, etc.):
+
+```ruby
+Rasti::AI.generate_text provider: :gemini, messages: [
+  {role: Rasti::AI::Roles::SYSTEM, content: 'Act as sports journalist'},
+  {role: Rasti::AI::Roles::USER, content: 'who is the best player'},
+  {role: Rasti::AI::Roles::ASSISTANT, content: 'Lionel Messi'},
+  {role: Rasti::AI::Roles::USER, content: 'how many goals did he score?'}
+]
+```
+
+`generate_text` is a single request without tools. For tool calling, multi-turn conversations and stateful interactions use an assistant.
+
+### Assistants — tool calling and multi-turn conversations
+
+`Rasti::AI.create_assistant` is the primary entry point for assistants. It resolves the provider at runtime — just like `generate_text` — and returns the provider-specific `Assistant` instance, so swapping models is a config change instead of a code change. Everything documented below (tools, state, structured responses, thinking, MCP) works the same across all providers:
+
+```ruby
+assistant = Rasti::AI.create_assistant provider: :open_ai,
+                                       model: 'gpt-4o',
+                                       system: 'Act as sports journalist',
+                                       tools: [GetCurrentWeather.new],
+                                       mcp_servers: {weather: mcp_client},
+                                       thinking: 'medium'
+
+assistant.call 'who is the best player' # => 'The best player is Lionel Messi'
+assistant # => #<Rasti::AI::OpenAI::Assistant>
+```
+
+Omit `provider:` to use `Rasti::AI.default_provider`, or pass `'provider:model'` as `model:` to set both in one string — handy for ENV-driven configuration:
+
+```ruby
+assistant = Rasti::AI.create_assistant model: ENV['AI_MODEL'], # 'anthropic:claude-sonnet-4-5'
+                                       system: 'Act as sports journalist',
+                                       tools: [GetCurrentWeather.new]
+```
+
+Both methods accept the same options:
+
+| Option | Purpose | `generate_text` | `create_assistant` |
+|---|---|---|---|
+| `provider:` | `:open_ai`, `:gemini`, `:anthropic`, `:open_router`, `:huawei_maas` (aliases: `:openai`, `:openrouter`, `:huawei`). Defaults to `Rasti::AI.default_provider` | ✓ | ✓ |
+| `model:` | Model name, or `'provider:model'` to set both. Defaults to the provider's configured default model | ✓ | ✓ |
+| `api_key:` | Overrides the configured API key — useful for multi-tenant apps | ✓ | ✓ |
+| `usage_tracker:` | Per-call usage tracker lambda | ✓ | ✓ |
+| `logger:` | Overrides the configured logger | ✓ | ✓ |
+| `http_connect_timeout:`, `http_read_timeout:`, `http_max_retries:` | Per-call HTTP settings | ✓ | ✓ |
+| `client:` | A pre-built client (skips building one from the options above) | ✓ | ✓ |
+| `json_schema:` | Schema for structured responses | ✓ | ✓ |
+| `thinking:` | `'low'`, `'medium'` or `'high'` | ✓ | ✓ |
+| `prompt:` | A single user message | ✓ | |
+| `messages:` | Conversation with generic roles — mutually exclusive with `prompt:` | ✓ | |
+| `system:` | System prompt. On `create_assistant` it's a shortcut for `state: AssistantState.new(context: ...)` | ✓ | ✓ |
+| `state:` | An existing `AssistantState` to continue a conversation | | ✓ |
+| `tools:` | Array of tool instances | | ✓ |
+| `mcp_servers:` | Hash of `{name => MCP::Client}` | | ✓ |
+
+### Provider
+
+A provider bundles everything needed to reach a model: credentials, default model, usage tracking and HTTP settings. `Rasti::AI.provider` returns a reusable instance — useful when the same credentials are used for many calls, e.g. per tenant:
+
+```ruby
+provider = Rasti::AI.provider :anthropic,
+                              model: 'claude-sonnet-4-5',
+                              api_key: tenant.anthropic_key,
+                              usage_tracker: ->(usage) { tenant.track usage },
+                              http_read_timeout: 300
+
+provider.name  # => :anthropic
+provider.model # => 'claude-sonnet-4-5'
+
+provider.generate_text prompt: 'who is the best player'          # => Rasti::AI::Result
+provider.generate_text prompt: '...', model: 'claude-opus-4-5'   # per call model override
+provider.create_assistant tools: [GetCurrentWeather.new]         # => Rasti::AI::Anthropic::Assistant
+provider.build_client                                            # => Rasti::AI::Anthropic::Client
+```
+
+The available providers are fixed: `Rasti::AI::Provider.names # => [:open_ai, :gemini, :anthropic, :open_router, :huawei_maas]`. An unknown name raises `Rasti::AI::Errors::UnknownProvider`.
+
+A provider instance can also be passed directly as `provider:` to the module-level methods:
+
+```ruby
+Rasti::AI.generate_text provider: provider, prompt: 'who is the best player'
+```
 
 ### Assistant
 
+`Rasti::AI.create_assistant` is the recommended way to build an assistant — it keeps the provider as a runtime value and shares the same options as `generate_text`:
+
+```ruby
+assistant = Rasti::AI.create_assistant provider: :open_ai,
+                                       system: 'Act as sports journalist',
+                                       tools: [GetCurrentWeather.new]
+
+assistant.call 'who is the best player' # => 'The best player is Lionel Messi'
+```
+
+Provider-specific classes are also available and are fully equivalent — useful when the provider is fixed by the application:
+
 ```ruby
-assistant = Rasti::AI::OpenAI::Assistant.new
+assistant = Rasti::AI::OpenAI::Assistant.new system: 'Act as sports journalist',
+                                             tools: [GetCurrentWeather.new]
 assistant.call 'who is the best player' # => 'The best player is Lionel Messi'
 ```
 
@@ -126,7 +263,7 @@ tools = [
   GetCurrentWeather.new
 ]
 
-assistant = Rasti::AI::OpenAI::Assistant.new tools: tools
+assistant = Rasti::AI.create_assistant provider: :open_ai, tools: tools
 
 assistant.call 'what time is it' # => 'The current time is 3:03 PM on April 28, 2025.'
 
@@ -137,7 +274,7 @@ assistant.call 'what is the weather in Buenos Aires' # => 'In Buenos Aires it is
 ```ruby
 state = Rasti::AI::AssistantState.new context: 'Act as sports journalist'
 
-assistant = Rasti::AI::OpenAI::Assistant.new state: state
+assistant = Rasti::AI.create_assistant provider: :open_ai, state: state
 
 assistant.call 'who is the best player'
 
@@ -145,14 +282,15 @@ state.context  # => 'Act as sports journalist'
 state.messages # Array of provider-specific message hashes
 ```
 
-The state keeps the conversation history, enabling multi-turn interactions. It also caches tool call results to avoid duplicate executions.
+The state keeps the conversation history, enabling multi-turn interactions. It also caches tool call results to avoid duplicate executions. The `system:` option is a shortcut for `state: AssistantState.new(context: ...)`.
 
 ### Structured responses (JSON Schema)
 ```ruby
-assistant = Rasti::AI::OpenAI::Assistant.new json_schema: {
-  player: 'string',
-  sport: 'string'
-}
+assistant = Rasti::AI.create_assistant provider: :open_ai,
+                                       json_schema: {
+                                         player: 'string',
+                                         sport: 'string'
+                                       }
 
 response = assistant.call 'who is the best player'
 JSON.parse response # => {"player" => "Lionel Messi", "sport" => "Football"}
@@ -161,7 +299,7 @@ JSON.parse response # => {"player" => "Lionel Messi", "sport" => "Football"}
 ### Custom model and client
 ```ruby
 # Override model
-assistant = Rasti::AI::OpenAI::Assistant.new model: 'gpt-4o'
+assistant = Rasti::AI.create_assistant provider: :open_ai, model: 'gpt-4o'
 
 # Custom client with per-client HTTP settings
 client = Rasti::AI::OpenAI::Client.new(
@@ -170,15 +308,15 @@ client = Rasti::AI::OpenAI::Client.new(
   http_max_retries: 5
 )
 
-assistant = Rasti::AI::OpenAI::Assistant.new client: client
+assistant = Rasti::AI.create_assistant provider: :open_ai, client: client
 
-# Anthropic client
+# Anthropic client — Claude can be slow on long responses
 client = Rasti::AI::Anthropic::Client.new(
   http_connect_timeout: 120,
-  http_read_timeout: 300  # Claude can be slow on long responses
+  http_read_timeout: 300
 )
 
-assistant = Rasti::AI::Anthropic::Assistant.new client: client
+assistant = Rasti::AI.create_assistant provider: :anthropic, client: client
 ```
 
 ### Thinking / extended reasoning
@@ -186,7 +324,7 @@ assistant = Rasti::AI::Anthropic::Assistant.new client: client
 Some providers support extended reasoning ("thinking") to improve accuracy on complex tasks. Pass `thinking:` with a level of `'low'`, `'medium'`, or `'high'` when creating an assistant:
 
 ```ruby
-assistant = Rasti::AI::Anthropic::Assistant.new thinking: 'high'
+assistant = Rasti::AI.create_assistant provider: :anthropic, thinking: 'high'
 assistant.call 'Solve this step by step: ...'
 ```
 
@@ -201,7 +339,7 @@ tracked_usage = []
 tracker = ->(usage) { tracked_usage << usage }
 
 client = Rasti::AI::OpenAI::Client.new usage_tracker: tracker
-assistant = Rasti::AI::OpenAI::Assistant.new client: client
+assistant = Rasti::AI.create_assistant provider: :open_ai, client: client
 assistant.call 'who is the best player'
 
 usage = tracked_usage.first
@@ -414,10 +552,8 @@ You can use MCP clients as tools for any assistant:
 ```ruby
 mcp_client = Rasti::AI::MCP::Client.new url: 'https://mcp.server.ai/mcp'
 
-
-assistant = Rasti::AI::OpenAI::Assistant.new(
-  mcp_servers: {my_mcp: mcp_client}
-)
+assistant = Rasti::AI.create_assistant provider: :open_ai,
+                                       mcp_servers: {my_mcp: mcp_client}
 
 # The assistant can now call tools from the MCP server
 assistant.call 'What is 5 plus 3?'
@@ -428,9 +564,11 @@ assistant.call 'What is 5 plus 3?'
 The gem includes interactive chat tasks wired to the [Pipeworx](https://pipeworx.io) public weather MCP server (no auth required):
 
 ```bash
-OPENAI_API_KEY=sk-...    rake assistant:openai
-GEMINI_API_KEY=AIza...   rake assistant:gemini
-ANTHROPIC_API_KEY=sk-... rake assistant:anthropic
+OPENAI_API_KEY=sk-...       rake assistant:openai
+GEMINI_API_KEY=AIza...      rake assistant:gemini
+ANTHROPIC_API_KEY=sk-...    rake assistant:anthropic
+OPENROUTER_API_KEY=sk-or... rake assistant:openrouter
+HUAWEI_MAAS_API_KEY=sk-...  rake assistant:huawei_maas
 ```
 
 Type your message and press Enter. Type `exit` or `Ctrl+C` to quit.

data/lib/rasti/ai/anthropic/assistant.rb

@@ -5,18 +5,8 @@ module Rasti
 
         ALLOWED_SCHEMA_FIELDS = %w[type description properties required enum items format nullable anyOf].freeze
 
-        THINKING_LEVELS = {
-          'low'    => {type: 'enabled', budget_tokens: 1_024}.freeze,
-          'medium' => {type: 'enabled', budget_tokens: 8_000}.freeze,
-          'high'   => {type: 'enabled', budget_tokens: 16_000}.freeze
-        }.freeze
-
         private
 
-        def build_default_client
-          Client.new
-        end
-
         def build_user_message(prompt)
           {role: Roles::USER, content: prompt}
         end
@@ -61,7 +51,7 @@ module Rasti
         end
 
         def thinking_config
-          THINKING_LEVELS[thinking]
+          Provider::THINKING_LEVELS[thinking]
         end
 
         def parse_tool_calls(response)

data/lib/rasti/ai/anthropic/client.rb

@@ -8,14 +8,14 @@ module Rasti
 
         def messages(messages:, model:nil, system:nil, tools:[], tool_choice:nil, max_tokens:nil, thinking:nil)
           body = {
-            model:      model || Rasti::AI.anthropic_default_model,
+            model: model || default_model,
             max_tokens: max_tokens || DEFAULT_MAX_TOKENS,
-            messages:   messages
+            messages: messages
           }
 
-          body[:thinking]    = thinking    if thinking
-          body[:system]      = system      if system
-          body[:tools]       = tools       unless tools.empty?
+          body[:thinking] = thinking if thinking
+          body[:system] = system if system
+          body[:tools] = tools unless tools.empty?
           body[:tool_choice] = tool_choice if tool_choice
 
           post '/messages', body
@@ -23,31 +23,9 @@ module Rasti
 
         private
 
-        def parse_usage(response)
-          usage = response['usage']
-          return unless usage
-          Usage.new(
-            provider:          'anthropic',
-            model:             response['model'],
-            input_tokens:      usage['input_tokens'],
-            output_tokens:     usage['output_tokens'],
-            cached_tokens:     usage['cache_read_input_tokens'] || 0,
-            reasoning_tokens:  0,
-            raw:               usage
-          )
-        end
-
-        def default_api_key
-          Rasti::AI.anthropic_api_key
-        end
-
-        def base_url
-          'https://api.anthropic.com/v1'
-        end
-
         def build_request(uri)
           request = super
-          request['x-api-key']        = api_key
+          request['x-api-key'] = api_key
           request['anthropic-version'] = ANTHROPIC_VERSION
           request
         end