Skip to content

Commit 405ebd7

Browse files
arun-venkataswamyarun-venkataswamy
authored
Merge pull request #7 from Zipstack/documentation-changes
Added Javascript client library documentation
2 parents 8925ac3 + 0303383 commit 405ebd7

File tree

3 files changed

+136
-152
lines changed

3 files changed

+136
-152
lines changed

‎docs/documentation.md

Lines changed: 119 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,142 @@
1-
# LLMWhispererClient Module
1+
# LLMWhisperer JavaScript Client
22

3-
## Overview
4-
This module provides the `LLMWhispererClient` class to interact with the LLMWhisperer API and the `LLMWhispererClientException` class to handle exceptions that may occur during API interactions.
3+
:::note
4+
This documentation is for the V2 version of the LLMWhisperer API. The corresponding Javascript/NodeJS client version is `2.x.y`. V1 and V2 are not backward compatible.
5+
:::
56

7+
This Javascript client provides a simple and efficient way to interact with the LLMWhisperer API. LLMWhisperer is a technology that presents data from complex documents (different designs and formats) to LLMs in a way that they can best understand.
8+
9+
## Features
10+
11+
- Easy to use Javascript interface.
12+
- Handles all the HTTP requests and responses for you.
13+
- Raises Javascript exceptions for API errors.
14+
15+
## Installation
16+
17+
```bash
18+
npm install llmwhisperer-client
19+
```
620

721
## Environment Variables
8-
These environment variables can be used to configure the client but are **optional**. You may use them to override the default values. If `LLMWHISPERER_API_KEY` is not set, you must provide the API key in the options object when creating a new client.
9-
10-
* `LLMWHISPERER_API_KEY`: The API key to use for authenticating requests to the API.
11-
* `LLMWHISPERER_BASE_URL` : The base URL of the API.
12-
* `LLMWHISPERER_LOG_LEVEL` : The logging level to use. Possible values are `error`, `warn`, `info`, `debug`
13-
14-
## Classes
15-
16-
### LLMWhispererClientException
17-
This class extends the built-in `Error` class to handle exceptions specific to the LLMWhisperer API.
18-
19-
#### Constructor
20-
- `constructor(message, statusCode)`
21-
- `message` (string): The error message.
22-
- `statusCode` (number): The HTTP status code.
23-
24-
#### Methods
25-
- `errorMessage()`
26-
- Returns the error message.
27-
28-
### LLMWhispererClient
29-
Represents a client for the LLMWhisperer API.
30-
31-
#### Constructor
32-
- `constructor({ baseUrl = '', apiKey = '', apiTimeout = 120, loggingLevel = '' } = {})`
33-
- `baseUrl` (string): The base URL for the API.
34-
- `apiKey` (string): The API key for authentication.
35-
- `apiTimeout` (number): The timeout duration for API requests, in seconds.
36-
- `loggingLevel` (string): The logging level (e.g., 'debug', 'info', 'warn', 'error').
37-
38-
#### Properties
39-
- `baseUrl` (string): The base URL for the API.
40-
- `apiKey` (string): The API key used for authentication.
41-
- `apiTimeout` (number): The timeout for API requests.
42-
- `loggingLevel` (string): The logging level for the client.
43-
- `logger` (Object): The logger used by the client, initialized in the constructor.
44-
45-
## Methods
46-
47-
### getUsageInfo
48-
Retrieves usage information from the API.
49-
50-
- `async getUsageInfo()`
51-
- **Returns**: A promise that resolves to an object containing usage information.
52-
53-
### whisper
54-
Processes a file using the whisper API.
55-
56-
- `async whisper({ filePath = '', url = '', processingMode = 'ocr', outputMode = 'line-printer', pageSeparator = '<<<', forceTextProcessing = false, pagesToExtract = '', timeout = 200, storeMetadataForHighlighting = false, medianFilterSize = 0, gaussianBlurRadius = 0, ocrProvider = 'advanced', lineSplitterTolerance = 0.4, horizontalStretchFactor = 1.0 } = {})`
57-
- `filePath` (string): The path to the file to be processed.
58-
- `url` (string): The URL of the file to be processed.
59-
- `processingMode` (string): The mode of processing, e.g., 'ocr'.
60-
- `outputMode` (string): The mode of output, e.g., 'line-printer'.
61-
- `pageSeparator` (string): The separator for pages in the output.
62-
- `forceTextProcessing` (boolean): Whether to force text processing.
63-
- `pagesToExtract` (string): The specific pages to extract.
64-
- `timeout` (number): The timeout for the request, in seconds.
65-
- `storeMetadataForHighlighting` (boolean): Whether to store metadata for highlighting.
66-
- `medianFilterSize` (number): The size of the median filter.
67-
- `gaussianBlurRadius` (number): The radius of the Gaussian blur.
68-
- `ocrProvider` (string): The OCR provider to use.
69-
- `lineSplitterTolerance` (number): The tolerance for splitting lines.
70-
- `horizontalStretchFactor` (number): The horizontal stretch factor.
71-
- **Returns**: A promise that resolves to the response from the whisper API.
72-
- **Throws**: `LLMWhispererClientException` if there is an error in the request.
73-
74-
### whisperStatus
75-
Retrieves the status of a whisper operation using the provided whisper hash.
76-
77-
- `async whisperStatus(whisperHash)`
78-
- `whisperHash` (string): The hash of the whisper operation whose status is to be retrieved.
79-
- **Returns**: A promise that resolves with an object containing the status of the whisper operation.
80-
- **Throws**: `LLMWhispererClientException` if an error occurs during the operation.
81-
82-
### whisperRetrieve
83-
Retrieves the result of a whisper operation using the provided whisper hash.
84-
85-
- `async whisperRetrieve(whisperHash)`
86-
- `whisperHash` (string): The hash of the whisper operation whose result is to be retrieved.
87-
- **Returns**: A promise that resolves with an object containing the result of the whisper operation.
88-
- **Throws**: `LLMWhispererClientException` if an error occurs during the operation.
89-
90-
### highlightData
91-
Highlights the specified text in the result of a whisper operation using the provided whisper hash.
92-
93-
- `async highlightData(whisperHash, searchText)`
94-
- `whisperHash` (string): The hash of the whisper operation whose result is to be highlighted.
95-
- `searchText` (string): The text to be highlighted.
96-
- **Returns**: A promise that resolves with an object containing the response from the highlight operation.
97-
- **Throws**: `LLMWhispererClientException` if an error occurs during the operation.
98-
99-
## Usage Example
100-
Setup the client and use it to interact with the API.
22+
| Variable | Description |
23+
| --- | --- |
24+
| LLMWHISPERER_BASE_URL_V2 | The base URL of the API. When left undefined, default `https://llmwhisperer-api.unstract.com/api/v2` is used |
25+
| LLMWHISPERER_API_KEY | The API key to use for authenticating requests to the API. |
26+
| LLMWHISPERER_LOGGING_LEVEL | The logging level to use. Possible values are `error`, `warn`, `info`, `debug` |
27+
28+
All environment variables are optional. If `LLMWHISPERER_API_KEY` is not set, you must provide the API key when creating a new client. The environment variables can be overridden by providing the values in the client constructor.
29+
30+
## Usage
31+
10132
```javascript
102-
const { LLMWhispererClient, LLMWhispererClientException } = require('llmwhisperer');
33+
const { LLMWhispererClientV2 } = require("llmwhisperer-client");
34+
35+
// Create a new client
36+
37+
const options = {
38+
baseUrl: "<base URL>",
39+
apiKey: "<API key>",
40+
loggingLevel: "info",
41+
};
42+
43+
// All the option keys are optional
44+
// apiKey is required if LLMWHISPERER_API_KEY environment variable is not set
45+
const client = new LLMWhispererClientV2(options);
46+
//or
47+
const client = new LLMWhispererClientV2();
10348

104-
const client = new LLMWhispererClient({ apiKey: 'your-api-key' });
10549
```
10650

107-
Let's get the usage information
51+
### Manual polling for the result
10852

10953
```javascript
110-
(async () => {
111-
try {
112-
const usageInfo = await client.getUsageInfo();
113-
console.log('Usage Info:', usageInfo);
114-
} catch (error) {
115-
if (error instanceof LLMWhispererClientException) {
116-
console.error('LLMWhispererClientException:', error.errorMessage());
117-
} else {
118-
console.error('Unexpected Error:', error);
119-
}
120-
}
121-
})();
54+
// Simplest use with a file path as input
55+
whisper = await client.whisper({
56+
filePath: 'sample_files/restaurant_invoice_photo.pdf'
57+
});
58+
// or with more options set
59+
whisper = await client.whisper({
60+
filePath: 'sample_files/credit_card.pdf',
61+
mode: 'high_quality',
62+
pagesToExtract: '1-2',
63+
});
64+
65+
// Poll for the status
66+
// whisper_hash is available in the 'whisper_hash' field of the result of the whisper operation
67+
whisper_status = await client.whisperStatus(whisper.whisper_hash);
68+
69+
// Retrieve the result
70+
whisper_result = await client.whisperRetrieve(whisper.whisper_hash);
12271
```
12372

124-
Let's process a file using the whisper API
73+
### Wait for completion in sync mode
74+
Note that this is a blocking call and will wait for the extraction to complete.
12575

12676
```javascript
127-
(async () => {
128-
try {
129-
const whisperResponse = await client.whisper({ filePath: 'path/to/file.pdf' });
130-
console.log('Whisper Response:', whisperResponse);
131-
} catch (error) {
132-
if (error instanceof LLMWhispererClientException) {
133-
console.error('LLMWhispererClientException:', error.errorMessage());
134-
} else {
135-
console.error('Unexpected Error:', error);
136-
}
137-
}
138-
})();
77+
whisper = await client.whisper({
78+
filePath: 'sample_files/restaurant_invoice_photo.pdf',
79+
waitForCompletion: true,
80+
waitTimeout: 120,
81+
});
13982
```
83+
## API
14084

141-
LLMWhisperer supports async extractions. So when a timeout occurs, LLMWhisperer will return `202` status code along with a whisper-hash. You can use this hash to check the status of the extraction. Once the extraction is complete, you can retrieve the result.
85+
The LLMWhisperer provides the following methods which are analogous to the API endpoints:
14286

143-
> Note that there is a system-wide timeout of 200 seconds and if the extraction is not complete within this time, the extraction will switch to async mode and you will have to use the retrieve method to fetch the extracted text
87+
- `whisper`: Performs a whisper operation.
88+
- `whisperStatus`: Retrieves the status of a whisper operation.
89+
- `whisperRetrieve`: Retrieves the result of a whisper operation.
90+
- `getUsageInfo`: Retrieves the usage information of the LLMWhisperer API.
91+
- `registerWebhook`: Registers a webhook URL for receiving whisper results.
92+
- `getWebhookDetails`: Retrieves the details of a registered webhook.
14493

145-
```javascript
146-
whisper = await client.whisper({
147-
filePath: 'sample_files/credit_card.pdf',
148-
timeout: 1, //Forcing a 1 second timeout for testing
149-
});
150-
//Keep checking the status until it is completed
151-
statusX = whisper.status;
152-
while (statusX === 'processing') {
153-
console.log('Processing... '+whisper['whisper-hash']);
154-
//Let's check every second
155-
await new Promise(r => setTimeout(r, 1000));
156-
whisperStatus = await client.whisperStatus(whisper['whisper-hash']);
157-
statusX = whisperStatus.status;
94+
## Error Handling
95+
96+
Errors are handled by the LLMWhispererClientException class. This class extends the built-in Error class and adds a `statusCode` property.
97+
98+
## Result format
99+
100+
### `whisper`
101+
102+
The `whisper` method returns a dictionary
103+
104+
#### For Asyn operation (default)
105+
106+
```json
107+
{
108+
"message": "Whisper Job Accepted",
109+
"status": "processing",
110+
"whisper_hash": "XXX37efd|XXXXXXXe92b30823c4ed3da759ef670f",
111+
"status_code": 202,
112+
"extraction": {}
158113
}
159-
if (statusX === 'processed') {
160-
//Retrieve the result
161-
whisper = await client.whisperRetrieve(whisper['whisper-hash']);
162-
console.log(whisper);
163-
} else {
164-
console.log('Error');
114+
```
115+
The `whisper_hash` can be used to check the status of the extraction and retrieve the result. `extraction` will be empty for async operations.
116+
117+
#### For Sync operation
118+
119+
```json
120+
{
121+
"message": "Whisper Job Accepted",
122+
"status": "processed",
123+
"whisper_hash": "XXX37efd|XXXXXXXe92b30823c4ed3da759ef670f",
124+
"status_code": 200,
125+
"extraction": {
126+
"confidence_metadata" : [],
127+
"line_metadata" : [],
128+
"metadata" : {},
129+
"result_text" : "<Extracted Text>",
130+
"webhook_metadata" : ""
131+
}
165132
}
166133
```
167134

135+
## Dependencies
136+
137+
- axios: Used for making HTTP requests.
138+
- winston: Used for logging.
139+
140+
## License
168141

142+
This project is licensed under the MIT License.

‎index.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -703,6 +703,16 @@ class LLMWhispererClientV2 {
703703
}
704704
}
705705

706+
/**
707+
* @function
708+
* @name getWebhookDetails
709+
* @description This function retrieves the details of a webhook.
710+
* @async
711+
* @param {string} webhookName - The name of the webhook.
712+
* @returns {Promise<Object>} Returns a promise that resolves with an object containing the details of the webhook. The object includes the status code and the response data.
713+
* @throws {LLMWhispererClientException} Throws an LLMWhispererClientException if an error occurs during the operation.
714+
*
715+
*/
706716
async getWebhookDetails(webhookName) {
707717
const apiUrl = `${this.baseUrl}/whisper-manage-callback`;
708718
const params = { webhook_name: webhookName };

‎test/test_v2.js

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ const client = new LLMWhispererClientV2();
88
(async () => {
99
// usage_info = await client.getUsageInfo();
1010
// console.log(usage_info);
11-
//whisper = await client.whisper({filePath: 'sample_files/restaurant_invoice_photo.pdf'});
11+
whisper = await client.whisper({filePath: 'data/restaurant_invoice_photo.pdf'});
1212
//whisper = await client.whisper({url: 'https://storage.googleapis.com/pandora-static/samples/bill.jpg.pdf'});
1313
// whisper = await client.whisper({
1414
// filePath: 'sample_files/credit_card.pdf',
1515
// processingMode: 'text',
1616
// forceTextProcessing: true,
1717
// pagesToExtract: '1-2',
1818
// });
19-
//console.log(whisper);
19+
console.log(whisper);
2020

2121
//b4c25f17|5f1d285a7cf18d203de7af1a1abb0a3a
2222
//whisper_status = await client.whisperStatus('b4c25f17|5f1d285a7cf18d203de7af1a1abb0a3a');
@@ -37,11 +37,11 @@ const client = new LLMWhispererClientV2();
3737
//result = await client.getWebhookDetails('wb4');
3838
//console.log(result);
3939

40-
whisper = await client.whisper({
41-
filePath: "data/restaurant_invoice_photo.pdf",
42-
useWebhook: "wb4",
43-
webhookMetadata: "Sample Metadata",
44-
});
40+
// whisper = await client.whisper({
41+
// filePath: "data/restaurant_invoice_photo.pdf",
42+
// useWebhook: "wb4",
43+
// webhookMetadata: "Sample Metadata",
44+
// });
4545

4646
// whisper = await client.whisper({
4747
// filePath: 'sample_files/credit_card.pdf',

0 commit comments

Comments
 (0)