Initial public release

Author: Silviano Diaz

.github/workflows/build.yml

@@ -0,0 +1,41 @@
+name: Build oracle-vecdb Python SDK
+
+permissions:
+  contents: read
+
+# Build job automatically on tags, e.g., v1.0.0, v2.1.3, etc.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout the repository to access code and build artifacts
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Set up Python for building the SDK
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      # Install build dependencies
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      # Build vecdb Python SDK
+      - name: Build vecdb Python SDK
+        run: python -m build --sdist --wheel --outdir dist/
+
+      # Upload build artifacts for use in Publish workflow
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: vecdb-python-sdk-artifacts
+          path: dist/*

.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+reports/
+
+venv/
+.venv310/
+.venv/
+.vscode/
+.python-version
+.pytest_cache
+.mypy_cache/
+
+
+# Translations
+*.mo
+*.pot
+
+*.log
+
+# Sphinx documentation
+docs/build/
+
+# PyBuilder
+target/
+
+# Ipython Notebook
+.ipynb_checkpoints
+
+# Oracle Parfait analysis cache
+__parfait__/

AGENTS.md

@@ -0,0 +1,113 @@
+# Agent Guide: vecdb-python-sdk
+
+## Purpose
+
+- This repository owns the Oracle VecDB Python SDK, its public Python API,
+  examples, package metadata, tests, and changelog.
+
+## Workspace Setup
+
+- Python 3.10+ is the user-facing requirement from `README.md` and
+  `pyproject.toml`.
+- Keep real hosts, tokens, usernames, passwords, and production table names out
+  of committed examples, tests, issues, and reviews.
+- Prefer `Configuration.access_token` when bearer tokens are available; use
+  username/password only when the target environment requires it.
+- Use host placeholders that preserve the documented ORDS VecDB URL shape:
+  `https://<host>/ords/<schema>/_/db-api/stable/vecdb/`.
+
+## API Surface (OracleVecDB)
+
+- Table management (`create_vector_table`, `describe_vector_table`,
+  `drop_vector_table`, `list_vector_tables`, `update_vector_table_annotation`).
+- Index lifecycle (`create_index`, `describe_index`, `describe_index_job`,
+  `list_index_jobs`, `get_index_job_log`, `rebuild_index`, `drop_index`).
+- Inference (`generate_embedding`, `rerank`).
+- Model orchestration (`load_model`, `list_models`, `describe_model`,
+  `drop_model`).
+- Vector operations (`upsert_vectors`, `list_vectors`, `delete_vectors`,
+  `load_vectors`, `describe_vector_load_job`, `get_vector_load_job_log`,
+  `list_vector_load_jobs`).
+- Search (`query`).
+- Summary (`describe_vector_database`).
+
+## Capability Workflows
+
+- Authentication and configuration: construct `Configuration` with a VecDB ORDS
+  host and either `access_token` or `username`/`password`, then pass it to
+  `OracleVecDB`.
+- Model management: use `list_models` and `describe_model` before binding a
+  model to table or rerank workflows. Use `load_model` and `drop_model` only
+  when the task explicitly includes model lifecycle work.
+- Vector tables: use `describe_vector_database` and `list_vector_tables` for
+  discovery, `create_vector_table` for storage, `describe_vector_table` for
+  schema/index checks, `update_vector_table_annotation` for metadata updates,
+  and `drop_vector_table` for cleanup when the workflow owns the table.
+- Ingestion: use `upsert_vectors` for inline batches, `delete_vectors` for
+  removing known records, `list_vectors` for inspection, and `load_vectors`
+  for object-storage bulk ingestion. Monitor bulk jobs with
+  `list_vector_load_jobs`, `describe_vector_load_job`, and
+  `get_vector_load_job_log`.
+- Embeddings and reranking: use hosted VecDB model flows through
+  `generate_embedding`, integrated table embedding configuration, `query`, and
+  `rerank`.
+- Search: use `query` with `query_by`, `top_k`, and verified `filters`. Query
+  examples may search by text, vector, or record ID only when that shape is
+  verified from README, docs, source, tests, or explicit checked instruction.
+- Index lifecycle: use `create_index`, `list_index_jobs`,
+  `describe_index_job`, `get_index_job_log`, `rebuild_index`,
+  `describe_index`, and `drop_index` for index build, monitoring, tuning, and
+  cleanup workflows.
+
+## Query Filters
+
+The public `query` method accepts a filter dictionary and forwards it through
+the SDK request model. The REST documentation lists these filter operators:
+
+```python
+filters = {
+    "$and": [
+        {"ACCOUNT_CATEGORY": {"$eq": "Savings"}},
+        {"ELIGIBILITY": {"$eq": "Student"}},
+        {"MONTHLY_FEE": {"$lte": 5}},
+    ]
+}
+```
+
+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.
+
+## Quick Start
+
+- Use the `README.md` Quickstart as the source of truth for runnable
+  quick-start examples.
+- Use the README Quickstart for integrated embedding flows and the README
+  "Bring your own vectors" section for BYOV examples.
+- If a quick-start flow changes, update `README.md` first and keep this section
+  as a pointer rather than duplicating runnable snippets.
+- Verify any adapted quick-start code against the public SDK surface in this
+  repo before publishing it.
+
+## Workflow Pointers
+
+- For SDK consumer examples, start with `README.md` and `docs/source/`.
+- For public method availability, inspect `OracleVecDB` in
+  `src/oracle_vecdb/client.py` and existing tests.
+- For request or response details, prefer typed SDK models and tests over
+  copied REST payloads.
+- For examples that create resources, include cleanup when it is part of the
+  demonstrated workflow and does not obscure the main point.
+
+## Troubleshooting
+
+- 401 or 403: check credentials, token freshness, endpoint privileges, and
+  schema access without exposing secret values.
+- 404: verify the ORDS URL shape, schema segment, table name, model name, index
+  name, and job name.
+- 409 or job conflicts: inspect existing load or index jobs before retrying.
+- Embedding or rerank failures: verify model availability and the public SDK
+  request shape before suggesting code changes.
+- Large payloads: prefer `load_vectors` over massive inline upserts when the
+  input is already staged in object storage.
+- Slow or unexpected search results: inspect table, index, filter, and query
+  configuration using public SDK methods before recommending service tuning.

CHANGELOG.rst

@@ -0,0 +1,54 @@
+Changelog
+=========
+
+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.0 - 2026-07-15
+------------------
+
+Added
+~~~~~
+
+- Initial public release of oracle_vecdb
+- Support for vector table management, indexing, search, and inference operations in Oracle AI Database (26ai+). Refer this for detailed documentation -
+ https://docs.oracle.com/en/cloud/paas/autonomous-vector-database/vcapi/overview.html
+
+
+1.0.0b2 - 2026-04-30
+------------------
+
+Added
+~~~~~
+
+- Added support for automatic batching during large dataset upsert.
+- Added support for case-insensitive input keys, allowing user data to use any capitalization for ID, DENSE_VECTOR, and METADATA.
+- Updated the host URL validation pattern to work in ExaCC environments for pool mappings.
+- Added "rest_url" as the preferred parameter and deprecated "host", with support for disabling "host" later via a feature toggle.
+
+Changed
+~~~~~~~
+
+- Renamed `agent.md` to `AGENTS.md` and streamlined it around verified public SDK workflows.
+
+Fixed
+~~~~~
+
+- Fixed the ``rerank`` API reference to mention results from ``query`` instead of ``query_vectors()``.
+
+1.0.0b1 - 2026-03-24
+------------------
+
+Added
+~~~~~
+
+- Limited Availability release.
+- Support for vector table management, indexing, search, and inference operations in Oracle AI Database (26ai+).
+
+
+Compatibility
+----------
+Requires - Oracle AI Database 23.26.3 and later with ORDS 26.2.2 and later
+Supported languages: Python 3.10+

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to this repository
+
+We welcome your contributions! There are multiple ways to contribute.
+
+## Opening issues
+
+For bugs or enhancement requests, please file a GitHub issue unless it's
+security related. When filing a bug remember that the better written the bug is,
+the more likely it is to be fixed. If you think you've found a security
+vulnerability, do not raise a GitHub issue and follow the instructions in our
+[security policy](./SECURITY.md).
+
+## Contributing code
+
+We welcome your code contributions. Before submitting code via a pull request,
+you will need to have signed the [Oracle Contributor Agreement][OCA] (OCA) and
+your commits need to include the following line using the name and e-mail
+address you used to sign the OCA:
+
+```text
+Signed-off-by: Your Name <you@example.org>
+```
+
+This can be automatically added to pull requests by committing with `--sign-off`
+or `-s`, e.g.
+
+```text
+git commit --signoff
+```
+
+Only pull requests from committers that can be verified as having signed the OCA
+can be accepted.
+
+## Pull request process
+
+1. Ensure there is an issue created to track and discuss the fix or enhancement
+   you intend to submit.
+1. Fork this repository.
+1. Create a branch in your fork to implement the changes. We recommend using
+   the issue number as part of your branch name, e.g. `1234-fixes`.
+1. Ensure that any documentation is updated with the changes that are required
+   by your change.
+1. Ensure that any samples are updated if the base image has been changed.
+1. Submit the pull request. *Do not leave the pull request blank*. Explain exactly
+   what your changes are meant to do and provide simple steps on how to validate.
+   your changes. Ensure that you reference the issue you created as well.
+1. We will assign the pull request to 2-3 people for review before it is merged.
+
+## Code of conduct
+
+Follow the [Golden Rule](https://en.wikipedia.org/wiki/Golden_Rule). If you'd
+like more specific guidelines, see the [Contributor Covenant Code of Conduct][COC].
+
+[OCA]: https://oca.opensource.oracle.com
+[COC]: https://www.contributor-covenant.org/version/1/4/code-of-conduct/

LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2026 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE.txt README.md CHANGELOG.rst pyproject.toml
+recursive-include examples *.py