Vectara Python Library

The Vectara Python library provides convenient access to the Vectara API from Python.

Installation

pip install vectara

Using the SDK in Different Contexts

The Python library is designed to run 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)

In order to satisfy this requirement, the client can be instantiated a few different ways:

1. Explicit Configuration
2. Environment Variables
3. Explicit Path to YAML file
4. Default YAML in home directory

Explicit Configuration

To create an instance of vectara.Client with Explicit Configuration any of the following methods.

Configuration as a Python Dict

We can specify a dict which matches vectara.config.ClientConfig

# API Key Example
config = {
    "customer_id": "foo", # Customer ID no longer needed but left in for now
    "auth": {
        "api_key": "YOUR API KEY"
    }
}

# OAuth2 Example
config = {
    "customer_id": "foo", # Customer ID no longer needed but left in for now
    "auth": {
        "app_client_id": "OAuth2 application client id",
        "app_client_secret": "OAuth2 application client secret"
    }
}

client = Factory(config=config).build()

Configuration as a Pydantic ClientConfig

You can also use a Pydantic well type configuration via vectara.config.ClientConfig.

config = ClientConfig.model_validate({...})
client = Factory(config=config).build()

Environment Based Configuration

When running in Docker environments, it is useful to initialize Vectara using environment variables. If you want to do this, please set the following, using either API Key or both of the OAuth2 properties:

If the client is built via the Factory with these present and not explicit configuration, these will be used to configure the vectara.Vectara client.

YAML Based Configuration

When using Vectara in shareable notebooks, it is desirable to remove any sensitive keys from the Notebook cells to prevent committing this to a repository or sharing inadvertently. To meet this need, we also have the YAML method of configuration.

By default, when configured with no arguments, the system will look for a file .vec_auth.yaml in the users home directory. If there is another location for the YAML file, it can be specified with the config_path parameter to the vectara.Factory initialization.

# Default from the users home directory.
client = Factory().build()

# Explict path referenced
client = Factory(config_path="/my/vectara/config.yaml").build()

YAML Configuration Format

The configuration format should like below. You can define multiple configuration blocks. If not specified, the factory will load the profile "default". You must specify your customer_id but may

default:
  customer_id : "1999999999"
  auth:
    # For API Key, you only need the API key
    api_key : "abcdabcdabcdabcdabcdabcdababcdabcd"
admin:
  customer_id : "1999999999" # Customer Id as a string
  auth:
    # For OAuth2, you need app_client_id, app_client_secret, auth_url
    app_client_id : "abcdabcdabcdabcdabcdabcdab"
    app_client_secret : "abcdabcdabcdabcdabcdabcdababcdabcdabcdabcdabcdabcdab"
    # This is optional, you can leave this blank in most circumstances
    auth_url : "https://vectara-prod-YOUR_CUSTOMER_ID.auth.us-west-2.amazoncognito.com/oauth2/token"

Multiple Profiles

You can load other configuration profiles using the property profile on the build command.

from vectara.factory import Factory
client = Factory(profile="admin").build()

Managers vs Direct API methods

This API was generated by FERN, but in some cases you want to perform operations at a "higher level of abstraction" that may comprise multiple method calls. There's also many convenience operations we can perform which are useful that may eventually make it into the Vectara API. For example, we can URL encode the doc_id to support multiple languages which isn't (yet) in the FERN generated code.

To that end, we have built and tested the following managers on top of the direct API methods. They are located in the module vectara.managers. We have the following managers defined which can be found on the client.

• client.corpus_manager - Provides abstractions over Corpus Methods
• client.upload_manager - Provides abstractions over file Uploads

Usage

Using the implicit configuration method we can create and run a query as follows.

from vectara.factory import Factory

client = Factory().build()
client.query(
    query="Am I allowed to bring pets to work?"
)

More complete examples can be found in the Getting Started notebooks.

API Generated Documentation

API reference documentation is available here.

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

from vectara.core.api_error import ApiError

try:
    client.query(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)

Streaming

The SDK supports streaming responses, as well, the response will be a generator that you can loop over.

from vectara import (
    CitationParameters,
    ContextConfiguration,
    CustomerSpecificReranker,
    GenerationParameters,
    ModelParameters,
    Vectara,
)
from vectara.corpora import SearchCorpusParameters

client = Vectara(
    api_key="YOUR_API_KEY",
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)
response = client.corpora.query_stream(
    corpus_key="string",
    request_timeout=1,
    request_timeout_millis=1,
    query="string",
    search=SearchCorpusParameters(
        custom_dimensions={"string": 1.1},
        metadata_filter="string",
        lexical_interpolation=1.1,
        semantics="default",
        offset=1,
        limit=1,
        context_configuration=ContextConfiguration(
            characters_before=1,
            characters_after=1,
            sentences_before=1,
            sentences_after=1,
            start_tag="string",
            end_tag="string",
        ),
        reranker=CustomerSpecificReranker(
            reranker_id="string",
            reranker_name="string",
            limit=1,
            cutoff=1.1,
        ),
    ),
    generation=GenerationParameters(
        generation_preset_name="string",
        prompt_name="string",
        max_used_search_results=1,
        prompt_template="string",
        prompt_text="string",
        max_response_characters=1,
        response_language="auto",
        model_parameters=ModelParameters(
            max_tokens=1,
            temperature=1.1,
            frequency_penalty=1.1,
            presence_penalty=1.1,
        ),
        citations=CitationParameters(
            style="none",
            url_pattern="string",
            text_pattern="string",
        ),
        enable_factual_consistency_score=True,
    ),
)
for chunk in response:
    yield chunk

Pagination

Paginated requests will return a SyncPager or AsyncPager, which can be used as generators for the underlying object.

from vectara import Vectara

client = Vectara(
    api_key="YOUR_API_KEY",
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)
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

Advanced

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retriable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retriable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the max_retries request option to configure this behavior.

client.query(..., request_options={
    "max_retries": 1
})

Timeouts

The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.

from vectara import Vectara

client = Vectara(
    ...,
    timeout=20.0,
)


# Override timeout for a specific method
client.query(..., request_options={
    "timeout_in_seconds": 1
})

Custom Client

You can override the httpx client to customize it for your use-case. Some common use-cases include support for proxies and transports.

import httpx
from vectara import Vectara

client = Vectara(
    ...,
    httpx_client=httpx.Client(
        proxies="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!