@gugacoder/agentic-sdk 0.2.0

package/src/context/compaction.ts

@@ -0,0 +1,265 @@
+import { generateText, Output, wrapLanguageModel, type ModelMessage, type LanguageModelMiddleware, type TelemetrySettings } from "ai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { z } from "zod";
+import { countTokens } from "./tokenizer.js";
+import { getContextWindow } from "./models.js";
+import type { AiTelemetryOptions } from "../types.js";
+import type { createAiProviderRegistry } from "../providers.js";
+
+const CompactionSchema = z.object({
+  summary: z.string().describe("Resumo conciso da conversa"),
+  decisions: z.array(z.string()).describe("Decisoes tomadas"),
+  filesModified: z.array(z.string()).describe("Arquivos modificados"),
+  currentState: z.string().describe("Estado atual do trabalho"),
+  nextSteps: z.array(z.string()).describe("Proximos passos"),
+});
+
+const TAIL_RATIO = 0.30;
+
+const SUMMARIZATION_PROMPT = `Summarize the conversation below preserving: decisions made, files modified, current state of work, and next steps. Be concise.`;
+
+export interface CompactOptions {
+  model: string;
+  apiKey: string;
+  contextWindow?: number;
+  systemPromptTokens: number;
+  toolDefinitionsTokens: number;
+  middleware?: LanguageModelMiddleware[];
+  telemetry?: AiTelemetryOptions;
+  /** Provider registry para reuso. Se nao fornecido, cria um internamente (backward compat). */
+  providers?: ReturnType<typeof createAiProviderRegistry>;
+}
+
+export interface CompactResult {
+  messages: ModelMessage[];
+  compacted: boolean;
+  warning?: string;
+}
+
+function countMessageTokens(msg: ModelMessage): number {
+  let tokens = 4; // overhead for role + framing
+  if (typeof msg.content === "string") {
+    tokens += countTokens(msg.content);
+  } else if (Array.isArray(msg.content)) {
+    for (const part of msg.content as any[]) {
+      if (part.type === "text" && typeof part.text === "string") {
+        tokens += countTokens(part.text);
+      } else if (part.type === "image") {
+        tokens += 300;
+      } else if (part.type === "file") {
+        const mime: string = part.mimeType ?? "";
+        if (mime === "application/pdf") {
+          tokens += 1500;
+        } else if (mime.startsWith("audio/")) {
+          tokens += 200;
+        } else {
+          tokens += 500;
+        }
+      } else {
+        tokens += 500; // unknown part fallback
+      }
+    }
+  }
+  return tokens;
+}
+
+function formatMessagesForSummary(messages: ModelMessage[]): string {
+  return messages
+    .map((msg) => {
+      const role = msg.role;
+      const content =
+        typeof msg.content === "string"
+          ? msg.content
+          : Array.isArray(msg.content)
+            ? msg.content
+                .filter((p) => "text" in p)
+                .map((p) => (p as any).text)
+                .join("\n")
+            : "[non-text content]";
+      return `[${role}]: ${content}`;
+    })
+    .join("\n\n");
+}
+
+/**
+ * Splits messages into head (to summarize) and tail (to keep intact).
+ * Tail = last messages that fit within 30% of the context window.
+ */
+function splitMessages(
+  messages: ModelMessage[],
+  contextWindow: number
+): { head: ModelMessage[]; tail: ModelMessage[] } {
+  const tailBudget = Math.floor(contextWindow * TAIL_RATIO);
+  let tailTokens = 0;
+  let tailStart = messages.length;
+
+  // Walk backwards to find tail boundary
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msgTokens = countMessageTokens(messages[i]);
+    if (tailTokens + msgTokens > tailBudget) break;
+    tailTokens += msgTokens;
+    tailStart = i;
+  }
+
+  // Ensure at least one message in head (nothing to compact otherwise)
+  if (tailStart <= 0) {
+    tailStart = 1;
+  }
+
+  return {
+    head: messages.slice(0, tailStart),
+    tail: messages.slice(tailStart),
+  };
+}
+
+/**
+ * Compacts conversation messages by summarizing older messages (head)
+ * and keeping recent messages (tail) intact.
+ *
+ * Uses the same model and apiKey as the agent for summarization.
+ * If summarization fails, returns original messages with a warning.
+ */
+export async function compactMessages(
+  messages: ModelMessage[],
+  options: CompactOptions
+): Promise<CompactResult> {
+  // Nothing to compact if 2 or fewer messages
+  if (messages.length <= 2) {
+    return { messages, compacted: false };
+  }
+
+  const contextWindow = getContextWindow(options.model, options.contextWindow);
+  const { head, tail } = splitMessages(messages, contextWindow);
+
+  // If head is empty or has only 1 message, nothing to compact
+  if (head.length <= 1) {
+    return { messages, compacted: false };
+  }
+
+  const conversationText = formatMessagesForSummary(head);
+
+  // Build telemetry config for compaction spans
+  const telemetryConfig: TelemetrySettings | undefined =
+    options.telemetry?.enabled
+      ? {
+          isEnabled: true,
+          functionId: options.telemetry.functionId
+            ? `${options.telemetry.functionId}-compaction`
+            : "ai-compaction",
+          recordInputs: false,
+          recordOutputs: false,
+          metadata: {
+            ...options.telemetry.metadata,
+          },
+        }
+      : undefined;
+
+  try {
+    const baseModel = options.providers
+      ? options.providers.model(options.model)
+      : createOpenAICompatible({
+          name: "openrouter",
+          baseURL: "https://openrouter.ai/api/v1",
+          apiKey: options.apiKey,
+        })(options.model);
+    const model =
+      options.middleware && options.middleware.length > 0
+        ? wrapLanguageModel({ model: baseModel, middleware: options.middleware })
+        : baseModel;
+
+    const result = await generateText({
+      model,
+      output: Output.object({ schema: CompactionSchema }),
+      system: SUMMARIZATION_PROMPT,
+      messages: [{ role: "user", content: conversationText }],
+      maxOutputTokens: 2000,
+      ...(telemetryConfig ? { experimental_telemetry: telemetryConfig } : {}),
+    });
+
+    const obj = result.output!;
+    if (!obj.summary || obj.summary.trim().length === 0) {
+      return {
+        messages,
+        compacted: false,
+        warning: "Compaction produced empty summary — keeping original messages",
+      };
+    }
+
+    const sections: string[] = [];
+    sections.push(`## Summary\n${obj.summary}`);
+    if (obj.decisions.length > 0) {
+      sections.push(`## Decisions\n${obj.decisions.map((d) => `- ${d}`).join("\n")}`);
+    }
+    if (obj.filesModified.length > 0) {
+      sections.push(`## Files Modified\n${obj.filesModified.map((f) => `- ${f}`).join("\n")}`);
+    }
+    sections.push(`## Current State\n${obj.currentState}`);
+    if (obj.nextSteps.length > 0) {
+      sections.push(`## Next Steps\n${obj.nextSteps.map((s) => `- ${s}`).join("\n")}`);
+    }
+
+    const summary = sections.join("\n\n");
+
+    const summaryMessage: ModelMessage = {
+      role: "user",
+      content: `<context_summary>\n${summary}\n</context_summary>`,
+    };
+
+    return {
+      messages: [summaryMessage, ...tail],
+      compacted: true,
+    };
+  } catch (structuredErr) {
+    // Fallback: generateObject() failed — try generateText() with free-text summarization
+    try {
+      const fallbackBaseModel = options.providers
+        ? options.providers.model(options.model)
+        : createOpenAICompatible({
+            name: "openrouter",
+            baseURL: "https://openrouter.ai/api/v1",
+            apiKey: options.apiKey,
+          })(options.model);
+      const fallbackModel =
+        options.middleware && options.middleware.length > 0
+          ? wrapLanguageModel({ model: fallbackBaseModel, middleware: options.middleware })
+          : fallbackBaseModel;
+
+      const result = await generateText({
+        model: fallbackModel,
+        system: SUMMARIZATION_PROMPT,
+        messages: [{ role: "user", content: conversationText }],
+        maxOutputTokens: 2000,
+        ...(telemetryConfig ? { experimental_telemetry: telemetryConfig } : {}),
+      });
+
+      const summary = result.text;
+      if (!summary || summary.trim().length === 0) {
+        return {
+          messages,
+          compacted: false,
+          warning: "Compaction fallback produced empty summary — keeping original messages",
+        };
+      }
+
+      const summaryMessage: ModelMessage = {
+        role: "user",
+        content: `<context_summary>\n${summary}\n</context_summary>`,
+      };
+
+      const structuredMsg = structuredErr instanceof Error ? structuredErr.message : String(structuredErr);
+      return {
+        messages: [summaryMessage, ...tail],
+        compacted: true,
+        warning: `Structured compaction failed (${structuredMsg}) — used text fallback`,
+      };
+    } catch (fallbackErr) {
+      const structuredMsg = structuredErr instanceof Error ? structuredErr.message : String(structuredErr);
+      const fallbackMsg = fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr);
+      return {
+        messages,
+        compacted: false,
+        warning: `Compaction failed: structured (${structuredMsg}), fallback (${fallbackMsg}) — keeping original messages`,
+      };
+    }
+  }
+}

package/src/context/models.ts

@@ -0,0 +1,42 @@
+const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  // Anthropic — Claude 4.x
+  "anthropic/claude-opus-4-6": 200000,
+  "anthropic/claude-sonnet-4-5": 200000,
+  "anthropic/claude-haiku-4-5": 200000,
+  // Anthropic — Claude 3.x
+  "anthropic/claude-3.5-sonnet": 200000,
+  "anthropic/claude-3.5-haiku": 200000,
+  "anthropic/claude-3-opus": 200000,
+  "anthropic/claude-3-sonnet": 200000,
+  "anthropic/claude-3-haiku": 200000,
+  // OpenAI
+  "openai/gpt-4o": 128000,
+  "openai/gpt-4o-mini": 128000,
+  "openai/gpt-4-turbo": 128000,
+  "openai/o1": 200000,
+  "openai/o1-mini": 128000,
+  "openai/o3": 200000,
+  "openai/o3-mini": 200000,
+  "openai/o4-mini": 200000,
+  // Google
+  "google/gemini-2.0-flash": 1048576,
+  "google/gemini-2.5-pro": 1048576,
+  // Meta
+  "meta-llama/llama-3.1-405b-instruct": 131072,
+  "meta-llama/llama-3.1-70b-instruct": 131072,
+  // DeepSeek
+  "deepseek/deepseek-chat-v3": 131072,
+  "deepseek/deepseek-r1": 131072,
+};
+
+const DEFAULT_CONTEXT_WINDOW = 128000;
+
+/**
+ * Returns the context window size for a model ID.
+ * If `override` is provided, it takes precedence over the map.
+ * Unknown models default to 128000.
+ */
+export function getContextWindow(modelId: string, override?: number): number {
+  if (override !== undefined) return override;
+  return MODEL_CONTEXT_WINDOWS[modelId] ?? DEFAULT_CONTEXT_WINDOW;
+}

package/src/context/tokenizer.ts

@@ -0,0 +1,12 @@
+import { encodingForModel } from "js-tiktoken";
+
+const encoder = encodingForModel("gpt-4o");
+
+/**
+ * Returns an estimated token count for the given text using cl100k_base encoding.
+ * Returns 0 for empty strings.
+ */
+export function countTokens(text: string): number {
+  if (!text) return 0;
+  return encoder.encode(text).length;
+}

package/src/context/usage.ts

@@ -0,0 +1,65 @@
+import type { ModelMessage } from "ai";
+import { countTokens } from "./tokenizer.js";
+import { getContextWindow } from "./models.js";
+import type { ContextUsage } from "../types.js";
+
+const DEFAULT_COMPACT_THRESHOLD = 0.65;
+
+export interface GetContextUsageOptions {
+  model: string;
+  systemPrompt: string;
+  toolDefinitions: Record<string, unknown>;
+  messages: ModelMessage[];
+  contextWindow?: number;
+  compactThreshold?: number;
+}
+
+function countMessagesTokens(messages: ModelMessage[]): number {
+  let total = 0;
+  for (const msg of messages) {
+    if (typeof msg.content === "string") {
+      total += countTokens(msg.content);
+    } else if (Array.isArray(msg.content)) {
+      for (const part of msg.content) {
+        if ("text" in part && typeof part.text === "string") {
+          total += countTokens(part.text);
+        }
+      }
+    }
+    // Add overhead for role + message framing (~4 tokens per message)
+    total += 4;
+  }
+  return total;
+}
+
+function countToolDefinitionsTokens(tools: Record<string, unknown>): number {
+  if (!tools || Object.keys(tools).length === 0) return 0;
+  return countTokens(JSON.stringify(tools));
+}
+
+export function getContextUsage(options: GetContextUsageOptions): ContextUsage {
+  const contextWindow = getContextWindow(options.model, options.contextWindow);
+  const compactThreshold = options.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD;
+
+  const systemPrompt = countTokens(options.systemPrompt);
+  const toolDefinitions = countToolDefinitionsTokens(options.toolDefinitions);
+  const messages = countMessagesTokens(options.messages);
+
+  const used = systemPrompt + toolDefinitions + messages;
+  const free = contextWindow - used;
+  const usagePercent = (used / contextWindow) * 100;
+  const willCompact = usagePercent >= compactThreshold * 100;
+
+  return {
+    model: options.model,
+    contextWindow,
+    systemPrompt,
+    toolDefinitions,
+    messages,
+    used,
+    free,
+    usagePercent,
+    compactThreshold: compactThreshold * 100,
+    willCompact,
+  };
+}

package/src/display-schemas.ts

@@ -0,0 +1,276 @@
+import { z } from "zod";
+
+// --- Primitivos reutilizaveis ---
+
+const MoneySchema = z.object({
+  value: z.number(),
+  currency: z.string().default("BRL"),
+});
+
+const SourceRefSchema = z.object({
+  name: z.string(),
+  url: z.string().url(),
+  favicon: z.string().url().optional(),
+});
+
+const ImageItemSchema = z.object({
+  url: z.string().url(),
+  alt: z.string().optional(),
+  caption: z.string().optional(),
+});
+
+const BadgeSchema = z.object({
+  label: z.string(),
+  variant: z.enum(["default", "success", "warning", "error", "info"]).default("default"),
+});
+
+// --- Display Tools ---
+
+// 1. METRICAS E DADOS
+
+export const DisplayMetricSchema = z.object({
+  label: z.string(),
+  value: z.union([z.string(), z.number()]),
+  unit: z.string().optional(),
+  trend: z.object({
+    direction: z.enum(["up", "down", "neutral"]),
+    value: z.string(),
+  }).optional(),
+  icon: z.string().optional(),
+});
+
+export const DisplayChartSchema = z.object({
+  type: z.enum(["bar", "line", "pie", "area", "donut"]),
+  title: z.string(),
+  data: z.array(z.object({
+    label: z.string(),
+    value: z.number(),
+    color: z.string().optional(),
+  })),
+  format: z.object({
+    prefix: z.string().optional(),
+    suffix: z.string().optional(),
+    locale: z.string().default("pt-BR"),
+  }).optional(),
+});
+
+export const DisplayTableSchema = z.object({
+  title: z.string().optional(),
+  columns: z.array(z.object({
+    key: z.string(),
+    label: z.string(),
+    type: z.enum(["text", "number", "money", "image", "link", "badge"]).default("text"),
+    align: z.enum(["left", "center", "right"]).default("left"),
+  })),
+  rows: z.array(z.record(z.unknown())),
+  sortable: z.boolean().default(false),
+});
+
+export const DisplayProgressSchema = z.object({
+  title: z.string().optional(),
+  steps: z.array(z.object({
+    label: z.string(),
+    status: z.enum(["completed", "current", "pending"]),
+    description: z.string().optional(),
+  })),
+});
+
+// 2. PRODUTOS E COMERCIO
+
+export const DisplayProductSchema = z.object({
+  title: z.string(),
+  image: z.string().url().optional(),
+  price: MoneySchema.optional(),
+  originalPrice: MoneySchema.optional(),
+  rating: z.object({
+    score: z.number().min(0).max(5),
+    count: z.number(),
+  }).optional(),
+  source: SourceRefSchema.optional(),
+  badges: z.array(BadgeSchema).optional(),
+  url: z.string().url().optional(),
+  description: z.string().optional(),
+});
+
+export const DisplayComparisonSchema = z.object({
+  title: z.string().optional(),
+  items: z.array(DisplayProductSchema),
+  attributes: z.array(z.object({
+    key: z.string(),
+    label: z.string(),
+  })).optional(),
+});
+
+export const DisplayPriceSchema = z.object({
+  value: MoneySchema,
+  label: z.string(),
+  context: z.string().optional(),
+  source: SourceRefSchema.optional(),
+  badge: BadgeSchema.optional(),
+});
+
+// 3. MIDIA
+
+export const DisplayImageSchema = z.object({
+  url: z.string().url(),
+  alt: z.string().optional(),
+  caption: z.string().optional(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+});
+
+export const DisplayGallerySchema = z.object({
+  title: z.string().optional(),
+  images: z.array(ImageItemSchema),
+  layout: z.enum(["grid", "masonry"]).default("grid"),
+  columns: z.number().min(2).max(5).default(3),
+});
+
+export const DisplayCarouselSchema = z.object({
+  title: z.string().optional(),
+  items: z.array(z.object({
+    image: z.string().url().optional(),
+    title: z.string(),
+    subtitle: z.string().optional(),
+    price: MoneySchema.optional(),
+    url: z.string().url().optional(),
+    badges: z.array(BadgeSchema).optional(),
+  })),
+});
+
+// 4. REFERENCIAS E NAVEGACAO
+
+export const DisplaySourcesSchema = z.object({
+  label: z.string().default("Fontes consultadas"),
+  sources: z.array(z.object({
+    title: z.string(),
+    url: z.string().url(),
+    favicon: z.string().url().optional(),
+    snippet: z.string().optional(),
+  })),
+});
+
+export const DisplayLinkSchema = z.object({
+  url: z.string().url(),
+  title: z.string(),
+  description: z.string().optional(),
+  image: z.string().url().optional(),
+  favicon: z.string().url().optional(),
+  domain: z.string().optional(),
+});
+
+export const DisplayMapSchema = z.object({
+  title: z.string().optional(),
+  pins: z.array(z.object({
+    lat: z.number(),
+    lng: z.number(),
+    label: z.string().optional(),
+    address: z.string().optional(),
+  })),
+  zoom: z.number().min(1).max(20).default(14),
+});
+
+// 5. DOCUMENTOS E ARQUIVOS
+
+export const DisplayFileSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  size: z.number().optional(),
+  url: z.string().url().optional(),
+  preview: z.string().optional(),
+});
+
+export const DisplayCodeSchema = z.object({
+  language: z.string(),
+  code: z.string(),
+  title: z.string().optional(),
+  lineNumbers: z.boolean().default(true),
+});
+
+export const DisplaySpreadsheetSchema = z.object({
+  title: z.string().optional(),
+  headers: z.array(z.string()),
+  rows: z.array(z.array(z.union([z.string(), z.number(), z.null()]))),
+  format: z.object({
+    moneyColumns: z.array(z.number()).optional(),
+    percentColumns: z.array(z.number()).optional(),
+  }).optional(),
+});
+
+// 6. INTERATIVO
+
+export const DisplayStepsSchema = z.object({
+  title: z.string().optional(),
+  steps: z.array(z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    status: z.enum(["completed", "current", "pending"]).default("pending"),
+  })),
+  orientation: z.enum(["vertical", "horizontal"]).default("vertical"),
+});
+
+export const DisplayAlertSchema = z.object({
+  variant: z.enum(["info", "warning", "error", "success"]),
+  title: z.string().optional(),
+  message: z.string(),
+  icon: z.string().optional(),
+});
+
+export const DisplayChoicesSchema = z.object({
+  question: z.string().optional(),
+  choices: z.array(z.object({
+    id: z.string(),
+    label: z.string(),
+    description: z.string().optional(),
+    icon: z.string().optional(),
+  })),
+  layout: z.enum(["buttons", "cards", "list"]).default("buttons"),
+});
+
+// --- Registry (mapa nome → schema) ---
+
+export const DisplayToolRegistry = {
+  display_metric: DisplayMetricSchema,
+  display_chart: DisplayChartSchema,
+  display_table: DisplayTableSchema,
+  display_progress: DisplayProgressSchema,
+  display_product: DisplayProductSchema,
+  display_comparison: DisplayComparisonSchema,
+  display_price: DisplayPriceSchema,
+  display_image: DisplayImageSchema,
+  display_gallery: DisplayGallerySchema,
+  display_carousel: DisplayCarouselSchema,
+  display_sources: DisplaySourcesSchema,
+  display_link: DisplayLinkSchema,
+  display_map: DisplayMapSchema,
+  display_file: DisplayFileSchema,
+  display_code: DisplayCodeSchema,
+  display_spreadsheet: DisplaySpreadsheetSchema,
+  display_steps: DisplayStepsSchema,
+  display_alert: DisplayAlertSchema,
+  display_choices: DisplayChoicesSchema,
+} as const;
+
+export type DisplayToolName = keyof typeof DisplayToolRegistry;
+
+// --- Tipos inferidos ---
+
+export type DisplayMetric = z.infer<typeof DisplayMetricSchema>;
+export type DisplayChart = z.infer<typeof DisplayChartSchema>;
+export type DisplayTable = z.infer<typeof DisplayTableSchema>;
+export type DisplayProgress = z.infer<typeof DisplayProgressSchema>;
+export type DisplayProduct = z.infer<typeof DisplayProductSchema>;
+export type DisplayComparison = z.infer<typeof DisplayComparisonSchema>;
+export type DisplayPrice = z.infer<typeof DisplayPriceSchema>;
+export type DisplayImage = z.infer<typeof DisplayImageSchema>;
+export type DisplayGallery = z.infer<typeof DisplayGallerySchema>;
+export type DisplayCarousel = z.infer<typeof DisplayCarouselSchema>;
+export type DisplaySources = z.infer<typeof DisplaySourcesSchema>;
+export type DisplayLink = z.infer<typeof DisplayLinkSchema>;
+export type DisplayMap = z.infer<typeof DisplayMapSchema>;
+export type DisplayFile = z.infer<typeof DisplayFileSchema>;
+export type DisplayCode = z.infer<typeof DisplayCodeSchema>;
+export type DisplaySpreadsheet = z.infer<typeof DisplaySpreadsheetSchema>;
+export type DisplaySteps = z.infer<typeof DisplayStepsSchema>;
+export type DisplayAlert = z.infer<typeof DisplayAlertSchema>;
+export type DisplayChoices = z.infer<typeof DisplayChoicesSchema>;