@axlsdk/axl 0.18.2 → 0.19.1

package/README.md

@@ -58,6 +58,17 @@ export const config = defineConfig({
 
 Provider API keys are also read automatically from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`/`GEMINI_API_KEY`), so for local development you can skip the `providers` block entirely.
 
+**Beyond the big three**, Axl ships presets for any OpenAI-compatible endpoint — pick a model with `preset:model` and set the matching env var:
+
+```typescript
+agent({ model: 'openrouter:anthropic/claude-opus-4.7' }); // OPENROUTER_API_KEY — 300+ models, one key
+agent({ model: 'groq:openai/gpt-oss-120b' });             // GROQ_API_KEY — fastest inference
+agent({ model: 'deepseek:deepseek-reasoner' });           // DEEPSEEK_API_KEY
+agent({ model: 'ollama:llama3' });                        // local — no key, $0
+```
+
+Presets: `openrouter`, `azure`, `xai`, `deepseek`, `mistral`, `groq`, `bedrock`, and self-hosted `ollama` / `vllm` / `lmstudio` / `llamacpp` / `sglang`. The unified `effort` knob and per-call cost tracking work across them. Build your own by cloning a `ProviderProfile`. See [docs/providers.md](../../docs/providers.md#openai-compatible-providers--presets).
+
 Each provider also accepts an opt-in `rateLimit` (`{ maxConcurrent?, minIntervalMs?, acquireTimeoutMs? }`) for proactive client-side pacing on top of the automatic 429/503/529 backoff — useful when a large fan-out (e.g. an eval) shares one API key. It caps in-flight request concurrency (not token throughput) for that provider's chat calls. See [Providers → Rate limiting](../../docs/providers.md#rate-limiting-opt-in).
 
 State store options: `'memory'` (default), `'sqlite'` (requires `better-sqlite3`), or a `RedisStore` instance for multi-process deployments. See [State Stores](#state-stores).
@@ -151,9 +162,14 @@ const calculator = tool({
   // handler also accepts (input, ctx) for nested agent invocations — see below
   retry: { attempts: 3, backoff: 'exponential' },
   sensitive: false,
+  // Keep the complete handler result for the host while sending only this
+  // allowlisted projection back to the model:
+  toModelOutput: (result) => ({ answer: result.result }),
 });
 ```
 
+`toModelOutput` is an opt-in, synchronous mapper for successful agent-invoked local tools. Strings are sent verbatim; JSON-compatible values are strictly validated and serialized once. The full post-hook result stays on `tool_call_end.data.result` for host rendering (subject to `trace.redact`). `sensitive: true` and thrown handler/hook/mock failures skip projection, and projection errors fail closed with `ToolModelOutputError`—there is no raw fallback. Direct `tool.run()`/`_execute()`, MCP tools, and handoffs are unchanged. See the [API reference](../../docs/api-reference.md#model-facing-tool-output) for the exact type, validation, mock, and delivery contract.
+
 Tool handlers receive a second parameter `ctx: WorkflowContext` (a child context), enabling the "agent-as-tool" composition pattern:
 
 ```typescript
@@ -738,12 +754,12 @@ import {
 
 ### Provider URIs
 
-Four built-in providers using the `provider:model` URI scheme:
+Four native adapters using the `provider:model` URI scheme (plus the OpenAI-compatible presets above):
 
 ```
 openai-responses:gpt-5.5               # OpenAI Responses API (preferred over Chat Completions)
 openai:gpt-5.4                         # OpenAI Chat Completions
-anthropic:claude-opus-4-7              # Anthropic (supports effort: 'xhigh')
+anthropic:claude-opus-4-8              # Anthropic (supports effort: 'xhigh' and 'max')
 google:gemini-3.1-pro-preview          # Google Gemini
 ```