# pinecone-plugin-assistant

> Assistant plugin for Pinecone SDK

- **URL**: https://www.freshcrate.ai/projects/pinecone-plugin-assistant
- **Author**: Pinecone Systems
- **Category**: AI Agents
- **Latest version**: `3.0.3` (2026-04-21)
- **License**: Apache-2.0
- **Homepage**: https://pypi.org/project/pinecone-plugin-assistant/
- **Language**: Python
- **Registry**: pypi (`pinecone-plugin-assistant`)
- **Tags**: `pypi`

## Description

# Assistant

Interact with Pinecone's Assistant APIs, e.g. create, manage, and chat with assistants (currently in beta). Pinecone Assistant is also available in the [console](https://app.pinecone.io/).


## Quickstart
The following example highlights how to use an assistant to store and understand documents on a particular topic and chat with
the assistant about those documents with the ultimate goal of semantically understanding your data.

```python
from pinecone import Pinecone
from pinecone_plugins.assistant.models.chat import Message

pc = Pinecone(api_key='<<PINECONE_API_KEY>>')

# Create an assistant (in this case we'll store documents about planets)
space_assistant = pc.assistant.create_assistant(assistant_name="space")

# Upload information to your assistant
space_assistant.upload_file("./space-fun-facts.pdf")

# Once the upload succeeded, ask the assistant a question
msg = Message(content="How old is the earth?")
resp = space_assistant.chat_completions(messages=[msg])
print(resp)

# {'choices': [{'finish_reason': 'stop',
# 'index': 0,
# 'message': {'content': 'The age of the Earth is estimated to be '
#                         'about 4.54 billion years, based on '
#                         'evidence from radiometric age dating of '
#                         'meteorite material and Earth rocks, as '
#                         'well as lunar samples. This estimate has '
#                         'a margin of error of about 1%.',
#             'role': 'assistant'}}],
# 'id': '00000000000000001a377ceeaabf3c18',

```

## Assistants API

### Create Assistant
To create an assistant, see the below example. This API creates a assistant with the specified name, metadata, and optional timeout settings.

```python
from pinecone import Pinecone

pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
metadata = {"author": "Jane Doe", "version": "1.0"}

assistant = pc.assistant.create_assistant(
    assistant_name="example_assistant", 
    instructions="Always use British English spelling and vocabulary.",
    metadata=metadata,
    timeout=30
)
```

Arguments:
- `assistant_name` The name to assign to the assistant. 
    - type: `str`
- `instructions`  Custom instructions for the assistant. These will be applied to all future chat interactions.
    - type: `Optional[str] = None` 
- `metadata`: A dictionary containing metadata for the assistant.
    - type: `Optional[dict[str, any]] = None`
- `timeout`: Specify the number of seconds to wait until assistant operation is completed. 
    - If None, wait indefinitely until operation completes
    - If >=0, time out after this many seconds
    - If -1, return immediately and do not wait. 
    - type: `Optional[int] = None`

Returns:
- `AssistantModel` object with the following properties:
    - `name`: Contains the name of the assistant.
    - `instructions`  Custom instructions for the assistant.
    - `metadata`: Contains the provided metadata.
    - `created_at`: Contains the timestamp of when the assistant was created.
    - `updated_at`: Contains the timestamp of when the assistant was last updated.
    - `status`: Contains the status of the assistant. This is one of:
        - 'Initializing'
        - 'Ready'
        - 'Terminating'
        - 'Failed'

### Describe Assistant
The example below describes/fetches an assistant with the specified name. Will raise a 404 if no model exists with the specified name. There are two methods for this:

```python
from pinecone import Pinecone

pc = Pinecone(api_key='<<PINECONE_API_KEY>>')

assistant = pc.assistant.describe_assistant(
    assistant_name="example_assistant", 
)

# we can also do this
assistant = pc.assistant.Assistant(
    assistant_name="example_assistant", 
)
```
Arguments:
- `assistant_name`: The name of the assistant to fetch.
    - type: `str`, required

Returns:
- `AssistantModel` see [Create Assistant](#create-assistant)

### Update Assistant
To update an assistant's metadata and/or instructions, see the below example.

```python
from pinecone import Pinecone

pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
metadata = {"author": "Jane Doe", "version": "2.0"}

assistant = pc.assistant.update_assistant(
    assistant_name="example_assistant", 
    instructions="Always use Australian English spelling and vocabulary.",
    metadata=metadata,
)
```

Arguments:
- `assistant_name`: The name of the assistant to fetch.
    - type: `str`, required
- `instructions`  Custom instructions for the assistant. These will be applied to all future chat interactions.
    - type: `Optional[str] = None`
- `metadata`: A dictionary containing metadata for the assistant. If provided, it will completely replace the existing metadata unless set to `None` (default).
    - type: `Optional[dict[str, any]] = None`

Returns:
- `AssistantModel` see [Create Assistant](#create-assistant)


### List Assistants
Lists all assistants created from the current project. Will raise a 404 if no assistant exists with the specified name.

```python
from pinecon

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `3.0.3` | 2026-04-21 | Low | Imported from PyPI (3.0.3) |

## Citation

- HTML: https://www.freshcrate.ai/projects/pinecone-plugin-assistant
- Markdown: https://www.freshcrate.ai/projects/pinecone-plugin-assistant.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/pinecone-plugin-assistant/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._