twelveai 0.1.0 → 0.2.0

package/README.md

@@ -36,6 +36,18 @@ console.log(res.message) // "Your current balance is NGN 307.05."
 
 Behind that one call the SDK also completed any **client-fetch hand-offs**: when a tool is configured as *"my app calls it"*, the engine returns the resolved request (method, URL, body - no credentials attached) instead of calling your API. The SDK performs it with your `clientAuth`, resumes the turn, and hands you the final grounded answer. Inspect what ran via `res.executedHandoffs`.
 
+## Level 0: classify only (zero commitment)
+
+Not ready to hand over the conversation? Keep every flow you have and use
+TwelveAI purely as the router - free, nothing stored:
+
+```ts
+const r = await twelve.classify({ message: 'send 5k to 0123456789' })
+// { intent: 'transfer', confidence: 0.8,
+//   entities: { amount: 5000, account_number: '0123456789' } }
+if (r.confidence > 0.6) routeToMyTransferFlow(r.entities)
+```
+
 ## Multi-turn conversations
 
 Pass the previous turn's `continuation` to keep context:

package/dist/index.cjs

@@ -67,6 +67,34 @@ var TwelveAI = class {
   async confirm(continuation, input = {}) {
     return this.chat({ message: "yes", ...input, continuation, confirmed: true });
   }
+  /**
+   * Level-0 integration: classify a message WITHOUT running the conversation.
+   * Returns the intent, a deterministic confidence score, and cheap extracted
+   * entities (amount / account number / phone) - you keep your existing flows
+   * and make the call yourself. Free: no tools run, nothing is stored.
+   */
+  async classify(input) {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}/v1/classify`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+        body: JSON.stringify({ message: input.message })
+      });
+      const data = await res.json().catch(() => ({}));
+      return {
+        ok: res.ok && data.ok !== false,
+        intent: data.intent ?? null,
+        label: data.label ?? null,
+        confidence: data.confidence ?? 0,
+        alternatives: data.alternatives ?? [],
+        entities: data.entities ?? {},
+        status: res.status,
+        ...res.ok ? {} : { error: data.error ?? `Engine returned ${res.status}` }
+      };
+    } catch (error) {
+      return { ok: false, intent: null, label: null, confidence: 0, alternatives: [], entities: {}, status: 0, error: error?.message || "Could not reach the engine." };
+    }
+  }
   /* ------------------------------ internals ------------------------------ */
   chatBody(input) {
     const body = {};

package/dist/index.d.cts

@@ -123,6 +123,22 @@ interface ChatResponse {
  * `clientAuth` headers and returns `{ ok, data }`.
  */
 type HandoffExecutor = (call: PendingToolCall) => Promise<unknown>;
+interface ClassifyResponse {
+    ok: boolean;
+    /** The winning agent intent, or null when nothing matched. */
+    intent: string | null;
+    label: string | null;
+    /** Deterministic confidence in [0, 0.95]; 0 = no match. */
+    confidence: number;
+    alternatives: Array<{
+        intent: string;
+        label: string;
+    }>;
+    /** Cheap extracted entities: amount, account_number, phone (when present). */
+    entities: Record<string, unknown>;
+    status: number;
+    error?: string;
+}
 
 /**
  * The TwelveAI client. One call does the whole conversation protocol:
@@ -161,6 +177,15 @@ declare class TwelveAI {
      * `confirmed: true` so the engine proceeds.
      */
     confirm(continuation: string, input?: Omit<ChatInput, 'continuation' | 'confirmed'>): Promise<ChatResponse>;
+    /**
+     * Level-0 integration: classify a message WITHOUT running the conversation.
+     * Returns the intent, a deterministic confidence score, and cheap extracted
+     * entities (amount / account number / phone) - you keep your existing flows
+     * and make the call yourself. Free: no tools run, nothing is stored.
+     */
+    classify(input: {
+        message: string;
+    }): Promise<ClassifyResponse>;
     private chatBody;
     private post;
     /**
@@ -227,4 +252,4 @@ declare function createJwksVerifier(options?: JwksVerifierOptions): (input: JwtR
     claims?: Record<string, unknown>;
 }>;
 
-export { type Attachment, type ChatInput, type ChatResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };
+export { type Attachment, type ChatInput, type ChatResponse, type ClassifyResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };

package/dist/index.d.ts

@@ -123,6 +123,22 @@ interface ChatResponse {
  * `clientAuth` headers and returns `{ ok, data }`.
  */
 type HandoffExecutor = (call: PendingToolCall) => Promise<unknown>;
+interface ClassifyResponse {
+    ok: boolean;
+    /** The winning agent intent, or null when nothing matched. */
+    intent: string | null;
+    label: string | null;
+    /** Deterministic confidence in [0, 0.95]; 0 = no match. */
+    confidence: number;
+    alternatives: Array<{
+        intent: string;
+        label: string;
+    }>;
+    /** Cheap extracted entities: amount, account_number, phone (when present). */
+    entities: Record<string, unknown>;
+    status: number;
+    error?: string;
+}
 
 /**
  * The TwelveAI client. One call does the whole conversation protocol:
@@ -161,6 +177,15 @@ declare class TwelveAI {
      * `confirmed: true` so the engine proceeds.
      */
     confirm(continuation: string, input?: Omit<ChatInput, 'continuation' | 'confirmed'>): Promise<ChatResponse>;
+    /**
+     * Level-0 integration: classify a message WITHOUT running the conversation.
+     * Returns the intent, a deterministic confidence score, and cheap extracted
+     * entities (amount / account number / phone) - you keep your existing flows
+     * and make the call yourself. Free: no tools run, nothing is stored.
+     */
+    classify(input: {
+        message: string;
+    }): Promise<ClassifyResponse>;
     private chatBody;
     private post;
     /**
@@ -227,4 +252,4 @@ declare function createJwksVerifier(options?: JwksVerifierOptions): (input: JwtR
     claims?: Record<string, unknown>;
 }>;
 
-export { type Attachment, type ChatInput, type ChatResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };
+export { type Attachment, type ChatInput, type ChatResponse, type ClassifyResponse, type HandoffExecutor, type HandoffRequest, type JwksVerifierOptions, type JwtRequestInput, type PendingToolCall, type SignedRequestInput, type ToolCall, type ToolResult, TwelveAI, type TwelveAIOptions, createJwksVerifier, verifySignedRequest, verifyWebhook };

package/dist/index.js

@@ -38,6 +38,34 @@ var TwelveAI = class {
   async confirm(continuation, input = {}) {
     return this.chat({ message: "yes", ...input, continuation, confirmed: true });
   }
+  /**
+   * Level-0 integration: classify a message WITHOUT running the conversation.
+   * Returns the intent, a deterministic confidence score, and cheap extracted
+   * entities (amount / account number / phone) - you keep your existing flows
+   * and make the call yourself. Free: no tools run, nothing is stored.
+   */
+  async classify(input) {
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}/v1/classify`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": this.apiKey },
+        body: JSON.stringify({ message: input.message })
+      });
+      const data = await res.json().catch(() => ({}));
+      return {
+        ok: res.ok && data.ok !== false,
+        intent: data.intent ?? null,
+        label: data.label ?? null,
+        confidence: data.confidence ?? 0,
+        alternatives: data.alternatives ?? [],
+        entities: data.entities ?? {},
+        status: res.status,
+        ...res.ok ? {} : { error: data.error ?? `Engine returned ${res.status}` }
+      };
+    } catch (error) {
+      return { ok: false, intent: null, label: null, confidence: 0, alternatives: [], entities: {}, status: 0, error: error?.message || "Could not reach the engine." };
+    }
+  }
   /* ------------------------------ internals ------------------------------ */
   chatBody(input) {
     const body = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twelveai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official SDK for TwelveAI - AI infrastructure for conversational banking. One call runs the whole chat protocol: routing, grounded tool calls, client-fetch hand-offs, confirmations, and request verification.",
   "license": "MIT",
   "author": "TwelveAI",