@lakitu/sdk 0.1.0

package/convex/cloud/intentSchema/types.ts

@@ -0,0 +1,418 @@
+/**
+ * Intent Schema Types
+ *
+ * Defines the structure for pre-analyzing user requests before sandbox execution.
+ * The Intent Schema guides the agent by providing:
+ * - Prioritized KSA selection
+ * - Structured goals and deliverables
+ * - User-configurable policies
+ *
+ * Similar to how STAGES work in boards, but dynamic and per-request.
+ */
+
+import { v } from "convex/values";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * Importance level for goals
+ */
+export type GoalImportance = "critical" | "important" | "nice-to-have";
+
+/**
+ * Confidence level for schema generation
+ */
+export type SchemaConfidence = "high" | "medium" | "low";
+
+/**
+ * Deliverable output types
+ */
+export type DeliverableType =
+  | "markdown"
+  | "json"
+  | "csv"
+  | "pdf"
+  | "html"
+  | "code"
+  | "image"
+  | "email";
+
+// ============================================================================
+// Intent Schema Structure
+// ============================================================================
+
+/**
+ * Breakdown of user intent
+ */
+export interface IntentBreakdown {
+  /** One-line summary of the request */
+  summary: string;
+  /** What the user wants to accomplish */
+  objective: string;
+  /** Key context elements extracted from the request */
+  context: string[];
+  /** Detected domain/topic area */
+  domain?: string;
+}
+
+/**
+ * KSA prioritization and selection
+ */
+export interface KSAPrioritization {
+  /** KSAs to import and use first (ordered by priority) */
+  priority: string[];
+  /** KSAs that may be useful as secondary options */
+  secondary: string[];
+  /** KSAs explicitly not relevant for this request */
+  notNeeded: string[];
+  /** Reasoning for these choices */
+  reasoning: string;
+}
+
+/**
+ * A goal for the agent to accomplish
+ */
+export interface IntentGoal {
+  /** Unique identifier */
+  id: string;
+  /** Goal description */
+  text: string;
+  /** How important is this goal */
+  importance: GoalImportance;
+}
+
+/**
+ * A deliverable the agent should produce
+ */
+export interface IntentDeliverable {
+  /** Unique identifier */
+  id: string;
+  /** Output format type */
+  type: DeliverableType;
+  /** Name of the deliverable */
+  name: string;
+  /** Description of what should be in it */
+  description: string;
+}
+
+/**
+ * Suggested execution plan
+ */
+export interface IntentPlan {
+  /** Goals to accomplish */
+  goals: IntentGoal[];
+  /** Deliverables to produce */
+  deliverables: IntentDeliverable[];
+  /** High-level execution steps */
+  steps: string[];
+}
+
+/**
+ * Policy controls (user-adjustable)
+ */
+export interface IntentPolicy {
+  /** KSAs that are enabled for this request */
+  enabledKSAs: string[];
+  /** KSAs explicitly blocked by user */
+  disabledKSAs: string[];
+  /** Maximum iterations/loops allowed */
+  maxIterations?: number;
+  /** Whether external API calls are allowed */
+  allowExternalCalls: boolean;
+  /** KSAs that require user approval before use */
+  requireApprovalFor?: string[];
+}
+
+/**
+ * Metadata about schema generation
+ */
+export interface IntentSchemaMeta {
+  /** Model used for generation */
+  model: string;
+  /** When the schema was generated */
+  generatedAt: number;
+  /** Confidence in the schema accuracy */
+  confidence: SchemaConfidence;
+  /** Generation latency in ms */
+  latencyMs?: number;
+}
+
+/**
+ * Complete Intent Schema
+ *
+ * Pre-analyzed structure that guides agent execution.
+ * Generated by a fast LLM (GROQ) while sandbox is warming up.
+ */
+export interface IntentSchema {
+  /** Breakdown of user intent */
+  intent: IntentBreakdown;
+  /** KSA prioritization and selection */
+  ksas: KSAPrioritization;
+  /** Suggested execution plan */
+  plan: IntentPlan;
+  /** Policy controls */
+  policy: IntentPolicy;
+  /** Generation metadata */
+  meta: IntentSchemaMeta;
+}
+
+// ============================================================================
+// User Policy Configuration
+// ============================================================================
+
+/**
+ * User-configurable policy settings
+ * Stored in user settings, applied to all agent requests
+ */
+export interface UserAgentPolicy {
+  /** KSAs the user has disabled globally */
+  disabledKSAs: string[];
+  /** KSAs that require approval before use */
+  requireApprovalFor: string[];
+  /** Blocked deliverable types (e.g., no emails) */
+  blockedDeliverableTypes: DeliverableType[];
+  /** Budget limit per request (in tokens) */
+  maxCostPerRequest?: number;
+  /** Whether to allow external API calls by default */
+  allowExternalCalls: boolean;
+}
+
+/**
+ * Default user policy - all KSAs except brandscan and boards
+ * These are powerful app-level KSAs that should be explicitly enabled.
+ */
+export const DEFAULT_USER_POLICY: UserAgentPolicy = {
+  disabledKSAs: ["brandscan", "boards"],
+  requireApprovalFor: ["email"], // Email sending requires approval by default
+  blockedDeliverableTypes: [],
+  allowExternalCalls: true,
+};
+
+// ============================================================================
+// Convex Validators
+// ============================================================================
+
+/**
+ * Convex validator for IntentSchema
+ */
+export const intentSchemaValidator = v.object({
+  intent: v.object({
+    summary: v.string(),
+    objective: v.string(),
+    context: v.array(v.string()),
+    domain: v.optional(v.string()),
+  }),
+  ksas: v.object({
+    priority: v.array(v.string()),
+    secondary: v.array(v.string()),
+    notNeeded: v.array(v.string()),
+    reasoning: v.string(),
+  }),
+  plan: v.object({
+    goals: v.array(
+      v.object({
+        id: v.string(),
+        text: v.string(),
+        importance: v.union(
+          v.literal("critical"),
+          v.literal("important"),
+          v.literal("nice-to-have")
+        ),
+      })
+    ),
+    deliverables: v.array(
+      v.object({
+        id: v.string(),
+        type: v.union(
+          v.literal("markdown"),
+          v.literal("json"),
+          v.literal("csv"),
+          v.literal("pdf"),
+          v.literal("html"),
+          v.literal("code"),
+          v.literal("image"),
+          v.literal("email")
+        ),
+        name: v.string(),
+        description: v.string(),
+      })
+    ),
+    steps: v.array(v.string()),
+  }),
+  policy: v.object({
+    enabledKSAs: v.array(v.string()),
+    disabledKSAs: v.array(v.string()),
+    maxIterations: v.optional(v.number()),
+    allowExternalCalls: v.boolean(),
+    requireApprovalFor: v.optional(v.array(v.string())),
+  }),
+  meta: v.object({
+    model: v.string(),
+    generatedAt: v.number(),
+    confidence: v.union(
+      v.literal("high"),
+      v.literal("medium"),
+      v.literal("low")
+    ),
+    latencyMs: v.optional(v.number()),
+  }),
+});
+
+/**
+ * Convex validator for UserAgentPolicy
+ */
+export const userAgentPolicyValidator = v.object({
+  disabledKSAs: v.array(v.string()),
+  requireApprovalFor: v.array(v.string()),
+  blockedDeliverableTypes: v.array(
+    v.union(
+      v.literal("markdown"),
+      v.literal("json"),
+      v.literal("csv"),
+      v.literal("pdf"),
+      v.literal("html"),
+      v.literal("code"),
+      v.literal("image"),
+      v.literal("email")
+    )
+  ),
+  maxCostPerRequest: v.optional(v.number()),
+  allowExternalCalls: v.boolean(),
+});
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Create an empty/default Intent Schema
+ */
+export function createDefaultIntentSchema(
+  prompt: string,
+  enabledKSAs: string[]
+): IntentSchema {
+  return {
+    intent: {
+      summary: prompt.slice(0, 100),
+      objective: "Process user request",
+      context: [],
+    },
+    ksas: {
+      priority: enabledKSAs.slice(0, 3),
+      secondary: enabledKSAs.slice(3),
+      notNeeded: [],
+      reasoning: "Default schema - no pre-analysis performed",
+    },
+    plan: {
+      goals: [
+        {
+          id: "g1",
+          text: "Complete the user's request",
+          importance: "critical",
+        },
+      ],
+      deliverables: [],
+      steps: ["Analyze request", "Execute", "Return results"],
+    },
+    policy: {
+      enabledKSAs,
+      disabledKSAs: [],
+      allowExternalCalls: true,
+    },
+    meta: {
+      model: "default",
+      generatedAt: Date.now(),
+      confidence: "low",
+    },
+  };
+}
+
+/**
+ * Merge user policy with generated schema policy
+ */
+export function applyUserPolicy(
+  schema: IntentSchema,
+  userPolicy: Partial<UserAgentPolicy>
+): IntentSchema {
+  const merged = { ...schema };
+
+  // Apply disabled KSAs from user policy
+  if (userPolicy.disabledKSAs?.length) {
+    merged.policy.disabledKSAs = [
+      ...new Set([
+        ...merged.policy.disabledKSAs,
+        ...userPolicy.disabledKSAs,
+      ]),
+    ];
+    // Remove disabled KSAs from enabled list
+    merged.policy.enabledKSAs = merged.policy.enabledKSAs.filter(
+      (k) => !merged.policy.disabledKSAs.includes(k)
+    );
+    // Remove from priority lists
+    merged.ksas.priority = merged.ksas.priority.filter(
+      (k) => !merged.policy.disabledKSAs.includes(k)
+    );
+    merged.ksas.secondary = merged.ksas.secondary.filter(
+      (k) => !merged.policy.disabledKSAs.includes(k)
+    );
+  }
+
+  // Apply approval requirements
+  if (userPolicy.requireApprovalFor?.length) {
+    merged.policy.requireApprovalFor = userPolicy.requireApprovalFor;
+  }
+
+  // Apply external calls setting
+  if (userPolicy.allowExternalCalls !== undefined) {
+    merged.policy.allowExternalCalls = userPolicy.allowExternalCalls;
+  }
+
+  // Filter blocked deliverable types
+  if (userPolicy.blockedDeliverableTypes?.length) {
+    merged.plan.deliverables = merged.plan.deliverables.filter(
+      (d) => !userPolicy.blockedDeliverableTypes!.includes(d.type)
+    );
+  }
+
+  return merged;
+}
+
+/**
+ * Validate that a parsed schema has all required fields
+ */
+export function validateIntentSchema(obj: unknown): obj is IntentSchema {
+  if (!obj || typeof obj !== "object") return false;
+
+  const schema = obj as Record<string, unknown>;
+
+  // Check top-level fields
+  if (!schema.intent || typeof schema.intent !== "object") return false;
+  if (!schema.ksas || typeof schema.ksas !== "object") return false;
+  if (!schema.plan || typeof schema.plan !== "object") return false;
+  if (!schema.policy || typeof schema.policy !== "object") return false;
+
+  // Check intent fields
+  const intent = schema.intent as Record<string, unknown>;
+  if (typeof intent.summary !== "string") return false;
+  if (typeof intent.objective !== "string") return false;
+  if (!Array.isArray(intent.context)) return false;
+
+  // Check ksas fields
+  const ksas = schema.ksas as Record<string, unknown>;
+  if (!Array.isArray(ksas.priority)) return false;
+  if (!Array.isArray(ksas.secondary)) return false;
+
+  // Check plan fields
+  const plan = schema.plan as Record<string, unknown>;
+  if (!Array.isArray(plan.goals)) return false;
+  if (!Array.isArray(plan.deliverables)) return false;
+  if (!Array.isArray(plan.steps)) return false;
+
+  // Check policy fields
+  const policy = schema.policy as Record<string, unknown>;
+  if (!Array.isArray(policy.enabledKSAs)) return false;
+
+  return true;
+}