rasti-ai 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81ed3eb7239ec9d47de179db57b6d55abb21c512ee6c830de189c77692bb1bf0
-  data.tar.gz: fb25a1ab3f55861676625021c91bfed4aea5c40058c3b6282041dadd39c9fdb3
+  metadata.gz: fa07486ef7216a0a1408d1711ea21ca521283673c06ca2845ad63197dd1dbe8d
+  data.tar.gz: dd42552dfd7e3752dac0264b1c89159f04f230c6d067fa674dd4347aae01b0b1
 SHA512:
-  metadata.gz: f3a1f07c3580de138323486de7255633eb67e1e14a3ea7ec847fededaf6f2ba771cf425d5ac27f80ed7180582e8b2070562ff42c84a1dbedbc541da9e1bb6a59
-  data.tar.gz: afa8bf99945c06a833b62ae3d53e42860b49a923715473b8a1cb8b4793dc653b9d48b93a991676d7cc79c79aa714bc2a8d6c94156c9fdb36f60bea125f660936
+  metadata.gz: 1cd0846a2f725823ba691f7d761c5abee299291d9307a7a870cc086f17a02ead88913acaf70cf257221b82a5b8684655595cdc4a8952d4825fa19f23ab7004e5
+  data.tar.gz: ea5880cc6e73795cac795189e6a6d192e27fdd11a252768f1b33933b13407d9e1f929e1aaf4020112164dfa880acbe4601708f202795737b434df0f5a63202d6

data/.features/api-normalization/api-design.md

@@ -0,0 +1,184 @@
+# Diseño de la API pública — `generate_text` / `Agent`
+
+Refinamiento de la propuesta de entry points. Conclusión previa: esta API **no es la Opción A**
+(fachada barata). El momento en que `messages:` acepta roles genéricos, el modelo canónico de
+mensajes se vuelve obligatorio — o sea, arrastra la Opción B por construcción. Eso es bueno: evita
+construir A con mensajes provider-specific para tirarlo después.
+
+---
+
+## 1. Firmas propuestas (revisadas)
+
+```ruby
+module Rasti
+  module AI
+
+    def self.generate_text(provider: nil, model: nil,
+                           prompt: nil, messages: nil, system: nil,
+                           tools: [], mcp_servers: {}, tool_choice: nil, max_steps: 1,
+                           json_schema: nil, thinking: nil, max_tokens: nil, temperature: nil,
+                           api_key: nil, usage_tracker: nil, logger: nil,
+                           http_connect_timeout: nil, http_read_timeout: nil, http_max_retries: nil,
+                           provider_options: {})
+    end
+
+    def self.generate_object(schema:, **options)  # generate_text + json_schema + result.object
+    end
+
+  end
+
+  class AI::Agent
+
+    def initialize(provider: nil, model: nil, state: nil,
+                   system: nil, tools: [], mcp_servers: {}, tool_choice: nil, max_steps: 20,
+                   json_schema: nil, thinking: nil, max_tokens: nil, temperature: nil,
+                   api_key: nil, usage_tracker: nil, logger: nil,
+                   http_connect_timeout: nil, http_read_timeout: nil, http_max_retries: nil,
+                   provider_options: {})
+    end
+
+    def call(prompt)  # => Result
+    end
+
+  end
+end
+```
+
+`Rasti::AI.create_agent(...)` queda como alias de `Agent.new` si se quiere simetría con
+`generate_text`, pero `Agent.new` es el idioma Ruby y debería ser el camino documentado.
+
+---
+
+## 2. Decisiones y por qué
+
+### 2.1 `prompt:` además de `messages:`
+
+El caso mayoritario es un string. Que la firma mínima sea
+`generate_text prompt: 'who is the best player'` vale más que la pureza de un solo parámetro.
+`messages:` queda para control total. Son mutuamente excluyentes (`ArgumentError` si vienen los dos).
+
+### 2.2 `system:` como parámetro, no como mensaje
+
+Anthropic y Gemini ponen el system prompt **fuera** del array de mensajes (`system`,
+`system_instruction`). Modelarlo como `{role: :system}` dentro de `messages:` obliga a que cada
+adapter lo extraiga del array. Mejor que sea un campo del `Request`. Igual se acepta un mensaje con
+`role: :system` en `messages:` y se normaliza hacia `system:` al construir el `Request`.
+
+Esto además deja claro qué pasa con `state.context`: es el `system` del agente. Sugerencia:
+`Agent.new(system:)` como nombre nuevo, `state.context` sigue funcionando como fuente si no se pasa
+`system:`.
+
+### 2.3 `provider:` acepta Symbol **o** instancia
+
+Con `api_key:`, `usage_tracker:`, timeouts y `logger:` como kwargs planos, la firma tiene 8
+parámetros que son de *transporte*, no de generación. Sirve para el caso simple, pero repetirlos en
+cada llamada es ruido. Solución: que `provider:` acepte las dos formas.
+
+```ruby
+# Simple: símbolo, resuelve api_key y defaults de la config global
+Rasti::AI.generate_text provider: :anthropic, model: 'claude-sonnet-4-5', prompt: '...'
+
+# Reusable / multi-tenant: instancia con su propia credencial y transporte
+provider = Rasti::AI.provider :anthropic, api_key: tenant.anthropic_key,
+                                          usage_tracker: ->(u) { tenant.track u },
+                                          http_read_timeout: 300
+
+Rasti::AI.generate_text provider: provider, model: 'claude-sonnet-4-5', prompt: '...'
+Rasti::AI::Agent.new provider: provider, model: 'claude-sonnet-4-5', tools: tools
+```
+
+Los kwargs planos (`api_key:`, `usage_tracker:`, ...) siguen existiendo como atajo y se usan para
+construir el provider internamente. Un provider explícito los ignora (o lanza `ArgumentError` si se
+mezclan — a definir).
+
+Beneficio concreto: `usage_tracker` per-session/per-tenant deja de necesitar un `Client` custom, que
+es la única forma de hacerlo hoy.
+
+### 2.4 `provider_options:` en vez de `**opts`
+
+Un `**opts` que se reenvía al body es cómodo pero silencioso: `temparature: 0.5` no falla, se manda y
+el provider lo ignora. Propuesta:
+
+- Parámetros **normalizados** explícitos: `thinking`, `max_tokens`, `temperature`, `tool_choice`,
+  `max_steps`, `json_schema`. Cada adapter los traduce a su dialecto (como hoy con `thinking`).
+- `provider_options:` — hash que se mergea crudo en el body del provider, escape hatch documentado.
+  Equivalente a `providerOptions` de Vercel.
+
+Cualquier kwarg desconocido debe explotar. Sin `**opts` en la firma pública.
+
+### 2.5 Valor de retorno: `Result`, no String
+
+Hoy `Assistant#call` devuelve un String, y eso obliga a un `Client` custom para conocer el usage y
+hace inaccesible el `finish_reason` y los tool calls ejecutados.
+
+```ruby
+result = Rasti::AI.generate_text provider: :openai, prompt: 'who is the best player'
+
+result.text           # => 'Lionel Messi'
+result.object         # => Hash parseado, cuando hay json_schema (hoy: hay que hacer JSON.parse a mano)
+result.usage          # => Usage (o Array de Usage si hubo varios pasos)
+result.messages       # => historial canónico completo
+result.tool_calls     # => [Part::ToolCall] ejecutados
+result.steps          # => [Step] request/response por iteración del loop
+result.finish_reason  # => :stop | :tool_calls | :max_steps | :length
+result.raw            # => payload crudo del último response
+```
+
+Compatibilidad: `Result#to_s` devuelve `text`. Así `assistant.call('...')` interpolado en un string
+o comparado con `==` sigue andando en la mayoría de los usos existentes. `Result#to_str` también, si
+se quiere coerción implícita completa (a evaluar: puede enmascarar errores).
+
+### 2.6 `json_schema:` acepta Hash **o** `Rasti::Form`
+
+`ToolSerializer` ya convierte Forms a JSON Schema. Aceptar un Form cierra el círculo y evita escribir
+schemas a mano. El Hash crudo actual sigue soportado.
+
+`generate_object(schema:)` es el azúcar: valida que haya schema y expone `result.object` ya parseado.
+
+### 2.7 `max_steps:`
+
+Hoy `Assistant#call` es un `loop do` sin tope: un modelo que insiste en llamar tools cuelga el
+proceso. `max_steps` con `finish_reason: :max_steps` cierra ese agujero. Default: `1` en
+`generate_text` (one-shot explícito, y si hay tools se sube a mano) y `20` en `Agent`.
+
+### 2.8 `state:` en el agente
+
+Debe ser opcional (default `AssistantState.new`). Cuando el modelo canónico esté en su lugar,
+`state.messages` es serializable a JSON y un thread se puede persistir y reanudar con otro provider.
+Ese es el entregable que justifica el major.
+
+Renombre sugerido: `AssistantState` → `Session` (o `Thread`), con alias de compatibilidad.
+
+### 2.9 Streaming: no hacerlo ahora, no bloquearlo
+
+`Provider#decode(raw_body)` sobre la respuesta completa no impide agregar después
+`Provider#decode_stream(chunks)` que emita los mismos `Part` de forma incremental. Basta con no
+asumir en el `Result` que todo llegó de una sola pieza. No entra en este alcance.
+
+---
+
+## 3. Orden de implementación
+
+La API pública se define primero (este documento) pero se **expone al final**, sobre base sólida.
+
+| Paso | Alcance | Release |
+|---|---|---|
+| 1 | Modelo canónico: `Message`, `Part::*`, `ToolDefinition`, `Request`, `Response`, `Result`, `Step`. Base `Provider` con `encode`/`decode`/`parse_usage`/`endpoint`. Motor `Engine` con el loop (el `call` actual, sin template methods). Port del adapter OpenAI. Los `<Provider>::Assistant` actuales siguen funcionando sobre el motor nuevo vía shim. | interno |
+| 2 | Port de Gemini, Anthropic, OpenRouter, HuaweiMaaS. Se borra: 5 `roles.rb`, `sanitize_schema` duplicado, los `Client` por provider (queda uno solo con auth pluggable), 12 template methods. | interno |
+| 3 | Registry + `Rasti::AI.provider`, `generate_text`, `generate_object`, `Agent`, config `default_provider` / `default_model`. Alias de compatibilidad. README nuevo. | 4.0.0 |
+
+Cada paso deja la suite verde. Los fixtures ERB de `spec/resources/` se reutilizan tal cual: pasan a
+testear `encode`/`decode` como funciones puras, sin WebMock, y el loop se testea una sola vez con un
+provider fake.
+
+---
+
+## 4. Puntos abiertos
+
+1. ¿`<Provider>::Client` sobrevive como API pública (shim `chat_completions`/`messages`/
+   `generate_content`) o se deprecia en 4.0?
+2. ¿`Result#to_str` (coerción implícita) o sólo `to_s`? `to_str` maximiza compatibilidad pero puede
+   ocultar bugs.
+3. ¿`Agent` reemplaza a `Assistant` con alias, o conviven documentados?
+4. Mezclar `provider:` instancia con kwargs de transporte: ¿ignorar en silencio o `ArgumentError`?
+5. `usage` en el `Result` con varios pasos: ¿array de `Usage` o un `Usage` agregado (+ `#usages`)?

data/.features/api-normalization/overview.md

@@ -0,0 +1,230 @@
+# Normalización de la API de Rasti::AI
+
+Objetivo: poder elegir provider y modelo **por configuración o por parámetro**, y usar la gema
+para (a) pegarle directo a un modelo y obtener una respuesta, o (b) armar un agente con tools,
+estado y structured output — sin importar el provider. Referencias de diseño: Vercel AI SDK
+(`generateText({ model })`, `LanguageModelV2`) y pi (`agent`, provider/model como strings).
+
+---
+
+## 1. Diagnóstico: qué impide hoy la unificación
+
+| Acoplamiento | Dónde | Consecuencia |
+|---|---|---|
+| Los mensajes se guardan con el shape del provider | `AssistantState#messages` + los 5 `build_*_message` | No se puede cambiar de provider en una conversación existente, ni persistir/reanudar una conversación con otro provider |
+| El nombre del método de API difiere | `chat_completions` / `messages` / `generate_content` | El `Assistant` no puede hablarle a un `Client` genérico; `request_completion` es template method |
+| La respuesta se parsea "in situ" | `parse_content`, `parse_tool_calls`, `finished?`, `extract_tool_call_info` | 4 de los 12 template methods son sólo "leer el JSON crudo" |
+| La serialización de tools se re-envuelve por provider | `wrap_tool_serialization`, `extract_tool_name`, `sanitize_schema` duplicado en Gemini y Anthropic | Código copiado; `ToolSerializer` emite `inputSchema` y cada uno lo renombra |
+| Un `Roles` por provider | 5 archivos `roles.rb` | 4 constantes con 3 valores distintos en total (`model`/`function` de Gemini) |
+| La clase elegida ES el provider | `Rasti::AI::OpenAI::Assistant` | La elección de provider es una constante en el código del usuario, no un dato |
+
+Números: de ~1.540 líneas de `lib`, los adaptadores de provider son ~700, y buena parte es
+duplicación mecánica (`sanitize_schema` está literalmente dos veces).
+
+Observación clave: **el loop de `Assistant#call` ya es universal**. Lo único que cambia por
+provider es la traducción de ida (request) y de vuelta (response). Eso es exactamente la
+frontera que hay que aislar.
+
+---
+
+## 2. Opción A — Fachada + registry (compatible, sin romper nada)
+
+Agregar una capa de resolución arriba de lo que ya existe. Cero cambios en las clases actuales.
+
+```ruby
+Rasti::AI.configure do |config|
+  config.default_provider = :anthropic
+  config.default_model = 'claude-sonnet-4-5'
+end
+
+# One-shot, sin agente
+Rasti::AI.generate 'who is the best player'
+Rasti::AI.generate 'who is the best player', model: 'openai:gpt-4o'
+
+# Agente, provider como dato
+assistant = Rasti::AI.assistant provider: :gemini, model: 'gemini-2.0-flash', tools: tools
+assistant.call 'what is the weather in Buenos Aires'
+```
+
+Implementación:
+
+- `Rasti::AI::Providers` — registry `{openai: OpenAI::Assistant, ...}` + `register`.
+- Parseo de `'provider:model'` (también `'provider/model'`) para resolver ambos de un string.
+- `Rasti::AI.assistant(...)` instancia la clase concreta y devuelve el objeto actual.
+- `Rasti::AI.generate(prompt, **opts)` = assistant efímero + `#call`.
+
+| Pros | Contras |
+|---|---|
+| No rompe nada; release 3.2.0 | No elimina una sola línea de duplicación |
+| Muy barato (~1 día con tests) | `state.messages` sigue siendo provider-specific → no se puede migrar una conversación |
+| Habilita ya el "provider por config" | Agregar un provider sigue costando 12 template methods |
+| Es un paso válido *hacia* B (la fachada sobrevive) | La API pública queda con dos formas de hacer lo mismo |
+
+Veredicto: útil como **paso 1**, insuficiente como solución.
+
+---
+
+## 3. Opción B — Mensajes canónicos + adaptadores (la normalización real)
+
+Un solo `Assistant`/`Agent`. El provider pasa a ser un objeto con dos responsabilidades:
+codificar un request canónico y decodificar una respuesta cruda a un objeto canónico.
+
+### 3.1 Modelo canónico
+
+```ruby
+Rasti::AI::Message   # role: :user | :assistant | :tool, parts: [...]
+Rasti::AI::Part::Text        # text
+Rasti::AI::Part::ToolCall    # id, name, arguments (Hash)
+Rasti::AI::Part::ToolResult  # tool_call_id, name, content
+Rasti::AI::Part::Reasoning   # text, signature, raw  (thinking blocks de Anthropic)
+Rasti::AI::ToolDefinition    # name, description, input_schema (JSON Schema neutro)
+
+Rasti::AI::Request   # messages, system, tools, tool_choice, model, thinking, json_schema, max_tokens
+Rasti::AI::Response  # message, finish_reason, usage, raw
+```
+
+`Reasoning` con `raw` es importante: Anthropic exige devolver los thinking blocks intactos en el
+turno siguiente. Guardando el `raw` del part, el encode los reinyecta sin que el modelo canónico
+tenga que entender el formato.
+
+### 3.2 Adaptador
+
+```ruby
+class Rasti::AI::Provider   # base abstracta
+
+  def encode(request)  # => Hash (body del provider)
+  def decode(raw)      # => Rasti::AI::Response
+  def parse_usage(raw) # => Usage
+  def endpoint(request)
+  def client            # HTTP genérico, hoy Rasti::AI::Client sin subclases por provider
+
+end
+```
+
+Cada provider implementa **4 métodos en vez de 12** (+ auth headers). El `sanitize_schema`
+compartido vive en un `SchemaSanitizer` con la lista de campos permitidos como constante del
+provider. `Roles` desaparece como concepto público: los roles canónicos son símbolos y cada
+adapter tiene su tabla de traducción.
+
+### 3.3 Assistant único
+
+```ruby
+class Rasti::AI::Assistant
+
+  def initialize(provider: nil, model: nil, tools: [], mcp_servers: {}, json_schema: nil,
+                 thinking: nil, state: nil, client: nil, logger: nil)
+
+  def call(prompt)  # mismo loop de hoy, sin template methods
+
+end
+```
+
+El loop no cambia: `messages << user` → `provider.decode(client.post(provider.endpoint, provider.encode(request)))`
+→ si hay `ToolCall` parts, ejecutar y agregar `ToolResult` → si no, devolver el texto.
+
+### 3.4 Lo que se gana
+
+- **Portabilidad de conversación**: `state.messages` es canónico y serializable a JSON. Se puede
+  persistir un thread, y reanudarlo con otro provider/modelo. Hoy es imposible.
+- **Fallback / routing**: reintentar el mismo request contra otro provider ante rate limit o 5xx.
+- **Un solo lugar** para tool calling, structured output y thinking.
+- **Agregar provider** = 1 archivo, ~4 métodos.
+- **Testing**: se puede testear el loop con un `Provider` fake, sin WebMock, y testear cada
+  adapter como función pura `encode/decode` contra los fixtures ERB que ya existen.
+
+### 3.5 Costo y compatibilidad
+
+Rotura real y única: el shape de `state.messages`. Todo lo demás se puede preservar:
+
+```ruby
+module Rasti::AI::OpenAI
+  class Assistant < Rasti::AI::Assistant
+    def initialize(**options)
+      super(**options, provider: :open_ai)
+    end
+  end
+end
+```
+
+`Rasti::AI::OpenAI::Client` se puede mantener como shim (`chat_completions` → encode/post) para
+quien lo use directo, o marcarlo deprecado. Los `Roles` se pueden dejar como constantes vivas.
+
+Es un **major (4.0.0)** por el cambio de `state.messages`, con las clases por provider intactas
+como alias. Esfuerzo estimado: 3-5 días incluyendo migración de specs.
+
+---
+
+## 4. Opción C — API funcional estilo Vercel/pi encima de B
+
+Con B en su lugar, la superficie pública se puede rediseñar para que el uso más común sea una
+línea. Esto es *aditivo* sobre B, no una alternativa.
+
+```ruby
+# Texto
+result = Rasti::AI.generate_text model: 'anthropic:claude-sonnet-4-5',
+                                 system: 'Act as sports journalist',
+                                 prompt: 'who is the best player'
+
+result.text            # => 'Lionel Messi'
+result.usage           # => Usage
+result.messages        # => historial canónico
+result.steps           # => [Step] con tool calls/results por iteración
+result.finish_reason   # => :stop
+
+# Objeto estructurado
+result = Rasti::AI.generate_object model: 'openai:gpt-4o',
+                                  schema: PlayerForm,        # Rasti::Form → JSON Schema
+                                  prompt: 'who is the best player'
+result.object          # => {player: 'Lionel Messi', sport: 'Football'}
+
+# Agente reutilizable con estado
+agent = Rasti::AI::Agent.new model: 'gemini:gemini-2.0-flash',
+                             instructions: 'Act as sports journalist',
+                             tools: [GetCurrentWeather.new],
+                             mcp_servers: {weather: mcp_client},
+                             thinking: 'medium'
+
+agent.call 'what is the weather in Buenos Aires'
+agent.call 'and tomorrow?'      # mismo thread
+agent.messages                  # canónico, serializable
+```
+
+Ideas adicionales que este diseño habilita naturalmente:
+
+- **`schema:` acepta un `Rasti::Form`** en vez de un Hash a mano — cierra el círculo con
+  `ToolSerializer`, que ya sabe convertir Forms a JSON Schema. El `json_schema:` actual (Hash
+  crudo) sigue funcionando.
+- **`Rasti::AI.model('openai:gpt-4o')`** como objeto de primera clase, reutilizable e inyectable:
+  `Agent.new model: Rasti::AI.model('...', api_key: tenant.key)` → multi-tenant sin globals.
+- **Middleware** (`wrapLanguageModel` de Vercel): un provider decorado para logging, caché de
+  respuestas, usage tracking, redacción de PII, o fallback. `usage_tracker` pasa a ser un
+  middleware más y deja de estar hardcodeado en el `Client`.
+- **`max_steps:`** para acotar el loop de tools (hoy `loop do` no tiene tope: un modelo que
+  insiste en llamar tools puede colgar el proceso indefinidamente — es un bug latente).
+- **Nombres**: `Assistant` → `Agent`, `AssistantState` → `Thread`/`Session`. Alinea con el
+  vocabulario de la industria y con lo que la clase realmente es.
+
+---
+
+## 5. Recomendación
+
+Camino en dos releases, sin trabajo tirado:
+
+1. **3.2.0 — Opción A.** Registry de providers + `Rasti::AI.assistant(provider:, model:)` +
+   `Rasti::AI.generate` + `default_provider`. Compatible. Deja la elección de provider como dato
+   y define la superficie pública que va a sobrevivir al refactor.
+2. **4.0.0 — Opción B + C.** Mensajes canónicos y adaptadores por debajo; `generate_text` /
+   `generate_object` / `Agent` por arriba. Las clases `<Provider>::Assistant` quedan como
+   subclases de una línea, así que el código existente sigue compilando salvo quien inspeccione
+   `state.messages`.
+
+Dos puntos a decidir antes de arrancar:
+
+- ¿Se mantiene `<Provider>::Client` como API pública (shim) o se deprecia? Afecta cuánto código
+  legacy sobrevive en 4.0.
+- ¿`Agent` reemplaza a `Assistant` o convive? Sugerencia: `Agent` como nombre nuevo y
+  `Assistant = Agent` como alias, deprecando en 5.0.
+
+Restricción a respetar en toda la implementación: **Ruby 2.3**. Sin pattern matching, sin
+`transform_keys`, sin `Hash#slice`. Los objetos canónicos con `Rasti::Model` (que ya es
+dependencia) resuelven la parte de tipado sin agregar nada.

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 |
 |---|---|---|
@@ -178,6 +280,8 @@ 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.
@@ -187,11 +291,12 @@ The loop does not change. Anthropic thinking blocks (`type: 'thinking'`) in resp
 
 ## 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 +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:
@@ -220,12 +329,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.