rasti-ai 3.1.0 → 3.2.1

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,22 +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
@@ -139,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) |
@@ -156,7 +258,7 @@ spec/
 
 ### 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. Their clients and assistants inherit from the OpenAI provider and override only `base_url`, `default_api_key`, `default_model`, and `provider_name` (client) / `build_default_client` (assistant). No template methods are reimplemented.
+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 |
 |---|---|---|
@@ -170,28 +272,36 @@ Thinking is inherited too: `reasoning_effort` is passed through as-is (same as O
 
 ## Thinking levels
 
-The base `Assistant` accepts `thinking: 'low' | 'medium' | 'high'` (validated on construction; nil = disabled). Each provider translates it in a private `thinking_config` method and passes the result to the client. The client includes it in the request body only if present.
+The base `Assistant` accepts `thinking: 'none' | 'low' | 'medium' | 'high'` (validated on construction). `nil` means the gem sends nothing and the model uses its own default — which for reasoning models (e.g. `gpt-6-luna`, `gemini-2.5-flash`, Huawei's DeepSeek/GLM) means reasoning *on*. `'none'` explicitly asks the provider to disable reasoning. Each provider translates it in a private `thinking_config` method and passes the result to the client. The client includes it in the request body only if present.
 
 | Level | OpenAI `reasoning_effort` | Anthropic `budget_tokens` | Gemini `thinking_budget` |
 |---|---|---|---|
+| `'none'` | `'none'` | _(field omitted)_ | `0` |
 | `'low'` | `'low'` | `1_024` | `1_024` |
 | `'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.
+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. Huawei MaaS rejects `reasoning_effort: 'none'` with a 400 (`deepseek-v4-flash` accepts `low|medium|high|xhigh|max`, `glm-5.3` only `low|high|max`), so `thinking: 'none'` fails there by design. Disabling reasoning on Huawei needs `thinking: {type: 'disabled'}` instead (works on DeepSeek and GLM ≤ 5.2, rejected by `glm-5.3`); the gem does not send it.
+
+`'none'` matters for `gpt-6-luna`: it reasons by default and rejects function tools on `/v1/chat/completions` unless `reasoning_effort: 'none'` is sent. Combining reasoning with tools there requires `/v1/responses`, which the gem does not support.
+
+Gemini's `thinking_budget: 0` is rejected by models that cannot turn reasoning off (e.g. `gemini-2.5-pro`).
 
 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
@@ -199,6 +309,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:
@@ -206,10 +320,12 @@ Add an entry to the `PROVIDERS` table in `tasks/assistant.rake` so the interacti
 ```ruby
 PROVIDERS = {
   # existing providers ...
-  '<provider>' => {key: '<PROVIDER>_API_KEY', klass: -> { Rasti::AI::<Provider>::Assistant }}
+  '<provider>' => {key: '<PROVIDER>_API_KEY', klass: -> { Rasti::AI::<Provider>::Assistant }, thinking: 'none'}
 }.freeze
 ```
 
+`thinking:` is optional and passed as-is to the assistant. All providers use `'none'` except `huawei_maas`, which rejects it (see [Thinking levels](#thinking-levels)).
+
 The task name, description, env-key check, logger path and banner are all derived automatically from this entry.
 
 Add to `spec/minitest_helper.rb`:
@@ -220,12 +336,13 @@ 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` and `Rasti::AI::OpenAI::Assistant` instead of the abstract bases. The assistant only overrides `build_default_client`; the client overrides `base_url`, `default_api_key`, `default_model`, and `provider_name`. No template methods are reimplemented.
+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:
 
-The OpenAI client exposes two private hooks that make this possible without duplicating `chat_completions` or `parse_usage`:
+- **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`
 
-- **`default_model`** — returns the provider's default model from `Rasti::AI` config
-- **`provider_name`** — the string written to `Usage#provider`
+`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.
 
@@ -282,7 +399,7 @@ All string constants use `.freeze`. Integer and array/hash literals that are alr
 USER = 'user'.freeze
 ASSISTANT = 'assistant'.freeze
 
-VALID_THINKING_LEVELS = %w[low medium high].freeze
+VALID_THINKING_LEVELS = %w[none low medium high].freeze
 
 THINKING_LEVELS = {
   'low' => {thinking_budget: 1_024}.freeze,

data/README.md

@@ -53,6 +53,9 @@ Rasti::AI.configure do |config|
   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
@@ -70,10 +73,132 @@ All providers share the same interface. The examples below use OpenAI, but apply
 
 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.
+
+```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:` | `'none'`, `'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::OpenAI::Assistant.new
+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 system: 'Act as sports journalist',
+                                             tools: [GetCurrentWeather.new]
 assistant.call 'who is the best player' # => 'The best player is Lionel Messi'
 ```
 
@@ -138,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.'
 
@@ -149,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'
 
@@ -157,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"}
@@ -173,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(
@@ -182,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
@@ -198,12 +324,20 @@ 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: ...'
 ```
 
 The level controls how much computation the model can spend reasoning before responding. Higher levels may improve answer quality at the cost of more tokens and latency. Not all models support thinking — check your provider's documentation.
 
+Omitting `thinking:` leaves the decision to the model, and many current models reason by default. Pass `thinking: 'none'` to disable reasoning explicitly. Some models require it — `gpt-6-luna`, for example, rejects function tools unless reasoning is disabled:
+
+```ruby
+assistant = Rasti::AI.create_assistant provider: :open_ai, model: 'gpt-6-luna', tools: [GetCurrentWeather.new], thinking: 'none'
+```
+
+Huawei MaaS does not accept `'none'` and returns an error.
+
 ### Usage tracking
 
 Track token consumption across API calls (including tool calls):
@@ -213,7 +347,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
@@ -426,10 +560,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?'

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