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  options?: {
5    provider: "openai" | "gemini" | "anthropic" | "deepseek" | "pollinations" | { custom: string }
6    modelId?: string
7  }
8): Promise<R>

Parameters#

• prompt (string): The natural language prompt describing the task or content to be parsed.

• schema (JSONSchemaArray | JSONSchemaObject): A schema describing the structure of the expected output in JSON format.

• options (optional):

  • provider: Specifies the AI provider to use. Supported values:

    • "openai"
    • "gemini"
    • "anthropic"
    • "deepseek"
    • "pollinations"
    • { custom: string }: Use a custom provider with the given name.

  • modelId: The model identifier for the selected provider. You must ensure the specified ID matches a model supported by that provider (e.g., "gpt-4-turbo" for OpenAI, or "gemini-1.5-pro" for Gemini). If not specified, the app will use the default model configured for the provider.

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 defines the expected shape of the JSON response.

JSONSchemaType#

1type JSONSchemaType = JSONSchemaPrimitive | JSONSchemaArray | JSONSchemaObject

Primitive#

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

Array#

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

Object#

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

Example: Parsing Bill Information#

Suppose you want to extract details from a bill:

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 schema: JSONSchemaObject = {
11  type: "object",
12  properties: {
13    totalAmount: { 
14      type: "number",
15      required: true,
16      description: "Total bill amount"
17    },
18    category: {
19      type: "string",
20      required: true,
21      description: "Bill category"
22    },
23    date: {
24      type: "string",
25      required: false,
26      description: "Bill date"
27    },
28    location: {
29      type: "string",
30      required: false,
31      description: "Bill location"
32    }
33  }
34}
35
36const data = await Assistant.requestStructuredData(
37  prompt,
38  schema,
39  {
40    provider: "openai",
41    modelId: "gpt-4-turbo"
42  }
43)
44
45console.log(data)

Sample 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. Define a clear schema Ensure the schema accurately represents the expected data shape.

2. Use required wisely If a field must be present, set required: true. Otherwise, it may be omitted.

3. Choose the right provider and model You can explicitly select providers and models based on their capabilities and pricing.

4. Handle errors gracefully Always use try-catch to manage potential parsing failures.

1try {
2  const result = await Assistant.requestStructuredData(prompt, schema, {
3    provider: { custom: "my-api" },
4    modelId: "my-model"
5  })
6  console.log("Parsed result:", result)
7} catch (err) {
8  console.error("Failed to parse structured data:", err)
9}