Promote v1.0.3 changes to main

.gitignore

@@ -71,4 +71,4 @@ target/
 .ipynb_checkpoints
 
 # Oracle Parfait analysis cache
-__parfait__/
+__parfait__/

.gitmessage

@@ -0,0 +1,32 @@
+# Based on Conventional Commits 1.0.0:
+# Conventional Commit format:
+#   <type>[optional scope][!]: <description>
+#
+# Examples:
+#   feat(query): add metadata filters
+#   fix: handle empty query results
+#   docs!: remove the legacy authentication flow
+#
+# Common types:
+#   feat      New user-visible capability
+#   fix       Corrected behavior or defect
+#   docs      User documentation change
+#   perf      User-visible performance improvement
+#   refactor  Internal restructuring without intended behavior change
+#   test      Test-only change
+#   build     Build or packaging change
+#   ci        Continuous-integration change
+#   chore     Routine maintenance
+#   revert    Revert a previous change
+#   style     Formatting-only change
+#
+# Keep the description concise and imperative. Add an optional body after a
+# blank line to explain motivation or implementation details.
+#
+# Use a footer for issue references or breaking-change details, for example:
+#   BREAKING CHANGE: describe the required migration
+#
+# To omit a redundant entry related to an unreleased feature, use:
+#   Changelog: skip
+# To omit an unreleased feature and the revert that removes it, use:
+#   Changelog: retract <full SHA of the feat commit>

AGENTS.md

@@ -77,6 +77,16 @@ filters = {
 Use only filter operators documented in `docs/source/rest_api.rst` or verified
 by SDK tests. Do not copy filter syntax from another vector database product.
 
+## Validation
+
+- For SDK source or test changes, run `make check` and `git diff --check`
+  before handoff.
+- Run focused tests for any changed development tool. Run `make build` when
+  packaging or build metadata changes.
+- Run `make integration_test` only when the change can affect live VecDB
+  behavior and the required test environment is configured.
+- Report any required validation that was not run.
+
 ## Quick Start
 
 - Use the `README.md` Quickstart as the source of truth for runnable

CHANGELOG.rst

@@ -6,6 +6,43 @@ 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.3 - 2026-09-07
+------------------
+
+Added
+~~~~~
+
+- Added verified public-operation defaults for omitted arguments, including
+  ``create_vector_table.table_params.auto_generate_id``,
+  ``list_vectors.limit``, and ``query.include_vectors``.
+- Added transport-neutral validation for parameter values
+  and cross-field combinations before requests are sent to ORDS.
+- Added explicit authentication-mode detection for unauthenticated, basic,
+  and bearer configurations, including validation of incomplete or conflicting
+  credentials.
+
+Changed
+~~~~~~~
+
+- Resource-name validation now rejects blank values and transport-unsafe NUL
+  or double-quote characters while leaving database-specific identifier rules
+  to Oracle Database.
+- Upsert vector field names are normalized case-insensitively; unknown fields
+  and duplicate fields with different casing now produce clear validation
+  errors.
+- Improved validation and error messages for vector index organizations,
+  distribution settings, quantization, metadata paths, query modes, and other
+  parameter dependencies.
+- Improved ORDS exception normalization and diagnostics by redacting sensitive
+  request and response data, preserving useful error categories, and avoiding
+  duplicate raw transport exception context.
+
+Fixed
+~~~~~
+
+- Fixed graph-index requests that omitted required distribution parameters from
+  reaching the service with an invalid request shape.
+
 1.0.2 - 2026-08-19
 ------------------
 

CONTRIBUTING.md

@@ -31,6 +31,22 @@ git commit --signoff
 Only pull requests from committers that can be verified as having signed the OCA
 can be accepted.
 
+### Commit messages
+
+Use [Conventional Commits][conventional-commits] for commit subjects so future
+release automation can derive changelog entries from commit history. Configure
+the repository template once after cloning:
+
+```bash
+git config --local commit.template .gitmessage
+```
+
+Use this format and retain the OCA sign-off with `git commit -s`:
+
+```text
+<type>[optional scope][!]: <description>
+```
+
 ## Pull request process
 
 1. Ensure there is an issue created to track and discuss the fix or enhancement
@@ -53,3 +69,4 @@ like more specific guidelines, see the [Contributor Covenant Code of Conduct][CO
 
 [OCA]: https://oca.opensource.oracle.com
 [COC]: https://www.contributor-covenant.org/version/1/4/code-of-conduct/
+[conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/

README.md

@@ -5,7 +5,7 @@ Keep vectors alongside your operational data, combine semantic similarity with r
 
 [![PyPI](https://img.shields.io/pypi/v/oracle-vecdb)](https://pypi.org/project/oracle-vecdb/)
 [![Python](https://img.shields.io/pypi/pyversions/oracle-vecdb)](https://pypi.org/project/oracle-vecdb/)
-[![License](https://img.shields.io/github/license/oracle/vecdb-python-sdk)](LICENSE.txt)
+[![License](https://img.shields.io/github/license/oracle/vecdb-python-sdk)](./LICENSE.txt)
 
 **⭐ [Star `oracle/vecdb-python-sdk`](https://github.com/oracle/vecdb-python-sdk) to follow the project and help more developers discover it.**
 
@@ -33,6 +33,25 @@ pip install oracle-vecdb
 uv add oracle-vecdb
 ```
 
+### Connect
+### Requirements
+
+- **Python:** 3.10+
+- **Oracle AI Database:** 23.26.3+
+- **ORDS:** 26.2.2+
+
+### Installation
+
+Install with `pip` or `uv`:
+
+```bash
+# pip
+pip install oracle-vecdb
+
+# uv
+uv add oracle-vecdb
+```
+
 ### Connect
 
 ```python
@@ -41,21 +60,27 @@ from oracle_vecdb import OracleVecDB, Configuration
 config = Configuration(
     rest_url="https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/",
     access_token="<access-token>",
+    access_token="<access-token>",
 )
 
 vecdb = OracleVecDB(config)
 ```
 
 ### Run a semantic search with metadata filtering
 
+> This example assumes a vector table named demo already exists and contains data. See the [full quickstart](https://docs.oracle.com/en/cloud/paas/autonomous-vector-database/vcapi/quickstart.html) for create_vector_table() and upsert().
+### Run a semantic search with metadata filtering
+
 > This example assumes a vector table named demo already exists and contains data. See the [full quickstart](https://docs.oracle.com/en/cloud/paas/autonomous-vector-database/vcapi/quickstart.html) for create_vector_table() and upsert().
 
 ```python
 results = vecdb.query(
     table_name="demo",
     query_by={"text": "family film"},  # uses integrated embeddings for the query text
+    query_by={"text": "family film"},  # uses integrated embeddings for the query text
     filters={"genre": {"$eq": "drama"}},
     top_k=3,
+    top_k=3,
 )
 
 for index in range(len(results)):
@@ -177,6 +202,120 @@ Learn Oracle VecDB hands-on. The Oracle AI Developer Hub includes runnable noteb
 
 [Browse all VecDB notebooks →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/notebooks/vecdb)
 
+---
+### ⚡ **Integrated embeddings. Automatic vector indexing. Semantic search + structured filtering. One Python SDK.**
+
+[Read the full quickstart →](https://docs.oracle.com/en/cloud/paas/autonomous-vector-database/vcapi/quickstart.html)
+
+---
+
+# 🧪 See what you can build
+
+Complete applications built with `oracle-vecdb` are available in the [Oracle AI Developer Hub](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/apps/vecdb).
+
+## 🌲 Semantic + Geospatial Search
+
+**Combine vector similarity with spatial filtering in one application.**
+
+Semantic search plus geographic and structured constraints, powered by Oracle AI Database.
+
+![Ask the Parks — semantic, metadata, and spatial search with Oracle VecDB](https://raw.githubusercontent.com/oracle-devrel/oracle-ai-developer-hub/main/apps/vecdb/vecdb_ask_parks/static/assets/ask_the_parks_demo.gif)
+
+**Oracle Spatial · Vector Search · Oracle VecDB**
+
+[View the sample app →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/apps/vecdb/vecdb_ask_parks)
+
+---
+
+## 💻 Semantic Code Search
+
+**Search source code by meaning, not just keywords.**
+
+Use natural-language queries to find relevant functions, files, and surrounding code.
+
+![Semantic Code Search - natural-language query, ranked code results, repository navigation, and highlighted source code](https://raw.githubusercontent.com/oracle-devrel/oracle-ai-developer-hub/main/apps/vecdb/semantic_code_search/images/semantic_code_search.gif)
+
+**FastAPI · React · Jina Embeddings · Oracle VecDB**
+
+[View the sample app →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/apps/vecdb/semantic_code_search)
+
+---
+
+## 🤖 RAG Document Chatbot
+
+**Upload documents and ask grounded questions over their content.**
+
+Chunk documents, generate embeddings, retrieve relevant context, and pass it to an LLM for grounded answers.
+
+![Document Chatbot UI showing uploaded documents, a user question, retrieved context, and a grounded answer](https://raw.githubusercontent.com/oracle-devrel/oracle-ai-developer-hub/main/apps/vecdb/doc_chatbot/images/doc_chat_bot.gif)
+
+**Streamlit · OpenAI / Ollama · Oracle VecDB**
+
+[View the sample app →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/apps/vecdb/doc_chatbot)
+
+---
+
+**More examples:** Multi-Modal Product Search, Product Recommendations · hands-on notebooks
+
+[Explore all sample applications →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/apps/vecdb)
+
+---
+
+# 💡 Why Oracle VecDB?
+
+Modern AI applications often need vector search plus the structured data around each result.
+
+Oracle VecDB lets Python applications use vector search alongside relational, spatial, and all other capabilities of the Oracle AI Database.
+
+Use Oracle VecDB to:
+
+- 🔎 Run semantic and similarity search
+- 🌍 Combine vector search with spatial and structured queries
+- 🤖 Build RAG applications and AI agents
+- 🧠 Use integrated embeddings or bring your own vectors
+- ⚡ Create vector indexes automatically by default
+- 🎛️ Tune HNSW and embedding settings when needed
+
+If you're building enterprise AI apps, the data you need is probably already in an Oracle AI Database, VecDB can reduce the need to move or synchronize that data into a separate vector database.
+
+---
+
+# 📓 Hands-on notebooks
+
+Learn Oracle VecDB hands-on. The Oracle AI Developer Hub includes runnable notebooks that take you from first query to production-oriented tuning.
+
+## 🧠 Embeddings & RAG
+
+- **Integrated embeddings** — generate embeddings as part of the VecDB workflow
+- **Bring Your Own Vectors** — use embeddings from your preferred model or provider
+- **Gemini RAG** — build retrieval-augmented generation with Gemini
+- **OCI Generative AI embeddings** — use OCI-hosted embedding models with VecDB
+- **Oracle Private AI Services Container** - use in an air-gapped environment with OpenAI-style inference layer
+
+[Explore embeddings & RAG notebooks →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/notebooks/vecdb)
+
+## 🔎 Search & filtering
+
+- **Semantic search** — retrieve results by meaning rather than keywords
+- **Metadata filtering** — combine vector similarity with structured constraints
+- **Search diagnostics** — inspect and understand vector-search behavior
+- **Financial-data search** — apply vector retrieval to structured financial datasets
+
+[Explore search notebooks →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/notebooks/vecdb)
+
+## ⚡ Performance & scale
+
+- **HNSW tuning** — understand and tune vector-index search parameters
+- **Bulk vector loading** — compare approaches for loading larger datasets
+- **Index management** — create, inspect, and manage vector indexes
+- **Maintenance workflows** — operate vector tables and indexes over time
+
+[Explore performance notebooks →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/notebooks/vecdb)
+
+> **New to Oracle VecDB?** Start with integrated embeddings and semantic search, then move on to filtering and HNSW tuning.
+
+[Browse all VecDB notebooks →](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/notebooks/vecdb)
+
 ---
 
 ## Examples
@@ -196,6 +335,18 @@ Learn Oracle VecDB hands-on. The Oracle AI Developer Hub includes runnable noteb
 - **[GitHub Releases](https://github.com/oracle/vecdb-python-sdk/releases)**
 - **[Locally-managed REST](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/26.2/)**
 
+---
+---
+
+# 📚 Documentation
+
+- **[Getting Started](https://docs.oracle.com/en/cloud/paas/autonomous-vector-database/vcapi/quickstart.html)**
+- **[Python API Reference](https://docs.oracle.com/en/cloud/paas/autonomous-vector-database/vcapi/python-api-reference.html)**
+- **[Sample Applications](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/apps/vecdb)**
+- **[Hands-on Notebooks](https://github.com/oracle-devrel/oracle-ai-developer-hub/tree/main/notebooks/vecdb)**
+- **[GitHub Releases](https://github.com/oracle/vecdb-python-sdk/releases)**
+- **[Locally-managed REST](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/26.2/)**
+
 ---
 
 ## Help
@@ -206,6 +357,8 @@ Problem reports can be raised in [GitHub Issues](https://github.com/oracle/vecdb
 
 ---
 
+---
+
 ## 🤝 Contributing
 
 This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)
@@ -214,12 +367,18 @@ This project welcomes contributions from the community. Before submitting a pull
 
 ---
 
+[Open an issue →](https://github.com/oracle/vecdb-python-sdk/issues)
+
+---
+
 ## 🔐 Security
 
 Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process
 
 ---
 
+---
+
 ## 📄 License
 
 See [LICENSE.txt](./LICENSE.txt), [THIRD_PARTY_LICENSE.txt](./THIRD_PARTY_LICENSE.txt), and [NOTICE.txt](./NOTICE.txt).
@@ -231,3 +390,11 @@ See [LICENSE.txt](./LICENSE.txt), [THIRD_PARTY_LICENSE.txt](./THIRD_PARTY_LICENS
 **[Star `oracle/vecdb-python-sdk` →](https://github.com/oracle/vecdb-python-sdk)**
 
 It helps you follow the project and helps other Python and AI developers discover it.
+
+---
+
+## ⭐ Like Oracle VecDB?
+
+**[Star `oracle/vecdb-python-sdk` →](https://github.com/oracle/vecdb-python-sdk)**
+
+It helps you follow the project and helps other Python and AI developers discover it.