select-ai 1.1.0__py3-none-any.whl → 1.2.0rc1__py3-none-any.whl

select_ai/agent/__init__.py

@@ -0,0 +1,24 @@
+# -----------------------------------------------------------------------------
+# 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 .core import Agent, AgentAttributes
+from .task import Task, TaskAttributes
+from .team import Team, TeamAttributes
+from .tool import (
+    EmailNotificationToolParams,
+    HTTPToolParams,
+    HumanToolParams,
+    RAGToolParams,
+    SlackNotificationToolParams,
+    SQLToolParams,
+    Tool,
+    ToolAttributes,
+    ToolParams,
+    ToolType,
+    WebSearchToolParams,
+)

select_ai/agent/core.py

@@ -0,0 +1,235 @@
+# ------------------------------------------------------------------------------
+# 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 abc import ABC
+from dataclasses import dataclass
+from typing import (
+    Any,
+    AsyncGenerator,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Union,
+)
+
+import oracledb
+
+from select_ai import BaseProfile
+from select_ai._abc import SelectAIDataClass
+from select_ai._enums import StrEnum
+from select_ai.agent.sql import (
+    GET_USER_AI_AGENT,
+    GET_USER_AI_AGENT_ATTRIBUTES,
+    LIST_USER_AI_AGENTS,
+)
+from select_ai.async_profile import AsyncProfile
+from select_ai.db import async_cursor, cursor
+from select_ai.errors import AgentNotFoundError
+from select_ai.profile import Profile
+
+
+@dataclass
+class AgentAttributes(SelectAIDataClass):
+    """AI Agent Attributes
+
+    :param str profile_name: Name of the AI Profile which agent will
+     use to send request to LLM
+    :param str role: Agent's role also sent to LLM
+    :param bool enable_human_tool: Enable human tool support. Agent
+     will ask question to the user for any clarification
+    """
+
+    profile_name: str
+    role: str
+    enable_human_tool: Optional[bool] = True
+
+
+class BaseAgent(ABC):
+
+    def __init__(
+        self,
+        agent_name: Optional[str] = None,
+        description: Optional[str] = None,
+        attributes: Optional[AgentAttributes] = None,
+    ):
+        if attributes is not None and not isinstance(
+            attributes, AgentAttributes
+        ):
+            raise TypeError(
+                "attributes must be an object of type "
+                "select_ai.agent.AgentAttributes"
+            )
+        self.agent_name = agent_name
+        self.description = description
+        self.attributes = attributes
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}("
+            f"agent_name={self.agent_name}, "
+            f"attributes={self.attributes}, description={self.description})"
+        )
+
+
+class Agent(BaseAgent):
+    """
+    select_ai.agent.Agent class lets you create, delete, enable, disable
+    and list AI agents
+
+    :param str agent_name: The name of the AI Agent
+    :param str description: Optional description of the AI agent
+    :param select_ai.agent.AgentAttributes attributes: AI agent attributes
+
+    """
+
+    @staticmethod
+    def _get_attributes(agent_name: str) -> AgentAttributes:
+        with cursor() as cr:
+            cr.execute(GET_USER_AI_AGENT, agent_name=agent_name.upper())
+            attributes = cr.fetchall()
+            if attributes:
+                post_processed_attributes = {}
+                for k, v in attributes:
+                    if isinstance(v, oracledb.LOB):
+                        post_processed_attributes[k] = v.read()
+                    else:
+                        post_processed_attributes[k] = v
+                return AgentAttributes(**post_processed_attributes)
+            else:
+                raise AgentNotFoundError(agent_name=agent_name)
+
+    def create(
+        self, enabled: Optional[bool] = True, replace: Optional[bool] = False
+    ):
+        """
+        Register a new AI Agent within the Select AI framework
+
+        :param bool enabled: Whether the AI Agent should be enabled.
+         Default value is True.
+
+        :param bool replace: Whether the AI Agent should be replaced.
+         Default value is False.
+
+        """
+        if self.agent_name is None:
+            raise AttributeError("Agent must have a name")
+        if self.attributes is None:
+            raise AttributeError("Agent must have attributes")
+
+        parameters = {
+            "agent_name": self.agent_name,
+            "attributes": self.attributes.json(),
+        }
+        if self.description:
+            parameters["description"] = self.description
+
+        if not enabled:
+            parameters["status"] = "disabled"
+
+        with cursor() as cr:
+            try:
+                cr.callproc(
+                    "DBMS_CLOUD_AI_AGENT.CREATE_AGENT",
+                    keyword_parameters=parameters,
+                )
+            except oracledb.Error as err:
+                (err_obj,) = err.args
+                if err_obj.code in (20050, 20052) and replace:
+                    self.delete(force=True)
+                    cr.callproc(
+                        "DBMS_CLOUD_AI_AGENT.CREATE_AGENT",
+                        keyword_parameters=parameters,
+                    )
+                else:
+                    raise
+
+    def delete(self, force: Optional[bool] = False):
+        """
+        Delete AI Agent from the database
+
+        :param bool force: Force the deletion. Default value is False.
+
+        """
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI_AGENT.DROP_AGENT",
+                keyword_parameters={
+                    "agent_name": self.agent_name,
+                    "force": force,
+                },
+            )
+
+    def disable(self):
+        """
+        Disable AI Agent
+
+        """
+        pass
+
+    def enable(self):
+        """
+        Enable AI Agent
+        """
+        pass
+
+    @classmethod
+    def fetch(cls, agent_name: str) -> "Agent":
+        """
+        Fetch AI Agent attributes from the Database and build a proxy object in
+        the Python layer
+
+        :param str agent_name: The name of the AI Agent
+
+        :return: select_ai.agent.Agent
+
+        :raises select_ai.errors.AgentNotFoundError:
+         If the AI Agent is not found
+
+        """
+        pass
+
+    @classmethod
+    def list(
+        cls, agent_name_pattern: Optional[str] = ".*"
+    ) -> Iterator["Agent"]:
+        """
+        List AI agents matching a pattern
+
+        :param str agent_name_pattern: Regular expressions can be used
+         to specify a pattern. Function REGEXP_LIKE is used to perform the
+         match. Default value is ".*" i.e. match all agent names.
+
+        :return: Iterator[Agent]
+        """
+        with cursor() as cr:
+            cr.execute(
+                LIST_USER_AI_AGENTS,
+                agent_name_pattern=agent_name_pattern,
+            )
+            for row in cr.fetchall():
+                agent_name = row[0]
+                if row[1]:
+                    description = row[1].read()  # Oracle.LOB
+                else:
+                    description = None
+                attributes = cls._get_attributes(agent_name=agent_name)
+                yield cls(
+                    agent_name=agent_name,
+                    description=description,
+                    attributes=attributes,
+                )
+
+    def set_attributes(self, attributes: AgentAttributes) -> None:
+        """
+        Set AI Agent attributes
+        """
+        pass
+
+    def set_attribute(self, attribute_name: str, attribute_value: Any) -> None:
+        pass

select_ai/agent/sql.py

@@ -0,0 +1,80 @@
+# -----------------------------------------------------------------------------
+# 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.
+# -----------------------------------------------------------------------------
+
+
+GET_USER_AI_AGENT = """
+SELECT a.agent_name, a.description
+from USER_AI_AGENTS a
+where a.agent_name = :agent_name
+"""
+
+GET_USER_AI_AGENT_ATTRIBUTES = """
+SELECT attribute_name, attribute_value
+FROM USER_AI_AGENT_ATTRIBUTES
+WHERE agent_name = :agent_name
+"""
+
+LIST_USER_AI_AGENTS = """
+SELECT a.agent_name, a.description
+from USER_AI_AGENTS a
+where REGEXP_LIKE(a.agent_name, :agent_name_pattern, 'i')
+"""
+
+GET_USER_AI_AGENT_TASK = """
+SELECT t.task_name, t.description
+FROM USER_AI_AGENT_TASKS t
+WHERE t.task_name= :task_name
+"""
+
+GET_USER_AI_AGENT_TASK_ATTRIBUTES = """
+SELECT attribute_name, attribute_value
+FROM USER_AI_AGENT_TASK_ATTRIBUTES
+WHERE task_name= :task_name
+"""
+
+LIST_USER_AI_AGENT_TASKS = """
+SELECT t.task_name, t.description
+FROM USER_AI_AGENT_TASKS t
+WHERE REGEXP_LIKE(t.task_name, :task_name_pattern, 'i')
+"""
+
+GET_USER_AI_TOOL = """
+SELECT t.tool_name, t.description
+FROM USER_AI_AGENT_TOOLS t
+WHERE t.tool_name = :tool_name
+"""
+
+GET_USER_AI_AGENT_TOOL_ATTRIBUTES = """
+SELECT attribute_name, attribute_value
+FROM USER_AI_AGENT_TOOL_ATTRIBUTES
+WHERE tool_name = :tool_name
+"""
+
+LIST_USER_AI_AGENT_TOOLS = """
+SELECT t.tool_name, t.description
+FROM USER_AI_AGENT_TOOLS t
+WHERE REGEXP_LIKE(t.tool_name, :tool_name_pattern, 'i')
+"""
+
+
+GET_USER_AI_AGENT_TEAM = """
+SELECT t.tool_name, t.description
+FROM USER_AI_AGENT_TEAMS t
+WHERE t.team_name = :team_name
+"""
+
+GET_USER_AI_AGENT_TEAM_ATTRIBUTES = """
+SELECT attribute_name, attribute_value
+FROM USER_AI_AGENT_TEAM_ATTRIBUTES
+WHERE team_name = :team_name
+"""
+
+LIST_USER_AI_AGENT_TEAMS = """
+SELECT t.tool_name, t.description
+FROM USER_AI_AGENT_TEAMS t
+WHERE REGEXP_LIKE(t.team_name, :team_name_pattern, 'i')
+"""

select_ai/agent/task.py

@@ -0,0 +1,247 @@
+# -----------------------------------------------------------------------------
+# 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 abc import ABC
+from dataclasses import dataclass
+from typing import (
+    Any,
+    AsyncGenerator,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Union,
+)
+
+import oracledb
+
+from select_ai import BaseProfile
+from select_ai._abc import SelectAIDataClass
+from select_ai._enums import StrEnum
+from select_ai.agent.sql import (
+    GET_USER_AI_AGENT_TASK,
+    GET_USER_AI_AGENT_TASK_ATTRIBUTES,
+    LIST_USER_AI_AGENT_TASKS,
+)
+from select_ai.async_profile import AsyncProfile
+from select_ai.db import async_cursor, cursor
+from select_ai.errors import AgentTaskNotFoundError
+from select_ai.profile import Profile
+
+
+@dataclass
+class TaskAttributes(SelectAIDataClass):
+    """AI Task attributes
+
+    :param str instruction: Statement describing what the task is
+     meant to accomplish
+
+    :param List[str] tools: List of tools the agent can use to
+     execute the task
+
+    :param str input: Task name whose output will be automatically
+     provided by select ai to LLM
+
+    :param bool enable_human_tool: Enable agent to ask question
+     to user when it requires information or clarification
+     during a task. Default value is True.
+
+    """
+
+    instruction: str
+    tools: Optional[List[str]] = None
+    input: Optional[str] = None
+    enable_human_tool: Optional[bool] = True
+
+
+class BaseTask(ABC):
+
+    def __init__(
+        self,
+        task_name: Optional[str] = None,
+        description: Optional[str] = None,
+        attributes: Optional[TaskAttributes] = None,
+    ):
+        if attributes and not isinstance(attributes, TaskAttributes):
+            raise TypeError(
+                "'attributes' must be an object of type "
+                "select_ai.agent.TaskAttributes"
+            )
+        self.task_name = task_name
+        self.description = description
+        self.attributes = attributes
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}("
+            f"task_name={self.task_name}, "
+            f"attributes={self.attributes}, description={self.description})"
+        )
+
+
+class Task(BaseTask):
+    """
+    select_ai.agent.Task class lets you create, delete, enable, disable and
+    list AI Tasks
+
+    :param str task_name: The name of the AI task
+    :param str description: Optional description of the AI task
+    :param select_ai.agent.TaskAttributes attributes: AI task attributes
+
+    """
+
+    @staticmethod
+    def _get_attributes(task_name: str) -> TaskAttributes:
+        with cursor() as cr:
+            cr.execute(
+                GET_USER_AI_AGENT_TASK_ATTRIBUTES, task_name=task_name.upper()
+            )
+            attributes = cr.fetchall()
+            if attributes:
+                post_processed_attributes = {}
+                for k, v in attributes:
+                    if isinstance(v, oracledb.LOB):
+                        post_processed_attributes[k] = v.read()
+                    else:
+                        post_processed_attributes[k] = v
+                return TaskAttributes(**post_processed_attributes)
+            else:
+                raise AgentTaskNotFoundError(task_name=task_name)
+
+    def create(
+        self, enabled: Optional[bool] = True, replace: Optional[bool] = False
+    ):
+        """
+        Create a task that a Select AI agent can include in its
+        reasoning process
+
+        :param bool enabled: Whether the AI Task should be enabled.
+         Default value is True.
+
+        :param bool replace: Whether the AI Task should be replaced.
+         Default value is False.
+
+        """
+        if self.task_name is None:
+            raise AttributeError("Task must have a name")
+        if self.attributes is None:
+            raise AttributeError("Task must have attributes")
+
+        parameters = {
+            "task_name": self.task_name,
+            "attributes": self.attributes.json(),
+        }
+
+        if self.description:
+            parameters["description"] = self.description
+
+        if not enabled:
+            parameters["status"] = "disabled"
+
+        with cursor() as cr:
+            try:
+                cr.callproc(
+                    "DBMS_CLOUD_AI_AGENT.CREATE_TASK",
+                    keyword_parameters=parameters,
+                )
+            except oracledb.Error as err:
+                (err_obj,) = err.args
+                if err_obj.code in (20051, 20052) and replace:
+                    self.delete(force=True)
+                    cr.callproc(
+                        "DBMS_CLOUD_AI_AGENT.CREATE_TASK",
+                        keyword_parameters=parameters,
+                    )
+                else:
+                    raise
+
+    def delete(self, force: bool = False):
+        """
+        Delete AI Task from the database
+
+        :param bool force: Force the deletion. Default value is False.
+        """
+        with cursor() as cr:
+            cr.callproc(
+                "DBMS_CLOUD_AI_AGENT.DROP_TASK",
+                keyword_parameters={
+                    "task_name": self.task_name,
+                    "force": force,
+                },
+            )
+
+    def disable(self):
+        """
+        Disable AI Task
+        """
+        pass
+
+    def enable(self):
+        """
+        Enable AI Task
+        """
+        pass
+
+    @classmethod
+    def list(cls, task_name_pattern: Optional[str] = ".*") -> Iterator["Task"]:
+        """List AI Tasks
+
+        :param str task_name_pattern: Regular expressions can be used
+         to specify a pattern. Function REGEXP_LIKE is used to perform the
+         match. Default value is ".*" i.e. match all tasks.
+
+        :return: Iterator[Task]
+        """
+        with cursor() as cr:
+            cr.execute(
+                LIST_USER_AI_AGENT_TASKS,
+                task_name_pattern=task_name_pattern,
+            )
+            for row in cr.fetchall():
+                task_name = row[0]
+                if row[1]:
+                    description = row[1].read()  # Oracle.LOB
+                else:
+                    description = None
+                attributes = cls._get_attributes(task_name=task_name)
+                yield cls(
+                    task_name=task_name,
+                    description=description,
+                    attributes=attributes,
+                )
+
+    @classmethod
+    def fetch(cls, task_name: str) -> "Task":
+        """
+        Fetch AI Task attributes from the Database and build a proxy object in
+        the Python layer
+
+        :param str task_name: The name of the AI Task
+
+        :return: select_ai.agent.Task
+
+        :raises select_ai.errors.AgentTaskNotFoundError:
+         If the AI Task is not found
+        """
+        pass
+
+    def set_attributes(self, attributes: TaskAttributes):
+        """
+        Set AI Task attributes
+        """
+        pass
+
+    def set_attribute(self, attribute_name: str, attribute_value: Any):
+        """
+        Set a single AI Task attribute specified using name and value
+        """
+        pass
+
+
+class AsyncTask(BaseTask):
+    pass