release: WRNexusJS 0.8.0

.publish/ai/README.md

@@ -1,5 +1,9 @@
 # @wrnexus/ai
 
+Provider-neutral AI orchestration for OpenAI, Anthropic, Google and local OpenAI-compatible models,
+with streaming, structured output, tools, embeddings, vector search/RAG, conversation persistence,
+templates, guardrails, usage events, fallback, rate limits and evaluation reports.
+
 > A tiny, zero-dependency Claude (Anthropic) client for WrNexus apps — generate and stream text with Claude from any server-side code.
 
 Part of the **WrNexus** framework — an SSR-first, Bun-native full-stack web framework.
@@ -120,6 +124,34 @@ try {
 }
 ```
 
+### Multi-provider client
+
+`createAIClient` adds named-provider selection and fallback, capability discovery,
+validated JSON output, validated tool execution, abort-aware exponential retries,
+and per-provider circuit breakers. Attempt events intentionally contain metadata
+only: prompts, credentials, and raw model responses are never passed to telemetry.
+
+```ts
+import { anthropicProvider, createAIClient } from "@wrnexus/ai";
+
+const ai = createAIClient({
+  providers: [anthropicProvider()],
+  retry: { attempts: 3, baseDelayMs: 100, maxDelayMs: 2_000 },
+  circuitBreaker: { failureThreshold: 5, resetAfterMs: 30_000 },
+});
+
+const result = await ai.generateObject<{ title: string }>("Return a JSON title", {
+  validate: (value): value is { title: string } =>
+    typeof value === "object" && value !== null && "title" in value,
+});
+```
+
+Providers can return normalized `usage` (`inputTokens`, `outputTokens`,
+`totalTokens`, and `costUsd`) and `toolCalls`. Use `executeTools` with a named,
+validated tool registry; unknown tools and invalid arguments are rejected before
+application code runs. `deterministicAIProvider` supplies ordered or computed
+offline responses for tests and examples without API keys or network calls.
+
 ## Usage
 
 ### Return generated JSON from an API route