@anvia/core 0.26.0 → 1.0.0-rc.10

package/README.md

@@ -12,10 +12,17 @@ The package is dependency-injection oriented: create provider models, typed tool
 
 ## Installation
 
+Anvia 1.0 is currently published on npm under the `rc` tag. The unqualified `latest` tag remains
+on the maintenance-only v0 line until 1.0 reaches general availability. Keep Core and every Anvia
+adapter on the same release channel.
+
 ```sh
-pnpm add @anvia/core
+pnpm add @anvia/core@rc
 ```
 
+See the repository's [1.0 release policy](../../docs/releases/v1.md) for channel and support
+details.
+
 In this monorepo, the package is available through the workspace:
 
 ```sh
@@ -26,177 +33,379 @@ pnpm --filter @anvia/core build
 
 ```ts
 import { z } from "zod";
-import { AgentBuilder, createTool } from "@anvia/core";
+import { Agent, createTool } from "@anvia/core";
 import { OpenAIClient } from "@anvia/openai";
 
 const client = new OpenAIClient({
   apiKey,
 });
 
-const model = client.completionModel("gpt-5");
+const model = client.completionModel({ modelId: "gpt-5", api: "responses" });
 
 const lookupOrder = createTool({
   name: "lookup_order",
   description: "Look up an order by id.",
-  input: z.object({ orderId: z.string() }),
+  inputSchema: z.object({ orderId: z.string() }),
   execute: async ({ orderId }) => ({ orderId, status: "processing" }),
 });
 
-const agent = new AgentBuilder("support", model)
-  .instructions("Help customers with order questions.")
-  .tool(lookupOrder)
-  .defaultMaxTurns(4)
-  .build();
-
-const response = await agent.prompt("What is happening with order A123?").send();
+const agent = new Agent({
+  id: "support",
+  model,
+  instructions: "Help customers with order questions.",
+  maxTurns: 4,
+  tools: [lookupOrder],
+});
 
-console.log(response.output);
+const result = await agent.generate({ prompt: "What is happening with order A123?" });
+if (result.status === "completed") console.log(result.output);
 ```
 
 ## Direct Completions
 
-Use `createCompletion` when you want a single provider call without agent turns, memory, or
-tool execution:
+Use `generateCompletion` for one provider call without Agent turns, memory, or local tool
+execution. The model and input are part of one options object:
 
 ```ts
-import { createCompletion } from "@anvia/core";
+import { generateCompletion } from "@anvia/core";
 import { OpenAIClient } from "@anvia/openai";
 
-const model = new OpenAIClient({ apiKey }).completionModel("gpt-5");
+const model = new OpenAIClient({ apiKey }).completionModel({ modelId: "gpt-5", api: "responses" });
 
-const result = await createCompletion(model, {
-  input: "Summarize Anvia in one sentence.",
+const result = await generateCompletion({
+  model,
+  prompt: "Summarize Anvia in one sentence.",
   instructions: "Answer clearly and concisely.",
 });
 
-console.log(result.text);
+console.log(result.output); // string
 ```
 
-Use `messages` when you already own the transcript. If `input` is also provided, it is appended as
-the final message:
+Use `messages` when the application already owns the transcript. Exactly one of `prompt` or
+`messages` is required:
 
 ```ts
-import { Message, createCompletion } from "@anvia/core";
+import { generateCompletion, type Message } from "@anvia/core";
 
-const result = await createCompletion(model, {
+const result = await generateCompletion({
+  model,
   messages: [
-    Message.system("You are concise."),
-    Message.user("Explain Anvia."),
-  ],
+    { role: "system", content: "You are concise." },
+    { role: "user", content: "Explain Anvia." },
+  ] satisfies readonly Message[],
   maxTokens: 300,
-  params: {
+  providerOptions: {
     reasoning: { effort: "low" },
   },
 });
 ```
 
-Use `createCompletionStream` to receive raw completion stream events from the model:
+Messages are plain, readonly `{ role, content }` objects. Use structural literals with
+`satisfies Message` or `satisfies readonly Message[]`; there is no message factory namespace.
+Multimodal user content uses `text`, `image`, and `file` parts, while assistant tool calls use
+`{ type: "tool-call", toolCallId, toolName, input }`. At external boundaries, validate with
+`parseMessage`, `parseMessages`, `messageSchema`, or an application-specific
+`createMessageSchema({ metadataSchema })`.
+
+Add `outputSchema` to the same function for typed, schema-validated output:
+
+```ts
+import { generateCompletion } from "@anvia/core";
+import { z } from "zod";
+
+const result = await generateCompletion({
+  model,
+  prompt: "Extract: Acme reports a high-priority checkout failure.",
+  outputSchema: z.object({
+    customer: z.string(),
+    priority: z.enum(["low", "medium", "high"]),
+  }),
+});
+
+console.log(result.output.priority); // fully typed
+```
+
+`CompletionResult` consistently contains `output`, the original `text`, normalized `content`,
+`usage`, and `rawResponse`, plus optional message, context, source, provider-tool, and finish-reason
+metadata. First-party adapters normalize provider termination into `finishReason` (`stop`, `length`,
+`content-filter`, `tool-calls`, or `other`) while preserving the provider value separately as
+`providerFinishReason`.
+
+Schema-backed completion checks termination before JSON parsing. `finishReason: "length"` throws
+`CompletionStructuredOutputError` with `phase: "truncated"`; `finishReason: "content-filter"`
+throws it with `phase: "content-filter"` and is not retried by the default policy. Ordinary text
+completion remains intentional: partial text is returned unchanged with its finish reason so the
+application decides whether to display, continue, or discard it. A direct structured stream can
+similarly end with one typed error event after any already-emitted deltas; it does not silently
+retract public stream progress.
+
+Use `streamCompletion` for the streaming form:
 
 ```ts
-import { createCompletionStream } from "@anvia/core";
+import { streamCompletion } from "@anvia/core";
 
-for await (const event of createCompletionStream(model, {
-  input: "Write a short launch note.",
+for await (const event of streamCompletion({
+  model,
+  prompt: "Write a short launch note.",
 })) {
   if (event.type === "text_delta") process.stdout.write(event.delta);
+  if (event.type === "final") console.log(event.result.usage);
+  if (event.type === "error") console.error(event.error);
 }
 ```
 
-React hooks keep `UIMessage[]` state locally, but send core `Message[]` in their request body. Pass
-those messages directly to `createCompletionStream`:
+Tool-call deltas are always emitted when a provider supplies them; there is no opt-in flag. A
+high-level stream emits at most one terminal `error` event and then closes. Provider model adapters
+use the lower-level `CompletionModelStreamEvent`, whose terminal event is `{ type: "final",
+response }`; `streamCompletion` normalizes it to `{ type: "final", result }`.
 
-```ts
-import { createCompletionStream } from "@anvia/core";
-import type { UIStreamRequest } from "@anvia/core/ui";
+Client requests carry core `Message[]`, so an endpoint can validate and pass them directly:
 
-const body = (await request.json()) as UIStreamRequest;
+```ts
+import { completionToClientStream, parseClientStreamRequest } from "@anvia/client";
+import { streamCompletion } from "@anvia/core";
+import { createClientStreamResponse } from "@anvia/server";
 
-const events = createCompletionStream(model, {
-  messages: body.messages,
+const body = parseClientStreamRequest(await request.json());
+const events = completionToClientStream({
+  events: streamCompletion({ model, messages: body.messages }),
 });
+return createClientStreamResponse({ events });
 ```
 
-Use `createParsedCompletion` when you want a direct completion to return schema-validated data:
+Core does not own UI messages, HTTP transports, or the public wire protocol. Those boundaries live
+in `@anvia/client`, `@anvia/server`, and framework packages such as `@anvia/react`.
+
+## Retries, Provider Options, and Cancellation
+
+Direct completion and media calls accept `retries?: RetryOptions | false`. An omitted or `false`
+value makes one provider attempt; `{}` enables the default retry policy. Only retry-safe provider
+calls are repeated.
 
 ```ts
-import { createParsedCompletion } from "@anvia/core";
-import { z } from "zod";
+const controller = new AbortController();
+
+const result = await generateCompletion({
+  model,
+  prompt: "Summarize this incident.",
+  retries: { maxAttempts: 3, initialDelayMs: 100, maxDelayMs: 1_000 },
+  abortSignal: controller.signal,
+  providerOptions: { reasoning: { effort: "medium" } },
+});
+```
 
-const eventSchema = z.object({
-  name: z.string(),
-  date: z.string(),
+`providerOptions` contains a strict JSON object passed to an adapter. Runtime values such as
+`undefined`, non-finite numbers, cycles, a top-level array, and class instances are rejected rather
+than coerced. Nested arrays are valid JSON. Canonical Anvia fields such as model, input,
+temperature, tools, dimensions, text, and voice take precedence over conflicting provider keys.
+Cancellation is forwarded to provider SDK calls and is never retried.
+
+## Agents
+
+Agents own their default retry policy. A run with no `retries` value inherits the Agent setting;
+`false` disables it for that run; an object replaces it for that run. Retries apply to the current
+completion only, so completed tools and earlier turns are never replayed. `maxAttempts` is the
+total number of model attempts for that completion, including the initial attempt; it is not the
+number of additional retries.
+
+```ts
+const agent = new Agent({
+  id: "support",
+  model,
+  retries: { maxAttempts: 3 },
 });
 
-const event = await createParsedCompletion(model, {
-  schema: eventSchema,
-  input: "Alice and Bob are going to a science fair on Friday.",
+await agent.generate({ prompt: "Try normally." });
+await agent.generate({ prompt: "Do not retry this run.", retries: false });
+await agent.generate({
+  prompt: "Use one custom policy.",
+  retries: { maxAttempts: 2, initialDelayMs: 0, maxDelayMs: 0 },
 });
+```
+
+When an Agent has `outputSchema`, truncation, JSON parsing, and schema-validation failures use the
+same retry budget when retries are explicitly enabled. Each retry starts from the original request
+rather than recursively accumulating failed attempts. Truncated output and reasoning are omitted;
+parse and schema repairs include only a bounded, text-only preview of the latest failed response.
+The correction asks for shorter raw JSON matching the schema, without Markdown or commentary.
+Transport failures and structured-output failures therefore cannot exceed `maxAttempts` in total.
+Completed Agent results expose the last generation's `finishReason` and `providerFinishReason`, and
+the same fields remain attached to each assistant message's Anvia generation metadata.
+
+Malformed, incomplete, or non-JSON provider tool arguments fail with
+`CompletionProviderOutputError`. The default policy retries only explicitly retry-safe provider
+output failures when retries are enabled; it does not make arbitrary `SyntaxError` instances
+retryable. Tool calls are validated as a complete set before any tool executes, and filtered tool
+calls are never retried by default. Raw provider arguments are not retained in the error or retry
+metadata. A no-argument tool call must still contain the JSON value `{}`; blank argument text is
+malformed provider output and is never replaced with invented input.
+
+Streaming attempts are retried only before any provider event has been exposed. Once progress has
+been emitted, Anvia returns the failure without starting another provider attempt, because replaying
+the stream could duplicate text, tool-call deltas, or other observable events. Applications that
+want post-progress recovery must buffer attempts and define their own reset or resume protocol.
+
+Structured output remains strict: Core trims surrounding whitespace, parses JSON, and validates the
+result with the configured Zod schema. As a compatibility fallback for OpenAI-compatible providers
+that violate strict JSON mode, Core also accepts a response consisting entirely of one lowercase
+`json` Markdown fence or one unlabeled Markdown fence. It does not search prose for JSON, accept
+content before or after a fence, or bypass schema validation. `AgentStructuredOutputError` reports
+the `truncated`, `content-filter`, `parse`, or `schema` phase, attempt counts, output length/format
+metadata, per-attempt and cumulative usage, finish reasons, and the original `cause` when one
+exists; its message never contains the rejected model response. The `completion.retry` observer
+event records the same safe diagnostics and whether failed output was omitted or previewed, never
+the model output itself.
+
+Agent results are discriminated by `status`. Completed results include typed `output` and `text`;
+guardrail blocks return `status: "blocked"`, `stage`, and `text`; tool approvals and first-class
+questions return a JSON-safe `status: "suspended"` result.
 
-console.log(event.data);
+```ts
+const result = await agent.generate({ prompt: "Help with this request." });
+
+if (result.status === "completed") console.log(result.output);
+if (result.status === "blocked") console.log(result.stage, result.text);
+if (result.status === "suspended") {
+  const resumed = await agent.generate({
+    continuation: result.continuation,
+    response:
+      result.interaction.type === "tool-approval"
+        ? { type: "tool-approval", approved: true }
+        : {
+            type: "tool-question",
+            answers: result.interaction.questions.map((question) => ({
+              questionId: question.id,
+              value: "application-provided answer",
+            })),
+          },
+  });
+  console.log(resumed.status, resumed.resumedFrom);
+}
 ```
 
-## Prompts and Memory
+Keep continuations server-side. A resumed phase receives a new `runId`; Core validates the
+continuation and current Agent/tool registration but does not provide a durable continuation store
+or exactly-once execution. Use `createQuestionTool({ name, description })` when a model must ask for
+structured free-text or choice answers.
 
-Use a plain prompt for stateless calls:
+Import JSON-safe interaction contracts and parsers from their browser-safe subpath. This entrypoint
+does not load the Agent runtime, MCP clients, or Node infrastructure:
 
 ```ts
-await agent.prompt("Summarize this ticket.").send();
+import {
+  type AgentInteractionResponse,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse,
+} from "@anvia/core/agent/interactions";
 ```
 
-Use a message array when you already own the transcript. The last message is the active prompt and earlier messages are request history:
+An Agent with `outputSchema` carries that output type through `generate`, `stream`, `asTool`, and
+Pipeline Agent stages. Agent stream finals use the same result shape:
 
 ```ts
-import { Message } from "@anvia/core";
-
-await agent
-  .prompt([
-    Message.user("My project is named Anvia."),
-    Message.assistant("Noted."),
-    Message.user("What is my project named?"),
-  ])
-  .send();
+for await (const event of agent.stream({ prompt: "Help with this request." })) {
+  if (event.type === "final") {
+    if (event.result.status === "completed") console.log(event.result.output);
+    else console.log(event.result.stage, event.result.text);
+  }
+}
 ```
 
-Configure durable conversation memory on the agent, then run through a session:
+Pass `abortSignal` on a run to cancel the active provider call, tools, and nested Agent tools.
+
+## Memory
+
+Configure durable conversation memory on the Agent, then run through a session:
 
 ```ts
-import { AgentBuilder, type MemoryStore, type Message } from "@anvia/core";
-import type { MemoryAppendInput, MemoryContext } from "@anvia/core/memory";
+import { Agent, type MemoryStore, type Message } from "@anvia/core";
+import type { MemoryAppendOptions, MemoryScope } from "@anvia/core/memory";
 
 class AppMemoryStore implements MemoryStore {
   private readonly sessions = new Map<string, Message[]>();
 
-  async load(context: MemoryContext): Promise<Message[]> {
-    return [...(this.sessions.get(context.sessionId) ?? [])];
+  async load({ scope }: { scope: MemoryScope }): Promise<Message[]> {
+    return [...(this.sessions.get(scope.sessionId) ?? [])];
   }
 
-  async append(input: MemoryAppendInput): Promise<void> {
-    const current = this.sessions.get(input.context.sessionId) ?? [];
-    this.sessions.set(input.context.sessionId, [...current, ...input.messages]);
+  async append(input: MemoryAppendOptions): Promise<void> {
+    const current = this.sessions.get(input.scope.sessionId) ?? [];
+    this.sessions.set(input.scope.sessionId, [...current, ...input.messages]);
   }
 
-  async clear(context: MemoryContext): Promise<void> {
-    this.sessions.delete(context.sessionId);
+  async clear({ scope }: { scope: MemoryScope }): Promise<void> {
+    this.sessions.delete(scope.sessionId);
   }
 }
 
 const memory = new AppMemoryStore();
-const agent = new AgentBuilder("support", model).memory(memory).build();
+const agent = new Agent({
+  id: "support",
+  model: model,
+  memory: { store: memory },
+});
 
-await agent.session("thread_123", { userId: "user_456" }).prompt("Remember my plan.").send();
-await agent.session("thread_123", { userId: "user_456" }).prompt("What is my plan?").send();
+const session = { sessionId: "thread_123", userId: "user_456" };
+await agent.generate({ prompt: "Remember my plan.", session });
+await agent.generate({ prompt: "What is my plan?", session });
 ```
 
 Memory defaults to `savePolicy: "message"`, which saves the user prompt, each completed assistant message, and each completed tool result as soon as they are ready. You can choose `"turn"` or `"run"` at configuration time:
 
 ```ts
-new AgentBuilder("support", model).memory(memory, { savePolicy: "turn" });
+new Agent({
+  id: "support",
+  model,
+  memory: { store: memory, savePolicy: "turn" },
+});
 ```
 
+Without `session`, the same Agent is stateless. Pass `{ messages }` when the caller already owns a
+complete transcript; transcripts cannot be combined with persisted sessions.
+
+Compaction is an explicit Agent policy over a store capability. The adapter persists the summary as
+an ordinary system message with `metadata.anvia.memoryCompaction`, so `load()` and inspectors expose
+exactly what future runs receive:
+
+```ts
+import { createSummaryMemoryCompactor } from "@anvia/core/memory";
+
+const compactor = createSummaryMemoryCompactor({
+  model: summaryModel,
+  maxTokens: 1024,
+  retries: { maxAttempts: 2 },
+});
+
+const agent = new Agent({
+  id: "support",
+  model,
+  memory: {
+    store: memory,
+    savePolicy: "message",
+    compaction: {
+      trigger: { afterMessages: 50 },
+      retention: { recentUserTurns: 4 },
+      compactor,
+      conflictRetries: false,
+    },
+  },
+});
+
+for await (const event of agent.stream({ prompt: "What did we decide?", session })) {
+  if (event.type === "memory_compaction") {
+    console.log(event.compactedMessageCount, event.usage);
+  }
+}
+```
+
+The trigger is a threshold, not a hard storage limit. Summary-provider retries belong to the
+compactor; full snapshot-to-replacement conflict retries are separately opt-in.
+
 ## Structured Extraction
 
 ```ts
-import { ExtractorBuilder } from "@anvia/core/extractor";
+import { extract } from "@anvia/core/extractor";
+import { z } from "zod";
 
 const ticketSchema = z.object({
   customer: z.string(),
@@ -204,45 +413,142 @@ const ticketSchema = z.object({
   summary: z.string(),
 });
 
-const extractor = new ExtractorBuilder(model, ticketSchema).retries(1).build();
-
-const ticket = await extractor.extract(
-  "Acme Co. reports checkout failures. Priority is high.",
-);
+const { output: ticket } = await extract({
+  model,
+  text: "Acme Co. reports checkout failures. Priority is high.",
+  outputSchema: ticketSchema,
+  retries: { maxAttempts: 2 },
+});
 ```
 
 ## Pipelines
 
 ```ts
-import { PipelineBuilder } from "@anvia/core/pipeline";
+import { Pipeline } from "@anvia/core/pipeline";
 import { z } from "zod";
 
-const pipeline = new PipelineBuilder(z.string())
-  .step((input) => `Extract this support ticket:\n\n${input}`)
-  .prompt(agent)
-  .extract(extractor)
-  .build();
+const pipeline = new Pipeline({ id: "support-flow", inputSchema: z.string() })
+  .agent({
+    id: "draft",
+    agent,
+    suspension: "reject",
+    request: ({ input }) => ({ prompt: `Draft a reply for this ticket:\n\n${input}` }),
+  })
+  .extract({
+    id: "parse",
+    model,
+    outputSchema: ticketSchema,
+    text: ({ input }) => input,
+  });
+
+const { runId, output } = await pipeline.run({
+  input: "Customer cannot complete checkout.",
+});
+```
+
+## Documents
+
+Applications own file discovery, file reads, source metadata, and per-file error policy. Core only
+provides deterministic in-memory chunking and scoped PDF text extraction:
+
+PDF extraction uses the optional `pdfjs-dist` peer dependency. Install it in applications that call
+`extractPdfText`:
+
+```sh
+pnpm add pdfjs-dist
+```
+
+```ts
+import { readFile } from "node:fs/promises";
+import { chunkText, extractPdfText } from "@anvia/core/documents";
+
+const text = await readFile("guide.txt", "utf8");
+const chunks = chunkText({
+  text,
+  strategy: "recursive",
+  maxSize: 1_000,
+  overlap: 100,
+  separators: ["\n\n", "\n", " "],
+});
+
+const { pages } = await extractPdfText({
+  data: new Uint8Array(await readFile("guide.pdf")),
+  abortSignal,
+});
+```
+
+Use `strategy: "fixed"` for deterministic sliding windows. Recursive chunking requires an explicit
+separator order and falls back to fixed-size splitting when none of those separators can divide an
+oversized section. Chunk offsets use JavaScript string indices and always identify the exact source
+slice. PDF pages are one-based, and the parser task is disposed before extraction settles.
+If parsing or abort handling fails together with parser cleanup, extraction rejects with an
+`AggregateError` containing the operation failure first and the cleanup failure second.
+
+## Media
+
+Media helpers follow the same one-object API and share `providerOptions`, `retries`, and
+`abortSignal`:
+
+```ts
+import { generateImage, generateSpeech, transcribe } from "@anvia/core";
+
+const image = await generateImage({
+  model: client.imageGenerationModel({ modelId: "gpt-image-1" }),
+  prompt: "A compact robot drawing an architecture diagram.",
+  width: 1024,
+  height: 1024,
+});
+console.log(image.images[0].data);
 
-const result = await pipeline.run("Customer cannot complete checkout.");
+const speech = await generateSpeech({
+  model: client.speechGenerationModel({ modelId: "gpt-4o-mini-tts" }),
+  text: "Hello from Anvia.",
+  voice: "alloy",
+});
+
+const transcript = await transcribe({
+  model: client.transcriptionModel({ modelId: "gpt-4o-mini-transcribe" }),
+  audio: {
+    data: speech.audio.data,
+    filename: "speech.mp3",
+    mediaType: speech.audio.mediaType,
+  },
+});
+console.log(transcript.text);
+```
+
+## MCP
+
+MCP clients live in the optional `@anvia/mcp` package. Core retains the lightweight registration
+contracts that let agents receive immutable MCP server snapshots without owning or closing their
+underlying transports:
+
+```sh
+pnpm add @anvia/mcp
 ```
 
+Import `McpClient` and `McpClientGroup` from `@anvia/mcp`, connect them, and pass the resulting
+`servers` to `new Agent({ mcpServers })`. See the `@anvia/mcp` README for transport configuration,
+connection ownership, URL safety, and cleanup.
+
 ## Public Areas
 
-- `agent`: agent runtime and `AgentBuilder`
+- `agent`: typed Agent runtime, retries, and stream events
+- `agent/interactions`: browser-safe interaction contracts, schemas, assertions, and parsers
 - `tool`: typed tool creation and tool sets
-- `completion`: provider-neutral completion request and response types
+- `completion`: direct completion helpers and provider-neutral model contracts
 - `memory`: durable session memory interfaces and in-memory store
 - `extractor`: schema-first structured extraction
 - `pipeline`: typed sequential and parallel workflows
 - `embeddings`: embedding helpers and document embedding utilities
 - `vector-store`: in-memory vector search and vector search tools
 - `streaming`: normalized stream helpers
-- `mcp`: MCP server connection helpers
+- `mcp`: lightweight MCP tool and server registration contracts used by Agent
 - `skills`: local skill loading
 - `observability`: observer interfaces for runs, generations, and tool calls
 - `evals`: evaluation helpers and reporters
-- `loaders`: document loading utilities
-- `audio-generation`, `image-generation`, `transcription`: provider-neutral media interfaces
+- `documents`: in-memory text chunking and PDF text extraction
+- `speech-generation`, `image-generation`, `transcription`: provider-neutral media interfaces
 
 ## Development