@arcote.tech/arc-ai 0.4.9 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-ai",
   "type": "module",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "private": false,
   "description": "AI provider abstraction, completion tracking, and budget management for Arc framework",
   "main": "./src/index.ts",
@@ -10,8 +10,8 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.4.9",
-    "@arcote.tech/arc-auth": "^0.4.9",
+    "@arcote.tech/arc": "^0.5.0",
+    "@arcote.tech/arc-auth": "^0.5.0",
     "typescript": "^5.0.0"
   },
   "devDependencies": {

package/src/aggregates/budget.ts

@@ -5,10 +5,10 @@ import {
   id,
   number,
   string,
-  type ArcAggregateElement,
   type ArcId,
 } from "@arcote.tech/arc";
 import type { Token } from "@arcote.tech/arc-auth";
+import type { createCompletionAggregate } from "./completion";
 
 // ─── ID ──────────────────────────────────────────────────────────
 
@@ -27,7 +27,7 @@ export type BudgetAggregateData = {
   budgetId: ArcId<any>;
   accountId: ArcId<any>;
   userToken: Token;
-  CompletionAggregate: ArcAggregateElement;
+  CompletionAggregate: ReturnType<typeof createCompletionAggregate>;
 };
 
 export const createBudgetAggregate = <
@@ -102,13 +102,11 @@ export const createBudgetAggregate = <
 
     .mutateMethod(
       "setBudget",
-      {
-        params: {
+      (fn) => fn.withParams({
           budgetType: string(),
           limitCents: number(),
           period: string().optional(),
-        },
-      },
+        }).handle(
       ONLY_SERVER &&
         (async (ctx, params) => {
           const bId = budgetId.generate();
@@ -124,13 +122,13 @@ export const createBudgetAggregate = <
 
           return { budgetId: bId };
         }),
-    )
+    ))
 
     .clientQuery(
       "getByAccount",
-      async (ctx) =>
+      (fn) => fn.handle(async (ctx) =>
         ctx.$query.find({ where: { accountId: ctx.$auth.params.accountId } }),
-    )
+    ))
 
     .protectBy(userToken, (p) => ({ accountId: p.accountId }))
 ;

package/src/aggregates/completion.ts

@@ -150,15 +150,13 @@ export const createCompletionAggregate = <
 
     .mutateMethod(
       "requestCompletion",
-      {
-        params: {
+      (fn) => fn.withParams({
           model: string(),
           messages: string(),
           tools: string().optional(),
           webSearch: string().optional(),
           metadata: string().optional(),
-        },
-      },
+        }).handle(
       ONLY_SERVER &&
         (async (ctx, params) => {
           const provider = resolveProvider(params.model);
@@ -221,14 +219,14 @@ export const createCompletionAggregate = <
             return { error: errorMessage };
           }
         }),
-    )
+    ))
 
-    .clientQuery("getAll", async (ctx) => ctx.$query.find({}))
+    .clientQuery("getAll", (fn) => fn.handle(async (ctx) => ctx.$query.find({})))
     .clientQuery(
       "getByAccount",
-      async (ctx) =>
+      (fn) => fn.handle(async (ctx) =>
         ctx.$query.find({ where: { accountId: ctx.$auth.params.accountId } }),
-    )
+    ))
 
     .protectBy(userToken, (p) => ({ accountId: p.accountId }))
 ;

package/src/ai-builder.ts

@@ -1,52 +1,17 @@
-import {
-  context,
-  type ArcAggregateElement,
-  type ArcContextElement,
-} from "@arcote.tech/arc";
+import { context, type ArcContextElement } from "@arcote.tech/arc";
 import type { AccountId, Token } from "@arcote.tech/arc-auth";
-import { createCompletionId, createCompletionAggregate } from "./aggregates/completion";
-import { createBudgetId, createBudgetAggregate } from "./aggregates/budget";
-import { createStreamCompletionRoute } from "./routes/stream-completion";
+import {
+  createCompletionId,
+  createCompletionAggregate,
+} from "./aggregates/completion";
+import {
+  createBudgetId,
+  createBudgetAggregate,
+} from "./aggregates/budget";
 import type { LLMProvider, PricingConfig } from "./types";
 
-export class AIBuilder<
-  CompId,
-  BudId,
-  Completion extends ArcAggregateElement,
-  Budget extends ArcAggregateElement,
-  Providers extends LLMProvider[],
-  Elements extends ArcContextElement<any>[],
-> {
-  constructor(
-    private readonly _name: string,
-    readonly completionId: CompId,
-    readonly budgetId: BudId,
-    readonly Completion: Completion,
-    readonly Budget: Budget,
-    readonly providers: Providers,
-    readonly elements: Elements,
-  ) {}
-
-  build() {
-    return {
-      context: context(this.elements),
-      completionId: this.completionId,
-      budgetId: this.budgetId,
-      Completion: this.Completion,
-      Budget: this.Budget,
-      providers: this.providers,
-      resolveProvider: (model: string) =>
-        this.providers.find((p) => p.models.includes(model)),
-    };
-  }
-}
-
-export function ai<
-  const Name extends string,
-  const Secret extends string | undefined,
->(config: {
-  name: Name;
-  secret: Secret;
+export function ai(config: {
+  name: string;
   accountId: AccountId;
   userToken: Token;
   providers: LLMProvider[];
@@ -63,7 +28,6 @@ export function ai<
     providers: config.providers,
     pricing: config.pricing,
   });
-  const completionElement = Completion;
 
   const Budget = createBudgetAggregate({
     name: config.name,
@@ -72,25 +36,20 @@ export function ai<
     userToken: config.userToken,
     CompletionAggregate: Completion,
   });
-  const budgetElement = Budget;
-
-  const streamRoute = createStreamCompletionRoute({
-    name: config.name,
-    completionElement,
-    userToken: config.userToken,
-    providers: config.providers,
-    pricing: config.pricing,
-  });
 
-  const elements = [completionElement, budgetElement, streamRoute];
+  const elements: ArcContextElement<any>[] = [Completion, Budget];
 
-  return new AIBuilder(
-    config.name,
+  return {
+    context: context(elements),
+    elements,
     completionId,
     budgetId,
     Completion,
     Budget,
-    config.providers,
-    elements,
-  );
+    providers: config.providers,
+    resolveProvider: (model: string) =>
+      config.providers.find((p) => p.models.includes(model)),
+  };
 }
+
+export type AIConfig = ReturnType<typeof ai>;

package/src/index.ts

@@ -1,9 +1,10 @@
 // --- Builder API ---
-export { ai, AIBuilder } from "./ai-builder";
+export { ai } from "./ai-builder";
+export type { AIConfig } from "./ai-builder";
 
 // --- Tool helper ---
 export { tool, ArcTool } from "./tool/tool";
-export type { ArcToolAny, JsonSchemaToolDef } from "./tool/tool";
+export type { ArcToolAny, JsonSchemaToolDef, ToolContext } from "./tool/tool";
 
 // --- Aggregate factories & types ---
 export { createCompletionAggregate, createCompletionId } from "./aggregates/completion";
@@ -11,9 +12,6 @@ export type { CompletionAggregate, CompletionId } from "./aggregates/completion"
 export { createBudgetAggregate, createBudgetId } from "./aggregates/budget";
 export type { BudgetAggregate, BudgetId } from "./aggregates/budget";
 
-// --- Route ---
-export { createStreamCompletionRoute } from "./routes/stream-completion";
-
 // --- Provider types ---
 export type {
   LLMProvider,
@@ -22,6 +20,8 @@ export type {
   CompletionResult,
   StreamChunk,
   StreamEventType,
+  ChatStreamEvent,
+  ChatStreamEventType,
   Message,
   MessageRole,
   ToolCall,

package/src/routes/stream-completion.ts

@@ -1,6 +1,6 @@
 import { route, type ArcAggregateElement } from "@arcote.tech/arc";
 import type { Token } from "@arcote.tech/arc-auth";
-import type { LLMProvider, PricingConfig, StreamChunk } from "../types";
+import type { LLMProvider, Message, PricingConfig, StreamChunk } from "../types";
 import type { ArcToolAny } from "../tool/tool";
 
 export type StreamCompletionRouteData = {
@@ -30,7 +30,7 @@ export const createStreamCompletionRoute = <
       POST: async (ctx, req) => {
         const body = await req.json() as {
           model: string;
-          messages: { role: string; content: string }[];
+          messages: Message[];
           tools?: { name: string; description: string; parameters: Record<string, unknown> }[];
           webSearch?: boolean;
         };
@@ -57,7 +57,7 @@ export const createStreamCompletionRoute = <
               const result = await provider.streamComplete(
                 {
                   model: body.model,
-                  messages: body.messages as any,
+                  messages: body.messages,
                   tools: body.tools,
                   webSearch: body.webSearch,
                 },

package/src/tool/tool.ts

@@ -1,4 +1,12 @@
-import { object, type ArcRawShape, type $type } from "@arcote.tech/arc";
+import {
+  ArcFunction,
+  defaultFunctionData,
+  object,
+  type ArcRawShape,
+  type $type,
+  type ArcContextElement,
+  type ArcFunctionData,
+} from "@arcote.tech/arc";
 
 // ─── JSON Schema Tool Definition (sent to LLM) ──────────────────
 
@@ -8,6 +16,14 @@ export interface JsonSchemaToolDef {
   parameters: Record<string, unknown>;
 }
 
+// ─── Tool Context (passed to handle) ────────────────────────────
+
+export interface ToolContext {
+  mutate: (element: ArcContextElement<any>) => any;
+  query: (element: ArcContextElement<any>) => any;
+  identifyBy: string;
+}
+
 // ─── ArcTool ─────────────────────────────────────────────────────
 
 export class ArcTool<
@@ -15,55 +31,84 @@ export class ArcTool<
   const S extends ArcRawShape = ArcRawShape,
 > {
   readonly name: Name;
-  #description: string = "";
-  #schema?: S;
-  #handler?: (params: $type<ReturnType<typeof object<S>>>) => Promise<string>;
+  #fn: ArcFunction<any>;
+  #handler?: (ctx: ToolContext, params: $type<ReturnType<typeof object<S>>>) => Promise<string>;
 
-  constructor(name: Name) {
+  constructor(name: Name, fn?: ArcFunction<any>) {
     this.name = name;
+    this.#fn = fn ?? new ArcFunction(defaultFunctionData);
   }
 
   description<const D extends string>(desc: D) {
-    this.#description = desc;
-    return this;
+    const next = new ArcTool<Name, S>(this.name, this.#fn.description(desc));
+    next.#handler = this.#handler;
+    return next;
   }
 
   schema<const NewS extends ArcRawShape>(shape: NewS) {
-    const next = new ArcTool<Name, NewS>(this.name);
-    next.#description = this.#description;
-    next.#schema = shape;
+    const next = new ArcTool<Name, NewS>(this.name, this.#fn.withParams(shape));
     return next;
   }
 
-  handle(handler: (params: $type<ReturnType<typeof object<S>>>) => Promise<string>) {
-    this.#handler = handler;
-    return this;
+  mutate(elements: ArcContextElement<any>[]) {
+    const next = new ArcTool<Name, S>(this.name, this.#fn.mutate(elements));
+    next.#handler = this.#handler;
+    return next;
   }
 
-  /**
-   * Convert Arc schema to JSON Schema for LLM tool definition
-   */
-  toJsonSchema(): JsonSchemaToolDef {
-    const parametersSchema = this.#schema
-      ? object(this.#schema).toJsonSchema()
-      : { type: "object", properties: {} };
+  handle(handler: (ctx: ToolContext, params: $type<ReturnType<typeof object<S>>>) => Promise<string>) {
+    const next = new ArcTool<Name, S>(this.name, this.#fn);
+    next.#handler = handler;
+    return next;
+  }
+
+  get hasHandler(): boolean {
+    return !!this.#handler;
+  }
 
+  get isServerTool(): boolean {
+    return this.hasHandler;
+  }
+
+  get isClientTool(): boolean {
+    return !this.hasHandler;
+  }
+
+  get mutationElements(): ArcContextElement<any>[] {
+    return this.#fn.data.mutationElements || [];
+  }
+
+  toJsonSchema(): JsonSchemaToolDef {
+    const fnSchema = this.#fn.toJsonSchema();
     return {
       name: this.name,
-      description: this.#description,
-      parameters: parametersSchema,
+      description: (this.#fn.data.description as string) || "",
+      parameters: fnSchema.params ?? { type: "object", properties: {} },
     };
   }
 
-  /**
-   * Execute the tool handler
-   */
-  async execute(params: Record<string, unknown>): Promise<string> {
+  async executeWithContext(params: Record<string, unknown>, ctx: ToolContext): Promise<string> {
     if (!this.#handler) {
       throw new Error(`Tool "${this.name}" has no handler`);
     }
+    return this.#handler(ctx, params as $type<ReturnType<typeof object<S>>>);
+  }
 
-    return this.#handler(params as any);
+  async execute(params: Record<string, unknown>): Promise<string> {
+    if (!this.#handler) {
+      throw new Error(`Tool "${this.name}" has no handler`);
+    }
+    if (this.mutationElements.length > 0) {
+      throw new Error(
+        `Tool "${this.name}" has mutation dependencies — use executeWithContext() instead`,
+      );
+    }
+    const emptyCtx: ToolContext = {
+      mutate: () => { throw new Error("No mutation context available"); },
+      query: () => { throw new Error("No query context available"); },
+      identifyBy: "",
+    };
+    return this.#handler(emptyCtx, params as $type<ReturnType<typeof object<S>>>);
   }
 }
 

package/src/types.ts

@@ -51,6 +51,7 @@ export interface CompletionRequest {
   webSearch?: boolean;
   temperature?: number;
   maxTokens?: number;
+  previousResponseId?: string;
 }
 
 export interface CompletionResult {
@@ -58,6 +59,7 @@ export interface CompletionResult {
   toolCalls: ToolCall[];
   usage: TokenUsage;
   finishReason: FinishReason;
+  responseId?: string;
 }
 
 // ─── Streaming ───────────────────────────────────────────────────
@@ -92,6 +94,30 @@ export interface LLMProvider {
   ): Promise<CompletionResult>;
 }
 
+// ─── Chat Stream (SSE events for chat streaming) ────────────────
+
+export type ChatStreamEventType =
+  | "content_delta"
+  | "server_tool_start"
+  | "server_tool_result"
+  | "client_tool_request"
+  | "usage_update"
+  | "done"
+  | "error";
+
+export interface ChatStreamEvent {
+  type: ChatStreamEventType;
+  sessionId: string;
+  content?: string;
+  toolCall?: ToolCall;
+  toolResult?: ToolResult;
+  toolCalls?: ToolCall[];
+  usage?: TokenUsage;
+  finishReason?: FinishReason;
+  executionCount?: number;
+  error?: string;
+}
+
 // ─── Pricing ─────────────────────────────────────────────────────
 
 export interface PricingConfig {