rasti-ai 3.0.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53a61c4811f7fc87198609ce9311d5208d5e6a3dfb3a616c40e17c2c8bb99e5d
-  data.tar.gz: 96314ebda147f3cfbf79e2c096fd33783a02d1038b8e233ef45e26121642d54a
+  metadata.gz: fa07486ef7216a0a1408d1711ea21ca521283673c06ca2845ad63197dd1dbe8d
+  data.tar.gz: dd42552dfd7e3752dac0264b1c89159f04f230c6d067fa674dd4347aae01b0b1
 SHA512:
-  metadata.gz: 2265c2a95f49854abef4259cec47b93e1e587f1e9397f547244c94f16d8cb3c4b31feba616275658beed6569267ec6398687d61478698ab396943e7c62e0b5cc
-  data.tar.gz: d7b8bd65dc9cda869ac6515a05e9eb93c9ff32affbad5a90669d0c0f5e363303ed0322944a06e2b668fa789370b8815b825382884644bb3519c19029a6d171da
+  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.