Creates an instance of the Assistant class.
The AssistantOptions for targeting the assistant.
The Pinecone configuration object containing an API key and other configuration parameters needed for API calls.
Readonly_chatReadonly_chatReadonly_chatReadonly_chatReadonly_contextReadonly_deleteReadonly_describeReadonly_describeReadonly_listReadonly_listReadonly_uploadReadonly_upsertSends a message to the assistant and receives a response. Retries the request if the server fails.
This is the recommended way to chat with an assistant: it offers more functionality and control over the assistant's responses and references (e.g. structured citations) than the OpenAI-compatible chatCompletion interface.
A ChatOptions object containing the message and optional parameters to send to the assistant, including contextOptions for controlling multimodal content.
A promise that resolves to a ChatModel object containing the response from the assistant.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const chatResp = await assistant.chat({messages: [{role: 'user', content: "What is the capital of France?"}]});
// {
// id: '000000000000000023e7fb015be9d0ad',
// finishReason: 'stop',
// message: {
// role: 'assistant',
// content: 'The capital of France is Paris.'
// },
// model: 'gpt-4o-2024-05-13',
// citations: [ { position: 209, references: [Array] } ],
// usage: { promptTokens: 493, completionTokens: 38, totalTokens: 531 }
// }
Sends a message to the assistant and receives a response that is compatible with [OpenAI's Chat Completion API](https://platform.openai.com/docs/guides/text-generation. Retries the request if the server fails.
This interface is useful when you need inline citations or OpenAI-compatible responses, but has limited functionality compared to chat, which is the recommended interface for chatting with an assistant.
A ChatCompletionOptions object containing the message and optional parameters to send to an assistant.
A promise that resolves to a ChatCompletionModel object containing the response from the assistant.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const chatCompletion = await assistant.chatCompletion({ messages: [{ role: 'user', content: 'What is the capital of France?' }]});
console.log(chatCompletion);
// {
// id: "response_id",
// choices: [
// {
// finishReason: "stop",
// index: 0,
// message: {
// role: "assistant",
// content: "The data mentioned is described as \"some temporary data\" [1].\n\nReferences:\n1. [test-chat.txt](https://storage.googleapis.com/knowledge-prod-files/your_file_resource) \n"
// }
// }
// ],
// model: "gpt-4o-2024-05-13",
// usage: {
// promptTokens: 371,
// completionTokens: 19,
// totalTokens: 390
// }
// }
Sends a message to the assistant and receives a streamed response as ChatStream
A ChatCompletionOptions object containing the message and optional parameters to send to an assistant.
A promise that resolves to a ChatStream
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const chatStream = await assistant.chatCompletionStream({messages: [{role: 'user', content: "What is the capital of France?"}]});
// stream the response and log each chunk
for await (const chunk of newStream) {
if (chunk.choices.length > 0 && chunk.choices[0].delta.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}
// { id: 'response_id', choices: [{ index: 0, delta: { role: 'assistant' }, finishReason: null }], model: 'gpt-4o-2024-05-13', usage: null }
// { id: 'response_id', choices: [{ index: 0, delta: { content: 'The' }}, finishReason: null }], model: 'gpt-4o-2024-05-13', usage: null }
// { id: 'response_id', choices: [{ index: 0, delta: { content: ' test' }}, finishReason: null }], model: 'gpt-4o-2024-05-13', usage: null }
// { id: 'response_id', choices: [], model: 'gpt-4o-2024-05-13', usage: { promptTokens: 371, completionTokens: 48, totalTokens: 419 }}
Sends a message to the assistant and receives a streamed response as ChatStream
A ChatOptions object containing the message and optional parameters to send to the assistant.
A promise that resolves to a ChatStream
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const chatStream = await assistant.chatStream({ messages: [{ role: 'user', content: 'What is the capital of France?'}]});
// stream the response and log each chunk
for await (const chunk of newStream) {
console.log(chunk);
}
// each chunk will have a variable shape depending on the type:
// { type:"message_start", id:"response_id", model:"gpt-4o-2024-05-13", role:"assistant"}
// { type:"content_chunk", id:"response_id", model:"gpt-4o-2024-05-13", delta:{ content:"The"}}
// { type:"content_chunk", id:"response_id", model:"gpt-4o-2024-05-13", delta:{ content:" test"}}
// { type:"message_end", id:"response_id", model:"gpt-4o-2024-05-13", finishReason:"stop",usage:{ promptTokens:371,completionTokens:48,totalTokens:419}}
Retrieves the context snippets used by an assistant during the retrieval process.
A ContextOptions object containing the query or messages, optional filter, and optional multimodal parameters.
A promise that resolves to a ContextModel object containing the context snippets.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const response = await assistant.context({query: "What is the capital of France?"});
console.log(response);
// {
// snippets: [
// {
// type: 'text',
// content: 'The capital of France is Paris.',
// score: 0.9978925,
// reference: [Object]
// },
// ],
// usage: { promptTokens: 527, completionTokens: 0, totalTokens: 527 }
// }
Deletes a file uploaded to an assistant by ID.
This is an asynchronous operation: the returned OperationModel can be polled for completion via describeOperation.
The ID of the file to delete.
A promise that resolves to an OperationModel describing the async delete operation.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const files = await assistant.listFiles();
if (files.files) {
const fileId = files.files[0].id;
await assistant.deleteFile(fileId);
}
Describes a file uploaded to an assistant.
The ID of the file to describe.
Whether to include the signed URL in the response. Defaults to true.
A promise that resolves to a AssistantFileModel object containing the file details.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
const files = await assistant.listFiles();
let fileId: string;
if (files.files) {
fileId = files.files[0].id;
} else {
fileId = '';
}
const resp = await assistant.describeFile({fileId: fileId})
console.log(resp);
// {
// name: 'test-file.txt',
// id: '1a56ddd0-c6d8-4295-80c0-9bfd6f5cb87b',
// metadata: undefined,
// createdOn: 2025-01-06T19:14:21.969Z,
// updatedOn: 2025-01-06T19:14:36.925Z,
// status: 'Available',
// percentDone: 1,
// signedUrl: undefined,
// errorMessage: undefined
// }
Describes an async operation (such as a file upload or delete) performed on the assistant. Use this to poll the status of an OperationModel returned by uploadFile, upsertFile, or deleteFile.
The ID of the operation to describe.
A promise that resolves to an OperationModel describing the operation.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistant = pc.assistant({ name: 'test1' });
const operation = await assistant.uploadFile({ path: 'report.pdf' });
const status = await assistant.describeOperation(operation.id);
console.log(status.status); // 'Processing' | 'Completed' | 'Failed'
Lists files (with optional filter) uploaded to an assistant.
Optionaloptions: ListFilesOptionsA ListFilesOptions object containing optional parameters to filter the list of files.
A promise that resolves to a AssistantFilesList object containing a list of files.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistantName = 'test1';
const assistant = pc.assistant({ name: assistantName });
// Metadata fields are referenced at the top level — not wrapped in a `metadata` key.
// See https://docs.pinecone.io/guides/data/filter-with-metadata for operators ($eq, $ne, $gt, $lt, $in).
const files = await assistant.listFiles({ filter: { version: { $eq: 'v1' } } });
console.log(files);
// {
// files: [
// {
// name: 'temp-file.txt',
// id: '1a56ddd0-c6d8-4295-80c0-9bfd6f5cb87b',
// metadata: undefined,
// createdOn: 2025-01-06T19:14:21.969Z,
// updatedOn: 2025-01-06T19:14:36.925Z,
// status: 'Available',
// percentDone: 1,
// signedUrl: undefined,
// errorMessage: undefined
// }
// ]
// }
Lists the async operations (such as file uploads and deletes) performed on the assistant, with optional filters. Returns operations that are in progress, as well as recently completed or failed operations. Both successful and failed operations are retained for 30 days after completion.
Optionaloptions: ListOperationsOptionsAn optional ListOperationsOptions object to filter and paginate the operations.
A promise that resolves to an OperationList object containing the list of operations.
Uploads a file to an assistant.
Accepts either a local file path or an in-memory Buffer, Blob, or
Node.js ReadableStream. Use the file + fileName form to forward an
incoming HTTP upload stream directly to the assistant without writing it
to disk or buffering the entire file in memory.
A UploadFileOptions object. Provide either
path (local file path) or file (Uploadable) + fileName,
along with optional metadata and multimodal flags.
A promise that resolves to an OperationModel describing the async upload operation. Use operation.fileId to track the file once processing begins.
Upload from a local path:
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistant = pc.Assistant({ name: 'my-assistant' });
await assistant.uploadFile({ path: 'report.pdf', metadata: { category: 'reports' } });
Upload from a Buffer (e.g. from multer memory storage):
// req.file.buffer is a Buffer provided by multer
await assistant.uploadFile({
file: req.file.buffer,
fileName: req.file.originalname,
});
Upload from a ReadableStream (zero server-side buffering):
// Forward an incoming upload stream directly — no disk write, no memory spike.
// Note: automatic retries are disabled for stream inputs because the stream
// is consumed after the first read and cannot be replayed.
await assistant.uploadFile({
file: req.file.stream, // e.g. from busboy / @fastify/multipart
fileName: req.file.filename,
});
Creates or replaces a file on an assistant at a caller-supplied file ID.
If a file with the given assistantFileId already exists, its content is
replaced; otherwise a new file is created with that identifier. This makes
upsert idempotent by ID — useful when you own the ID space, e.g. mirroring
your own document IDs into the assistant or re-syncing a changed source
document to the same ID.
Contrast with uploadFile, which always creates a new file with a
server-generated ID and additionally supports metadata. upsertFile
does not accept metadata.
Accepts the same file inputs as uploadFile — a local file path or
an in-memory Buffer, Blob, or Node.js ReadableStream. Like upload,
this is asynchronous: poll the returned operation with
describeOperation to track completion.
An UpsertFileOptions object. Provide the
assistantFileId to create or replace, along with either path
(local file path) or file (Uploadable) + fileName, and an
optional multimodal flag.
A promise that resolves to an OperationModel describing the async upsert operation.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const assistant = pc.assistant({ name: 'my-assistant' });
// Create-or-replace the file at this ID with new content.
const operation = await assistant.upsertFile({
assistantFileId: '1a56ddd0-c6d8-4295-80c0-9bfd6f5cb87b',
path: 'report.pdf',
});
const status = await assistant.describeOperation(operation.id);
The
Assistantclass holds the data plane methods for interacting with Assistants.This class can be instantiated through a Pinecone object, and is used to interact with a specific assistant.
Example