anumathad-o · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/.gitignore b/.gitignore
@@ -44,7 +44,7 @@ nosetests.xml
 coverage.xml
 *,cover
 .hypothesis/
-reports/
+reports*/
 
 venv/
 .venv310/

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -6,6 +6,36 @@ All notable changes to this project will be documented in this file.
 The format is based on the `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`__,
 and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
+1.0.6 - 2026-10-16
+------------------
+
+Added
+~~~~~
+
+- Added network failure details to ``VecDBException`` so callers can see
+  whether a request failed because of a timeout, DNS lookup, connection, or
+  TLS/certificate problem, and whether retrying may help.
+- Added ``get_vecdb_oauth_token`` for OAuth client-credentials token requests,
+  with HTTPS validation, configurable TLS, timeout and proxy settings, and
+  sanitized ``OAuthTokenError`` diagnostics. Updated ``examples/test_client.py``
+  to demonstrate OAuth authentication and retain a basic-auth option.
+
+Changed
+~~~~~~~
+
+- Network failures now include distinct error codes and advice on what to
+  check next.
+- Removed ``distribute_method`` validation for "INMEMORY GRAPH" organization
+  when ``distribute_params`` is null.
+- ``query.top_k`` must now be a positive integer; booleans and fractional
+  values are rejected.
+
+Fixed
+~~~~~
+
+- Made exception formatting resilient to unsupported, circular, and deeply
+  nested diagnostic values while keeping sensitive data redacted.
+
 1.0.5 - 2026-10-01
 ------------------
 

diff --git a/Makefile b/Makefile
@@ -23,6 +23,8 @@ TARGET_DIRS = $(SOURCE_DIR) tests examples
 REPORT ?= 
 INTEGRATION_TEST_WORKERS ?= 10
 DEBUG ?= 1
+PERFORMANCE_TEST ?= false
+PERFORMANCE_TEST_ENABLED := $(if $(filter 1 true TRUE True yes YES Yes on ON On,$(PERFORMANCE_TEST)),true,false)
 INTEGRATION_TEST_PARALLEL_FILES ?= 
 # Kept for callers that select a subset of files.  Those files are added to
 # the same bounded xdist pool; a second pool oversubscribes the VecDB service.
@@ -136,21 +138,25 @@ integration_test: reports_dirs ## Run live VecDB integration tests
 	@set +e; \
 	export RUN_INTEGRATION_TESTS=true; \
 	export VECDB_REQUIRE_INTEGRATION_TEST_ENV=true; \
+	export PERFORMANCE_TEST="$(PERFORMANCE_TEST)"; \
 	export PYTHONPATH="$(abspath $(SOURCE_DIR))"; \
 	export VECDB_TEST_RUN_ID="$${VECDB_TEST_RUN_ID:-$$(date +%Y%m%d%H%M%S)}"; \
-	EXCLUDED_TEST_FILE="dev-tools/tests/integration/test_tkvcvecdb_sdk_sample_sanity.py"; \
 	TEST_FILES=(); \
 	if [ -n "$(INTEGRATION_TEST_PARALLEL_FILES)" ]; then \
 		for test_file in $(INTEGRATION_TEST_PARALLEL_FILES); do \
-			if [ "$$test_file" != "$$EXCLUDED_TEST_FILE" ] && [ "$$(basename "$$test_file")" != "test_tkvcvecdb_sdk_sample_sanity.py" ]; then \
+			if [ "$(PERFORMANCE_TEST_ENABLED)" = "true" ] || [ "$$(basename "$$test_file")" != "test_tkvcvecdb_sdk_sample_sanity.py" ]; then \
 				TEST_FILES+=("$$test_file"); \
 			fi; \
 		done; \
 	else \
-		while IFS= read -r test_file; do TEST_FILES+=("$$test_file"); done < <(find dev-tools/tests/integration -type f -name 'test_*.py' ! -name 'test_tkvcvecdb_sdk_sample_sanity.py' -print | sort); \
+		while IFS= read -r test_file; do \
+			if [ "$(PERFORMANCE_TEST_ENABLED)" = "true" ] || [ "$$(basename "$$test_file")" != "test_tkvcvecdb_sdk_sample_sanity.py" ]; then \
+				TEST_FILES+=("$$test_file"); \
+			fi; \
+		done < <(find dev-tools/tests/integration -type f -name 'test_*.py' -print | sort); \
 	fi; \
 	for test_file in $(INTEGRATION_TEST_SERIAL_FILES); do \
-		if [ "$$test_file" != "$$EXCLUDED_TEST_FILE" ] && [ "$$(basename "$$test_file")" != "test_tkvcvecdb_sdk_sample_sanity.py" ] && [[ ! " $${TEST_FILES[*]} " =~ " $$test_file " ]]; then TEST_FILES+=("$$test_file"); fi; \
+		if { [ "$(PERFORMANCE_TEST_ENABLED)" = "true" ] || [ "$$(basename "$$test_file")" != "test_tkvcvecdb_sdk_sample_sanity.py" ]; } && [[ ! " $${TEST_FILES[*]} " =~ " $$test_file " ]]; then TEST_FILES+=("$$test_file"); fi; \
 	done; \
 	REPORT_ARG=(); \
 	if [ -n "$(REPORT)" ]; then \
@@ -163,6 +169,8 @@ integration_test: reports_dirs ## Run live VecDB integration tests
 	TEST_STATUS=0; \
 	if [ "$${#TEST_FILES[@]}" -eq 0 ]; then \
 		echo "No integration test files selected."; \
+		if [ "$(PERFORMANCE_TEST_ENABLED)" != "true" ]; then echo "Set PERFORMANCE_TEST=true to include performance-gated integration tests."; fi; \
+		TEST_STATUS=2; \
 	elif [ "$(DEBUG)" -gt 0 ]; then \
 		MASTER_PID=$$$$ $(PYTEST) \
 			-rfE \
@@ -190,7 +198,7 @@ integration_test: reports_dirs ## Run live VecDB integration tests
 		TEST_STATUS=$$?; \
 	fi; \
 	set -e; \
-	if [ -n "$(REPORT)" ]; then \
+	if [ -n "$(REPORT)" ] && [ "$${#TEST_FILES[@]}" -gt 0 ]; then \
 		$(PYTHON) dev-tools/merge_junit_reports.py \
 			--input-dir "$(INTEGRATION_TEST_REPORT_SHARDS_DIR)" \
 			--output "$(INTEGRATION_TEST_REPORT_DIR)/pytest_report.xml"; \

diff --git a/examples/test_client.py b/examples/test_client.py
@@ -3,19 +3,45 @@
 ## Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
 ##
 
-import os
+from getpass import getpass
 
-from oracle_vecdb import OracleVecDB, Configuration
+from oracle_vecdb import Configuration, OracleVecDB, get_vecdb_oauth_token
 
 
 def main():
-    # Use a valid HTTPS ORDS VecDB endpoint. Example pattern:
-    # https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/
-    config = Configuration(
-        rest_url="https://example.com/ords/foo/_/db-api/stable/vecdb/",
-        username="username",
-        password=os.getenv("DB_PASSWORD"),
-    )
+    # Replace these example values with your ORDS host, port, and schema.
+    host = "example.com"
+    port = 8443
+    schema = "foo"
+    ords_url = f"https://{host}:{port}/ords/{schema}"
+    rest_url = f"{ords_url}/_/db-api/stable/vecdb/"
+
+    # Choose OAuth client credentials or basic authentication.
+    ords_oauth = True
+
+    if ords_oauth:
+        # Create or obtain an OAuth client in ORDS. The client ID is entered
+        # visibly; getpass hides the client secret while you type it.
+        # TLS certificate verification is on by default. For a private CA,
+        # provide its bundle with the optional ssl_ca_cert argument below.
+        token_response = get_vecdb_oauth_token(
+            client_id=input("ORDS OAuth client ID: "),
+            client_secret=getpass("ORDS OAuth client secret: "),
+            token_url=f"{ords_url}/oauth/token",
+            timeout=(5, 30),  # connect timeout, then read timeout
+            # ssl_ca_cert="/path/to/ca-bundle.pem",
+        )
+        config = Configuration(
+            rest_url=rest_url,
+            access_token=token_response["access_token"],
+        )
+    else:
+        # Use this branch only when your ORDS deployment requires basic auth.
+        config = Configuration(
+            rest_url=rest_url,
+            username=input("Vector DB Username: "),
+            password=getpass("Vector DB Password: "),
+        )
 
     vecdb = OracleVecDB(config)
     table_name = "TEST_TABLE"

diff --git a/pyproject.toml b/pyproject.toml
@@ -8,7 +8,7 @@ authors = [
 license = "UPL-1.0"
 license-files = ["LICENSE.txt"]
 readme = "README.md"
-requires-python = ">=3.10,<3.15"
+requires-python = ">=3.10,<3.16"
 keywords = ["Oracle", "vecdb", "vector", "database", "ords", "sdk"]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
@@ -19,6 +19,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
   "Topic :: Database :: Database Engines/Servers",
   "Topic :: Software Development :: Libraries",
 ]

diff --git a/src/oracle_vecdb/__init__.py b/src/oracle_vecdb/__init__.py
@@ -4,9 +4,11 @@
 ##
 
 from .client import OracleVecDB  # noqa: F401
+from .auth import get_vecdb_oauth_token  # noqa: F401
 from . import data_types  # noqa: F401
 from .configuration import Configuration  # noqa: F401
 from .vecdb_errors import VecDBError  # noqa: F401
 from .vecdb_errors import InsecureConnectionError  # noqa: F401
 from .vecdb_errors import InvalidHostFormatError  # noqa: F401
+from .vecdb_errors import OAuthTokenError  # noqa: F401
 from .vecdb_exception import VecDBException  # noqa: F401