This guide shows you how to set up and use Pinecone Assistant, a service that allows you to upload documents, ask questions, and receive responses that reference your documents.

​
1. Install the Python SDK

You can use the Assistant API directly or via the Pinecone Python SDK.

To interact with Pinecone Assistant using the Python SDK, install the client and the pinecone-plugin-assistant package as follows:

pip install pinecone
pip install pinecone-plugin-assistant

​
2. Get an API key

You need an API key to make calls to your assistant.

Create a new API key in the Pinecone console, or use the widget below to generate a key. If you don’t have a Pinecone account, the widget will sign you up for the free Starter plan.

Your generated API key:

"{{YOUR_API_KEY}}"

​
3. Create an assistant

To create an assistant, use the create_assistant operation as in the following example:

Python
from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

assistant = pc.assistant.create_assistant(
    assistant_name="example-assistant", 
    instructions="Use American English for spelling and grammar.", # Description or directive for the assistant to apply to all responses.
    timeout=30 # Maximum seconds to wait for assistant status to become "Ready" before timing out.
)

​
4. Upload a file to the assistant

With Pinecone Assistant, you can upload documents, ask questions, and receive responses that reference your documents. This is known as retrieval-augmented generation (RAG).

For this quickstart, download a sample 10-k filing file to your local device.

Next, use the upload_file operation to upload the file to your assistant:

Python
from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

# Get the assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# Upload a file.
response = assistant.upload_file(
    file_path="/path/to/file/Netflix-10-K-01262024.pdf",
    metadata={"company": "netflix", "document_type": "form 10k"},
    timeout=None
)

​
5. Chat with the assistant

With the sample file uploaded, you can now ask the assistant questions about your document.

To chat with a Pinecone assistant, use the chat_assistant endpoint. It returns either a JSON object or a text stream.

The following example requests a JSON response to the message, “How many employees did Netflix have by the end of 2023?”:

Python
from pinecone import Pinecone
from pinecone_plugins.assistant.models.chat import Message

pc = Pinecone(api_key='YOUR_API_KEY')
assistant = pc.assistant.Assistant(assistant_name="example-assistant")

msg = Message(role="user", content="Who is the CFO of Netflix?")
resp = assistant.chat(messages=[msg])

print(resp)

The example above returns a response like the following:

{
    'citations': 
    [
        {
            'position': 72,
            'references': 
                [
                    {
                        'file': 
                        {
                            'created_on': '2024-11-04T18:11:52.243609916Z',
                            'id': 'b8a4e98e-56e8-4e51-b68c-4e5282770ecb', 
                            'metadata': None, 
                            'name': 'Netflix-10-K-01262024.pdf', 
                            'percent_done': 1.0, 
                            'signed_url': 'https://storage.googleapis.com/knowledge-prod-files/...', 
                            'error_message': None, 
                            'size': 1073470.0, 
                            'status': 'Available', 
                            'updated_on': '2024-11-04T18:12:29.663628217Z'
                            }, 
                            'pages': [5]
                            }
                        ]
                    }
                ],
 'finish_reason': 'stop',
 'id': '0000000000000000591358cd74e3e938',
 'message': 
 {
    'content': 'By the end of 2023, Netflix had approximately 13,000 ' 'full-time employees.', 
    'role': '"assistant"'
    }, 
    'model': 'gpt-4o-2024-05-13', 
    'usage': 
    {
        'completion_tokens': 28, 
        'prompt_tokens': 15111, 
        'total_tokens': 15139
    }
}

​
6. Clean up

When you no longer need the example-assistant, use the delete_assistant operation to delete it:

Deleting an assistant also deletes all files uploaded to the assistant.

Python
from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

pc.assistant.delete_assistant(
    assistant_name="example-assistant", 
)

​
Next steps

Was this page helpful?

Database quickstartKey features