feat: Add support for embedded operations in IRISVector and enhance runtime facade with execute, gref, and ref methods

Author: bot

README.md

@@ -418,8 +418,9 @@ For the native object proxy path (`iris.cls(...)` with `iris.runtime` configured
 ##### ByRef
 
 `iris.ByRef(value)` is a lightweight by-reference container with a mutable
-`.value` attribute. `iris.make_ref(value)` returns `iris.ref` when the
-embedded runtime exposes it and falls back to `ByRef` otherwise.
+`.value` attribute. `iris.ref(value)` and `iris.make_ref(value)` use the
+embedded runtime reference type when available and otherwise return a
+`ByRef`-compatible container.
 
 For ObjectScript methods that declare a `ByRef` argument:
 
@@ -478,7 +479,34 @@ with SQL `TO_VECTOR(?, decimal)`, `TO_VECTOR(?, double)`, or
 storage; embedded `$VECTOROP` operations evaluate that value as an
 ObjectScript double because `$VECTOR` has no float storage type. Vector
 operations delegate to embedded ObjectScript `$VECTOROP`, so they require an
-embedded runtime with `iris.gref` and `iris.execute` available.
+embedded runtime with `iris.gref` and `iris.execute` available. They are not
+routed through the remote/native bridge.
+
+FastEmbed is an optional dependency (`pip install fastembed`). It returns NumPy
+embedding arrays, which can be passed directly to `iris.Vector`:
+
+```python
+from fastembed import TextEmbedding
+import iris
+
+model = TextEmbedding(model_name="BAAI/bge-small-en-v1.5")
+embedding = iris.Vector(next(model.embed(["store this text"])), dtype="float")
+
+cur.execute(
+	"INSERT INTO Demo.Documents (content, embedding) VALUES (?, TO_VECTOR(?, float))",
+	("store this text", embedding),
+)
+```
+
+Complete runnable examples:
+
+- [`examples/fastembed_vector_search.py`](examples/fastembed_vector_search.py)
+  stores embeddings in an IRIS SQL `VECTOR` column and ranks with
+  `VECTOR_COSINE`.
+- [`examples/fastembed_vector_operations.py`](examples/fastembed_vector_operations.py)
+  keeps the embeddings as Python `iris.Vector` objects and ranks with
+  `Vector.cosine()` without SQL. It requires embedded `iris.gref` and
+  `iris.execute`.
 
 #### Connect modes
 

_iris_ep/_runtime_facade.py

@@ -9,6 +9,7 @@
 from iris_utils._module_exports import copy_public_exports
 
 from . import _bootstrap
+from ._byref import ByRef
 from ._dbapi import make_dbapi
 
 _WRAPPER_EXPORTS = {
@@ -17,6 +18,9 @@
     "dbapi",
     "cls",
     "connect",
+    "execute",
+    "gref",
+    "ref",
     "ByRef",
     "make_ref",
     "IRISVector",
@@ -287,8 +291,20 @@ def public_cls(class_name):
         def public_connect(*args, path=None, **kwargs):
             return self.connect(*args, path=path, **kwargs)
 
+        def public_execute(statements):
+            return self.execute(statements)
+
+        def public_gref(global_name):
+            return self.gref(global_name)
+
+        def public_ref(value=""):
+            return self.ref(value)
+
         public_cls.__name__ = "cls"
         public_connect.__name__ = "connect"
+        public_execute.__name__ = "execute"
+        public_gref.__name__ = "gref"
+        public_ref.__name__ = "ref"
         self._public_cls = public_cls
         self._public_connect = public_connect
 
@@ -297,6 +313,9 @@ def public_connect(*args, path=None, **kwargs):
         self.module_globals["dbapi"] = self.dbapi
         self.module_globals["cls"] = public_cls
         self.module_globals["connect"] = public_connect
+        self.module_globals["execute"] = public_execute
+        self.module_globals["gref"] = public_gref
+        self.module_globals["ref"] = public_ref
 
     def finalize_all(self) -> None:
         existing_all = self.module_globals.get("__all__")
@@ -313,6 +332,9 @@ def finalize_all(self) -> None:
             "dbapi",
             "cls",
             "connect",
+            "execute",
+            "gref",
+            "ref",
             "ByRef",
             "make_ref",
             "IRISVector",
@@ -378,6 +400,9 @@ def sync_public_modules(self):
                 "cls",
                 "connect",
                 "system",
+                "execute",
+                "gref",
+                "ref",
                 "ByRef",
                 "make_ref",
                 "IRISVector",
@@ -454,6 +479,82 @@ def get_dbapi_embedded_cls(self):
             return cls_candidate
         return None
 
+    def _get_embedded_module_attr(self, current_runtime, name, *, required=False):
+        current_runtime = self.ensure_embedded_backend(
+            current_runtime,
+            required=required,
+        )
+        module = getattr(current_runtime, "embedded_module", None)
+        if module is not None:
+            attr = getattr(module, name, None)
+            if callable(attr):
+                return attr
+        return None
+
+    def execute(self, statements):
+        current_runtime = self.runtime_manager.get()
+        if current_runtime.mode == "native":
+            if current_runtime.iris is None:
+                raise RuntimeError("iris.runtime is configured for native mode, but no native IRIS handle is bound")
+            raise RuntimeError("iris.execute requires an embedded runtime")
+
+        if current_runtime.mode == "embedded":
+            embedded_execute = self._get_embedded_module_attr(
+                current_runtime,
+                "execute",
+                required=True,
+            )
+            if callable(embedded_execute):
+                return embedded_execute(statements)
+            raise RuntimeError("iris.runtime is configured for embedded mode, but embedded execute is unavailable")
+
+        if current_runtime.embedded_available:
+            embedded_execute = self._get_embedded_module_attr(current_runtime, "execute")
+            if callable(embedded_execute):
+                return embedded_execute(statements)
+
+        raise RuntimeError("iris.execute requires an embedded runtime")
+
+    def gref(self, global_name):
+        current_runtime = self.runtime_manager.get()
+        if current_runtime.mode == "native":
+            if current_runtime.iris is None:
+                raise RuntimeError("iris.runtime is configured for native mode, but no native IRIS handle is bound")
+            raise RuntimeError("iris.gref requires an embedded runtime")
+
+        if current_runtime.mode == "embedded":
+            embedded_gref = self._get_embedded_module_attr(
+                current_runtime,
+                "gref",
+                required=True,
+            )
+            if callable(embedded_gref):
+                return embedded_gref(global_name)
+            raise RuntimeError("iris.runtime is configured for embedded mode, but embedded gref is unavailable")
+
+        if current_runtime.embedded_available:
+            embedded_gref = self._get_embedded_module_attr(current_runtime, "gref")
+            if callable(embedded_gref):
+                return embedded_gref(global_name)
+
+        raise RuntimeError("iris.gref requires an embedded runtime")
+
+    def ref(self, value=""):
+        current_runtime = self.runtime_manager.get()
+        if current_runtime.mode == "embedded" or (
+            current_runtime.mode == "auto" and current_runtime.embedded_available
+        ):
+            embedded_ref = self._get_embedded_module_attr(
+                current_runtime,
+                "ref",
+                required=current_runtime.mode == "embedded",
+            )
+            if callable(embedded_ref):
+                return embedded_ref(value)
+            if current_runtime.mode == "embedded":
+                raise RuntimeError("iris.runtime is configured for embedded mode, but embedded ref is unavailable")
+        return ByRef(value)
+
     def cls(self, class_name):
         current_runtime = self.runtime_manager.get()
         if current_runtime.mode == 'native':

_iris_ep/_vector.py

@@ -95,7 +95,7 @@ def _coerce_iris_vector_operand(value: Any, dtype: str) -> "IRISVector":
 
 
 class IRISVector:
-    """Python value wrapper for IRIS SQL VECTOR parameters and operations."""
+    """Python value wrapper for IRIS SQL VECTOR parameters and embedded operations."""
 
     __slots__ = ("_objectscript_dtype", "_values", "dtype")
 

examples/fastembed_vector_operations.py

@@ -0,0 +1,108 @@
+"""FastEmbed + iris.Vector operations without SQL.
+
+Prerequisites:
+    pip install fastembed
+
+Run from an embedded IRIS-capable environment:
+    python examples/fastembed_vector_operations.py
+
+This example does not create a table or execute SQL. FastEmbed embeddings are
+wrapped as iris.Vector objects and ranked with ObjectScript $VECTOROP through
+the Python Vector methods. Vector operations require embedded iris.gref and
+iris.execute; they are not routed through the remote/native bridge.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+import iris
+from fastembed import TextEmbedding
+
+
+DOCUMENTS = [
+    "IRIS stores vectors in SQL VECTOR columns.",
+    "FastEmbed generates local text embeddings.",
+    "ByRef lets Python receive ObjectScript output arguments.",
+    "VECTOR_COSINE ranks documents by embedding similarity.",
+    "DB-API parameters should be cast with TO_VECTOR.",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--model",
+        default="BAAI/bge-small-en-v1.5",
+        help="FastEmbed model name.",
+    )
+    parser.add_argument(
+        "--query",
+        default="How do I store embeddings in IRIS?",
+        help="Search query to embed and rank against the example documents.",
+    )
+    parser.add_argument("--top-k", type=int, default=3)
+    return parser.parse_args()
+
+
+def embed_texts(model: TextEmbedding, texts: Iterable[str]) -> list[iris.Vector]:
+    return [iris.Vector(embedding, dtype="float") for embedding in model.embed(texts)]
+
+
+def rank_documents(
+    query_vector: iris.Vector,
+    documents: Sequence[str],
+    document_vectors: Sequence[iris.Vector],
+    top_k: int,
+):
+    scores = [
+        (query_vector.cosine(document_vector), index, content)
+        for index, (content, document_vector) in enumerate(
+            zip(documents, document_vectors),
+            start=1,
+        )
+    ]
+    return sorted(scores, reverse=True)[: max(1, int(top_k))]
+
+
+def centroid(vectors: Sequence[iris.Vector]) -> iris.Vector:
+    if not vectors:
+        raise ValueError("centroid requires at least one vector")
+
+    total = vectors[0]
+    for vector in vectors[1:]:
+        total = total + vector
+    return total / len(vectors)
+
+
+def main() -> None:
+    args = parse_args()
+    model = TextEmbedding(model_name=args.model)
+
+    document_vectors = embed_texts(model, DOCUMENTS)
+    query_vector = embed_texts(model, [args.query])[0]
+    average_document_vector = centroid(document_vectors)
+
+    print(f"dimension: {len(query_vector)}")
+    print(f"query sum: {query_vector.sum():.4f}")
+    print(f"centroid cosine: {query_vector.cosine(average_document_vector):.4f}")
+    print()
+
+    for score, row_id, content in rank_documents(
+        query_vector,
+        DOCUMENTS,
+        document_vectors,
+        args.top_k,
+    ):
+        print(f"{score:.4f} #{row_id}: {content}")
+
+
+if __name__ == "__main__":
+    main()