Description

n8n-nodes-pinecone-assistant

This is the official n8n community node for interacting with Pinecone Assistant in your workflows.

Pinecone Assistant allows you to build production-grade chat and agent-based applications quickly. It abstracts the complexities of implementing retrieval-augmented (RAG) systems by managing the chunking, embedding, storage, query planning, vector search, model orchestration, and reranking for you.

Installation

Follow the installation guide in the n8n community nodes documentation.

Operations

Assistants

#### List Assistants

Retrieves a list of all Pinecone Assistants in your project. Use this operation to discover available assistants or populate assistant selection fields in your workflows.

##### Fields

• Additional Fields:

– Source Tag (optional): Specify a source tag to attribute usage to this integration. This is primarily used for Pinecone integration partners. Read more in the Pinecone documentation.

##### Output

Returns an array of assistant objects containing assistant names and host URLs.

Files

#### List Files

Retrieves all files associated with a specific Pinecone Assistant. Use this to see what files are available in an assistant, filter files by metadata, or verify file uploads.

##### Fields

• Assistant Name (required): The name of the Pinecone Assistant to query. This list is populated dynamically based on your available assistants.
• Additional Fields:

– Metadata Filter (optional): Limit the list of files to only those matching the metadata filter. Add key-value pairs to filter by specific metadata.
– Advanced Metadata Filter (JSON) (optional): Use advanced metadata filtering when you need support for operators like $or, $ne, $in, etc. Provide a JSON object with filter expressions. Learn more about metadata filter expressions in the Pinecone documentation.
– Source Tag (optional): Specify a source tag to attribute usage to this integration. This is primarily used for Pinecone integration partners. Read more in the Pinecone documentation.

Note: Only one of Metadata Filter or Advanced Metadata Filter can be set, not both.

##### Output

Returns an array of file objects with their metadata and external file IDs.

#### Upload File

Uploads a new file to a Pinecone Assistant. Assistant automatically chunks, embeds, and indexes the file for retrieval. Use this to add new documents or content to your assistant’s knowledge.

##### Fields

• Assistant Name (required): The name of the Pinecone Assistant to upload the file to. This list is populated dynamically based on your available assistants.
• External File ID (required): A unique identifier for the file in the Pinecone Assistant. This should be unique for each file.
• Input Data Field Name (required): The name of the field in the input item that contains the file data. Default is “data”.
• Additional Fields:

– Metadata (optional): A collection of key-value pairs to add as metadata to the file. This metadata can be used later for filtering files or context snippets.
– Source Tag (optional): Specify a source tag to attribute usage to this integration. This is primarily used for Pinecone integration partners. Read more in the Pinecone documentation.

Note: There is no need to specify External File ID in the metadata field directly as this operation will make sure it’s set.

##### Output

Returns the uploaded file information.

#### Update File

Updates an existing file in a Pinecone Assistant. This operation deletes the existing file(s) with the specified external file ID and uploads the new version.

##### Fields

• Assistant Name (required): The name of the Pinecone Assistant containing the file to update. This list is populated dynamically based on your available assistants.
• External File ID (required): The external file ID of the file to update. If the existing file does not exist, a new file will be uploaded. Use this to refresh or modify content in your assistant’s knowledge base. If there are multiple files with the same external file ID, all will be updated.
• Input Data Field Name (required): The name of the field in the input item that contains the updated file data. Default is “data”.
• Additional Fields:

– Metadata (optional): A collection of key-value pairs to update the file’s metadata.
– Source Tag (optional): Specify a source tag to attribute usage to this integration. This is primarily used for Pinecone integration partners. Read more in the Pinecone documentation.

##### Output

Returns the updated file information.

#### Delete File

Deletes a file from a Pinecone Assistant. Use this to remove outdated or unwanted content from your assistant’s knowledge.

##### Fields

• Assistant Name (required): The name of the Pinecone Assistant containing the file to delete. This list is populated dynamically based on your available assistants.
• External File ID (required): The external file ID to identify the file in the Pinecone Assistant. If there are multiple files with the same external file ID, this operation will delete all of them.
• Additional Fields:

– Source Tag (optional): Specify a source tag to attribute usage to this integration. This is primarily used for Pinecone integration partners. Read more in the Pinecone documentation.

##### Output

Returns a confirmation object with deleted: true.

Context Snippets

#### Get Context Snippets

Retrieves relevant context snippets from a Pinecone Assistant based on a query. This is the core RAG (Retrieval-Augmented Generation) operation that finds and returns the most relevant chunks of text from your assistant’s files that match your query. Use this to provide context to LLMs or to retrieve relevant information for your applications.

##### Fields

• Assistant Name (required): The name of the Pinecone Assistant to query for context snippets. This list is populated dynamically based on your available assistants.
• Query (required): The query text used to retrieve relevant context snippets. This is the search term that will be used to find matching content in your assistant’s files.
• Additional Fields:

– Include Multimodal Context (optional): Whether to include multimodal context snippets. Default is true. When enabled, the assistant will return multimodal context snippets (e.g., images from PDFs) in addition to text snippets.
– Include Binary Content (optional): Whether to include binary content with multimodal context snippets. Default is true. Only applies when Include Multimodal Context is enabled. When enabled, binary content (e.g., base64 image data) will be included in the response.
– Metadata Filter (optional): Limit the context snippets to only those from files matching the metadata filter. Add key-value pairs to filter by specific metadata.
– Snippet Size (optional): The maximum context snippet size in tokens. Default is 2048.
– Top K (optional): The maximum number of context snippets to return. Default is 16.
– Advanced Metadata Filter (JSON) (optional): Use advanced metadata filtering when you need support for operators like $or, $ne, $in, etc. Provide a JSON object with filter expressions. Learn more about metadata filter expressions in the Pinecone documentation.
– Source Tag (optional): Specify a source tag to attribute usage to this integration. This is primarily used for Pinecone integration partners. Read more in the Pinecone documentation.

Note: Only one of Metadata Filter or Advanced Metadata Filter can be set, not both.

##### Output

Returns an array of context snippets with their text or image content, relevance scores, references, and associated metadata.

Credentials

To use the Pinecone Assistant node, you’ll need a Pinecone account and an API key. You can get started for free on the Starter plan (refer to current pricing and limits for more info).

1. Sign up for a Pinecone account
2. Create an API key

Compatibility

This node was tested locally against n8n 2.9.4.

Usage

Refer to our Pinecone Assistant quickstart for n8n to get started with a pre-built workflow using this node, an Assistant, and Open AI.

Version history

• V1 – Initial version of the Pinecone Assistant node
• V1.2 – Deprecates the pineconeAssistantApi credential in favor of pineconeApi

Node development

To develop, build, and run this node locally, use the n8n-node cli tool or pnpm. For more info on n8n-node, refer here.

1. Install dependencies

$ cd n8n-nodes-pinecone-assistant
$ pnpm install

2. Build the node

This compiles Typescript files and bundles project assets into the dist folder.

$ pnpm run build

Running this will clean the dist folder.

3. Test the node

This runs a local instance of n8n with the node. It watches the project directory and automatically rebuilds when changes are detected.

$ pnpm run dev

Head over to http://localhost:5678 to test the node in a workflow.

4. Run tests

Run the unit test suite.

$ pnpm test

5. Versioning the node

When making changes to a version of the node, ensure backwards compatibility with the current version as all existing workflows will use the previous version until it is manually migrated. If it cannot be backwards compatible, create a new version of the node:

• In PineconeAssistant.node.ts, change defaultVersion to the new version number
• In PineconeAssistant.node.ts, update the list of nodeVersions
• Add a new version directory, named v# (i.e. v2)
• In the new version directory, add the versioned node, PineconeAssistantV2.node.ts and all the functionality.

Note: It is possible to continue using the previous version’s functionality and configure per version using displayOptions, etc. See version 1.2.

6. Release the node and publish to npm

Releases are performed via the Release: NPM Package GitHub Actions workflow. The workflow:

• Lints and builds the project
• Bumps the version in package.json (patch, minor, or major)
• Updates nodes/PineconeAssistant/version.json
• Regenerates CHANGELOG.md with auto-changelog
• Commits the changes and creates a git tag
• Builds again (so the published package contains the new version)
• Publishes to npm with provenance
• Pushes the commit and tag to the repository
• Creates a draft GitHub release

To release a new version:

1. Open the Actions tab in the repository, select Release: NPM Package, and click Run workflow.
2. Optionally choose a branch to release from (default is the repository default branch).
3. Choose the release type: patch (bug fixes), minor (new features, backwards compatible), or major (breaking changes).
4. Run the workflow. It uses the npm-publish environment; ensure npm trusted publishing (or your chosen auth) is configured for that environment.
5. After the run completes, publish the draft GitHub release from the Releases page if you use GitHub releases.

Contributing

We welcome contributions! Please feel free to:

• Submit issues and bug reports
• Propose new features and improvements
• Contribute code via pull requests
• Share your use cases and success stories

License

This project is licensed under the MIT License – see the LICENSE file for details.