@arcote.tech/arc-ai 0.4.6

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@arcote.tech/arc-ai",
+  "type": "module",
+  "version": "0.4.6",
+  "private": false,
+  "description": "AI provider abstraction, completion tracking, and budget management for Arc framework",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "^0.4.6",
+    "@arcote.tech/arc-auth": "^0.4.6",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/aggregates/budget.ts

@@ -0,0 +1,139 @@
+/// <reference path="../arc.d.ts" />
+import {
+  aggregate,
+  boolean,
+  id,
+  number,
+  string,
+  type AggregateConstructorAny,
+  type ArcId,
+} from "@arcote.tech/arc";
+import type { Token } from "@arcote.tech/arc-auth";
+
+// ─── ID ──────────────────────────────────────────────────────────
+
+export const createBudgetId = <const Name extends string>(data: {
+  name: Name;
+}) => id(`${data.name}Budget`);
+
+export type BudgetId<Name extends string = string> = ReturnType<
+  typeof createBudgetId<Name>
+>;
+
+// ─── Aggregate ───────────────────────────────────────────────────
+
+export type BudgetAggregateData = {
+  name: string;
+  budgetId: ArcId<any>;
+  accountId: ArcId<any>;
+  userToken: Token;
+  CompletionAggregate: AggregateConstructorAny;
+};
+
+export const createBudgetAggregate = <
+  const Data extends BudgetAggregateData,
+>(
+  data: Data,
+) => {
+  const { budgetId, accountId, userToken, CompletionAggregate } = data;
+
+  const completionFinishedEvent =
+    CompletionAggregate.getEvent("completionFinished");
+
+  return aggregate(`${data.name}Budgets`, budgetId, {
+    accountId,
+    budgetType: string(),
+    limitCents: number(),
+    usedCents: number(),
+    period: string().optional(),
+    isExceeded: boolean(),
+  })
+    .publicEvent(
+      "budgetSet",
+      {
+        budgetId,
+        accountId,
+        budgetType: string(),
+        limitCents: number(),
+        period: string().optional(),
+      },
+      async (ctx, event) => {
+        const p = event.payload;
+        await ctx.set(p.budgetId, {
+          accountId: p.accountId,
+          budgetType: p.budgetType,
+          limitCents: p.limitCents,
+          usedCents: 0,
+          period: p.period,
+          isExceeded: false,
+        });
+      },
+    )
+
+    .publicEvent(
+      "budgetUsageRecorded",
+      {
+        budgetId,
+        amountCents: number(),
+      },
+      async (ctx, event) => {
+        const existing = await ctx.findOne({ _id: event.payload.budgetId });
+        if (!existing) return;
+
+        const newUsed = existing.usedCents + event.payload.amountCents;
+        await ctx.modify(event.payload.budgetId, {
+          usedCents: newUsed,
+          isExceeded: newUsed >= existing.limitCents,
+        });
+      },
+    )
+
+    .handleEvent(completionFinishedEvent, async (ctx, event) => {
+      // Record usage from completion cost on all matching budgets
+      const budgets = await ctx.find({});
+      for (const budget of budgets) {
+        const newUsed = budget.usedCents + event.payload.costCents;
+        await ctx.modify(budget._id, {
+          usedCents: newUsed,
+          isExceeded: newUsed >= budget.limitCents,
+        });
+      }
+    })
+
+    .mutateMethod(
+      "setBudget",
+      {
+        params: {
+          budgetType: string(),
+          limitCents: number(),
+          period: string().optional(),
+        },
+      },
+      ONLY_SERVER &&
+        (async (ctx, params) => {
+          const bId = budgetId.generate();
+          const aId = ctx.$auth.params.accountId;
+
+          await ctx.budgetSet.emit({
+            budgetId: bId,
+            accountId: accountId.parse(aId),
+            budgetType: params.budgetType,
+            limitCents: params.limitCents,
+            period: params.period,
+          });
+
+          return { budgetId: bId };
+        }),
+    )
+
+    .clientQuery(
+      "getByAccount",
+      async (ctx) =>
+        ctx.$query.find({ where: { accountId: ctx.$auth.params.accountId } }),
+    )
+
+    .protectBy(userToken, (p) => ({ accountId: p.accountId }))
+    .build();
+};
+
+export type BudgetAggregate = ReturnType<typeof createBudgetAggregate>;

package/src/aggregates/completion.ts

@@ -0,0 +1,237 @@
+/// <reference path="../arc.d.ts" />
+import {
+  aggregate,
+  date,
+  id,
+  number,
+  string,
+  type ArcId,
+} from "@arcote.tech/arc";
+import type { Token } from "@arcote.tech/arc-auth";
+import type { LLMProvider, PricingConfig, TokenUsage } from "../types";
+
+// ─── ID ──────────────────────────────────────────────────────────
+
+export const createCompletionId = <const Name extends string>(data: {
+  name: Name;
+}) => id(`${data.name}Completion`);
+
+export type CompletionId<Name extends string = string> = ReturnType<
+  typeof createCompletionId<Name>
+>;
+
+// ─── Aggregate ───────────────────────────────────────────────────
+
+export type CompletionAggregateData = {
+  name: string;
+  completionId: ArcId<any>;
+  accountId: ArcId<any>;
+  userToken: Token;
+  providers: LLMProvider[];
+  pricing?: Record<string, PricingConfig>;
+};
+
+export const createCompletionAggregate = <
+  const Data extends CompletionAggregateData,
+>(
+  data: Data,
+) => {
+  const { completionId, accountId, userToken, providers, pricing } = data;
+
+  function resolveProvider(model: string): LLMProvider | undefined {
+    return providers.find((p) => p.models.includes(model));
+  }
+
+  function calculateCostCents(
+    model: string,
+    usage: TokenUsage,
+  ): number {
+    const config = pricing?.[model];
+    if (!config) return 0;
+
+    const inputCost =
+      (usage.inputTokens / 1_000_000) * config.inputPer1M;
+    const outputCost =
+      (usage.outputTokens / 1_000_000) * config.outputPer1M;
+    const cachedCost = config.cachedInputPer1M
+      ? (usage.cachedTokens / 1_000_000) * config.cachedInputPer1M
+      : 0;
+    const reasoningCost = config.reasoningPer1M
+      ? (usage.reasoningTokens / 1_000_000) * config.reasoningPer1M
+      : 0;
+
+    return Math.round((inputCost + outputCost + cachedCost + reasoningCost) * 100);
+  }
+
+  return aggregate(
+    `${data.name}Completions`,
+    completionId,
+    {
+      accountId,
+      model: string(),
+      provider: string(),
+      status: string(),
+      promptTokens: number(),
+      completionTokens: number(),
+      totalTokens: number(),
+      costCents: number(),
+      finishReason: string().optional(),
+      errorMessage: string().optional(),
+      requestedAt: date(),
+      completedAt: date().optional(),
+      metadata: string().optional(),
+    },
+  )
+    .publicEvent(
+      "completionRequested",
+      {
+        completionId,
+        accountId,
+        model: string(),
+        provider: string(),
+        metadata: string().optional(),
+      },
+      async (ctx, event) => {
+        const { completionId: cId, accountId: aId, model, provider, metadata } =
+          event.payload;
+        await ctx.set(cId, {
+          accountId: aId,
+          model,
+          provider,
+          status: "pending",
+          promptTokens: 0,
+          completionTokens: 0,
+          totalTokens: 0,
+          costCents: 0,
+          requestedAt: event.createdAt,
+          metadata,
+        });
+      },
+    )
+
+    .publicEvent(
+      "completionFinished",
+      {
+        completionId,
+        promptTokens: number(),
+        completionTokens: number(),
+        totalTokens: number(),
+        costCents: number(),
+        finishReason: string(),
+      },
+      async (ctx, event) => {
+        const p = event.payload;
+        await ctx.modify(p.completionId, {
+          status: "completed",
+          promptTokens: p.promptTokens,
+          completionTokens: p.completionTokens,
+          totalTokens: p.totalTokens,
+          costCents: p.costCents,
+          finishReason: p.finishReason,
+          completedAt: event.createdAt,
+        });
+      },
+    )
+
+    .publicEvent(
+      "completionFailed",
+      {
+        completionId,
+        errorMessage: string(),
+      },
+      async (ctx, event) => {
+        await ctx.modify(event.payload.completionId, {
+          status: "error",
+          errorMessage: event.payload.errorMessage,
+          completedAt: event.createdAt,
+        });
+      },
+    )
+
+    .mutateMethod(
+      "requestCompletion",
+      {
+        params: {
+          model: string(),
+          messages: string(),
+          tools: string().optional(),
+          webSearch: string().optional(),
+          metadata: string().optional(),
+        },
+      },
+      ONLY_SERVER &&
+        (async (ctx, params) => {
+          const provider = resolveProvider(params.model);
+          if (!provider) {
+            return { error: "PROVIDER_NOT_FOUND" as const };
+          }
+
+          const cId = completionId.generate();
+          const aId = ctx.$auth.params.accountId;
+
+          await ctx.completionRequested.emit({
+            completionId: cId,
+            accountId: accountId.parse(aId),
+            model: params.model,
+            provider: provider.name,
+            metadata: params.metadata,
+          });
+
+          try {
+            const messages = JSON.parse(params.messages);
+            const webSearch = params.webSearch === "true";
+
+            const toolDefs = params.tools
+              ? JSON.parse(params.tools) as { name: string; description: string; parameters: Record<string, unknown> }[]
+              : undefined;
+
+            const result = await provider.complete({
+              model: params.model,
+              messages,
+              tools: toolDefs,
+              webSearch,
+            });
+
+            const costCents = calculateCostCents(params.model, result.usage);
+
+            await ctx.completionFinished.emit({
+              completionId: cId,
+              promptTokens: result.usage.inputTokens,
+              completionTokens: result.usage.outputTokens,
+              totalTokens: result.usage.totalTokens,
+              costCents,
+              finishReason: result.finishReason,
+            });
+
+            return {
+              completionId: cId,
+              content: result.content,
+              toolCalls: result.toolCalls,
+              finishReason: result.finishReason,
+            };
+          } catch (error) {
+            const errorMessage =
+              error instanceof Error ? error.message : "Unknown error";
+
+            await ctx.completionFailed.emit({
+              completionId: cId,
+              errorMessage,
+            });
+
+            return { error: errorMessage };
+          }
+        }),
+    )
+
+    .clientQuery("getAll", async (ctx) => ctx.$query.find({}))
+    .clientQuery(
+      "getByAccount",
+      async (ctx) =>
+        ctx.$query.find({ where: { accountId: ctx.$auth.params.accountId } }),
+    )
+
+    .protectBy(userToken, (p) => ({ accountId: p.accountId }))
+    .build();
+};
+
+export type CompletionAggregate = ReturnType<typeof createCompletionAggregate>;

package/src/ai-builder.ts

@@ -0,0 +1,97 @@
+import {
+  aggregateContextElement,
+  context,
+  type AggregateConstructorAny,
+  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 type { LLMProvider, PricingConfig } from "./types";
+
+export class AIBuilder<
+  CompId,
+  BudId,
+  Completion extends AggregateConstructorAny,
+  Budget extends AggregateConstructorAny,
+  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;
+  accountId: AccountId;
+  userToken: Token;
+  providers: LLMProvider[];
+  pricing?: Record<string, PricingConfig>;
+}) {
+  const completionId = createCompletionId({ name: config.name });
+  const budgetId = createBudgetId({ name: config.name });
+
+  const Completion = createCompletionAggregate({
+    name: config.name,
+    completionId,
+    accountId: config.accountId,
+    userToken: config.userToken,
+    providers: config.providers,
+    pricing: config.pricing,
+  });
+  const completionElement = aggregateContextElement(Completion);
+
+  const Budget = createBudgetAggregate({
+    name: config.name,
+    budgetId,
+    accountId: config.accountId,
+    userToken: config.userToken,
+    CompletionAggregate: Completion,
+  });
+  const budgetElement = aggregateContextElement(Budget);
+
+  const streamRoute = createStreamCompletionRoute({
+    name: config.name,
+    completionElement,
+    userToken: config.userToken,
+    providers: config.providers,
+    pricing: config.pricing,
+  });
+
+  const elements = [completionElement, budgetElement, streamRoute];
+
+  return new AIBuilder(
+    config.name,
+    completionId,
+    budgetId,
+    Completion,
+    Budget,
+    config.providers,
+    elements,
+  );
+}

package/src/arc.d.ts

@@ -0,0 +1,6 @@
+declare const BROWSER: boolean;
+declare const NOT_ON_BROWSER: boolean;
+declare const ONLY_BROWSER: boolean;
+declare const SERVER: boolean;
+declare const NOT_ON_SERVER: boolean;
+declare const ONLY_SERVER: boolean;

package/src/index.ts

@@ -0,0 +1,32 @@
+// --- Builder API ---
+export { ai, AIBuilder } from "./ai-builder";
+
+// --- Tool helper ---
+export { tool, ArcTool } from "./tool/tool";
+export type { ArcToolAny, JsonSchemaToolDef } from "./tool/tool";
+
+// --- Aggregate factories & types ---
+export { createCompletionAggregate, createCompletionId } from "./aggregates/completion";
+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,
+  ProviderName,
+  CompletionRequest,
+  CompletionResult,
+  StreamChunk,
+  StreamEventType,
+  Message,
+  MessageRole,
+  ToolCall,
+  ToolResult,
+  TokenUsage,
+  FinishReason,
+  PricingConfig,
+} from "./types";

package/src/routes/stream-completion.ts

@@ -0,0 +1,94 @@
+import { route, type ArcAggregateElement, type AggregateConstructorAny } from "@arcote.tech/arc";
+import type { Token } from "@arcote.tech/arc-auth";
+import type { LLMProvider, PricingConfig, StreamChunk } from "../types";
+import type { ArcToolAny } from "../tool/tool";
+
+export type StreamCompletionRouteData = {
+  name: string;
+  completionElement: ArcAggregateElement<AggregateConstructorAny>;
+  userToken: Token;
+  providers: LLMProvider[];
+  pricing?: Record<string, PricingConfig>;
+};
+
+export const createStreamCompletionRoute = <
+  const Data extends StreamCompletionRouteData,
+>(
+  data: Data,
+) => {
+  const { completionElement, userToken, providers, pricing } = data;
+
+  function resolveProvider(model: string): LLMProvider | undefined {
+    return providers.find((p) => p.models.includes(model));
+  }
+
+  return route(`${data.name}AiStream`)
+    .path(`/ai/${data.name}/stream/:completionId`)
+    .protectBy(userToken, () => true)
+    .mutate([completionElement])
+    .handle({
+      POST: async (ctx, req) => {
+        const body = await req.json() as {
+          model: string;
+          messages: { role: string; content: string }[];
+          tools?: { name: string; description: string; parameters: Record<string, unknown> }[];
+          webSearch?: boolean;
+        };
+
+        const provider = resolveProvider(body.model);
+        if (!provider) {
+          return new Response(
+            JSON.stringify({ error: "PROVIDER_NOT_FOUND" }),
+            { status: 400, headers: { "Content-Type": "application/json" } },
+          );
+        }
+
+        const encoder = new TextEncoder();
+
+        const stream = new ReadableStream({
+          async start(controller) {
+            const sendEvent = (chunk: StreamChunk) => {
+              controller.enqueue(
+                encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`),
+              );
+            };
+
+            try {
+              const result = await provider.streamComplete(
+                {
+                  model: body.model,
+                  messages: body.messages as any,
+                  tools: body.tools,
+                  webSearch: body.webSearch,
+                },
+                sendEvent,
+              );
+
+              // Send final done event with usage
+              sendEvent({
+                type: "done",
+                usage: result.usage,
+                finishReason: result.finishReason,
+              });
+            } catch (error) {
+              sendEvent({
+                type: "error",
+                content:
+                  error instanceof Error ? error.message : "Unknown error",
+              });
+            } finally {
+              controller.close();
+            }
+          },
+        });
+
+        return new Response(stream, {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+          },
+        });
+      },
+    });
+};

package/src/tool/tool.ts

@@ -0,0 +1,76 @@
+import { object, type ArcRawShape, type $type } from "@arcote.tech/arc";
+
+// ─── JSON Schema Tool Definition (sent to LLM) ──────────────────
+
+export interface JsonSchemaToolDef {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+// ─── ArcTool ─────────────────────────────────────────────────────
+
+export class ArcTool<
+  const Name extends string = string,
+  const S extends ArcRawShape = ArcRawShape,
+> {
+  readonly name: Name;
+  #description: string = "";
+  #schema?: S;
+  #handler?: (params: $type<ReturnType<typeof object<S>>>) => Promise<string>;
+
+  constructor(name: Name) {
+    this.name = name;
+  }
+
+  description<const D extends string>(desc: D) {
+    this.#description = desc;
+    return this;
+  }
+
+  schema<const NewS extends ArcRawShape>(shape: NewS) {
+    const next = new ArcTool<Name, NewS>(this.name);
+    next.#description = this.#description;
+    next.#schema = shape;
+    return next;
+  }
+
+  handle(handler: (params: $type<ReturnType<typeof object<S>>>) => Promise<string>) {
+    this.#handler = handler;
+    return this;
+  }
+
+  /**
+   * Convert Arc schema to JSON Schema for LLM tool definition
+   */
+  toJsonSchema(): JsonSchemaToolDef {
+    const parametersSchema = this.#schema
+      ? object(this.#schema).toJsonSchema()
+      : { type: "object", properties: {} };
+
+    return {
+      name: this.name,
+      description: this.#description,
+      parameters: parametersSchema,
+    };
+  }
+
+  /**
+   * Execute the tool handler
+   */
+  async execute(params: Record<string, unknown>): Promise<string> {
+    if (!this.#handler) {
+      throw new Error(`Tool "${this.name}" has no handler`);
+    }
+
+    return this.#handler(params as any);
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────
+
+export function tool<const Name extends string>(name: Name) {
+  return new ArcTool(name);
+}
+
+export type ArcToolAny = ArcTool<string, ArcRawShape>;

package/src/types.ts

@@ -0,0 +1,102 @@
+import type { JsonSchemaToolDef } from "./tool/tool";
+
+// ─── Provider Names ──────────────────────────────────────────────
+
+export type ProviderName = "openai" | "gemini" | "claude";
+
+// ─── Messages ────────────────────────────────────────────────────
+
+export type MessageRole = "system" | "user" | "assistant" | "tool";
+
+export interface Message {
+  role: MessageRole;
+  content: string;
+  name?: string;
+  toolCallId?: string;
+}
+
+// ─── Tool Calls ──────────────────────────────────────────────────
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface ToolResult {
+  toolCallId: string;
+  name: string;
+  content: string;
+  isError: boolean;
+}
+
+// ─── Token Usage ─────────────────────────────────────────────────
+
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cachedTokens: number;
+  reasoningTokens: number;
+}
+
+// ─── Completion ──────────────────────────────────────────────────
+
+export type FinishReason = "stop" | "tool_call" | "max_tokens" | "error";
+
+export interface CompletionRequest {
+  model: string;
+  messages: Message[];
+  tools?: JsonSchemaToolDef[];
+  webSearch?: boolean;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface CompletionResult {
+  content: string;
+  toolCalls: ToolCall[];
+  usage: TokenUsage;
+  finishReason: FinishReason;
+}
+
+// ─── Streaming ───────────────────────────────────────────────────
+
+export type StreamEventType =
+  | "content_delta"
+  | "tool_call_start"
+  | "tool_call_delta"
+  | "tool_result"
+  | "usage_update"
+  | "done"
+  | "error";
+
+export interface StreamChunk {
+  type: StreamEventType;
+  content?: string;
+  toolCall?: ToolCall;
+  toolResult?: ToolResult;
+  usage?: TokenUsage;
+  finishReason?: FinishReason;
+}
+
+// ─── LLM Provider ────────────────────────────────────────────────
+
+export interface LLMProvider {
+  name: ProviderName;
+  models: string[];
+  complete(request: CompletionRequest): Promise<CompletionResult>;
+  streamComplete(
+    request: CompletionRequest,
+    onChunk: (chunk: StreamChunk) => void,
+  ): Promise<CompletionResult>;
+}
+
+// ─── Pricing ─────────────────────────────────────────────────────
+
+export interface PricingConfig {
+  inputPer1M: number;
+  outputPer1M: number;
+  cachedInputPer1M?: number;
+  reasoningPer1M?: number;
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "include": ["src/**/*"]
+}