| Name | vectara JSON |
| Version |
0.2.43
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2025-02-26 06:11:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.8 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Vectara Python SDK
[](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fvectara%2Fpython-sdk)
[](https://pypi.python.org/pypi/vectara)
The Vectara Python SDK provides convenient access to the Vectara API for building powerful AI applications.
---
## Installation
Install the library via pip:
```bash
pip install vectara
```
## Getting Started
### API Generated Documentation
API reference documentation is available [here](https://vectara.docs.buildwithfern.com/).
### Examples
Complete examples can be found in the [Getting Started notebooks](./examples/01_getting_started).
### Usage
First, create an SDK client.<br />
You can use either an `api_key` or OAuth (`client_id` and `client_secret`) for [authentication](https://docs.vectara.com/docs/console-ui/api-access-overview).
```python
from vectara import Vectara
# creating the client using API key
client = Vectara(
api_key="YOUR_API_KEY"
)
# creating the client using oauth credentials
client = Vectara(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
)
```
If you don't already have a corpus, you can create it using the SDK:
```python
client.corpora.create(name="my-corpus", key="my-corpus-key")
```
### Add a document to a corpus
You can add documents to a corpus in two formats: [structured](https://docs.vectara.com/docs/learn/select-ideal-indexing-api#structured-document-definition) or [core](https://docs.vectara.com/docs/learn/select-ideal-indexing-api#core-document-definition).<br/> For more information, refer to the [Indexing Guide](https://docs.vectara.com/docs/learn/select-ideal-indexing-api).
Here is an example for adding a Structured document
```python
from vectara import StructuredDocument, StructuredDocumentSection
client.documents.create(
corpus_key="my-corpus-key",
request=StructuredDocument(
id="my-doc-id",
type="structured",
sections=[
StructuredDocumentSection(
id="id_1",
title="A nice title.",
text="I'm a nice document section.",
metadata={'section': '1.1'}
),
StructuredDocumentSection(
id="id_2",
title="Another nice title.",
text="I'm another document section on something else.",
metadata={'section': '1.2'}
),
],
metadata={'url': 'https://example.com'}
),
)
```
And here is one with Core document:
```python
from vectara import CoreDocument, CoreDocumentPart
client.documents.create(
corpus_key="my-corpus-key",
request=CoreDocument(
id="my-doc-id",
type="core",
document_parts=[
CoreDocumentPart(
text="I'm a first document part.",
metadata={'author': 'Ofer'}
)
CoreDocumentPart(
text="I'm a second document part.",
metadata={'author': 'Adeel'}
)
],
metadata={'url': 'https://example.com'}
),
)
```
### Upload a file to the corpus
In addition to creating a document as shown above (using StructuredDocument or CoreDocument), you can also upload files (such as PDFs or Word Documents) directly to Vectara.
In this case Vectara will parse the files automatically, extract text and metadata, chunk them and add them to the corpus.
Using the SDK you need to provide both the file name, the binary content of the file, and the content_type, as follows:
```python
filename = "examples.pdf"
with open(filename, "rb") as f:
content = f.read()
client.upload.file(
'my-corpus-key',
file=content,
filename=filename,
metadata={"author": "Adeel"}
)
```
### Querying the corpora
With the SDK it's super easy to run a query from one or more corpora. For more detailed information, see this [Query API guide](https://docs.vectara.com/docs/api-reference/search-apis/search)
A query uses two important objects:
* The `SearchCorporaParameters` object defines parameters for search such as hybrid search, metadata filtering or reranking
* The `GenerationParameters` object defines parameters for the generative step.
Here is an example query for our corpus above:
```python
search = SearchCorporaParameters(
corpora=[
KeyedSearchCorpus(
corpus_key="my-corpus-key",
metadata_filter="",
lexical_interpolation=0.005,
)
],
context_configuration=ContextConfiguration(
sentences_before=2,
sentences_after=2,
),
reranker=CustomerSpecificReranker(
reranker_id="rnk_272725719"
),
)
generation = GenerationParameters(
response_language="eng",
enable_factual_consistency_score=True,
)
client.query(
query="Am I allowed to bring pets to work?",
search=search,
generation=generation
)
```
### Using Chat
Vectara [chat](https://docs.vectara.com/docs/api-reference/chat-apis/chat-apis-overview) provides a way to automatically store chat history to support multi-turn conversations.
Here is an example of how to start a chat with the SDK:
```python
from vectara import SearchCorporaParameters
search = SearchCorporaParameters(
corpora=[
KeyedSearchCorpus(
corpus_key="test-corpus",
metadata_filter="",
lexical_interpolation=0.005,
)
],
context_configuration=ContextConfiguration(
sentences_before=2,
sentences_after=2,
),
reranker=CustomerSpecificReranker(
reranker_id="rnk_272725719"
),
)
generation = GenerationParameters(
response_language="eng",
citations=CitationParameters(
style="none",
),
enable_factual_consistency_score=True,
)
chat = ChatParameters(store=True)
session = client.create_chat_session(
search=search,
generation=generation,
chat_config=chat,
)
response_1 = session.chat(query="Tell me about machine learning.")
print(response_1.answer)
response_2 = session.chat(query="what is generative AI?")
print(response_2.answer)
```
Note that we used the `create_chat_session` with `chat_config` set for storing chat history. The resulting session can then be used for turn-by-turn chat, simply by using the `chat()` method of the session object.
### Streaming
The SDK supports streaming responses for both query and chat. When using streaming, the response will be a generator that you can iterate.
Here's an example of calling `query_stream`:
Streaming the query response
```python
from vectara import SearchCorporaParameters
search = SearchCorporaParameters(
corpora=[...],
...
)
generation = GenerationParameters(...)
response = client.query_stream(
query="Am I allowed to bring pets to work?",
search=search,
generation=generation
)
for chunk in response:
if chunk.type == 'generation_chunk':
print(chunk.generation_chunk)
if chunk.type == "search_results":
print(chunk.search_results)
```
And streaming the chat response:
```python
from vectara import SearchCorporaParameters
search = SearchCorporaParameters(
corpora=[...],
...
)
generation = GenerationParameters(...)
chat_params = ChatParameters(store=True)
session = client.create_chat_session(
search=search_params,
generation=generation_params,
chat_config=chat_params,
)
response = session.chat_stream(query="Tell me about machine learning.")
for chunk in response:
if chunk.type == 'generation_chunk':
print(chunk.generation_chunk)
if chunk.type == "search_results":
print(chunk.search_results)
if chunk.type == "chat_info":
print(chunk.chat_id)
print(chunk.turn_id)
```
## Additional Functionality
There is a lot more functionality packed into the SDK, matching [all API endpoints](https://docs.vectara.com/docs/rest-api) that are available in Vectara including for things like managing documents, corpora, api keys, users, and even for query history retrieval.
## Exception Handling
When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
will be thrown.
```python
from vectara.core.api_error import ApiError
try:
client.query(...)
except ApiError as e:
print(e.status_code)
print(e.body)
```
## Pagination
Paginated requests will return a `SyncPager` or `AsyncPager`, which can be used as generators for the underlying object.
```python
response = client.corpora.list(
limit=1,
)
for item in response:
yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
yield page
```
### Advance Usage
For more information related to customization, Timeouts and Retries in the SDK, refer to the [Advanced Usage Guide](./ADVANCED.md)
### Using the SDK in Different Contexts
The Python library can be used in a number of environments with different requirements:
1. **Notebooks** - using implicit configuration from a users home directory
2. **Docker Environments** - using ENV variables for configuration
3. **Complex Applications** - allowing explicit configuration from mutable stores (e.g. RDBMS / NoSQL)
For more details, refer to the [Configuration Guide](./CONFIGURATION.md)
## Author
👤 **Vectara**
- Website: https://vectara.com
- Twitter: [@vectara](https://twitter.com/vectara)
- GitHub: [@vectara](https://github.com/vectara)
- LinkedIn: [@vectara](https://www.linkedin.com/company/vectara/)
- Discord: [@vectara](https://discord.gg/GFb8gMz6UH)
## 🤝 Contributing
Contributions, issues and feature requests are welcome!<br/>
Feel free to check [issues page](https://github.com/vectara/python-sdk/issues). You can also take a look at the [contributing guide](./CONTRIBUTING.md).
## Show your support
Give a ⭐️ if this project helped you!
Raw data
{
"_id": null,
"home_page": null,
"name": "vectara",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d3/59/a6d4d2dbb7a3daa95aa179c88a1514d34d6d326d650c36a20acb3ae7ae85/vectara-0.2.43.tar.gz",
"platform": null,
"description": "# Vectara Python SDK\n\n[](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fvectara%2Fpython-sdk)\n[](https://pypi.python.org/pypi/vectara)\n\nThe Vectara Python SDK provides convenient access to the Vectara API for building powerful AI applications.\n\n---\n\n## Installation\n\nInstall the library via pip:\n\n```bash\npip install vectara\n```\n## Getting Started\n\n### API Generated Documentation\nAPI reference documentation is available [here](https://vectara.docs.buildwithfern.com/).\n\n### Examples\nComplete examples can be found in the [Getting Started notebooks](./examples/01_getting_started).\n\n### Usage\n\nFirst, create an SDK client.<br />\nYou can use either an `api_key` or OAuth (`client_id` and `client_secret`) for [authentication](https://docs.vectara.com/docs/console-ui/api-access-overview).\n\n```python\nfrom vectara import Vectara\n\n# creating the client using API key\nclient = Vectara(\n api_key=\"YOUR_API_KEY\"\n)\n \n# creating the client using oauth credentials\nclient = Vectara(\n client_id=\"YOUR_CLIENT_ID\",\n client_secret=\"YOUR_CLIENT_SECRET\",\n) \n```\n\nIf you don't already have a corpus, you can create it using the SDK:\n\n```python\nclient.corpora.create(name=\"my-corpus\", key=\"my-corpus-key\")\n```\n \n### Add a document to a corpus\nYou can add documents to a corpus in two formats: [structured](https://docs.vectara.com/docs/learn/select-ideal-indexing-api#structured-document-definition) or [core](https://docs.vectara.com/docs/learn/select-ideal-indexing-api#core-document-definition).<br/> For more information, refer to the [Indexing Guide](https://docs.vectara.com/docs/learn/select-ideal-indexing-api).\n\nHere is an example for adding a Structured document\n ```python\n from vectara import StructuredDocument, StructuredDocumentSection\n client.documents.create(\n corpus_key=\"my-corpus-key\",\n request=StructuredDocument(\n id=\"my-doc-id\",\n type=\"structured\",\n sections=[\n StructuredDocumentSection(\n id=\"id_1\",\n title=\"A nice title.\",\n text=\"I'm a nice document section.\",\n metadata={'section': '1.1'}\n ),\n StructuredDocumentSection(\n id=\"id_2\",\n title=\"Another nice title.\",\n text=\"I'm another document section on something else.\",\n metadata={'section': '1.2'}\n ),\n ],\n metadata={'url': 'https://example.com'}\n ),\n )\n ```\n\n\nAnd here is one with Core document:\n```python\nfrom vectara import CoreDocument, CoreDocumentPart\n\nclient.documents.create(\n corpus_key=\"my-corpus-key\",\n request=CoreDocument(\n id=\"my-doc-id\",\n type=\"core\",\n document_parts=[\n CoreDocumentPart(\n text=\"I'm a first document part.\",\n metadata={'author': 'Ofer'}\n )\n CoreDocumentPart(\n text=\"I'm a second document part.\",\n metadata={'author': 'Adeel'}\n )\n ],\n metadata={'url': 'https://example.com'}\n ),\n)\n```\n\n### Upload a file to the corpus\nIn addition to creating a document as shown above (using StructuredDocument or CoreDocument), you can also upload files (such as PDFs or Word Documents) directly to Vectara.\nIn this case Vectara will parse the files automatically, extract text and metadata, chunk them and add them to the corpus.\n\nUsing the SDK you need to provide both the file name, the binary content of the file, and the content_type, as follows:\n\n```python\nfilename = \"examples.pdf\"\nwith open(filename, \"rb\") as f:\n content = f.read()\n\nclient.upload.file(\n 'my-corpus-key', \n file=content,\n filename=filename,\n metadata={\"author\": \"Adeel\"}\n)\n```\n\n\n### Querying the corpora\nWith the SDK it's super easy to run a query from one or more corpora. For more detailed information, see this [Query API guide](https://docs.vectara.com/docs/api-reference/search-apis/search)\n\nA query uses two important objects:\n* The `SearchCorporaParameters` object defines parameters for search such as hybrid search, metadata filtering or reranking\n* The `GenerationParameters` object defines parameters for the generative step.\n\nHere is an example query for our corpus above:\n\n```python \nsearch = SearchCorporaParameters(\n corpora=[\n KeyedSearchCorpus(\n corpus_key=\"my-corpus-key\",\n metadata_filter=\"\",\n lexical_interpolation=0.005,\n )\n ],\n context_configuration=ContextConfiguration(\n sentences_before=2,\n sentences_after=2,\n ),\n reranker=CustomerSpecificReranker(\n reranker_id=\"rnk_272725719\"\n ),\n )\ngeneration = GenerationParameters(\n response_language=\"eng\",\n enable_factual_consistency_score=True,\n )\n\nclient.query(\n query=\"Am I allowed to bring pets to work?\",\n search=search,\n generation=generation\n \n)\n```\n \n### Using Chat\n\nVectara [chat](https://docs.vectara.com/docs/api-reference/chat-apis/chat-apis-overview) provides a way to automatically store chat history to support multi-turn conversations.\n\nHere is an example of how to start a chat with the SDK:\n\n```python\nfrom vectara import SearchCorporaParameters \nsearch = SearchCorporaParameters(\n corpora=[\n KeyedSearchCorpus(\n corpus_key=\"test-corpus\",\n metadata_filter=\"\",\n lexical_interpolation=0.005,\n )\n ],\n context_configuration=ContextConfiguration(\n sentences_before=2,\n sentences_after=2,\n ),\n reranker=CustomerSpecificReranker(\n reranker_id=\"rnk_272725719\"\n ),\n )\ngeneration = GenerationParameters(\n response_language=\"eng\",\n citations=CitationParameters(\n style=\"none\",\n ),\n enable_factual_consistency_score=True,\n )\nchat = ChatParameters(store=True)\n\nsession = client.create_chat_session(\n search=search,\n generation=generation,\n chat_config=chat,\n)\n\nresponse_1 = session.chat(query=\"Tell me about machine learning.\")\nprint(response_1.answer)\nresponse_2 = session.chat(query=\"what is generative AI?\")\nprint(response_2.answer)\n```\n\nNote that we used the `create_chat_session` with `chat_config` set for storing chat history. The resulting session can then be used for turn-by-turn chat, simply by using the `chat()` method of the session object.\n\n\n### Streaming\n\nThe SDK supports streaming responses for both query and chat. When using streaming, the response will be a generator that you can iterate.\n\nHere's an example of calling `query_stream`:\n \nStreaming the query response\n```python\nfrom vectara import SearchCorporaParameters\nsearch = SearchCorporaParameters(\n corpora=[...],\n ...\n)\ngeneration = GenerationParameters(...)\n\nresponse = client.query_stream(\n query=\"Am I allowed to bring pets to work?\",\n search=search,\n generation=generation\n \n)\nfor chunk in response:\n if chunk.type == 'generation_chunk':\n print(chunk.generation_chunk)\n if chunk.type == \"search_results\":\n print(chunk.search_results)\n```\n\nAnd streaming the chat response:\n\n```python\nfrom vectara import SearchCorporaParameters\n\nsearch = SearchCorporaParameters(\n corpora=[...],\n ...\n)\ngeneration = GenerationParameters(...)\nchat_params = ChatParameters(store=True)\n\nsession = client.create_chat_session(\n search=search_params,\n generation=generation_params,\n chat_config=chat_params,\n)\n\nresponse = session.chat_stream(query=\"Tell me about machine learning.\")\nfor chunk in response:\n if chunk.type == 'generation_chunk':\n print(chunk.generation_chunk)\n if chunk.type == \"search_results\":\n print(chunk.search_results) \n if chunk.type == \"chat_info\":\n print(chunk.chat_id)\n print(chunk.turn_id)\n```\n\n## Additional Functionality\nThere is a lot more functionality packed into the SDK, matching [all API endpoints](https://docs.vectara.com/docs/rest-api) that are available in Vectara including for things like managing documents, corpora, api keys, users, and even for query history retrieval. \n\n\n## Exception Handling\n\nWhen the API returns a non-success status code (4xx or 5xx response), a subclass of the following error\nwill be thrown.\n\n```python\nfrom vectara.core.api_error import ApiError\n\ntry:\n client.query(...)\nexcept ApiError as e:\n print(e.status_code)\n print(e.body)\n``` \n\n## Pagination\n\nPaginated requests will return a `SyncPager` or `AsyncPager`, which can be used as generators for the underlying object.\n\n```python\nresponse = client.corpora.list(\n limit=1,\n)\nfor item in response:\n yield item\n# alternatively, you can paginate page-by-page\nfor page in response.iter_pages():\n yield page\n```\n\n### Advance Usage\n\nFor more information related to customization, Timeouts and Retries in the SDK, refer to the [Advanced Usage Guide](./ADVANCED.md)\n\n\n### Using the SDK in Different Contexts\nThe Python library can be used in a number of environments with different requirements:\n\n1. **Notebooks** - using implicit configuration from a users home directory\n2. **Docker Environments** - using ENV variables for configuration\n3. **Complex Applications** - allowing explicit configuration from mutable stores (e.g. RDBMS / NoSQL)\n\nFor more details, refer to the [Configuration Guide](./CONFIGURATION.md)\n\n## Author\n\n\ud83d\udc64 **Vectara**\n\n- Website: https://vectara.com\n- Twitter: [@vectara](https://twitter.com/vectara)\n- GitHub: [@vectara](https://github.com/vectara)\n- LinkedIn: [@vectara](https://www.linkedin.com/company/vectara/)\n- Discord: [@vectara](https://discord.gg/GFb8gMz6UH)\n\n## \ud83e\udd1d Contributing\n\nContributions, issues and feature requests are welcome!<br/>\nFeel free to check [issues page](https://github.com/vectara/python-sdk/issues). You can also take a look at the [contributing guide](./CONTRIBUTING.md).\n\n## Show your support\n\nGive a \u2b50\ufe0f if this project helped you!",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.2.43",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b92773d593e37537b30211d957973d41d57f21bcdd97bf42f261a0aa24713889",
"md5": "babfcbf8b12bc128c0cf1771a755f01c",
"sha256": "72c11851bf04c199e412f9fdd8ba237dc7e452658284551ffdeb7f918e7ffbb0"
},
"downloads": -1,
"filename": "vectara-0.2.43-py3-none-any.whl",
"has_sig": false,
"md5_digest": "babfcbf8b12bc128c0cf1771a755f01c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 166250,
"upload_time": "2025-02-26T06:11:14",
"upload_time_iso_8601": "2025-02-26T06:11:14.726485Z",
"url": "https://files.pythonhosted.org/packages/b9/27/73d593e37537b30211d957973d41d57f21bcdd97bf42f261a0aa24713889/vectara-0.2.43-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d359a6d4d2dbb7a3daa95aa179c88a1514d34d6d326d650c36a20acb3ae7ae85",
"md5": "3a283852f8735506bd00492c13bfe1ad",
"sha256": "c6bb80733bff8af72322fee09e9943f7af306968e27955f10de3eabbad53d2ec"
},
"downloads": -1,
"filename": "vectara-0.2.43.tar.gz",
"has_sig": false,
"md5_digest": "3a283852f8735506bd00492c13bfe1ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 92198,
"upload_time": "2025-02-26T06:11:16",
"upload_time_iso_8601": "2025-02-26T06:11:16.733814Z",
"url": "https://files.pythonhosted.org/packages/d3/59/a6d4d2dbb7a3daa95aa179c88a1514d34d6d326d650c36a20acb3ae7ae85/vectara-0.2.43.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-26 06:11:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "vectara"
}
