oracle-haystack 0.1.0__tar.gz

oracle_haystack-0.1.0/.gitignore

@@ -0,0 +1,146 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# 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/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+volumes/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDEs
+.vscode
+
+# Docs generation artifacts
+_readme_*.md
+.idea
+
+# macOS
+.DS_Store
+
+# http cache (requests-cache)
+**/http_cache.sqlite
+
+# ruff
+.ruff_cache

oracle_haystack-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [integrations/oracle-v0.1.0] - 2026-04-15
+
+### 🚀 Features
+
+- Initial release of `oracle-haystack` — Haystack DocumentStore backed by Oracle AI Vector Search (Oracle Database 23ai+)
+- `OracleDocumentStore`: write, filter, count, and delete documents; embedding retrieval with COSINE/DOT_PRODUCT/EUCLIDEAN distance metrics
+- `OracleEmbeddingRetriever`: synchronous and asynchronous embedding-based retrieval with `FilterPolicy` support
+- `OracleConnectionConfig`: thin-mode (direct TCP) and thick-mode (wallet / ADB-S) connection configuration
+- Optional HNSW vector index creation (`create_index=True`) with configurable neighbours, ef-construction, accuracy, and parallelism
+- Connection pool managed via `oracledb.create_pool`; async operations offloaded with `asyncio.run_in_executor`
+
+### 🧪 Testing
+
+- Unit tests for `OracleDocumentStore`, `OracleEmbeddingRetriever`, and `FilterTranslator`
+- Integration test suite using a live Oracle 23ai Free instance (Docker-compose provided)
+- CI workflow (`.github/workflows/oracle.yml`) covering lint, unit tests, integration tests, and nightly Haystack-main compatibility checks

oracle_haystack-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: oracle-haystack
+Version: 0.1.0
+Summary: Oracle AI Vector Search DocumentStore integration for Haystack
+Project-URL: Source Code, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/oracle
+Project-URL: Bug Tracker, https://github.com/deepset-ai/haystack-core-integrations/issues
+Author-email: deepset GmbH <info@deepset.ai>
+License-Expression: Apache-2.0
+Keywords: OCI,RAG,document store,haystack,oracle,vector search
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=2.26.1
+Requires-Dist: oracledb<3.0.0,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# oracle-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/oracle-haystack.svg)](https://pypi.org/project/oracle-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oracle-haystack.svg)](https://pypi.org/project/oracle-haystack)
+
+Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.com/database/ai-vector-search/), available in Oracle Database 23ai and later.
+
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/oracle/CHANGELOG.md)
+
+---
+
+## Installation
+
+```bash
+pip install oracle-haystack
+```
+
+Requires Python 3.10+ and Oracle Database 23ai (or later). No Oracle Instant Client is needed for direct TCP connections (thin mode).
+
+## Usage
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.document_stores.oracle import OracleConnectionConfig, OracleDocumentStore
+from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever
+
+# Configure the connection
+config = OracleConnectionConfig(
+    user=Secret.from_env_var("ORACLE_USER"),
+    password=Secret.from_env_var("ORACLE_PASSWORD"),
+    dsn=Secret.from_env_var("ORACLE_DSN"),
+)
+
+# Create the document store
+store = OracleDocumentStore(
+    connection_config=config,
+    table_name="my_documents",
+    embedding_dim=768,
+    distance_metric="COSINE",
+    create_table_if_not_exists=True,
+)
+
+# Write documents
+from haystack.dataclasses import Document
+store.write_documents([
+    Document(content="Oracle 23ai supports native vector search."),
+])
+
+# Retrieve by embedding
+retriever = OracleEmbeddingRetriever(document_store=store, top_k=5)
+results = retriever.run(query_embedding=[0.1] * 768)
+print(results["documents"])
+```
+
+### Connecting to Oracle Autonomous Database (ADB-S / wallet)
+
+```python
+config = OracleConnectionConfig(
+    user=Secret.from_env_var("ORACLE_USER"),
+    password=Secret.from_env_var("ORACLE_PASSWORD"),
+    dsn=Secret.from_env_var("ORACLE_DSN"),
+    wallet_location="/path/to/wallet",
+    wallet_password=Secret.from_env_var("WALLET_PASSWORD"),
+)
+```
+
+### Optional HNSW index
+
+Pass `create_index=True` when constructing the store to build an HNSW vector index, which dramatically speeds up approximate nearest-neighbour search on large collections:
+
+```python
+store = OracleDocumentStore(
+    connection_config=config,
+    table_name="my_documents",
+    embedding_dim=768,
+    create_index=True,
+    hnsw_neighbors=32,
+    hnsw_ef_construction=200,
+    hnsw_accuracy=95,
+)
+```
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+### Running tests
+
+#### Unit tests
+
+```bash
+PYTHONPATH=src hatch run test:unit -vvv
+```
+
+#### Integration tests against a live Oracle instance
+
+Set `ORACLE_USER`, `ORACLE_PASSWORD`, and `ORACLE_DSN` environment variables to point at your Oracle 23ai instance, then:
+
+```bash
+PYTHONPATH=src hatch run test:integration -vvv
+```
+
+#### Integration tests via Docker (local Oracle 23ai Free)
+
+A `docker-compose.yml` is provided that runs [`gvenzl/oracle-free:23-slim`](https://hub.docker.com/r/gvenzl/oracle-free) (Oracle Database 23ai Free edition).
+
+```bash
+docker compose up -d --wait
+```
+
+`--wait` blocks until the Oracle healthcheck passes (the first boot takes 2–4 minutes while Oracle initialises its data files).
+
+Run the full integration test suite:
+
+```bash
+PYTHONPATH=src hatch run test:integration -vvv
+```

oracle_haystack-0.1.0/README.md

@@ -0,0 +1,117 @@
+# oracle-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/oracle-haystack.svg)](https://pypi.org/project/oracle-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oracle-haystack.svg)](https://pypi.org/project/oracle-haystack)
+
+Haystack DocumentStore backed by [Oracle AI Vector Search](https://www.oracle.com/database/ai-vector-search/), available in Oracle Database 23ai and later.
+
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/oracle/CHANGELOG.md)
+
+---
+
+## Installation
+
+```bash
+pip install oracle-haystack
+```
+
+Requires Python 3.10+ and Oracle Database 23ai (or later). No Oracle Instant Client is needed for direct TCP connections (thin mode).
+
+## Usage
+
+```python
+from haystack.utils import Secret
+from haystack_integrations.document_stores.oracle import OracleConnectionConfig, OracleDocumentStore
+from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever
+
+# Configure the connection
+config = OracleConnectionConfig(
+    user=Secret.from_env_var("ORACLE_USER"),
+    password=Secret.from_env_var("ORACLE_PASSWORD"),
+    dsn=Secret.from_env_var("ORACLE_DSN"),
+)
+
+# Create the document store
+store = OracleDocumentStore(
+    connection_config=config,
+    table_name="my_documents",
+    embedding_dim=768,
+    distance_metric="COSINE",
+    create_table_if_not_exists=True,
+)
+
+# Write documents
+from haystack.dataclasses import Document
+store.write_documents([
+    Document(content="Oracle 23ai supports native vector search."),
+])
+
+# Retrieve by embedding
+retriever = OracleEmbeddingRetriever(document_store=store, top_k=5)
+results = retriever.run(query_embedding=[0.1] * 768)
+print(results["documents"])
+```
+
+### Connecting to Oracle Autonomous Database (ADB-S / wallet)
+
+```python
+config = OracleConnectionConfig(
+    user=Secret.from_env_var("ORACLE_USER"),
+    password=Secret.from_env_var("ORACLE_PASSWORD"),
+    dsn=Secret.from_env_var("ORACLE_DSN"),
+    wallet_location="/path/to/wallet",
+    wallet_password=Secret.from_env_var("WALLET_PASSWORD"),
+)
+```
+
+### Optional HNSW index
+
+Pass `create_index=True` when constructing the store to build an HNSW vector index, which dramatically speeds up approximate nearest-neighbour search on large collections:
+
+```python
+store = OracleDocumentStore(
+    connection_config=config,
+    table_name="my_documents",
+    embedding_dim=768,
+    create_index=True,
+    hnsw_neighbors=32,
+    hnsw_ef_construction=200,
+    hnsw_accuracy=95,
+)
+```
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+### Running tests
+
+#### Unit tests
+
+```bash
+PYTHONPATH=src hatch run test:unit -vvv
+```
+
+#### Integration tests against a live Oracle instance
+
+Set `ORACLE_USER`, `ORACLE_PASSWORD`, and `ORACLE_DSN` environment variables to point at your Oracle 23ai instance, then:
+
+```bash
+PYTHONPATH=src hatch run test:integration -vvv
+```
+
+#### Integration tests via Docker (local Oracle 23ai Free)
+
+A `docker-compose.yml` is provided that runs [`gvenzl/oracle-free:23-slim`](https://hub.docker.com/r/gvenzl/oracle-free) (Oracle Database 23ai Free edition).
+
+```bash
+docker compose up -d --wait
+```
+
+`--wait` blocks until the Oracle healthcheck passes (the first boot takes 2–4 minutes while Oracle initialises its data files).
+
+Run the full integration test suite:
+
+```bash
+PYTHONPATH=src hatch run test:integration -vvv
+```

oracle_haystack-0.1.0/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  oracle:
+    image: gvenzl/oracle-free:23-slim
+    ports:
+      - 1521:1521
+    environment:
+      - ORACLE_PASSWORD=haystack
+      - APP_USER=haystack
+      - APP_USER_PASSWORD=haystack
+      - ORACLE_INIT_PARAMS=vector_memory_size=512M
+    volumes:
+      - ./init:/container-entrypoint-initdb.d
+    healthcheck:
+      test: ["CMD", "healthcheck.sh"]
+      interval: 10s
+      timeout: 5s
+      retries: 20
+      start_period: 30s

oracle_haystack-0.1.0/init/01_vector_memory.sql

@@ -0,0 +1,7 @@
+-- Enable vector memory pool required for HNSW in-memory vector indexes.
+-- This script runs at container startup via /container-entrypoint-initdb.d.
+-- The primary mechanism is ORACLE_INIT_PARAMS=vector_memory_size=512M in
+-- docker-compose.yml (writes to SPFILE at DB creation time).  This ALTER
+-- SYSTEM acts as a belt-and-suspenders dynamic setter for pre-existing
+-- database volumes where the SPFILE value may not have been written yet.
+ALTER SYSTEM SET vector_memory_size = 512M SCOPE=BOTH;

oracle_haystack-0.1.0/pydoc/config_docusaurus.yml

@@ -0,0 +1,14 @@
+loaders:
+  - modules:
+      - haystack_integrations.components.retrievers.oracle.embedding_retriever
+      - haystack_integrations.document_stores.oracle.document_store
+    search_path: [../src]
+processors:
+  - type: filter
+    documented_only: true
+    skip_empty_modules: true
+renderer:
+  description: Oracle AI Vector Search integration for Haystack
+  id: integrations-oracle
+  filename: oracle.md
+  title: Oracle AI Vector Search

oracle_haystack-0.1.0/pyproject.toml

@@ -0,0 +1,173 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oracle-haystack"
+dynamic = ["version"]
+description = "Oracle AI Vector Search DocumentStore integration for Haystack"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+keywords = ["haystack", "oracle", "vector search", "document store", "RAG", "OCI"]
+authors = [{ name = "deepset GmbH", email = "info@deepset.ai" }]
+classifiers = [
+  "License :: OSI Approved :: Apache Software License",
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
+dependencies = [
+  "haystack-ai>=2.26.1",
+  "oracledb>=2.1.0,<3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "ruff>=0.4.0",
+  "mypy>=1.9.0",
+]
+
+[project.urls]
+"Source Code" = "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/oracle"
+"Bug Tracker" = "https://github.com/deepset-ai/haystack-core-integrations/issues"
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = 'integrations\/oracle-v(?P<version>.*)'
+fallback-version = "0.1.0"
+
+[tool.hatch.version.raw-options]
+root = "../.."
+git_describe_command = 'git describe --tags --match="integrations/oracle-v[0-9]*"'
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/haystack_integrations"]
+
+[tool.hatch.envs.default]
+installer = "uv"
+dependencies = ["haystack-pydoc-tools", "ruff"]
+
+[tool.hatch.envs.default.scripts]
+docs = ["haystack-pydoc pydoc/config_docusaurus.yml"]
+fmt = "ruff check --fix {args}; ruff format {args}"
+fmt-check = "ruff check {args} && ruff format --check {args}"
+
+[tool.hatch.envs.test]
+dependencies = [
+  "pytest",
+  "pytest-asyncio",
+  "pytest-cov",
+  "pytest-rerunfailures",
+  "mypy",
+  "pip",
+]
+
+[tool.hatch.envs.test.scripts]
+unit = 'pytest -m "not integration" {args:tests}'
+integration = 'pytest -m "integration" {args:tests}'
+all = 'pytest {args:tests}'
+unit-cov-retry = 'pytest --cov=haystack_integrations --reruns 3 --reruns-delay 30 -x -m "not integration" {args:tests}'
+integration-cov-append-retry = 'pytest --cov=haystack_integrations --cov-append --reruns 3 --reruns-delay 30 -x -m "integration" {args:tests}'
+types = "mypy -p haystack_integrations.document_stores.oracle -p haystack_integrations.components.retrievers.oracle {args}"
+
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+markers = ["unit: unit tests", "integration: integration tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "class"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+  "A",
+  "ANN",
+  "ARG",
+  "B",
+  "C",
+  "D102",   # Missing docstring in public method
+  "D103",   # Missing docstring in public function
+  "D205",   # 1 blank line required between summary line and description
+  "D209",   # Closing triple quotes go to new line
+  "D213",   # summary lines must be positioned on the second physical line of the docstring
+  "D417",   # Missing argument descriptions in the docstring
+  "D419",   # Docstring is empty
+  "DTZ",
+  "E",
+  "EM",
+  "F",
+  "FBT",
+  "I",
+  "ICN",
+  "ISC",
+  "N",
+  "PLC",
+  "PLE",
+  "PLR",
+  "PLW",
+  "Q",
+  "RUF",
+  "S",
+  "T",
+  "TID",
+  "UP",
+  "W",
+  "YTT",
+]
+ignore = [
+  # Allow non-abstract empty methods in abstract base classes
+  "B027",
+  # Allow boolean positional values in function calls, like `dict.get(... True)`
+  "FBT003",
+  # Ignore checks for possible passwords
+  "S105",
+  "S106",
+  "S107",
+  # Ignore complexity
+  "C901",
+  "PLR0911",
+  "PLR0912",
+  "PLR0913",
+  "PLR0915",
+  # Allow `Any` - used legitimately for dynamic types and SDK boundaries
+  "ANN401",
+  # SQL is built from developer-supplied, regex-validated identifiers (table_name,
+  # distance_metric, embedding_dim); all user data is bound via named parameters.
+  "S608",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["haystack_integrations"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can use magic values, assertions, relative imports, and don't need type annotations
+"tests/**/*" = ["D", "PLR2004", "S101", "TID252", "ANN"]
+
+[tool.coverage.run]
+source = ["haystack_integrations"]
+branch = true
+relative_files = true
+parallel = false
+
+[tool.coverage.report]
+omit = ["*/tests/*", "*/__init__.py"]
+show_missing = true
+exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
+
+[tool.mypy]
+install_types = true
+non_interactive = true
+check_untyped_defs = true
+disallow_incomplete_defs = true

oracle_haystack-0.1.0/src/haystack_integrations/components/retrievers/oracle/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2023-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack_integrations.components.retrievers.oracle.embedding_retriever import OracleEmbeddingRetriever
+
+__all__ = ["OracleEmbeddingRetriever"]