update fernignore

.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

.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!

.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

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"),
+    )
+)
+
+```

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
+
+<img src="./resources/configuration.png" />
+
+### 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()
+```

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.