select-ai 1.0.0.dev4__py3-none-any.whl

select_ai/conversation.py

@@ -0,0 +1,249 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+from dataclasses import dataclass
+from typing import AsyncGenerator, Iterator, Optional
+
+import oracledb
+
+from select_ai._abc import SelectAIDataClass
+from select_ai.db import async_cursor, cursor
+from select_ai.errors import ConversationNotFoundError
+from select_ai.sql import (
+    GET_USER_CONVERSATION_ATTRIBUTES,
+    LIST_USER_CONVERSATIONS,
+)
+
+__all__ = ["AsyncConversation", "Conversation", "ConversationAttributes"]
+
+
+@dataclass
+class ConversationAttributes(SelectAIDataClass):
+    """Conversation Attributes
+
+    :param str title: Conversation Title
+    :param str description: Description of the conversation topic
+    :param int retention_days: The number of days the conversation will be
+     stored in the database from its creation date. If value is 0, we will
+     not remove the conversation unless it is manually deleted by
+     drop_conversation
+
+    """
+
+    title: Optional[str] = "New Conversation"
+    description: Optional[str] = None
+    retention_days: Optional[int] = 7
+    # conversation_length: Optional[int] = 10
+
+
+class _BaseConversation:
+
+    def __init__(
+        self,
+        conversation_id: Optional[str] = None,
+        attributes: Optional[ConversationAttributes] = None,
+    ):
+        self.conversation_id = conversation_id
+        self.attributes = attributes
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}(conversation_id={self.conversation_id}, "
+            f"attributes={self.attributes})"
+        )
+
+
+class Conversation(_BaseConversation):
+    """Conversation class can be used to create, update and delete
+    conversations in the database
+
+    Typical usage is to combine this conversation object with an AI
+    Profile.chat_session() to have context-aware conversations with
+    the LLM provider
+
+    :param str conversation_id: Conversation ID
+    :param ConversationAttributes attributes: Conversation attributes
+
+    """
+
+    def create(self) -> str:
+        """Creates a new conversation and returns the conversation_id
+        to be used in context-aware conversations with LLMs
+
+        :return: conversation_id
+        """
+        with cursor() as cr:
+            self.conversation_id = cr.callfunc(
+                "DBMS_CLOUD_AI.CREATE_CONVERSATION",
+                oracledb.DB_TYPE_VARCHAR,
+                keyword_parameters={"attributes": self.attributes.json()},
+            )
+        return self.conversation_id
+
+    def delete(self, force: bool = False):
+        """Drops the conversation"""
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.DROP_CONVERSATION",
+                keyword_parameters={
+                    "conversation_id": self.conversation_id,
+                    "force": force,
+                },
+            )
+
+    def set_attributes(self, attributes: ConversationAttributes):
+        """Updates the attributes of the conversation in the database"""
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.UPDATE_CONVERSATION",
+                keyword_parameters={
+                    "conversation_id": self.conversation_id,
+                    "attributes": attributes.json(),
+                },
+            )
+
+    def get_attributes(self) -> ConversationAttributes:
+        """Get attributes of the conversation from the database"""
+        with cursor() as cr:
+            cr.execute(
+                GET_USER_CONVERSATION_ATTRIBUTES,
+                conversation_id=self.conversation_id,
+            )
+            attributes = cr.fetchone()
+            if attributes:
+                conversation_title = attributes[0]
+                description = attributes[1].read()  # Oracle.LOB
+                retention_days = attributes[2]
+                return ConversationAttributes(
+                    title=conversation_title,
+                    description=description,
+                    retention_days=retention_days,
+                )
+            else:
+                raise ConversationNotFoundError(
+                    conversation_id=self.conversation_id
+                )
+
+    @classmethod
+    def list(cls) -> Iterator["Conversation"]:
+        """List all conversations
+
+        :return: Iterator[VectorIndex]
+        """
+        with cursor() as cr:
+            cr.execute(
+                LIST_USER_CONVERSATIONS,
+            )
+            for row in cr.fetchall():
+                conversation_id = row[0]
+                conversation_title = row[1]
+                description = row[2].read()  # Oracle.LOB
+                retention_days = row[3]
+                attributes = ConversationAttributes(
+                    title=conversation_title,
+                    description=description,
+                    retention_days=retention_days,
+                )
+                yield cls(
+                    attributes=attributes, conversation_id=conversation_id
+                )
+
+
+class AsyncConversation(_BaseConversation):
+    """AsyncConversation class can be used to create, update and delete
+    conversations in the database in an async manner
+
+    Typical usage is to combine this conversation object with an
+    AsyncProfile.chat_session() to have context-aware conversations
+
+    :param str conversation_id: Conversation ID
+    :param ConversationAttributes attributes: Conversation attributes
+
+    """
+
+    async def create(self) -> str:
+        """Creates a new conversation and returns the conversation_id
+        to be used in context-aware conversations with LLMs
+
+        :return: conversation_id
+        """
+        async with async_cursor() as cr:
+            self.conversation_id = await cr.callfunc(
+                "DBMS_CLOUD_AI.CREATE_CONVERSATION",
+                oracledb.DB_TYPE_VARCHAR,
+                keyword_parameters={"attributes": self.attributes.json()},
+            )
+        return self.conversation_id
+
+    async def delete(self, force: bool = False):
+        """Delete the conversation"""
+        async with async_cursor() as cr:
+            await cr.callproc(
+                "DBMS_CLOUD_AI.DROP_CONVERSATION",
+                keyword_parameters={
+                    "conversation_id": self.conversation_id,
+                    "force": force,
+                },
+            )
+
+    async def set_attributes(self, attributes: ConversationAttributes):
+        """Updates the attributes of the conversation"""
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.UPDATE_CONVERSATION",
+                keyword_parameters={
+                    "conversation_id": self.conversation_id,
+                    "attributes": attributes.json(),
+                },
+            )
+
+    async def get_attributes(self) -> ConversationAttributes:
+        """Get attributes of the conversation from the database"""
+        async with async_cursor() as cr:
+            await cr.execute(
+                GET_USER_CONVERSATION_ATTRIBUTES,
+                conversation_id=self.conversation_id,
+            )
+            attributes = await cr.fetchone()
+            if attributes:
+                conversation_title = attributes[0]
+                description = await attributes[1].read()  # Oracle.AsyncLOB
+                retention_days = attributes[2]
+                return ConversationAttributes(
+                    title=conversation_title,
+                    description=description,
+                    retention_days=retention_days,
+                )
+            else:
+                raise ConversationNotFoundError(
+                    conversation_id=self.conversation_id
+                )
+
+    @classmethod
+    async def list(cls) -> AsyncGenerator["AsyncConversation", None]:
+        """List all conversations
+
+        :return: Iterator[VectorIndex]
+        """
+        async with async_cursor() as cr:
+            await cr.execute(
+                LIST_USER_CONVERSATIONS,
+            )
+            rows = await cr.fetchall()
+            for row in rows:
+                conversation_id = row[0]
+                conversation_title = row[1]
+                description = await row[2].read()  # Oracle.AsyncLOB
+                retention_days = row[3]
+                attributes = ConversationAttributes(
+                    title=conversation_title,
+                    description=description,
+                    retention_days=retention_days,
+                )
+                yield cls(
+                    attributes=attributes, conversation_id=conversation_id
+                )

select_ai/db.py

@@ -0,0 +1,171 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+import contextlib
+import os
+from threading import get_ident
+from typing import Dict, Hashable
+
+import oracledb
+
+__conn__: Dict[Hashable, oracledb.Connection] = {}
+__async_conn__: Dict[Hashable, oracledb.AsyncConnection] = {}
+
+__all__ = [
+    "connect",
+    "async_connect",
+    "is_connected",
+    "async_is_connected",
+    "get_connection",
+    "async_get_connection",
+    "cursor",
+    "async_cursor",
+]
+
+
+def connect(user: str, password: str, dsn: str, *args, **kwargs):
+    """Creates an oracledb.Connection object
+    and saves it global dictionary __conn__
+    The connection object is thread local meaning
+    in a multithreaded application, individual
+    threads cannot see each other's connection
+    object
+    """
+    conn = oracledb.connect(
+        user=user,
+        password=password,
+        dsn=dsn,
+        connection_id_prefix="python-select-ai",
+        *args,
+        **kwargs,
+    )
+    _set_connection(conn=conn)
+
+
+async def async_connect(user: str, password: str, dsn: str, *args, **kwargs):
+    """Creates an oracledb.AsyncConnection object
+    and saves it global dictionary __async_conn__
+    The connection object is thread local meaning
+    in a multithreaded application, individual
+    threads cannot see each other's connection
+    object
+    """
+    async_conn = await oracledb.connect_async(
+        user=user, password=password, dsn=dsn, *args, **kwargs
+    )
+    _set_connection(async_conn=async_conn)
+
+
+def is_connected() -> bool:
+    """Checks if database connection is open and healthy"""
+    global __conn__
+    key = (os.getpid(), get_ident())
+    conn = __conn__.get(key)
+    if conn is None:
+        return False
+    try:
+        return conn.ping() is None
+    except oracledb.DatabaseError:
+        return False
+
+
+async def async_is_connected() -> bool:
+    """Asynchronously checks if database connection is open and healthy"""
+
+    global __async_conn__
+    key = (os.getpid(), get_ident())
+    conn = __async_conn__.get(key)
+    if conn is None:
+        return False
+    try:
+        return await conn.ping() is None
+    except oracledb.DatabaseError:
+        return False
+
+
+def _set_connection(
+    conn: oracledb.Connection = None,
+    async_conn: oracledb.AsyncConnection = None,
+):
+    """Set existing connection for select_ai Python API to reuse
+
+    :param conn: python-oracledb Connection object
+    :param async_conn: python-oracledb
+    :return:
+    """
+    key = (os.getpid(), get_ident())
+    if conn:
+        global __conn__
+        __conn__[key] = conn
+    if async_conn:
+        global __async_conn__
+        __async_conn__[key] = async_conn
+
+
+def get_connection() -> oracledb.Connection:
+    """Returns the connection object if connection is healthy"""
+    if not is_connected():
+        raise Exception(
+            "Not connected to the Database. "
+            "Use select_ai.db.connect() to establish connection"
+        )
+    global __conn__
+    key = (os.getpid(), get_ident())
+    return __conn__[key]
+
+
+async def async_get_connection() -> oracledb.AsyncConnection:
+    """Returns the AsyncConnection object if connection is healthy"""
+    if not await async_is_connected():
+        raise Exception(
+            "Not connected to the Database. "
+            "Use select_ai.db.async_connect() to establish "
+            "connection"
+        )
+    global __async_conn__
+    key = (os.getpid(), get_ident())
+    return __async_conn__[key]
+
+
+@contextlib.contextmanager
+def cursor():
+    """
+    Creates a context manager for database cursor
+
+    Typical usage:
+
+        with select_ai.cursor() as cr:
+            cr.execute(<QUERY>)
+
+    This ensures that the cursor is closed regardless
+    of whether an exception occurred
+
+    """
+    cr = get_connection().cursor()
+    try:
+        yield cr
+    finally:
+        cr.close()
+
+
+@contextlib.asynccontextmanager
+async def async_cursor():
+    """
+    Creates an async context manager for database cursor
+
+    Typical usage:
+
+        async with select_ai.cursor() as cr:
+            await cr.execute(<QUERY>)
+    :return:
+    """
+    conn = await async_get_connection()
+    cr = conn.cursor()
+    try:
+        yield cr
+    finally:
+        cr.close()

select_ai/errors.py

@@ -0,0 +1,49 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+
+class SelectAIError(Exception):
+    """Base class for any SelectAIErrors"""
+
+    pass
+
+
+class ConversationNotFoundError(SelectAIError):
+    """Conversation not found in the database"""
+
+    def __init__(self, conversation_id: str):
+        self.conversation_id = conversation_id
+
+    def __str__(self):
+        return f"Conversation with id {self.conversation_id} not found"
+
+
+class ProfileNotFoundError(SelectAIError):
+    """Profile not found in the database"""
+
+    def __init__(self, profile_name: str):
+        self.profile_name = profile_name
+
+    def __str__(self):
+        return f"Profile {self.profile_name} not found"
+
+
+class VectorIndexNotFoundError(SelectAIError):
+    """VectorIndex not found in the database"""
+
+    def __init__(self, index_name: str, profile_name: str = None):
+        self.index_name = index_name
+        self.profile_name = profile_name
+
+    def __str__(self):
+        if self.profile_name:
+            return (
+                f"VectorIndex {self.index_name} "
+                f"not found for profile {self.profile_name}"
+            )
+        else:
+            return f"VectorIndex {self.index_name} not found"