@anvia/core 1.0.0-rc.1 → 1.0.0-rc.2

package/README.md

@@ -33,7 +33,7 @@ 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",
@@ -44,141 +44,210 @@ const lookupOrder = createTool({
 
 const agent = new Agent({
   id: "support",
-  model: model,
+  model,
   instructions: "Help customers with order questions.",
   maxTurns: 4,
   tools: [lookupOrder],
 });
 
-const response = await agent.prompt("What is happening with order A123?").send();
-
-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 { createCompletionStream } from "@anvia/core";
+import { generateCompletion } from "@anvia/core";
+import { z } from "zod";
 
-for await (const event of createCompletionStream(model, {
-  input: "Write a short launch note.",
+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, and provider-tool metadata.
+
+Use `streamCompletion` for the streaming form:
+
+```ts
+import { streamCompletion } from "@anvia/core";
+
+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 eventSchema = z.object({
-  name: z.string(),
-  date: z.string(),
+const result = await generateCompletion({
+  model,
+  prompt: "Summarize this incident.",
+  retries: { maxAttempts: 3, initialDelayMs: 100, maxDelayMs: 1_000 },
+  abortSignal: controller.signal,
+  providerOptions: { reasoning: { effort: "medium" } },
 });
+```
+
+`providerOptions` contains strict JSON passed to an adapter. 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
+provider call only, so completed tools and earlier turns are never replayed.
 
-const event = await createParsedCompletion(model, {
-  schema: eventSchema,
-  input: "Alice and Bob are going to a science fair on Friday.",
+```ts
+const agent = new Agent({
+  id: "support",
+  model,
+  retries: { maxAttempts: 3 },
 });
 
-console.log(event.data);
+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 },
+});
 ```
 
-## Prompts and Memory
-
-Use a plain prompt for stateless calls:
+Agent results are discriminated by `status`. Completed results include typed `output` and `text`;
+guardrail blocks return `status: "blocked"`, `stage`, and `text`; tool approval can return
+`status: "approval_required"`.
 
 ```ts
-await agent.prompt("Summarize this ticket.").send();
+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);
 ```
 
-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 { Agent, type MemoryStore, type Message } from "@anvia/core";
-import type { MemoryAppendInput, MemoryContext } from "@anvia/core/memory";
+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);
   }
 }
 
@@ -189,8 +258,9 @@ const agent = new Agent({
   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:
@@ -203,10 +273,52 @@ new Agent({
 });
 ```
 
+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(),
@@ -214,45 +326,132 @@ 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,
+    approval: "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.",
+});
+```
+
+## Media
+
+Media helpers follow the same one-object API and share `providerOptions`, `retries`, and
+`abortSignal`:
 
-const result = await pipeline.run("Customer cannot complete checkout.");
+```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 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 own connections. Agents receive immutable server registrations and never own or close
+the underlying transport:
+
+```ts
+import { Agent } from "@anvia/core/agent";
+import { McpClient, McpClientGroup } from "@anvia/core/mcp";
+
+const filesystem = new McpClient({
+  name: "filesystem",
+  transport: {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"],
+  },
+});
+const github = new McpClient({
+  name: "github",
+  transport: {
+    type: "streamableHttp",
+    url: "https://mcp.example.com/mcp",
+    requestInit: { headers: { authorization: `Bearer ${process.env.MCP_TOKEN}` } },
+  },
+  tools: { prefix: "github_" },
+});
+
+const mcp = await McpClientGroup.connect({ clients: [filesystem, github] });
+const agent = new Agent({ id: "assistant", model, mcpServers: mcp.servers });
+
+try {
+  await agent.generate({ prompt: "Find the issue and update it." });
+} finally {
+  await mcp.close();
+}
+```
+
+Construction performs no I/O. `connect()` discovers every tool page once and returns a frozen
+registration snapshot. Reconnect and rebuild the Agent to adopt changed remote tools. Built-in
+Streamable HTTP connections enforce Anvia URL safety and do not accept a custom `fetch`; use the
+explicit caller-owned `custom` transport only when you intentionally own that security boundary.
+MCP server instructions remain inspectable metadata and are not added to Agent instructions.
+
 ## Public Areas
 
-- `agent`: agent runtime and the compatibility `AgentBuilder`
+- `agent`: typed Agent runtime, run results, approvals, retries, and stream events
 - `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`: lifecycle-owning MCP clients, groups, and immutable Agent registrations
 - `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
+- `speech-generation`, `image-generation`, `transcription`: provider-neutral media interfaces
 
 ## Development
 

package/dist/agent/index.d.ts

@@ -1,22 +1,26 @@
-export { R as RetryContext, a as RetryOptions } from '../retry-D3Ruy-ba.js';
-export { A as Agent, a as AgentContextInput, b as AgentMemoryOptions, c as AgentObserverInput, d as AgentOptions, e as AgentSession, f as AgentToolInput, g as AgentToolOptions, C as ContextIndex, h as CreateContextIndexOptions, i as createContextIndex, j as isContextIndex } from '../agent-DGYY_onS.js';
-import { M as Message } from '../types-B3A4YxaA.js';
-export { A as AgentApprovalDecision, a as AgentApprovalRequiredEvent, b as AgentApprovalRequiredResult, c as AgentChildStreamEvent, d as AgentChildStreamEventWithToolCallDeltas, e as AgentChildStreamEventWithoutToolCallDeltas, f as AgentDeltaEvent, g as AgentErrorEvent, h as AgentErrorStreamEvent, i as AgentFinishEvent, j as AgentInput, k as AgentLifecycle, l as AgentResponse, m as AgentResult, n as AgentRunOptions, o as AgentStartEvent, p as AgentStepFinishEvent, q as AgentStream, r as AgentStreamEvent, s as AgentStreamEventWithToolCallDeltas, t as AgentStreamEventWithoutToolCallDeltas, u as AgentStreamOptions, v as AgentToolApprovalRequest, w as AgentToolCallDeltaEvent, x as AgentToolFinishEvent, y as AgentToolStartEvent } from '../index-DxB74ybJ.js';
-import '../guardrails/index.js';
-import '../type-utils-CtHVDRn_.js';
-import '../types-BBEGKB9m.js';
-import '../middleware-KynLg_RW.js';
-import '../tool-C_8GudXn.js';
+export { M as ModelCallOptions } from '../model-call-options-CZkSw_xN.js';
+export { R as RetryContext, a as RetryOptions, b as RetrySetting } from '../retry-CjvSlKGW.js';
+export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-yBG8e9Jj.js';
+import { M as Message } from '../types-CQ_ioXWK.js';
+import { c as AgentBlockedResult } from '../types-3x3mOLHU.js';
+export { A as AgentApprovalDecision, a as AgentApprovalRequiredEvent, b as AgentApprovalRequiredResult, d as AgentChildStreamEvent, e as AgentDeltaEvent, f as AgentErrorEvent, g as AgentErrorStreamEvent, h as AgentFinishEvent, i as AgentInput, j as AgentLifecycle, k as AgentMemoryCompactionEvent, l as AgentPrompt, m as AgentResponse, n as AgentResult, o as AgentRunOptions, p as AgentRunSettings, q as AgentStartEvent, r as AgentSteerInput, s as AgentStepFinishEvent, t as AgentStream, u as AgentStreamEvent, v as AgentToolApprovalRequest, w as AgentToolCallDeltaEvent, x as AgentToolFinishEvent, y as AgentToolStartEvent } from '../types-3x3mOLHU.js';
 import '../zod-schema-C7F4clpm.js';
 import 'zod';
-import '../types-DulRCYdB.js';
-import '@modelcontextprotocol/sdk/client/sse.js';
-import '@modelcontextprotocol/sdk/client/stdio.js';
+import '../guardrails/index.js';
+import '../type-utils-CtHVDRn_.js';
+import '../client-B8DT1vUG.js';
+import 'node:child_process';
+import 'node:stream';
+import '@modelcontextprotocol/sdk/client/auth.js';
 import '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import '../types-DhQfwiZn.js';
-import '../dynamic-tools-i9woysFa.js';
-import '../types-p55Jc-sr.js';
-import '../types-DT3nEemY.js';
+import '@modelcontextprotocol/sdk/shared/transport.js';
+import '../tool--Mz4v1eL.js';
+import '../middleware-C7PdmKF7.js';
+import '../types-BVzM4RsC.js';
+import '../types-DiJqJejp.js';
+import '../dynamic-tools-KwEGRbHp.js';
+import '../types-Cr4uiYo5.js';
+import '../types-Dld1TpWj.js';
 
 declare class MaxTurnsError extends Error {
     readonly maxTurns: number;
@@ -27,7 +31,11 @@ declare class MaxTurnsError extends Error {
 declare class AgentRunCancelledError extends Error {
     readonly chatHistory: Message[];
     readonly reason: string;
-    constructor(chatHistory: Message[], reason: string);
+    constructor(chatHistory: Message[], reason: string, options?: ErrorOptions);
+}
+declare class AgentRunBlockedError extends Error {
+    readonly result: AgentBlockedResult;
+    constructor(result: AgentBlockedResult);
 }
 
-export { AgentRunCancelledError, MaxTurnsError };
+export { AgentBlockedResult, AgentRunBlockedError, AgentRunCancelledError, MaxTurnsError };

package/dist/agent/index.js

@@ -1,26 +1,30 @@
 import {
   Agent,
+  AgentRunBlockedError,
   AgentRunCancelledError,
   MaxTurnsError,
-  createContextIndex,
-  isContextIndex
-} from "../chunk-IL3ZSNJI.js";
+  createVectorContext,
+  isVectorContext
+} from "../chunk-DBSCKTUL.js";
 import "../chunk-YK4WAAS4.js";
-import "../chunk-6WGGTJE6.js";
-import "../chunk-R2LJSQUW.js";
-import "../chunk-5XKDW36Z.js";
-import "../chunk-DZ3CKYTH.js";
-import "../chunk-I6G7BC42.js";
-import "../chunk-M3IOWB4Y.js";
-import "../chunk-RFDVKCIE.js";
-import "../chunk-ADH7NNCS.js";
-import "../chunk-A3UBYTJT.js";
-import "../chunk-FNQB2JEH.js";
+import "../chunk-EINTGEGY.js";
+import "../chunk-CQNNSZPG.js";
+import "../chunk-D37WMSP6.js";
+import "../chunk-77AIYARB.js";
+import "../chunk-OJH6HWHX.js";
+import "../chunk-CWM7B2OO.js";
+import "../chunk-FMHLROPQ.js";
+import "../chunk-MGNTXGTX.js";
+import "../chunk-KR3RCCHJ.js";
+import "../chunk-TIZYTPJO.js";
+import "../chunk-KIDGIJM7.js";
+import "../chunk-FN7HLLAZ.js";
 export {
   Agent,
+  AgentRunBlockedError,
   AgentRunCancelledError,
   MaxTurnsError,
-  createContextIndex,
-  isContextIndex
+  createVectorContext,
+  isVectorContext
 };
 //# sourceMappingURL=index.js.map