@antseed/node 0.1.0

package/src/metering/token-counter.ts

@@ -0,0 +1,127 @@
+import type { ProviderType, TokenCount } from '../types/metering.js';
+
+/**
+ * Provider-specific bytes-to-token ratios.
+ *
+ * These are empirical averages. The actual ratio depends on the
+ * tokenizer and content, but for billing estimates they are
+ * sufficiently accurate (typically within 10-15%).
+ *
+ * Rationale:
+ * - English text averages ~4 bytes per token across most tokenizers
+ * - JSON overhead (keys, brackets, quotes) increases the ratio
+ * - Request bodies include system prompts, tool definitions, etc.
+ * - Response bodies include JSON wrapping around the actual content
+ */
+export const BYTES_PER_TOKEN: Record<string, number> = {
+  anthropic: 4.2,   // Claude tokenizer, JSON Messages API
+  openai: 4.0,      // tiktoken cl100k_base, JSON Chat API
+  google: 4.1,      // Gemini tokenizer, JSON generateContent API
+  moonshot: 4.0,    // Similar to OpenAI tokenizer
+  default: 4.0,     // Fallback for unknown providers
+};
+
+/**
+ * Minimum token estimate when Content-Length is missing or zero.
+ * LLM API requests always have some tokens (at least a system prompt).
+ */
+export const MIN_REQUEST_TOKENS = 100;
+export const MIN_RESPONSE_TOKENS = 10;
+
+/**
+ * Estimate token count from HTTP Content-Length header value.
+ *
+ * @param contentLength - Value of Content-Length header (bytes), or null if absent
+ * @param provider - Provider type for selecting bytes-per-token ratio
+ * @param direction - Whether this is a request (input) or response (output)
+ * @returns Estimated token count
+ */
+export function estimateTokensFromContentLength(
+  contentLength: number | null,
+  provider: ProviderType,
+  direction: 'request' | 'response'
+): number {
+  if (contentLength === null || contentLength === 0) {
+    return direction === 'request' ? MIN_REQUEST_TOKENS : MIN_RESPONSE_TOKENS;
+  }
+
+  const ratio = BYTES_PER_TOKEN[provider] ?? BYTES_PER_TOKEN['default']!;
+  return Math.max(
+    Math.ceil(contentLength / ratio),
+    direction === 'request' ? MIN_REQUEST_TOKENS : MIN_RESPONSE_TOKENS
+  );
+}
+
+/**
+ * Estimate token count from accumulated SSE stream chunk sizes.
+ * Used when Content-Length is not available (streaming responses).
+ *
+ * @param totalBytes - Total bytes received across all SSE chunks
+ * @param provider - Provider type
+ * @returns Estimated token count
+ */
+export function estimateTokensFromStreamBytes(
+  totalBytes: number,
+  provider: ProviderType
+): number {
+  if (totalBytes === 0) return MIN_RESPONSE_TOKENS;
+
+  const ratio = BYTES_PER_TOKEN[provider] ?? BYTES_PER_TOKEN['default']!;
+  // SSE streams have additional overhead: "data: " prefix, newlines, event framing
+  // Approximately 15-20% of stream bytes are SSE overhead, not content
+  const contentBytes = totalBytes * 0.82;
+  return Math.max(Math.ceil(contentBytes / ratio), MIN_RESPONSE_TOKENS);
+}
+
+/**
+ * Build a complete TokenCount from request and response metadata.
+ *
+ * @param requestContentLength - Request Content-Length header value (bytes), or null
+ * @param responseContentLength - Response Content-Length header value (bytes), or null
+ * @param provider - Provider type
+ * @param isStreaming - Whether the response was an SSE stream
+ * @param streamTotalBytes - Total bytes from stream chunks (only if isStreaming)
+ */
+export function estimateTokens(
+  requestContentLength: number | null,
+  responseContentLength: number | null,
+  provider: ProviderType,
+  isStreaming: boolean,
+  streamTotalBytes?: number
+): TokenCount {
+  const inputTokens = estimateTokensFromContentLength(
+    requestContentLength,
+    provider,
+    'request'
+  );
+
+  let outputTokens: number;
+  let method: TokenCount['method'];
+  let confidence: TokenCount['confidence'];
+
+  if (isStreaming && streamTotalBytes !== undefined) {
+    outputTokens = estimateTokensFromStreamBytes(streamTotalBytes, provider);
+    method = 'chunk-accumulation';
+    confidence = 'medium';
+  } else if (responseContentLength !== null && responseContentLength > 0) {
+    outputTokens = estimateTokensFromContentLength(
+      responseContentLength,
+      provider,
+      'response'
+    );
+    method = 'content-length';
+    confidence = 'high';
+  } else {
+    outputTokens = MIN_RESPONSE_TOKENS;
+    method = 'fallback';
+    confidence = 'low';
+  }
+
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    method,
+    confidence,
+  };
+}

package/src/metering/usage-aggregator.ts

@@ -0,0 +1,236 @@
+import type { UsageAggregate, SessionMetrics, ProviderType } from '../types/metering.js';
+
+export type AggregationGranularity = 'daily' | 'weekly' | 'monthly';
+
+/**
+ * Time period boundaries for aggregation.
+ */
+export interface TimePeriod {
+  start: number; // ms since epoch
+  end: number;   // ms since epoch
+}
+
+/**
+ * Aggregates session metrics into time-period summaries.
+ */
+export class UsageAggregator {
+  /**
+   * Aggregate a list of session metrics into time-period buckets.
+   *
+   * @param sessions - Session metrics to aggregate
+   * @param granularity - Time period granularity
+   * @param topPeerCount - Number of top peers to include (default: 5)
+   * @returns Array of UsageAggregate, one per period that has data
+   */
+  aggregate(
+    sessions: SessionMetrics[],
+    granularity: AggregationGranularity,
+    topPeerCount: number = 5
+  ): UsageAggregate[] {
+    if (sessions.length === 0) return [];
+
+    // Group sessions by period
+    const buckets = new Map<string, SessionMetrics[]>();
+
+    for (const session of sessions) {
+      const period = this.getPeriod(session.startedAt, granularity);
+      const key = `${period.start}`;
+      const bucket = buckets.get(key);
+      if (bucket) {
+        bucket.push(session);
+      } else {
+        buckets.set(key, [session]);
+      }
+    }
+
+    // Build aggregates
+    const aggregates: UsageAggregate[] = [];
+
+    for (const [_key, bucketSessions] of buckets) {
+      const period = this.getPeriod(bucketSessions[0]!.startedAt, granularity);
+      aggregates.push(this.buildAggregate(bucketSessions, period, granularity, topPeerCount));
+    }
+
+    // Sort by period start
+    aggregates.sort((a, b) => a.periodStart - b.periodStart);
+
+    return aggregates;
+  }
+
+  /**
+   * Get the time period that a timestamp falls into.
+   */
+  getPeriod(timestamp: number, granularity: AggregationGranularity): TimePeriod {
+    const date = new Date(timestamp);
+
+    switch (granularity) {
+      case 'daily': {
+        const start = new Date(Date.UTC(
+          date.getUTCFullYear(),
+          date.getUTCMonth(),
+          date.getUTCDate()
+        ));
+        const end = new Date(Date.UTC(
+          date.getUTCFullYear(),
+          date.getUTCMonth(),
+          date.getUTCDate() + 1
+        ));
+        return { start: start.getTime(), end: end.getTime() };
+      }
+      case 'weekly': {
+        // Monday 00:00 UTC to next Monday 00:00 UTC
+        const dayOfWeek = date.getUTCDay();
+        // getUTCDay() returns 0 for Sunday, 1 for Monday, etc.
+        // We want Monday as the start, so offset: Monday=0, Tue=1, ..., Sun=6
+        const daysFromMonday = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+        const monday = new Date(Date.UTC(
+          date.getUTCFullYear(),
+          date.getUTCMonth(),
+          date.getUTCDate() - daysFromMonday
+        ));
+        const nextMonday = new Date(monday.getTime() + 7 * 24 * 60 * 60 * 1000);
+        return { start: monday.getTime(), end: nextMonday.getTime() };
+      }
+      case 'monthly': {
+        const start = new Date(Date.UTC(
+          date.getUTCFullYear(),
+          date.getUTCMonth(),
+          1
+        ));
+        const end = new Date(Date.UTC(
+          date.getUTCFullYear(),
+          date.getUTCMonth() + 1,
+          1
+        ));
+        return { start: start.getTime(), end: end.getTime() };
+      }
+    }
+  }
+
+  /**
+   * Get aggregates for a specific date range.
+   *
+   * @param sessions - All available session metrics
+   * @param startDate - Start of range (ms since epoch)
+   * @param endDate - End of range (ms since epoch)
+   * @param granularity - Bucket granularity
+   * @param topPeerCount - Number of top peers to include (default: 5)
+   */
+  aggregateRange(
+    sessions: SessionMetrics[],
+    startDate: number,
+    endDate: number,
+    granularity: AggregationGranularity,
+    topPeerCount: number = 5
+  ): UsageAggregate[] {
+    const filtered = sessions.filter(
+      (s) => s.startedAt >= startDate && s.startedAt < endDate
+    );
+    return this.aggregate(filtered, granularity, topPeerCount);
+  }
+
+  /**
+   * Get a single aggregate for all-time usage.
+   */
+  aggregateAll(sessions: SessionMetrics[]): UsageAggregate {
+    if (sessions.length === 0) {
+      return {
+        periodStart: 0,
+        periodEnd: 0,
+        granularity: 'monthly',
+        totalSessions: 0,
+        totalRequests: 0,
+        totalTokens: 0,
+        totalCostCents: 0,
+        byProvider: {},
+        topPeers: [],
+      };
+    }
+
+    let minStart = Infinity;
+    let maxEnd = -Infinity;
+
+    for (const s of sessions) {
+      if (s.startedAt < minStart) minStart = s.startedAt;
+      const end = s.endedAt ?? s.startedAt;
+      if (end > maxEnd) maxEnd = end;
+    }
+
+    return this.buildAggregate(
+      sessions,
+      { start: minStart, end: maxEnd },
+      'monthly',
+      sessions.length // Include all peers in all-time view
+    );
+  }
+
+  /**
+   * Build a single UsageAggregate from a list of sessions.
+   */
+  private buildAggregate(
+    sessions: SessionMetrics[],
+    period: TimePeriod,
+    granularity: AggregationGranularity,
+    topPeerCount: number
+  ): UsageAggregate {
+    const byProvider: Record<ProviderType, { requests: number; tokens: number; costCents: number }> = {};
+    const peerMap = new Map<string, { requests: number; tokens: number; costCents: number }>();
+
+    let totalRequests = 0;
+    let totalTokens = 0;
+    let totalCostCents = 0;
+
+    for (const session of sessions) {
+      totalRequests += session.totalRequests;
+      totalTokens += session.totalTokens;
+      totalCostCents += session.totalCostCents;
+
+      // Provider breakdown
+      const providerEntry = byProvider[session.provider];
+      if (providerEntry) {
+        providerEntry.requests += session.totalRequests;
+        providerEntry.tokens += session.totalTokens;
+        providerEntry.costCents += session.totalCostCents;
+      } else {
+        byProvider[session.provider] = {
+          requests: session.totalRequests,
+          tokens: session.totalTokens,
+          costCents: session.totalCostCents,
+        };
+      }
+
+      // Peer breakdown (use sellerPeerId as the peer identifier)
+      const peerId = session.sellerPeerId;
+      const peerEntry = peerMap.get(peerId);
+      if (peerEntry) {
+        peerEntry.requests += session.totalRequests;
+        peerEntry.tokens += session.totalTokens;
+        peerEntry.costCents += session.totalCostCents;
+      } else {
+        peerMap.set(peerId, {
+          requests: session.totalRequests,
+          tokens: session.totalTokens,
+          costCents: session.totalCostCents,
+        });
+      }
+    }
+
+    // Sort peers by costCents descending, take top N
+    const topPeers = Array.from(peerMap.entries())
+      .map(([peerId, data]) => ({ peerId, ...data }))
+      .sort((a, b) => b.costCents - a.costCents)
+      .slice(0, topPeerCount);
+
+    return {
+      periodStart: period.start,
+      periodEnd: period.end,
+      granularity,
+      totalSessions: sessions.length,
+      totalRequests,
+      totalTokens,
+      totalCostCents,
+      byProvider,
+      topPeers,
+    };
+  }
+}