Skip to content

Commit 98b5488

Browse files
rriley99-ociomaryashraf5franciscojavierarceo
authored
feat(new provider): Adding OCI 26ai Vector Support (llamastack#4411)
# What does this PR do? Adding Oracle 26ai as a vector store. <!-- If resolving an issue, uncomment and update the line below --> <!-- Closes #[issue-number] --> ## Test Plan We cannot as of yet add integration tests without providing a database for 26ai. However, they can be run locally with: ``` uv run --env-file .env -- pytest -sv tests/integration/vector_io \ --stack-config="inference=oci,vector_io=oci,files=s3" \ --embedding-model oci/openai.text-embedding-3-small \ --embedding-dimension 768 \ --inference-mode live ``` FYI here are the results from the test: <img width="995" height="141" alt="image" src="https://github.com/user-attachments/assets/b3c23633-886d-43dc-b977-6bc01d616ea2" /> These tests fail bc they pull the wrong documents in the test. However it works perfectly fine in our external blueprint tools. It appears that the similarity scores for the open-ai models provided by oci collapse near 0, which causes issues in these test specifically. --------- Co-authored-by: Omar Abdelwahab <omaryashraf10@gmail.com> Co-authored-by: Francisco Javier Arceo <arceofrancisco@gmail.com>
1 parent 95ab7c2 commit 98b5488

14 files changed

Lines changed: 952 additions & 13 deletions

File tree

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,7 @@ docs/docs/api-experimental/
3737
docs/docs/api/
3838
tests/integration/client-typescript/node_modules/
3939
.ts-client-checkout/
40+
41+
# oracle connection files
42+
**/tnsnames.ora
43+
**/ewallet.pem

‎docs/docs/providers/vector_io/remote_oci.mdx‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
description: |
3+
[Oracle 26ai](https://docs.oracle.com/en/database/oracle/oracle-database/26/index.html)
4+
is a remote vector database provider for Llama Stack. It allows you to store and query vectors directly
5+
in an Oracle 26ai database.
6+
## Features
7+
- Easy to use
8+
- Fully integrated with Llama Stack
9+
- Supports vector search, keyword search, and hybrid search
10+
## Usage
11+
To use Oracle 26ai in your Llama Stack project, follow these steps:
12+
1. Install the necessary dependencies.
13+
2. Configure your Llama Stack project to use Oracle 26ai.
14+
3. Start storing and querying vectors.
15+
## Installation
16+
You can install the Oracle 26ai client using pip:
17+
```bash
18+
pip install oracledb
19+
```
20+
## Configuration
21+
```yaml
22+
vector_io:
23+
- provider_id: oci
24+
provider_type: remote::oci
25+
config:
26+
conn_str: "${env.OCI26AI_CONNECTION_STRING}"
27+
user: "${env.OCI26AI_USER}"
28+
password: "${env.OCI26AI_PASSWORD}"
29+
tnsnames_loc: "${env.OCI26AI_TNSNAMES_LOC}"
30+
ewallet_pem_loc: "${env.OCI26AI_EWALLET_PEM_LOC}"
31+
ewallet_password: "${env.OCI26AI_EWALLET_PWD}"
32+
vector_datatype: "${env.OCI26AI_VECTOR_DATATYPE:=FLOAT32}"
33+
persistence:
34+
namespace: vector_id::oci26ai
35+
backend: kv_default
36+
```
37+
## Documentation
38+
See the [Oracle 26ai documentation](https://docs.oracle.com/en/database/oracle/oracle-database/26/index.html)
39+
for more details about Oracle 26ai in general.
40+
sidebar_label: Remote - Oci
41+
title: remote::oci
42+
---
43+
44+
# remote::oci
45+
46+
## Description
47+
48+
49+
[Oracle 26ai](https://docs.oracle.com/en/database/oracle/oracle-database/26/index.html)
50+
is a remote vector database provider for Llama Stack. It allows you to store and query vectors directly
51+
in an Oracle 26ai database.
52+
## Features
53+
- Easy to use
54+
- Fully integrated with Llama Stack
55+
- Supports vector search, keyword search, and hybrid search
56+
## Usage
57+
To use Oracle 26ai in your Llama Stack project, follow these steps:
58+
1. Install the necessary dependencies.
59+
2. Configure your Llama Stack project to use Oracle 26ai.
60+
3. Start storing and querying vectors.
61+
## Installation
62+
You can install the Oracle 26ai client using pip:
63+
```bash
64+
pip install oracledb
65+
```
66+
## Configuration
67+
```yaml
68+
vector_io:
69+
- provider_id: oci
70+
provider_type: remote::oci
71+
config:
72+
conn_str: "${env.OCI26AI_CONNECTION_STRING}"
73+
user: "${env.OCI26AI_USER}"
74+
password: "${env.OCI26AI_PASSWORD}"
75+
tnsnames_loc: "${env.OCI26AI_TNSNAMES_LOC}"
76+
ewallet_pem_loc: "${env.OCI26AI_EWALLET_PEM_LOC}"
77+
ewallet_password: "${env.OCI26AI_EWALLET_PWD}"
78+
vector_datatype: "${env.OCI26AI_VECTOR_DATATYPE:=FLOAT32}"
79+
persistence:
80+
namespace: vector_id::oci26ai
81+
backend: kv_default
82+
```
83+
## Documentation
84+
See the [Oracle 26ai documentation](https://docs.oracle.com/en/database/oracle/oracle-database/26/index.html)
85+
for more details about Oracle 26ai in general.
86+
87+
88+
## Configuration
89+
90+
| Field | Type | Required | Default | Description |
91+
|-------|------|----------|---------|-------------|
92+
| `conn_str` | `str` | No | | Connection string for the given 26ai Service |
93+
| `user` | `str` | No | | Username name to connect to the service |
94+
| `password` | `str` | No | | Password to connect to the service |
95+
| `tnsnames_loc` | `str` | No | | Directory location of the tsnanames.ora file |
96+
| `ewallet_pem_loc` | `str` | No | | Directory location of the ewallet.pem file |
97+
| `ewallet_password` | `str` | No | | Password for the ewallet.pem file |
98+
| `persistence` | `KVStoreReference` | No | | Config for KV store backend |
99+
| `persistence.namespace` | `str` | No | | Key prefix for KVStore backends |
100+
| `persistence.backend` | `str` | No | | Name of backend from storage.backends |
101+
| `consistency_level` | `str` | No | Strong | The consistency level of the OCI26ai server |
102+
| `vector_datatype` | `str` | No | FLOAT32 | Vector datatype for embeddings |
103+
104+
## Sample Configuration
105+
106+
```yaml
107+
conn_str: ${env.OCI26AI_CONNECTION_STRING}
108+
user: ${env.OCI26AI_USER}
109+
password: ${env.OCI26AI_PASSWORD}
110+
tnsnames_loc: ${env.OCI26AI_TNSNAMES_LOC}
111+
ewallet_pem_loc: ${env.OCI26AI_EWALLET_PEM_LOC}
112+
ewallet_password: ${env.OCI26AI_EWALLET_PWD}
113+
vector_datatype: ${env.OCI26AI_VECTOR_DATATYPE:=FLOAT32}
114+
persistence:
115+
namespace: vector_io::oci26ai
116+
backend: kv_default
117+
```

‎docs/notebooks/oci/OCI_LlamaStack_Agents_Demo.ipynb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2136,7 +2136,7 @@
21362136
],
21372137
"metadata": {
21382138
"kernelspec": {
2139-
"display_name": "Python 3 (ipykernel)",
2139+
"display_name": "llama-stack",
21402140
"language": "python",
21412141
"name": "python3"
21422142
},
@@ -2150,7 +2150,7 @@
21502150
"name": "python",
21512151
"nbconvert_exporter": "python",
21522152
"pygments_lexer": "ipython3",
2153-
"version": "3.12.7"
2153+
"version": "3.12.12"
21542154
}
21552155
},
21562156
"nbformat": 4,

‎docs/sidebars.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,8 @@ const sidebars: SidebarsConfig = {
170170
'providers/vector_io/remote_pgvector',
171171
'providers/vector_io/remote_qdrant',
172172
'providers/vector_io/remote_weaviate',
173-
'providers/vector_io/remote_elasticsearch'
173+
'providers/vector_io/remote_elasticsearch',
174+
'providers/vector_io/remote_oci'
174175
],
175176
},
176177
{

‎pyproject.toml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,10 @@ dependencies = [
5656
"psycopg2-binary",
5757
"tornado>=6.5.3",
5858
"urllib3>=2.6.3",
59-
"mcp>=1.23.0" # for connectors
59+
"oracledb>=3.4.1",
60+
"oci>=2.165.0",
61+
"numpy>=2.3.2",
62+
"mcp>=1.23.0", # for connectors
6063
]
6164

6265
[project.optional-dependencies]

‎src/llama_stack/providers/registry/vector_io.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -894,6 +894,55 @@ def available_providers() -> list[ProviderSpec]:
894894
895895
## Documentation
896896
See [Elasticsearch's documentation](https://www.elastic.co/docs/solutions/search) for more details about Elasticsearch in general.
897+
""",
898+
),
899+
RemoteProviderSpec(
900+
api=Api.vector_io,
901+
adapter_type="oci",
902+
provider_type="remote::oci",
903+
pip_packages=["oracledb", "numpy"] + DEFAULT_VECTOR_IO_DEPS,
904+
module="llama_stack.providers.remote.vector_io.oci",
905+
config_class="llama_stack.providers.remote.vector_io.oci.OCI26aiVectorIOConfig",
906+
api_dependencies=[Api.inference],
907+
optional_api_dependencies=[Api.files, Api.models],
908+
description="""
909+
[Oracle 26ai](https://docs.oracle.com/en/database/oracle/oracle-database/26/index.html)
910+
is a remote vector database provider for Llama Stack. It allows you to store and query vectors directly
911+
in an Oracle 26ai database.
912+
## Features
913+
- Easy to use
914+
- Fully integrated with Llama Stack
915+
- Supports vector search, keyword search, and hybrid search
916+
## Usage
917+
To use Oracle 26ai in your Llama Stack project, follow these steps:
918+
1. Install the necessary dependencies.
919+
2. Configure your Llama Stack project to use Oracle 26ai.
920+
3. Start storing and querying vectors.
921+
## Installation
922+
You can install the Oracle 26ai client using pip:
923+
```bash
924+
pip install oracledb
925+
```
926+
## Configuration
927+
```yaml
928+
vector_io:
929+
- provider_id: oci
930+
provider_type: remote::oci
931+
config:
932+
conn_str: "${env.OCI26AI_CONNECTION_STRING}"
933+
user: "${env.OCI26AI_USER}"
934+
password: "${env.OCI26AI_PASSWORD}"
935+
tnsnames_loc: "${env.OCI26AI_TNSNAMES_LOC}"
936+
ewallet_pem_loc: "${env.OCI26AI_EWALLET_PEM_LOC}"
937+
ewallet_password: "${env.OCI26AI_EWALLET_PWD}"
938+
vector_datatype: "${env.OCI26AI_VECTOR_DATATYPE:=FLOAT32}"
939+
persistence:
940+
namespace: vector_id::oci26ai
941+
backend: kv_default
942+
```
943+
## Documentation
944+
See the [Oracle 26ai documentation](https://docs.oracle.com/en/database/oracle/oracle-database/26/index.html)
945+
for more details about Oracle 26ai in general.
897946
""",
898947
),
899948
]

‎src/llama_stack/providers/remote/vector_io/oci/__init__.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the terms described in the LICENSE file in
5+
# the root directory of this source tree.
6+
7+
from llama_stack.providers.remote.vector_io.oci.config import OCI26aiVectorIOConfig
8+
from llama_stack_api import Api, ProviderSpec
9+
10+
11+
async def get_adapter_impl(config: OCI26aiVectorIOConfig, deps: dict[Api, ProviderSpec]):
12+
from typing import cast
13+
14+
from llama_stack.providers.remote.vector_io.oci.oci26ai import OCI26aiVectorIOAdapter
15+
from llama_stack_api import Files, Inference
16+
17+
assert isinstance(config, OCI26aiVectorIOConfig), f"Unexpected config type: {type(config)}"
18+
inference_api = cast(Inference, deps[Api.inference])
19+
files_api = cast(Files | None, deps.get(Api.files))
20+
impl = OCI26aiVectorIOAdapter(config, inference_api, files_api)
21+
await impl.initialize()
22+
return impl

‎src/llama_stack/providers/remote/vector_io/oci/config.py‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Copyright (c) Meta Platforms, Inc. and affiliates.
2+
# All rights reserved.
3+
#
4+
# This source code is licensed under the terms described in the LICENSE file in
5+
# the root directory of this source tree.
6+
7+
from typing import Any
8+
9+
from pydantic import BaseModel, Field
10+
11+
from llama_stack.core.storage.datatypes import KVStoreReference
12+
from llama_stack_api import json_schema_type
13+
14+
15+
@json_schema_type
16+
class OCI26aiVectorIOConfig(BaseModel):
17+
conn_str: str = Field(description="Connection string for the given 26ai Service")
18+
user: str = Field(description="Username name to connect to the service")
19+
password: str = Field(description="Password to connect to the service")
20+
tnsnames_loc: str = Field(description="Directory location of the tsnanames.ora file")
21+
ewallet_pem_loc: str = Field(description="Directory location of the ewallet.pem file")
22+
ewallet_password: str = Field(description="Password for the ewallet.pem file")
23+
persistence: KVStoreReference = Field(description="Config for KV store backend")
24+
consistency_level: str = Field(description="The consistency level of the OCI26ai server", default="Strong")
25+
vector_datatype: str = Field(description="Vector datatype for embeddings", default="FLOAT32")
26+
27+
@classmethod
28+
def sample_run_config(cls, __distro_dir__: str, **kwargs: Any) -> dict[str, Any]:
29+
return {
30+
"conn_str": "${env.OCI26AI_CONNECTION_STRING}",
31+
"user": "${env.OCI26AI_USER}",
32+
"password": "${env.OCI26AI_PASSWORD}",
33+
"tnsnames_loc": "${env.OCI26AI_TNSNAMES_LOC}",
34+
"ewallet_pem_loc": "${env.OCI26AI_EWALLET_PEM_LOC}",
35+
"ewallet_password": "${env.OCI26AI_EWALLET_PWD}",
36+
"vector_datatype": "${env.OCI26AI_VECTOR_DATATYPE:=FLOAT32}",
37+
"persistence": KVStoreReference(
38+
backend="kv_default",
39+
namespace="vector_io::oci26ai",
40+
).model_dump(exclude_none=True),
41+
}

0 commit comments

Comments
 (0)