v1.4.1

samples/README.md

@@ -18,6 +18,11 @@ export TNS_ADMIN=<path/to/dir_containing_tnsnames.ora>
 > grant privileges to regular user. They are used in 2 sample scripts
 > `enable_ai_provider.py` and `disable_ai_provider.py`
 
+Some of the new samples use this optional environment variable:
+
+- `SELECT_AI_PROFILE_NAME` — existing profile for the conversation and
+  supervised-team samples.
+
 
 `SELECT_AI_DB_CONNECT_STRING` can be in any one of the following formats
 

samples/agent/async/get_definition.py

@@ -0,0 +1,42 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# agent/async/get_definition.py
+#
+# Create a temporary task and asynchronously print its PL/SQL definition.
+# -----------------------------------------------------------------------------
+
+import asyncio
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import AsyncTask, TaskAttributes, async_get_definition
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+
+
+async def main():
+    await select_ai.async_connect(user=user, password=password, dsn=dsn)
+    task = AsyncTask(
+        task_name=f"SAMPLE_DEFINITION_TASK_{uuid.uuid4().hex.upper()}",
+        attributes=TaskAttributes(
+            instruction="Answer the user's question: {query}", tools=[]
+        ),
+    )
+    await task.create(replace=True)
+
+    try:
+        print(await async_get_definition("TASK", task.task_name))
+    finally:
+        await task.delete(force=True)
+
+
+asyncio.run(main())

samples/agent/async/team_supervisor_inspect.py

@@ -0,0 +1,91 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# agent/async/team_supervisor_inspect.py
+#
+# Async version of the supervised team creation and inspection sample.
+# Requires SELECT_AI_PROFILE_NAME to name an existing AI profile.
+# -----------------------------------------------------------------------------
+
+import asyncio
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import (
+    AgentAttributes,
+    AsyncAgent,
+    AsyncTask,
+    AsyncTeam,
+    TaskAttributes,
+    TeamAttributes,
+)
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+profile_name = os.getenv("SELECT_AI_PROFILE_NAME", "LLAMA_4_MAVERICK")
+
+
+async def main():
+    suffix = uuid.uuid4().hex.upper()
+    await select_ai.async_connect(user=user, password=password, dsn=dsn)
+
+    task = AsyncTask(
+        task_name=f"SAMPLE_TASK_{suffix}",
+        attributes=TaskAttributes(
+            instruction="Answer the user's question: {query}",
+            tools=[],
+            enable_human_tool=False,
+        ),
+    )
+    worker = AsyncAgent(
+        agent_name=f"SAMPLE_WORKER_{suffix}",
+        attributes=AgentAttributes(
+            profile_name=profile_name,
+            role="You answer user questions.",
+            enable_human_tool=False,
+        ),
+    )
+    supervisor = AsyncAgent(
+        agent_name=f"SAMPLE_SUPERVISOR_{suffix}",
+        attributes=AgentAttributes(
+            profile_name=profile_name,
+            role="You supervise and coordinate the team.",
+            enable_human_tool=False,
+            supervisor=True,
+        ),
+    )
+    team = AsyncTeam(
+        team_name=f"SAMPLE_TEAM_{suffix}",
+        attributes=TeamAttributes(
+            agents=[{"name": worker.agent_name, "task": task.task_name}],
+            process="sequential",
+            supervisor_agent=supervisor.agent_name,
+        ),
+    )
+
+    await task.create(replace=True)
+    await worker.create(replace=True)
+    await supervisor.create(replace=True)
+    await team.create(replace=True)
+
+    try:
+        fetched = await AsyncTeam.fetch(team.team_name)
+        print("Supervisor agent:", fetched.attributes.supervisor_agent)
+        print("Supervisor task:", fetched.attributes.supervisor_task)
+        print("Team description:", await team.describe_team())
+        print("Team tools:", await team.list_tools())
+    finally:
+        await team.delete(force=True)
+        await supervisor.delete(force=True)
+        await worker.delete(force=True)
+        await task.delete(force=True)
+
+
+asyncio.run(main())

samples/agent/async/tool_run_describe.py

@@ -0,0 +1,61 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# agent/async/tool_run_describe.py
+#
+# Async version of the direct tool execution sample. The database user needs
+# permission to create a function.
+# -----------------------------------------------------------------------------
+
+import asyncio
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import AsyncTool
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+
+
+async def main():
+    await select_ai.async_connect(user=user, password=password, dsn=dsn)
+    suffix = uuid.uuid4().hex.upper()
+    function_name = f"SAMPLE_CALCULATE_AGE_{suffix}"
+    tool_name = f"SAMPLE_AGE_TOOL_{suffix}"
+
+    async with select_ai.async_cursor() as cursor:
+        await cursor.execute(
+            f"""
+            CREATE OR REPLACE FUNCTION {function_name}(p_birth_date DATE)
+            RETURN NUMBER IS
+            BEGIN
+                RETURN TRUNC(MONTHS_BETWEEN(SYSDATE, p_birth_date) / 12);
+            END;
+            """
+        )
+
+    tool = await AsyncTool.create_pl_sql_tool(
+        tool_name=tool_name,
+        function=function_name,
+        description="Calculate age from a birth date",
+    )
+
+    try:
+        print("Tool description:")
+        print(await tool.describe_tool())
+        print("Tool result:")
+        print(await tool.run_tool('{"p_birth_date":"2000-01-01"}'))
+    finally:
+        await tool.delete(force=True)
+        async with select_ai.async_cursor() as cursor:
+            await cursor.execute(f"DROP FUNCTION {function_name}")
+
+
+asyncio.run(main())

samples/agent/get_definition.py

@@ -0,0 +1,37 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# agent/get_definition.py
+#
+# Create a temporary task and print its canonical PL/SQL definition.
+# -----------------------------------------------------------------------------
+
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import Task, TaskAttributes, get_definition
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+
+select_ai.connect(user=user, password=password, dsn=dsn)
+
+task = Task(
+    task_name=f"SAMPLE_DEFINITION_TASK_{uuid.uuid4().hex.upper()}",
+    attributes=TaskAttributes(
+        instruction="Answer the user's question: {query}", tools=[]
+    ),
+)
+task.create(replace=True)
+
+try:
+    print(get_definition("TASK", task.task_name))
+finally:
+    task.delete(force=True)

samples/agent/team_supervisor_inspect.py

@@ -0,0 +1,85 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# agent/team_supervisor_inspect.py
+#
+# Create a supervised team, then inspect its metadata and available tools.
+# Requires SELECT_AI_PROFILE_NAME to name an existing AI profile.
+# -----------------------------------------------------------------------------
+
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import (
+    Agent,
+    AgentAttributes,
+    Task,
+    TaskAttributes,
+    Team,
+    TeamAttributes,
+)
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+profile_name = os.getenv("SELECT_AI_PROFILE_NAME", "LLAMA_4_MAVERICK")
+suffix = uuid.uuid4().hex.upper()
+
+select_ai.connect(user=user, password=password, dsn=dsn)
+
+task = Task(
+    task_name=f"SAMPLE_TASK_{suffix}",
+    attributes=TaskAttributes(
+        instruction="Answer the user's question: {query}",
+        tools=[],
+        enable_human_tool=False,
+    ),
+)
+worker = Agent(
+    agent_name=f"SAMPLE_WORKER_{suffix}",
+    attributes=AgentAttributes(
+        profile_name=profile_name,
+        role="You answer user questions.",
+        enable_human_tool=False,
+    ),
+)
+supervisor = Agent(
+    agent_name=f"SAMPLE_SUPERVISOR_{suffix}",
+    attributes=AgentAttributes(
+        profile_name=profile_name,
+        role="You supervise and coordinate the team.",
+        enable_human_tool=False,
+        supervisor=True,
+    ),
+)
+team = Team(
+    team_name=f"SAMPLE_TEAM_{suffix}",
+    attributes=TeamAttributes(
+        agents=[{"name": worker.agent_name, "task": task.task_name}],
+        process="sequential",
+        supervisor_agent=supervisor.agent_name,
+    ),
+)
+
+task.create(replace=True)
+worker.create(replace=True)
+supervisor.create(replace=True)
+team.create(replace=True)
+
+try:
+    fetched = Team.fetch(team.team_name)
+    print("Supervisor agent:", fetched.attributes.supervisor_agent)
+    print("Supervisor task:", fetched.attributes.supervisor_task)
+    print("Team description:", team.describe_team())
+    print("Team tools:", team.list_tools())
+finally:
+    team.delete(force=True)
+    supervisor.delete(force=True)
+    worker.delete(force=True)
+    task.delete(force=True)

samples/agent/tool_run_describe.py

@@ -0,0 +1,56 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2026, Oracle and/or its affiliates.
+#
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# http://oss.oracle.com/licenses/upl.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# agent/tool_run_describe.py
+#
+# Create a temporary PL/SQL tool, inspect its metadata, and invoke it.
+# The database user needs permission to create a function.
+# -----------------------------------------------------------------------------
+
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import Tool
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+
+select_ai.connect(user=user, password=password, dsn=dsn)
+
+suffix = uuid.uuid4().hex.upper()
+function_name = f"SAMPLE_CALCULATE_AGE_{suffix}"
+tool_name = f"SAMPLE_AGE_TOOL_{suffix}"
+
+with select_ai.cursor() as cursor:
+    cursor.execute(
+        f"""
+        CREATE OR REPLACE FUNCTION {function_name}(p_birth_date DATE)
+        RETURN NUMBER IS
+        BEGIN
+            RETURN TRUNC(MONTHS_BETWEEN(SYSDATE, p_birth_date) / 12);
+        END;
+        """
+    )
+
+tool = Tool.create_pl_sql_tool(
+    tool_name=tool_name,
+    function=function_name,
+    description="Calculate age from a birth date",
+)
+
+try:
+    print("Tool description:")
+    print(tool.describe_tool())
+    print("Tool result:")
+    print(tool.run_tool('{"p_birth_date":"2000-01-01"}'))
+finally:
+    tool.delete(force=True)
+    with select_ai.cursor() as cursor:
+        cursor.execute(f"DROP FUNCTION {function_name}")