diff --git a/.fernignore b/.fernignore index c5d7e9d..317dd22 100644 --- a/.fernignore +++ b/.fernignore @@ -1,6 +1,7 @@ # Specify files that shouldn't be modified by Fern .github/workflows/ci.yml +.github/ISSUE_TEMPLATE/ src/vectara/client.py src/vectara/base_client.py # do not remove @@ -25,6 +26,7 @@ examples/ pytest.ini mypy.ini + README.md ADVANCED.md CONTRIBUTING.md diff --git a/.github/.github/ISSUE_TEMPLATE /.github/ISSUE_TEMPLATE /issue-form.yml b/.github/.github/ISSUE_TEMPLATE /.github/ISSUE_TEMPLATE /issue-form.yml deleted file mode 100644 index e69de29..0000000 diff --git a/.github/.github/ISSUE_TEMPLATE /config.yml b/.github/.github/ISSUE_TEMPLATE /config.yml index e69de29..3a73e79 100644 --- a/.github/.github/ISSUE_TEMPLATE /config.yml +++ b/.github/.github/ISSUE_TEMPLATE /config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Questions + url: https://discuss.vectara.com/ + about: Ask questions and interact with the community here! diff --git a/.github/.github/ISSUE_TEMPLATE /issue-form.yml b/.github/.github/ISSUE_TEMPLATE /issue-form.yml new file mode 100644 index 0000000..557e777 --- /dev/null +++ b/.github/.github/ISSUE_TEMPLATE /issue-form.yml @@ -0,0 +1,36 @@ +name: 🐞 Python SDK Bug +description: File a bug about Python SDK +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + Please complete the following form to help us assist you. + - type: textarea + id: what-happened + attributes: + label: Bug Description + description: What happened? + validations: + required: true + - type: input + id: version + attributes: + label: Version + description: What version of python sdk are you using? + validations: + required: true + - type: textarea + id: steps-to-reproduce + attributes: + label: Steps to Reproduce + description: Which steps should someone take to run into the same error? + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant Logs/Tracbacks + description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + render: shell \ No newline at end of file diff --git a/ADVANCED.md b/ADVANCED.md new file mode 100644 index 0000000..7973f25 --- /dev/null +++ b/ADVANCED.md @@ -0,0 +1,69 @@ +## Advanced Usage + +### Retries + +The SDK includes **automatic retry handling** with exponential backoff to enhance reliability. A request will be retried if it meets the following conditions: +1. The response status code indicates a retriable error. +2. The number of retry attempts is less than the configured retry limit (default: `2`). + +#### Retriable HTTP Status Codes +The following status codes are considered retriable: +- **[408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408)**: Request Timeout +- **[429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)**: Too Many Requests +- **[5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500)**: Internal Server Errors + +#### Configuring Retries +You can customize the retry behavior using the `max_retries` option in `request_options`. + +```python +client.query( + query="Tell me about AI.", + request_options={"max_retries": 3} # Configure the maximum number of retries +) +``` + +### Timeouts +The SDK applies a **default timeout of 60 seconds** for all requests. You can adjust this timeout globally at the client level or for specific API calls. + +#### Configuring a Global Timeout +Set the timeout for all SDK operations when initializing the client: + +```python +from vectara import Vectara + +client = Vectara( + ..., + timeout=30.0 # Set a 30-second timeout for all requests +) + +``` +#### Overriding Timeout Per Request +Customize the timeout for individual API calls using `request_options`: + +```python +client.query( + query="Tell me about AI.", + request_options={"timeout_in_seconds": 10} # Set a 10-second timeout for this request +) + +``` +### Custom HTTP Client +The SDK allows you to provide a custom `httpx.Client` to fine-tune network configurations, such as: + +1. Using a proxy server. +2. Specifying a local transport address. +#### Example: Custom HTTP Client Configuration + +```python +import httpx +from vectara import Vectara + +client = Vectara( + ..., + httpx_client=httpx.Client( + proxies="http://proxy.example.com:8080", + transport=httpx.HTTPTransport(local_address="192.168.1.100"), + ) +) + +``` \ No newline at end of file diff --git a/CONFIGURATION.md b/CONFIGURATION.md index e69de29..1d43fa5 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -0,0 +1,106 @@ +### 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 + +```python +# 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`. +```python +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: + +| Environment Variable | Description | +|----------------------|-------------| +| **VECTARA_CUSTOMER_ID** | The customer id for the given Account | +| **VECTARA_API_KEY** | The API key | +| **VECTARA_CLIENT_ID** | The OAuth2 Client ID | +| **VECTARA_CLIENT_SECRET** | The OAuth2 Client Secret | + +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 + +```yaml +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. +```python +from vectara.factory import Factory +client = Factory(profile="admin").build() +``` \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..214aac4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing to the Vectara Python SDK + +We appreciate your interest in contributing to the Vectara Python SDK! + +--- + +## About This SDK + +This SDK is **programmatically generated**, meaning that much of the code is automatically created by a generation system. As a result: +1. **Direct changes to the SDK code** (e.g., methods, classes) would need to be replicated in the generation system. +2. Contributions such as **proof-of-concepts** or **bug fixes** are welcome, but they may require additional work on our end to integrate into the generation process. + +--- + +## How to Contribute + +### 1. Open an Issue +Before submitting a pull request (PR), we encourage you to: +- Open an issue to describe your proposed changes. +- Discuss the idea with the maintainers to ensure alignment with the project goals. + +## Getting started + +1. Fork the repository and clone your fork. +2. Create a new branch for your changes (e.g. `bug-fix-1234`) +3. Make your changes in the new branch and test. +4. Commit and push your changes to your fork. Add useful comments to describe your changes. +5. Create a pull request following the guidelines in the [Submitting Pull Requests](#submitting-pull-requests) section. + +## Contributing + +### Reporting bugs + +If you find a bug in the project, please create an issue on GitHub with the following information: + +- A clear, descriptive title for the issue. +- A description of the problem, including steps to reproduce the issue. +- Any relevant logs, screenshots, or other supporting information. + +### Suggesting enhancements + +If you have an idea for a new feature or improvement, please create an issue on GitHub with the following information: + +- A clear, descriptive title for the issue. +- A detailed description of the proposed enhancement, including any benefits and potential drawbacks. +- Any relevant examples, mockups, or supporting information. + +### Submitting pull requests + +When submitting a pull request, please ensure that your changes meet the following criteria: + +- Your pull request should be atomic and focus on a single change. +- You should have thoroughly tested your changes with multiple different scenarios. +- You should have considered potential risks and mitigations for your changes. +- You should have documented your changes clearly and comprehensively. +- Please do not include any unrelated or "extra" small tweaks or changes. \ No newline at end of file