v1.4.0

README.md

@@ -8,11 +8,18 @@ Select AI for Python enables you to leverage the broader Python ecosystem in com
 
 ## Installation
 
-Run
+Install the Python package:
+
 ```bash
 python3 -m pip install select_ai
 ```
 
+Install the optional command line interface:
+
+```bash
+python3 -m pip install 'select_ai[cli]'
+```
+
 ## Documentation
 
 See [Select AI for Python documentation][documentation]
@@ -21,6 +28,17 @@ See [Select AI for Python documentation][documentation]
 
 Examples can be found in the [/samples][samples] directory
 
+## Command Line Interface
+
+The optional `select-ai` command provides an interactive chat REPL for Select AI
+profiles:
+
+```bash
+select-ai chat --profile OCI_AI_PROFILE
+```
+
+![Select AI CLI demo](doc/source/image/select_ai_cli_demo.gif)
+
 ### Basic Example
 
 ```python

doc/source/index.rst

@@ -78,6 +78,15 @@ Profile
 
     user_guide/profile.rst
 
+Command Line Interface
+======================
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/cli.rst
+
 
 Conversation
 ============
@@ -125,3 +134,12 @@ AI Agent
     :maxdepth: 3
 
     user_guide/agent.rst
+
+Web Frameworks
+==============
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/web_frameworks.rst

doc/source/user_guide/agent.rst

@@ -45,11 +45,6 @@ Python layer and persist the tool in the Database using
          - ``recipient``
          - ``sender``
          - ``smtp_host``
-    * - ``HTTP``
-      - ``select_ai.agent.Tool.create_http_tool``
-      - - ``tool_name``
-        - ``credential_name``
-        - ``endpoint``
     * - ``SQL``
       - ``select_ai.agent.Tool.create_sql_tool``
       - - ``tool_name``
@@ -288,6 +283,58 @@ output::
 
 .. latex:clearpage::
 
+Export and Import Team
+++++++++++++++++++++++
+
+Select AI agent teams can be exported into a portable specification and
+imported into the same database, a different database, or another Select AI
+service. The specification describes the team composition and the associated
+agent, task, and tool definitions that are needed to recreate the team.
+
+``Team.export_team()`` returns the specification as a JSON string by default.
+``Team.import_team()`` accepts either that JSON string or a Python mapping. On
+import, ``profile_name`` identifies the Select AI profile to use in the target
+database. ``team_name`` can be provided to create the imported team under a new
+name; this is useful when importing into the same database as the source team.
+
+If imported object names conflict with existing agents, tasks, tools, or teams,
+set ``force=True`` to let the database replace the conflicting objects. Use this
+carefully when importing into a shared schema because conflicting components can
+be dropped and recreated.
+
+.. literalinclude:: ../../../samples/agent/team_export_import.py
+   :language: python
+   :lines: 14-
+
+output::
+
+    Exported specification:
+    {
+      "name": "EXPORT_IMPORT_MOVIE_ANALYST",
+      "component_type": "Agent",
+      "task": {
+        "task_name": "EXPORT_IMPORT_MOVIE_TASK",
+        "instruction": "Help the user with movie questions. Question: {query}",
+        "task_attributes": {
+          "enable_human_tool": "false",
+          "tools": []
+        }
+      },
+      "llm_config": {
+        "name": "LLAMA_4_MAVERICK",
+        "component_type": "oci"
+      }
+    }
+    Imported team: Team(team_name=IMPORTED_MOVIE_AGENT_TEAM, ...)
+
+The same APIs can also read from or write to object storage by passing both
+``object_storage_credential_name`` and ``location``. When exporting to object
+storage, ``Team.export_team()`` writes the specification to the location and
+returns ``None``. When importing from object storage, pass the same credential
+and location instead of ``specification``.
+
+.. latex:clearpage::
+
 *****************
 AI agent examples
 *****************

doc/source/user_guide/async_agent.rst

@@ -19,11 +19,6 @@
          - ``recipient``
          - ``sender``
          - ``smtp_host``
-    * - ``HTTP``
-      - ``select_ai.agent.AsyncTool.create_http_tool``
-      - - ``tool_name``
-        - ``credential_name``
-        - ``endpoint``
     * - ``SQL``
       - ``select_ai.agent.AsyncTool.create_sql_tool``
       - - ``tool_name``
@@ -227,6 +222,60 @@ output::
 .. latex:clearpage::
 
 
+Export and Import Team
+++++++++++++++++++++++
+
+Select AI agent teams can be exported into a portable specification and
+imported into the same database, a different database, or another Select AI
+service. The specification describes the team composition and the associated
+agent, task, and tool definitions that are needed to recreate the team.
+
+``AsyncTeam.export_team()`` returns the specification as a JSON string by
+default. ``AsyncTeam.import_team()`` accepts either that JSON string or a Python
+mapping. On import, ``profile_name`` identifies the Select AI profile to use in
+the target database. ``team_name`` can be provided to create the imported team
+under a new name; this is useful when importing into the same database as the
+source team.
+
+If imported object names conflict with existing agents, tasks, tools, or teams,
+set ``force=True`` to let the database replace the conflicting objects. Use this
+carefully when importing into a shared schema because conflicting components can
+be dropped and recreated.
+
+.. literalinclude:: ../../../samples/agent/async/team_export_import.py
+   :language: python
+   :lines: 14-
+
+output::
+
+    Exported specification:
+    {
+      "name": "EXPORT_IMPORT_MOVIE_ANALYST",
+      "component_type": "Agent",
+      "task": {
+        "task_name": "EXPORT_IMPORT_MOVIE_TASK",
+        "instruction": "Help the user with movie questions. Question: {query}",
+        "task_attributes": {
+          "enable_human_tool": "false",
+          "tools": []
+        }
+      },
+      "llm_config": {
+        "name": "LLAMA_4_MAVERICK",
+        "component_type": "oci"
+      }
+    }
+    Imported team: AsyncTeam(team_name=IMPORTED_MOVIE_AGENT_TEAM, ...)
+
+The same APIs can also read from or write to object storage by passing both
+``object_storage_credential_name`` and ``location``. When exporting to object
+storage, ``AsyncTeam.export_team()`` writes the specification to the location
+and returns ``None``. When importing from object storage, pass the same
+credential and location instead of ``specification``.
+
+.. latex:clearpage::
+
+
 List Teams
 ++++++++++
 

doc/source/user_guide/async_profile.rst

@@ -177,6 +177,27 @@ output::
 
 .. latex:clearpage::
 
+***********************
+Async streaming chat
+***********************
+
+.. literalinclude:: ../../../samples/async/profile_chat_stream.py
+   :language: python
+   :lines: 14-
+
+``stream=True`` lets callers consume generated CLOB responses chunk by chunk,
+reducing memory pressure and making it easier to progressively forward output
+to files, services, or user interfaces. Async streaming text APIs return an
+async iterator of ``str`` chunks after the awaited method call. The
+``chunk_size`` parameter controls the number of CLOB characters read per chunk;
+it is not a byte count.
+
+Streaming is supported by ``generate()``, ``chat()``, ``narrate()``,
+``explain_sql()``, ``show_sql()``, and ``show_prompt()``. It is not supported
+for ``run_sql()``, which returns a ``pandas.DataFrame``.
+
+.. latex:clearpage::
+
 **************************
 Summarize
 **************************

doc/source/user_guide/cli.rst

@@ -0,0 +1,94 @@
+.. _cli:
+
+**************************
+Command line interface
+**************************
+
+.. only:: html
+
+   .. image:: /image/select_ai_cli_demo.gif
+      :alt: Select AI CLI demo
+      :width: 100%
+
+.. only:: latex
+
+   .. image:: /image/select_ai_cli_demo.png
+      :alt: Select AI CLI demo
+      :width: 100%
+
+The package provides an optional ``select-ai`` command line tool. Install the
+CLI extra to use it:
+
+.. code-block:: bash
+
+    pip install 'select_ai[cli]'
+
+Set the database connection details as environment variables, or pass them as
+command line options:
+
+.. code-block:: bash
+
+    export SELECT_AI_USER=<db_user>
+    export SELECT_AI_PASSWORD=<db_password>
+    export SELECT_AI_DB_CONNECT_STRING=<db_connect_string>
+
+Interactive chat
+================
+
+The ``chat`` subcommand starts an interactive profile chat REPL. Pass an
+existing Select AI profile with ``--profile``:
+
+.. code-block:: bash
+
+    select-ai chat --profile OCI_AI_PROFILE
+
+The REPL uses ``Profile.chat_session()`` so prompts in the same terminal session
+share conversation context. Responses stream by default. Use ``--no-stream`` to
+print each response after it is fully generated.
+
+.. code-block:: text
+
+    Connected to Select AI profile: OCI_AI_PROFILE
+    Type /help for commands. Type /exit to quit.
+    select_ai> What tables can I ask about?
+    ...
+    select_ai> /exit
+
+Useful options:
+
+- ``--user``, ``--password``, and ``--dsn`` override the environment values.
+- ``--wallet-location`` and ``--wallet-password`` configure wallet connections.
+- ``--chunk-size`` controls the number of CLOB characters read per stream chunk.
+- ``--conversation-length`` controls how many prompts are retained in context.
+- ``--keep-conversation`` keeps the database conversation after the REPL exits.
+
+SQL commands
+============
+
+SQL operations are one-shot subcommands instead of a REPL:
+
+.. code-block:: bash
+
+    select-ai sql show --profile OCI_AI_PROFILE "count movies by genre"
+    select-ai sql run --profile OCI_AI_PROFILE "count movies by genre"
+    select-ai sql explain --profile OCI_AI_PROFILE "count movies by genre"
+    select-ai sql narrate --profile OCI_AI_PROFILE "count movies by genre"
+
+Profile commands
+================
+
+Summarize and translate are available under the ``profile`` command group:
+
+.. code-block:: bash
+
+    select-ai profile list
+    select-ai profile list --pattern "OCI.*"
+
+    select-ai profile summarize --profile OCI_AI_PROFILE "Text to summarize"
+    select-ai profile summarize --profile OCI_AI_PROFILE --file notes.txt
+
+    select-ai profile translate \
+        --profile OCI_AI_PROFILE \
+        --source-language English \
+        --target-language German \
+        "Thank you"

doc/source/user_guide/privileges.rst

@@ -37,6 +37,7 @@ output::
 
     Granted privileges to: <select_ai_db_user>
 
+.. latex:clearpage::
 
 ****************
 Revoke privilege
@@ -52,4 +53,55 @@ Similarly, to revoke use the method
 
 output::
 
-    Granted privileges to: <select_ai_db_user>
+    Revoked privileges from: <select_ai_db_user>
+
+.. latex:clearpage::
+
+***************************
+Grant network access
+***************************
+
+Connect as admin and run
+``select_ai.grant_network_access(...)`` to add a network ACL entry for
+host access. This wraps ``DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE`` and can be
+used for hosts that require privileges such as ``connect``, ``http``, or
+``smtp``.
+
+.. literalinclude:: ../../../samples/grant_network_access.py
+   :language: python
+   :lines: 14-
+
+output::
+
+    Granted network access to: <select_ai_db_user>
+
+The async API is ``select_ai.async_grant_network_access(...)``.
+
+.. literalinclude:: ../../../samples/async/grant_network_access.py
+   :language: python
+   :lines: 14-
+
+.. latex:clearpage::
+
+***************************
+Revoke network access
+***************************
+
+Connect as admin and run
+``select_ai.revoke_network_access(...)`` to remove a network ACL entry for
+host access. This wraps ``DBMS_NETWORK_ACL_ADMIN.REMOVE_HOST_ACE`` and should
+use the same host, privileges, and port range that were used to grant access.
+
+.. literalinclude:: ../../../samples/revoke_network_access.py
+   :language: python
+   :lines: 14-
+
+output::
+
+    Revoked network access from: <select_ai_db_user>
+
+The async API is ``select_ai.async_revoke_network_access(...)``.
+
+.. literalinclude:: ../../../samples/async/revoke_network_access.py
+   :language: python
+   :lines: 14-