Assistant#

The Assistant module provides a powerful API that allows users to request structured JSON data from the assistant. This functionality can be used for automation tasks such as extracting bill details, categorizing expenses, or parsing text data.

isAvailable Variable#

Description#

Indicates whether the Assistant API is available.

• This status depends on the selected AI provider and whether a valid API Key is configured.
• If the appropriate API Key is not provided, the Assistant API will be unavailable.

requestStructuredData Method#

Description#

requestStructuredData allows users to send a text prompt to the assistant and receive structured data in JSON format based on a defined schema.

Syntax#

1function requestStructuredData<R>(
2  prompt: string,
3  schema: JSONSchemaArray | JSONSchemaObject
4): Promise<R>

Parameters#

• prompt (string): The input prompt describing the content to be parsed.
• schema (JSONSchemaArray | JSONSchemaObject): The expected output JSON schema, defining the structure of the returned data.

Return Value#

Returns a Promise resolving to structured JSON data that matches the schema definition, with a type of R.

JSON Schema Definition#

The schema parameter in the requestStructuredData method defines the structure of the returned JSON data, with the following types:

JSONSchemaType#

1type JSONSchemaType = JSONSchemaPrimitive | JSONSchemaArray | JSONSchemaObject

Primitive data type definition:

1type JSONSchemaPrimitive = {
2    type: "string" | "number" | "boolean"
3    required?: boolean
4    description: string
5}

Array type definition:

1type JSONSchemaArray = {
2    type: "array"
3    items: JSONSchemaType
4    required?: boolean
5    description: string
6}

Object type definition:

1type JSONSchemaObject = {
2    type: "object"
3    properties: Record<string, JSONSchemaType>
4    required?: boolean
5    description: string
6}

Example#

1const schema: JSONSchemaObject = {
2  type: "object",
3  properties: {
4    totalAmount: { 
5      type: "number",
6      required: true,
7      description: "Total bill amount"
8    },
9    category: {
10      type: "string",
11      required: true,
12      description: "Bill category"
13    },
14    date: {
15      type: "string",
16      required: false,
17      description: "Bill date"
18    },
19    location: {
20      type: "string",
21      required: false,
22      description: "Bill location"
23    }
24  }
25}

Example Usage#

Parsing Bill Information#

Suppose we have a bill, and we need to extract its amount, date, category, and location.

1const someBillDetails = `
2- Amount: $15.00
3- Date: 2024-03-11 14:30
4- Location: City Center Parking Lot
5- Category: Parking
6`
7
8const prompt = `Please parse the following bill and output the structured data: ${someBillDetails}`
9
10const data = await Assistant.requestStructuredData(
11  prompt,
12  schema
13)
14console.log(data)

Possible Output#

1{
2  "totalAmount": 15.00,
3  "category": "Parking",
4  "date": "2024-03-11 14:30",
5  "location": "City Center Parking Lot"
6}

Usage Considerations#

1. Ensure the schema is correctly defined: The JSON schema should match the expected data format.
2. Use required attributes carefully: If a field is essential, set required: true.
3. Provide a clear prompt: A detailed prompt improves the accuracy of the assistant's response.
4. Error Handling: Since requestStructuredData returns a Promise, handle potential errors using try-catch.

Example error handling:

1try {
2  const data = await Assistant.requestStructuredData(
3    prompt,
4    schema
5  )
6  console.log("Parsed result:", data)
7} catch (error) {
8  console.error("Parsing failed:", error)
9}