v1.4.0 documentation

.github/workflows/release.yaml

@@ -0,0 +1,60 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yaml
+    secrets: inherit
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Check out python-select-ai repository code
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.13"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+
+      - name: Upload release distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: release-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/select_ai
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download release distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-distributions
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

.github/workflows/test.yaml

@@ -1,5 +1,7 @@
 name: select_ai_py_tests
-on: push
+on:
+  push:
+  workflow_call:
 
 permissions:
   contents: read

MANIFEST.in

@@ -1,2 +1,3 @@
 recursive-include tests *.py
 recursive-include samples *.py
+recursive-include recipes *.py

doc/source/index.rst

@@ -48,7 +48,7 @@ Provider
     :numbered:
     :maxdepth: 3
 
-    user_guide/provider.rst
+    Provider <user_guide/provider.rst>
 
 Credential
 ==========
@@ -78,15 +78,14 @@ Profile
 
     user_guide/profile.rst
 
-Command Line Interface
-======================
+Async Profile
+=============
 
 .. toctree::
     :numbered:
     :maxdepth: 3
 
-    user_guide/cli.rst
-
+    user_guide/async_profile.rst
 
 Conversation
 ============
@@ -135,6 +134,24 @@ AI Agent
 
     user_guide/agent.rst
 
+Async AI Agent
+==============
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/async_agent.rst
+
+Command Line Interface
+======================
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/cli.rst
+
 Web Frameworks
 ==============
 
@@ -143,3 +160,12 @@ Web Frameworks
     :maxdepth: 3
 
     user_guide/web_frameworks.rst
+
+Concurrent Prompt Processing
+============================
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/concurrent_prompt_processing.rst

doc/source/user_guide/actions.rst

@@ -1,45 +1,154 @@
 .. _actions:
 
-An action in Select AI is a keyword that instructs Select AI to perform different behavior when acting on the prompt.
+An action in Select AI is a keyword that instructs Select AI to perform
+different behavior when acting on the prompt.
+
+Most applications use the convenience methods on ``Profile`` or
+``AsyncProfile``, such as ``show_sql()``, ``run_sql()``, ``narrate()``, and
+``chat()``. Use ``generate(..., action=...)`` when you want to choose the
+action dynamically at runtime.
+
+The default action for ``generate()`` is ``select_ai.Action.RUNSQL``.
 
 ********************
 Supported Actions
 ********************
 
-Following list of actions can be performed using ``select_ai``
+The following actions can be performed using ``select_ai``:
 
 .. list-table:: Select AI Actions
-    :header-rows: 1
-    :widths: 20 30 50
-    :align: left
-
-    * - Actions
-      - Enum
-      - Description
-    * - chat
-      - ``select_ai.Action.CHAT``
-      - Enables general conversations with the LLM, potentially for clarifying prompts, exploring data, or generating content.
-    * - explainsql
-      - ``select_ai.Action.EXPLAINSQL``
-      - Explain the generated SQL query
-    * - narrate
-      - ``select_ai.Action.NARRATE``
-      - Explains the output of the query in natural language, making the results accessible to users without deep technical expertise.
-    * - runsql
-      - ``select_ai.Action.RUNSQL``
-      - Executes a SQL query generated from a natural language prompt. This is the default action.
-    * - showprompt
-      - ``select_ai.Action.SHOWPROMPT``
-      - Show the details of the prompt sent to LLM
-    * - showsql
-      - ``select_ai.Action.SHOWSQL``
-      - Displays the generated SQL statement without executing it.
-    * - summarize
-      - ``select_ai.Action.SUMMARIZE``
-      - Generate summary of your large texts
-    * - feedback
-      - ``select_ai.Action.FEEDBACK``
-      - Provide feedback to improve accuracy of the generated SQL
-    * - translate
-      - ``select_ai.Action.TRANSLATE``
-      - Translate text from one language to another
+   :header-rows: 1
+   :widths: 20 30 50
+   :align: left
+
+   * - Action
+     - Enum
+     - Description
+   * - chat
+     - ``select_ai.Action.CHAT``
+     - Enables general conversations with the LLM, potentially for clarifying
+       prompts, exploring data, or generating content.
+   * - explainsql
+     - ``select_ai.Action.EXPLAINSQL``
+     - Explains the generated SQL query.
+   * - narrate
+     - ``select_ai.Action.NARRATE``
+     - Executes generated SQL and explains the output in natural language.
+   * - runsql
+     - ``select_ai.Action.RUNSQL``
+     - Executes SQL generated from a natural language prompt. This is the
+       default action for ``generate()``.
+   * - showprompt
+     - ``select_ai.Action.SHOWPROMPT``
+     - Shows the prompt sent to the LLM.
+   * - showsql
+     - ``select_ai.Action.SHOWSQL``
+     - Displays the generated SQL statement without executing it.
+   * - summarize
+     - ``select_ai.Action.SUMMARIZE``
+     - Generates a summary of inline content or content referenced by a URI.
+   * - feedback
+     - ``select_ai.Action.FEEDBACK``
+     - Provides feedback to improve the accuracy of generated SQL.
+   * - translate
+     - ``select_ai.Action.TRANSLATE``
+     - Translates text from one language to another.
+
+Action methods
+==============
+
+.. list-table:: Action to method mapping
+   :header-rows: 1
+   :widths: 30 35 35
+   :align: left
+
+   * - Action
+     - Convenience method
+     - Return type
+   * - ``RUNSQL``
+     - ``profile.run_sql(prompt)``
+     - ``pandas.DataFrame``
+   * - ``SHOWSQL``
+     - ``profile.show_sql(prompt)``
+     - ``str``
+   * - ``EXPLAINSQL``
+     - ``profile.explain_sql(prompt)``
+     - ``str``
+   * - ``NARRATE``
+     - ``profile.narrate(prompt)``
+     - ``str``
+   * - ``CHAT``
+     - ``profile.chat(prompt)``
+     - ``str``
+   * - ``SHOWPROMPT``
+     - ``profile.show_prompt(prompt)``
+     - ``str``
+   * - ``SUMMARIZE``
+     - ``profile.summarize(...)``
+     - ``str``
+   * - ``TRANSLATE``
+     - ``profile.translate(...)``
+     - ``str``
+
+Choosing an action
+==================
+
+Use ``show_sql`` before ``run_sql`` when you want to inspect generated SQL
+before executing it. Use ``run_sql`` when the application should return a
+tabular result. Use ``narrate`` when users need a natural language answer
+instead of a table. Use ``explain_sql`` and ``show_prompt`` when tuning profile
+attributes, object lists, comments, constraints, or feedback.
+
+Examples
+========
+
+Use a convenience method:
+
+.. code-block:: python
+
+   profile = select_ai.Profile(profile_name="oci_ai_profile")
+   sql = profile.show_sql(prompt="How many promotions?")
+
+Use ``generate`` with an explicit action:
+
+.. code-block:: python
+
+   profile = select_ai.Profile(profile_name="oci_ai_profile")
+
+   sql = profile.generate(
+       prompt="How many promotions?",
+       action=select_ai.Action.SHOWSQL,
+   )
+
+   df = profile.generate(
+       prompt="How many promotions?",
+       action=select_ai.Action.RUNSQL,
+   )
+
+Use an action selected at runtime:
+
+.. code-block:: python
+
+   action = select_ai.Action("showsql")
+   result = profile.generate(
+       prompt="How many promotions?",
+       action=action,
+   )
+
+Streaming
+=========
+
+Streaming is supported for text-returning generation actions:
+``CHAT``, ``NARRATE``, ``EXPLAINSQL``, ``SHOWSQL``, and ``SHOWPROMPT``.
+Streaming is not supported for ``RUNSQL`` because it returns a
+``pandas.DataFrame``.
+
+.. code-block:: python
+
+   for chunk in profile.generate(
+       prompt="What is OCI?",
+       action=select_ai.Action.CHAT,
+       stream=True,
+       chunk_size=4096,
+   ):
+       print(chunk, end="")