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

select_ai/profile.py

@@ -0,0 +1,397 @@
+# -----------------------------------------------------------------------------
+# 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 json
+from contextlib import contextmanager
+from dataclasses import replace as dataclass_replace
+from typing import Iterator, Mapping, Optional, Union
+
+import oracledb
+import pandas
+
+from select_ai import Conversation
+from select_ai.action import Action
+from select_ai.base_profile import BaseProfile, ProfileAttributes
+from select_ai.db import cursor
+from select_ai.errors import ProfileNotFoundError
+from select_ai.provider import Provider
+from select_ai.sql import (
+    GET_USER_AI_PROFILE_ATTRIBUTES,
+    LIST_USER_AI_PROFILES,
+)
+from select_ai.synthetic_data import SyntheticDataAttributes
+
+
+class Profile(BaseProfile):
+    """Profile class represents an AI Profile. It defines
+    attributes and methods to interact with the underlying
+    AI Provider. All methods in this class are synchronous
+    or blocking
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._init_profile()
+
+    def _init_profile(self) -> None:
+        """Initializes AI profile based on the passed attributes
+
+        :return: None
+        :raises: oracledb.DatabaseError
+        """
+        if self.profile_name is not None:
+            profile_exists = False
+            try:
+                saved_attributes = self._get_attributes(
+                    profile_name=self.profile_name
+                )
+                profile_exists = True
+            except ProfileNotFoundError:
+                if self.attributes is None:
+                    raise
+            else:
+                if self.attributes is None:
+                    self.attributes = saved_attributes
+                if self.merge:
+                    self.replace = True
+                    if self.attributes is not None:
+                        self.attributes = dataclass_replace(
+                            saved_attributes,
+                            **self.attributes.dict(exclude_null=True),
+                        )
+            if self.replace or not profile_exists:
+                self.create(replace=self.replace)
+
+    @staticmethod
+    def _get_attributes(profile_name) -> ProfileAttributes:
+        """Get AI profile attributes from the Database
+
+        :param str profile_name: Name of the profile
+        :return: select_ai.ProfileAttributes
+        :raises: ProfileNotFoundError
+        """
+        with cursor() as cr:
+            cr.execute(
+                GET_USER_AI_PROFILE_ATTRIBUTES,
+                profile_name=profile_name.upper(),
+            )
+            attributes = cr.fetchall()
+            if attributes:
+                return ProfileAttributes.create(**dict(attributes))
+            else:
+                raise ProfileNotFoundError(profile_name=profile_name)
+
+    def get_attributes(self) -> ProfileAttributes:
+        """Get AI profile attributes from the Database
+
+        :return: select_ai.ProfileAttributes
+        """
+        return self._get_attributes(profile_name=self.profile_name)
+
+    def _set_attribute(
+        self,
+        attribute_name: str,
+        attribute_value: Union[bool, str, int, float],
+    ):
+        parameters = {
+            "profile_name": self.profile_name,
+            "attribute_name": attribute_name,
+            "attribute_value": attribute_value,
+        }
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.SET_ATTRIBUTE", keyword_parameters=parameters
+            )
+
+    def set_attribute(
+        self,
+        attribute_name: str,
+        attribute_value: Union[bool, str, int, float, Provider],
+    ):
+        """Updates AI profile attribute on the Python object and also
+        saves it in the database
+
+        :param str attribute_name: Name of the AI profile attribute
+        :param Union[bool, str, int, float, Provider] attribute_value: Value of
+         the profile attribute
+        :return: None
+
+        """
+        self.attributes.set_attribute(attribute_name, attribute_value)
+        if isinstance(attribute_value, Provider):
+            for k, v in attribute_value.dict().items():
+                self._set_attribute(k, v)
+        else:
+            self._set_attribute(attribute_name, attribute_value)
+
+    def set_attributes(self, attributes: ProfileAttributes):
+        """Updates AI profile attributes on the Python object and also
+        saves it in the database
+
+        :param ProviderAttributes attributes: Object specifying AI profile
+         attributes
+        :return: None
+        """
+        self.attributes = attributes
+        parameters = {
+            "profile_name": self.profile_name,
+            "attributes": self.attributes.json(),
+        }
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.SET_ATTRIBUTES", keyword_parameters=parameters
+            )
+
+    def create(self, replace: Optional[int] = False) -> None:
+        """Create an AI Profile in the Database
+
+        :param bool replace: Set True to replace else False
+        :return: None
+        :raises: oracledb.DatabaseError
+        """
+
+        parameters = {
+            "profile_name": self.profile_name,
+            "attributes": self.attributes.json(),
+        }
+        if self.description:
+            parameters["description"] = self.description
+
+        with cursor() as cr:
+            try:
+                cr.callproc(
+                    "DBMS_CLOUD_AI.CREATE_PROFILE",
+                    keyword_parameters=parameters,
+                )
+            except oracledb.DatabaseError as e:
+                (error,) = e.args
+                # If already exists and replace is True then drop and recreate
+                if "already exists" in error.message.lower() and replace:
+                    self.delete(force=True)
+                    cr.callproc(
+                        "DBMS_CLOUD_AI.CREATE_PROFILE",
+                        keyword_parameters=parameters,
+                    )
+                else:
+                    raise
+
+    def delete(self, force=False) -> None:
+        """Deletes an AI profile from the database
+
+        :param bool force: Ignores errors if AI profile does not exist.
+        :return: None
+        :raises: oracledb.DatabaseError
+        """
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.DROP_PROFILE",
+                keyword_parameters={
+                    "profile_name": self.profile_name,
+                    "force": force,
+                },
+            )
+
+    @classmethod
+    def _from_db(cls, profile_name: str) -> "Profile":
+        """Create a Profile object from attributes saved in the database
+
+        :param str profile_name:
+        :return: select_ai.Profile
+        :raises: ProfileNotFoundError
+        """
+        with cursor() as cr:
+            cr.execute(
+                GET_USER_AI_PROFILE_ATTRIBUTES, profile_name=profile_name
+            )
+            attributes = cr.fetchall()
+            if attributes:
+                attributes = ProfileAttributes.create(**dict(attributes))
+                return cls(profile_name=profile_name, attributes=attributes)
+            else:
+                raise ProfileNotFoundError(profile_name=profile_name)
+
+    @classmethod
+    def list(cls, profile_name_pattern: str) -> Iterator["Profile"]:
+        """List AI Profiles saved in the database.
+
+        :param str profile_name_pattern: Regular expressions can be used
+         to specify a pattern. Function REGEXP_LIKE is used to perform the
+         match
+
+        :return: Iterator[Profile]
+        """
+        with cursor() as cr:
+            cr.execute(
+                LIST_USER_AI_PROFILES,
+                profile_name_pattern=profile_name_pattern,
+            )
+            for row in cr.fetchall():
+                profile_name = row[0]
+                description = row[1]
+                attributes = cls._get_attributes(profile_name=profile_name)
+                yield cls(
+                    profile_name=profile_name,
+                    description=description,
+                    attributes=attributes,
+                )
+
+    def generate(
+        self,
+        prompt: str,
+        action: Optional[Action] = Action.RUNSQL,
+        params: Mapping = None,
+    ) -> Union[pandas.DataFrame, str, None]:
+        """Perform AI translation using this profile
+
+        :param str prompt: Natural language prompt to translate
+        :param select_ai.profile.Action action:
+        :param params: Parameters to include in the LLM request. For e.g.
+         conversation_id for context-aware chats
+        :return: Union[pandas.DataFrame, str]
+        """
+        parameters = {
+            "prompt": prompt,
+            "action": action,
+            "profile_name": self.profile_name,
+            # "attributes": self.attributes.json(),
+        }
+        if params:
+            parameters["params"] = json.dumps(params)
+        with cursor() as cr:
+            data = cr.callfunc(
+                "DBMS_CLOUD_AI.GENERATE",
+                oracledb.DB_TYPE_CLOB,
+                keyword_parameters=parameters,
+            )
+        if data is not None:
+            return data.read()
+        return None
+
+    def chat(self, prompt: str, params: Mapping = None) -> str:
+        """Chat with the LLM
+
+        :param str prompt: Natural language prompt
+        :param params: Parameters to include in the LLM request
+        :return: str
+        """
+        return self.generate(prompt, action=Action.CHAT, params=params)
+
+    @contextmanager
+    def chat_session(self, conversation: Conversation, delete: bool = False):
+        """Starts a new chat session for context-aware conversations
+
+        :param Conversation conversation: Conversation object to use for this
+         chat session
+        :param bool delete: Delete conversation after session ends
+
+        :return:
+        """
+        try:
+            if (
+                conversation.conversation_id is None
+                and conversation.attributes is not None
+            ):
+                conversation.create()
+            params = {"conversation_id": conversation.conversation_id}
+            session = Session(profile=self, params=params)
+            yield session
+        finally:
+            if delete:
+                conversation.delete()
+
+    def narrate(self, prompt: str, params: Mapping = None) -> str:
+        """Narrate the result of the SQL
+
+        :param str prompt: Natural language prompt
+        :param params: Parameters to include in the LLM request
+        :return: str
+        """
+        return self.generate(prompt, action=Action.NARRATE, params=params)
+
+    def explain_sql(self, prompt: str, params: Mapping = None) -> str:
+        """Explain the generated SQL
+
+        :param str prompt: Natural language prompt
+        :param params: Parameters to include in the LLM request
+        :return: str
+        """
+        return self.generate(prompt, action=Action.EXPLAINSQL, params=params)
+
+    def run_sql(self, prompt: str, params: Mapping = None) -> pandas.DataFrame:
+        """Run the generate SQL statement and return a pandas Dataframe built
+        using the result set
+
+        :param str prompt: Natural language prompt
+        :param params: Parameters to include in the LLM request
+        :return: pandas.DataFrame
+        """
+        data = json.loads(
+            self.generate(prompt, action=Action.RUNSQL, params=params)
+        )
+        return pandas.DataFrame(data)
+
+    def show_sql(self, prompt: str, params: Mapping = None) -> str:
+        """Show the generated SQL
+
+        :param str prompt: Natural language prompt
+        :param params: Parameters to include in the LLM request
+        :return: str
+        """
+        return self.generate(prompt, action=Action.SHOWSQL, params=params)
+
+    def show_prompt(self, prompt: str, params: Mapping = None) -> str:
+        """Show the prompt sent to LLM
+
+        :param str prompt: Natural language prompt
+        :param params: Parameters to include in the LLM request
+        :return: str
+        """
+        return self.generate(prompt, action=Action.SHOWPROMPT, params=params)
+
+    def generate_synthetic_data(
+        self, synthetic_data_attributes: SyntheticDataAttributes
+    ):
+        """Generate synthetic data for a single table, multiple tables or a
+        full schema.
+
+        :param select_ai.SyntheticDataAttributes synthetic_data_attributes:
+        :return: None
+        :raises: oracledb.DatabaseError
+
+        """
+        keyword_parameters = synthetic_data_attributes.prepare()
+        keyword_parameters["profile_name"] = self.profile_name
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI.GENERATE_SYNTHETIC_DATA",
+                keyword_parameters=keyword_parameters,
+            )
+
+
+class Session:
+    """Session lets you persist request parameters across DBMS_CLOUD_AI
+    requests. This is useful in context-aware conversations
+    """
+
+    def __init__(self, profile: Profile, params: Mapping):
+        """
+
+        :param profile: An AI Profile to use in this session
+        :param params: Parameters to be persisted across requests
+        """
+        self.params = params
+        self.profile = profile
+
+    def chat(self, prompt: str):
+        # params = {"conversation_id": self.conversation_id}
+        return self.profile.chat(prompt=prompt, params=self.params)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass

select_ai/provider.py

@@ -0,0 +1,187 @@
+# -----------------------------------------------------------------------------
+# 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, fields
+from typing import Optional
+
+from select_ai._abc import SelectAIDataClass
+
+OPENAI = "openai"
+COHERE = "cohere"
+AZURE = "azure"
+OCI = "oci"
+GOOGLE = "google"
+ANTHROPIC = "anthropic"
+HUGGINGFACE = "huggingface"
+AWS = "aws"
+
+
+@dataclass
+class Provider(SelectAIDataClass):
+    """
+    Base class for AI Provider
+
+    To create an object of Provider class, use any one of the concrete AI
+    provider implementations
+
+    :param str embedding_model: The embedding model, also known as a
+     transformer. Depending on the AI provider, the supported embedding models
+     vary
+    :param str model: The name of the LLM being used to generate
+     responses
+    :param str provider_name: The name of the provider being used
+    :param str provider_endpoint: Endpoint URL of the AI provider being used
+    :param str region: The cloud region of the Gen AI cluster
+
+    """
+
+    embedding_model: Optional[str] = None
+    model: Optional[str] = None
+    provider_name: Optional[str] = None
+    provider_endpoint: Optional[str] = None
+    region: Optional[str] = None
+
+    @classmethod
+    def create(cls, *, provider_name: Optional[str] = None, **kwargs):
+        for subclass in cls.__subclasses__():
+            if subclass.provider_name == provider_name:
+                return subclass(**kwargs)
+        return cls(**kwargs)
+
+    @classmethod
+    def key_alias(cls, k):
+        return {"provider": "provider_name", "provider_name": "provider"}.get(
+            k, k
+        )
+
+    @classmethod
+    def keys(cls):
+        return {
+            "provider",
+            "provider_name",
+            "embedding_model",
+            "model",
+            "region",
+            "provider_endpoint",
+            "azure_deployment_name",
+            "azure_embedding_deployment_name",
+            "azure_resource_name",
+            "oci_apiformat",
+            "oci_compartment_id",
+            "oci_endpoint_id",
+            "oci_runtimetype",
+            "aws_apiformat",
+        }
+
+
+@dataclass
+class AzureProvider(Provider):
+    """
+    Azure specific attributes
+
+    :param str azure_deployment_name: Name of the Azure OpenAI Service
+     deployed model.
+    :param str azure_embedding_deployment_name: Name of the Azure OpenAI
+     deployed embedding model.
+    :param str azure_resource_name: Name of the Azure OpenAI Service resource
+    """
+
+    provider_name: str = AZURE
+    azure_deployment_name: Optional[str] = None
+    azure_embedding_deployment_name: Optional[str] = None
+    azure_resource_name: Optional[str] = None
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.provider_endpoint = f"{self.azure_resource_name}.openai.azure.com"
+
+
+@dataclass
+class OpenAIProvider(Provider):
+    """
+    OpenAI specific attributes
+    """
+
+    provider_name: str = OPENAI
+    provider_endpoint: Optional[str] = "api.openai.com"
+
+
+@dataclass
+class OCIGenAIProvider(Provider):
+    """
+    OCI Gen AI specific attributes
+
+    :param str oci_apiformat: Specifies the format in which the API expects
+     data to be sent and received. Supported values are 'COHERE' and 'GENERIC'
+    :param str oci_compartment_id: Specifies the OCID of the compartment you
+     are permitted to access when calling the OCI Generative AI service
+    :param str oci_endpoint_id: This attributes indicates the endpoint OCID
+     of the Oracle dedicated AI hosting cluster
+    :param str oci_runtimetype: This attribute indicates the runtime type of
+     the provided model. The supported values are 'COHERE' and 'LLAMA'
+    """
+
+    provider_name: str = OCI
+    oci_apiformat: Optional[str] = None
+    oci_compartment_id: Optional[str] = None
+    oci_endpoint_id: Optional[str] = None
+    oci_runtimetype: Optional[str] = None
+
+
+@dataclass
+class CohereProvider(Provider):
+    """
+    Cohere AI specific attributes
+    """
+
+    provider_name: str = COHERE
+    provider_endpoint = "api.cohere.ai"
+
+
+@dataclass
+class GoogleProvider(Provider):
+    """
+    Google AI specific attributes
+    """
+
+    provider_name: str = GOOGLE
+    provider_endpoint = "generativelanguage.googleapis.com"
+
+
+@dataclass
+class HuggingFaceProvider(Provider):
+    """
+    HuggingFace specific attributes
+    """
+
+    provider_name: str = HUGGINGFACE
+    provider_endpoint = "api-inference.huggingface.co"
+
+
+@dataclass
+class AWSProvider(Provider):
+    """
+    AWS specific attributes
+    """
+
+    provider_name: str = AWS
+    aws_apiformat: Optional[str] = None
+
+    def __post_init__(self):
+        super().__post_init__()
+        self.provider_endpoint = f"bedrock-runtime.{self.region}.amazonaws.com"
+
+
+
+@dataclass
+class AnthropicProvider(Provider):
+    """
+    Anthropic specific attributes
+    """
+
+    provider_name: str = ANTHROPIC
+    provider_endpoint = "api.anthropic.com"

select_ai/sql.py

@@ -0,0 +1,105 @@
+# -----------------------------------------------------------------------------
+# 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.
+# -----------------------------------------------------------------------------
+
+GRANT_PRIVILEGES_TO_USER = """
+DECLARE
+    TYPE array_t IS VARRAY(3) OF VARCHAR2(60);
+    v_packages array_t;
+BEGIN
+    v_packages := array_t(
+        'DBMS_CLOUD', 'DBMS_CLOUD_AI', 'DBMS_CLOUD_PIPELINE'
+    );
+    FOR i in 1..v_packages.count LOOP
+        EXECUTE IMMEDIATE
+            'GRANT EXECUTE ON ' || v_packages(i) || ' TO {0}';
+    END LOOP;
+END;
+"""
+
+REVOKE_PRIVILEGES_FROM_USER = """
+DECLARE
+    TYPE array_t IS VARRAY(3) OF VARCHAR2(60);
+    v_packages array_t;
+BEGIN
+    v_packages := array_t(
+        'DBMS_CLOUD', 'DBMS_CLOUD_AI', 'DBMS_CLOUD_PIPELINE'
+    );
+    FOR i in 1..v_packages.count LOOP
+        EXECUTE IMMEDIATE
+            'REVOKE EXECUTE ON ' || v_packages(i) || ' FROM {0}';
+    END LOOP;
+END;
+"""
+
+ENABLE_AI_PROFILE_DOMAIN_FOR_USER = """
+BEGIN
+    DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
+         host => :host,
+         ace  => xs$ace_type(privilege_list => xs$name_list('http'),
+                             principal_name => :user,
+                             principal_type => xs_acl.ptype_db)
+   );
+END;
+"""
+
+DISABLE_AI_PROFILE_DOMAIN_FOR_USER = """
+BEGIN
+    DBMS_NETWORK_ACL_ADMIN.REMOVE_HOST_ACE(
+         host => :host,
+         ace  => xs$ace_type(privilege_list => xs$name_list('http'),
+                             principal_name => :user,
+                             principal_type => xs_acl.ptype_db)
+   );
+END;
+"""
+
+GET_USER_AI_PROFILE_ATTRIBUTES = """
+SELECT attribute_name, attribute_value
+FROM USER_CLOUD_AI_PROFILE_ATTRIBUTES
+WHERE profile_name = :profile_name
+"""
+
+GET_USER_AI_PROFILE = """
+SELECT count(*)
+FROM  USER_CLOUD_AI_PROFILES
+WHERE profile_name = :profile_name
+"""
+
+
+LIST_USER_AI_PROFILES = """
+SELECT profile_name, description
+FROM USER_CLOUD_AI_PROFILES
+WHERE REGEXP_LIKE(profile_name, :profile_name_pattern, 'i')
+"""
+
+LIST_USER_VECTOR_INDEXES = """
+SELECT v.index_name, v.description
+FROM USER_CLOUD_VECTOR_INDEXES v
+WHERE REGEXP_LIKE(v.index_name, :index_name_pattern, 'i')
+"""
+
+GET_USER_VECTOR_INDEX_ATTRIBUTES = """
+SELECT attribute_name, attribute_value
+FROM USER_CLOUD_VECTOR_INDEX_ATTRIBUTES
+WHERE INDEX_NAME = :index_name
+"""
+
+LIST_USER_CONVERSATIONS = """
+SELECT conversation_id,
+       conversation_title,
+       description,
+       retention_days
+from USER_CLOUD_AI_CONVERSATIONS
+"""
+
+GET_USER_CONVERSATION_ATTRIBUTES = """
+SELECT conversation_title,
+       description,
+       retention_days
+from USER_CLOUD_AI_CONVERSATIONS
+WHERE conversation_id = :conversation_id
+"""