@arcote.tech/arc-ai 0.5.1 → 0.5.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-ai",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.5.5",
   "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.5.1",
-    "@arcote.tech/arc-auth": "^0.5.1",
+    "@arcote.tech/arc": "^0.5.5",
+    "@arcote.tech/arc-auth": "^0.5.5",
     "typescript": "^5.0.0"
   },
   "devDependencies": {

package/src/aggregates/credit-ledger.ts

@@ -0,0 +1,178 @@
+/// <reference path="../arc.d.ts" />
+import {
+  aggregate,
+  context,
+  id,
+  number,
+  string,
+  type ArcId,
+} from "@arcote.tech/arc";
+import type { Token } from "@arcote.tech/arc-auth";
+
+// ─── ID ──────────────────────────────────────────────────────────
+
+export const createLedgerId = <const Name extends string>(data: {
+  name: Name;
+}) => id(`${data.name}Ledger`);
+
+// ─── Factory ────────────────────────────────────────────────────
+
+export function creditLedger(config: {
+  name: string;
+  scopeId: ArcId<any>;
+  accountId: ArcId<any>;
+  protectBy: Token;
+}) {
+  const { name, scopeId, protectBy } = config;
+  const ledgerId = createLedgerId({ name });
+
+  const Ledger = aggregate(`${name}Ledger`, ledgerId, {
+    scopeId,
+    balance: number(),
+    totalCredited: number(),
+    totalDebited: number(),
+  })
+
+    // ─── credited — top up balance ──────────────────────────────
+    .publicEvent(
+      "credited",
+      {
+        ledgerId,
+        scopeId,
+        amount: number(),
+        reason: string(),
+        metadata: string().optional(),
+      },
+      async (ctx, event) => {
+        const p = event.payload;
+        const existing = await ctx.findOne({ scopeId: p.scopeId });
+
+        if (existing) {
+          await ctx.set(existing._id, {
+            ...existing,
+            balance: (existing.balance ?? 0) + p.amount,
+            totalCredited: (existing.totalCredited ?? 0) + p.amount,
+          });
+        } else {
+          await ctx.set(p.ledgerId, {
+            scopeId: p.scopeId,
+            balance: p.amount,
+            totalCredited: p.amount,
+            totalDebited: 0,
+          });
+        }
+      },
+    )
+
+    // ─── debited — deduct from balance ──────────────────────────
+    .publicEvent(
+      "debited",
+      {
+        ledgerId,
+        scopeId,
+        amount: number(),
+        reason: string(),
+        model: string().optional(),
+        metadata: string().optional(),
+      },
+      async (ctx, event) => {
+        const p = event.payload;
+        const existing = await ctx.findOne({ scopeId: p.scopeId });
+
+        if (existing) {
+          await ctx.set(existing._id, {
+            ...existing,
+            balance: (existing.balance ?? 0) - p.amount,
+            totalDebited: (existing.totalDebited ?? 0) + p.amount,
+          });
+        } else {
+          await ctx.set(p.ledgerId, {
+            scopeId: p.scopeId,
+            balance: -p.amount,
+            totalCredited: 0,
+            totalDebited: p.amount,
+          });
+        }
+      },
+    )
+
+    // ─── topUp — add credits ────────────────────────────────────
+    .mutateMethod(
+      "topUp",
+      (fn) => fn.withParams({
+        scopeId,
+        amount: number(),
+        reason: string(),
+        metadata: string().optional(),
+      }).handle(
+        ONLY_SERVER &&
+        (async (ctx, params) => {
+          const entryId = ledgerId.generate();
+          await ctx.credited.emit({
+            ledgerId: entryId,
+            scopeId: params.scopeId,
+            amount: params.amount,
+            reason: params.reason,
+            metadata: params.metadata,
+          });
+          return { ok: true };
+        }),
+      ),
+    )
+
+    // ─── deduct — remove credits ────────────────────────────────
+    .mutateMethod(
+      "deduct",
+      (fn) => fn.withParams({
+        scopeId,
+        amount: number(),
+        reason: string(),
+        model: string().optional(),
+        metadata: string().optional(),
+      }).handle(
+        ONLY_SERVER &&
+        (async (ctx, params) => {
+          const entryId = ledgerId.generate();
+          await ctx.debited.emit({
+            ledgerId: entryId,
+            scopeId: params.scopeId,
+            amount: params.amount,
+            reason: params.reason,
+            model: params.model,
+            metadata: params.metadata,
+          });
+          return { ok: true };
+        }),
+      ),
+    )
+
+    // ─── checkBalance — query current balance ───────────────────
+    .clientQuery(
+      "checkBalance",
+      (fn) => fn
+        .withParams({ scopeId: string() })
+        .handle(async (ctx, params) => {
+          const entry = await ctx.$query.findOne({ scopeId: params.scopeId });
+          const balance = entry?.balance ?? 0;
+          return {
+            balance,
+            canUse: balance > 0,
+            totalCredited: entry?.totalCredited ?? 0,
+            totalDebited: entry?.totalDebited ?? 0,
+          };
+        }),
+    )
+
+    .protectBy(protectBy, (p: any) => ({ scopeId: p.workspaceId ?? p.accountId }));
+
+  const elements = [Ledger];
+
+  return {
+    context: context(elements),
+    elements,
+    ledgerId,
+    Ledger,
+  };
+}
+
+export type CreditLedgerConfig = ReturnType<typeof creditLedger>;

package/src/ai-builder.ts

@@ -1,54 +1,37 @@
 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 type { LLMProvider, PricingConfig } from "./types";
+import type { CreditLedgerConfig } from "./aggregates/credit-ledger";
+import type { BillingStrategy } from "./billing/types";
+import { wrapProviderWithBilling } from "./billing/wrap-provider";
+import type { LLMProvider } from "./types";
 
 export function ai(config: {
   name: string;
   accountId: AccountId;
   userToken: Token;
   providers: LLMProvider[];
-  pricing?: Record<string, PricingConfig>;
+  billing?: {
+    ledger: CreditLedgerConfig;
+    strategy: BillingStrategy;
+  };
 }) {
-  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 Budget = createBudgetAggregate({
-    name: config.name,
-    budgetId,
-    accountId: config.accountId,
-    userToken: config.userToken,
-    CompletionAggregate: Completion,
-  });
+  const elements: ArcContextElement<any>[] = [];
 
-  const elements: ArcContextElement<any>[] = [Completion, Budget];
+  if (config.billing) {
+    elements.push(...config.billing.ledger.elements);
+  }
 
   return {
     context: context(elements),
     elements,
-    completionId,
-    budgetId,
-    Completion,
-    Budget,
     providers: config.providers,
-    resolveProvider: (model: string) =>
-      config.providers.find((p) => p.models.includes(model)),
+    billing: config.billing,
+    resolveProvider: (model: string, scopeId?: string): LLMProvider | undefined => {
+      const provider = config.providers.find((p) => p.models.includes(model));
+      if (!provider) return undefined;
+      if (!config.billing || !scopeId) return provider;
+      return wrapProviderWithBilling(provider, config.billing, scopeId);
+    },
   };
 }
 

package/src/billing/index.ts

@@ -0,0 +1,5 @@
+export type { BillingStrategy, AdapterPricing } from "./types";
+export { fixedMarkupStrategy } from "./strategies/fixed-markup";
+export { flatRateStrategy } from "./strategies/flat-rate";
+export { tokenPassStrategy } from "./strategies/token-pass";
+export { wrapProviderWithBilling } from "./wrap-provider";

package/src/billing/strategies/fixed-markup.ts

@@ -0,0 +1,32 @@
+import type { BillingStrategy, AdapterPricing } from "../types";
+import type { TokenUsage } from "../../types";
+
+export function fixedMarkupStrategy(config: {
+  multiplier: number;
+}): BillingStrategy {
+  const { multiplier } = config;
+
+  return {
+    name: "fixedMarkup",
+
+    calculateCost({ usage, adapterPricing }) {
+      if (!adapterPricing) return 0;
+
+      const inputCost = (usage.inputTokens / 1_000_000) * adapterPricing.inputPer1M;
+      const outputCost = (usage.outputTokens / 1_000_000) * adapterPricing.outputPer1M;
+      const cachedCost = adapterPricing.cachedInputPer1M
+        ? (usage.cachedTokens / 1_000_000) * adapterPricing.cachedInputPer1M
+        : 0;
+      const reasoningCost = adapterPricing.reasoningPer1M
+        ? (usage.reasoningTokens / 1_000_000) * adapterPricing.reasoningPer1M
+        : 0;
+
+      const baseCost = inputCost + outputCost + cachedCost + reasoningCost;
+      return Math.round(baseCost * multiplier * 100) / 100;
+    },
+
+    canExecute(balance) {
+      return balance > 0;
+    },
+  };
+}

package/src/billing/strategies/flat-rate.ts

@@ -0,0 +1,19 @@
+import type { BillingStrategy } from "../types";
+
+export function flatRateStrategy(config: {
+  creditsPerRequest: number;
+}): BillingStrategy {
+  const { creditsPerRequest } = config;
+
+  return {
+    name: "flatRate",
+
+    calculateCost() {
+      return creditsPerRequest;
+    },
+
+    canExecute(balance) {
+      return balance > 0;
+    },
+  };
+}

package/src/billing/strategies/index.ts

@@ -0,0 +1,3 @@
+export { fixedMarkupStrategy } from "./fixed-markup";
+export { flatRateStrategy } from "./flat-rate";
+export { tokenPassStrategy } from "./token-pass";

package/src/billing/strategies/token-pass.ts

@@ -0,0 +1,15 @@
+import type { BillingStrategy } from "../types";
+
+export function tokenPassStrategy(): BillingStrategy {
+  return {
+    name: "tokenPass",
+
+    calculateCost({ usage }) {
+      return usage.totalTokens;
+    },
+
+    canExecute(balance) {
+      return balance > 0;
+    },
+  };
+}

package/src/billing/types.ts

@@ -0,0 +1,24 @@
+import type { TokenUsage } from "../types";
+
+// ─── Adapter Pricing ────────────────────────────────────────────
+
+export interface AdapterPricing {
+  inputPer1M: number;
+  outputPer1M: number;
+  cachedInputPer1M?: number;
+  reasoningPer1M?: number;
+}
+
+// ─── Billing Strategy ───────────────────────────────────────────
+
+export interface BillingStrategy {
+  readonly name: string;
+
+  calculateCost(params: {
+    model: string;
+    usage: TokenUsage;
+    adapterPricing?: AdapterPricing;
+  }): number;
+
+  canExecute(balance: number): boolean;
+}

package/src/billing/wrap-provider.ts

@@ -0,0 +1,52 @@
+import type { LLMProvider, CompletionRequest, CompletionResult, StreamChunk } from "../types";
+import type { CreditLedgerConfig } from "../aggregates/credit-ledger";
+import type { BillingStrategy } from "./types";
+
+export function wrapProviderWithBilling(
+  provider: LLMProvider,
+  billing: { ledger: CreditLedgerConfig; strategy: BillingStrategy },
+  scopeId: string,
+): LLMProvider {
+  const { ledger, strategy } = billing;
+
+  async function checkBalanceOrThrow() {
+    const result = await (ledger.Ledger as any).checkBalance({ scopeId });
+    if (!strategy.canExecute(result?.balance ?? 0)) {
+      throw new Error("Insufficient credits");
+    }
+  }
+
+  async function deductUsage(model: string, usage: any) {
+    const adapterPricing = provider.getPricing?.(model);
+    const cost = strategy.calculateCost({ model, usage, adapterPricing });
+    if (cost > 0) {
+      await (ledger.Ledger as any).deduct({
+        scopeId,
+        amount: cost,
+        reason: `AI: ${model}`,
+        model,
+      });
+    }
+  }
+
+  return {
+    ...provider,
+
+    async complete(request: CompletionRequest): Promise<CompletionResult> {
+      await checkBalanceOrThrow();
+      const result = await provider.complete(request);
+      await deductUsage(request.model, result.usage);
+      return result;
+    },
+
+    async streamComplete(
+      request: CompletionRequest,
+      onChunk: (chunk: StreamChunk) => void,
+    ): Promise<CompletionResult> {
+      await checkBalanceOrThrow();
+      const result = await provider.streamComplete(request, onChunk);
+      await deductUsage(request.model, result.usage);
+      return result;
+    },
+  };
+}

package/src/index.ts

@@ -4,13 +4,20 @@ export type { AIConfig } from "./ai-builder";
 
 // --- Tool helper ---
 export { tool, ArcTool } from "./tool/tool";
-export type { ArcToolAny, JsonSchemaToolDef, ToolContext } from "./tool/tool";
+export type {
+  ArcToolAny,
+  JsonSchemaToolDef,
+  ServerToolViewProps,
+  InteractiveToolViewProps,
+} from "./tool/tool";
+
+// --- Credit Ledger ---
+export { creditLedger } from "./aggregates/credit-ledger";
+export type { CreditLedgerConfig } from "./aggregates/credit-ledger";
 
-// --- 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";
+// --- Billing strategies ---
+export { fixedMarkupStrategy, flatRateStrategy, tokenPassStrategy } from "./billing";
+export type { BillingStrategy, AdapterPricing } from "./billing";
 
 // --- Provider types ---
 export type {
@@ -18,15 +25,20 @@ export type {
   ProviderName,
   CompletionRequest,
   CompletionResult,
+  Conversation,
+  ConversationTurn,
+  UserTurn,
+  AssistantTurn,
+  ToolResultTurn,
+  AssistantContentBlock,
+  TextBlock,
+  ToolCallBlock,
   StreamChunk,
   StreamEventType,
   ChatStreamEvent,
   ChatStreamEventType,
-  Message,
-  MessageRole,
   ToolCall,
   ToolResult,
   TokenUsage,
   FinishReason,
-  PricingConfig,
 } from "./types";