Merge branch 'v1.0.0.dev6' into 'main'

V1.0.0.dev6

See merge request adbs/python-select-ai!8

Author: aosingh

README.md

@@ -1,6 +1,6 @@
 # select-ai
 
-Python API for Select AI
+Select AI for Python
 
 ## Install
 

doc/requirements.txt

@@ -1,2 +1,3 @@
 sphinx
 sphinx-rtd-theme
+sphinx_toolbox

doc/source/conf.py

@@ -8,6 +8,10 @@
 import os
 import sys
 
+import sphinx_prompt
+
+sys.modules["sphinx-prompt"] = sphinx_prompt
+
 sys.path.insert(0, os.path.join("..", "..", "src", "select_ai"))
 
 autodocs_default_options = {
@@ -16,14 +20,14 @@
     "undoc-members": True,
 }
 
-project = "Python API for Select AI"
+project = "Select AI for Python"
 copyright = "2025, Oracle and/or its affiliates. All rights reserved."
 author = "Oracle"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.autodoc", "sphinx_toolbox.latex"]
 
 # The suffix of source filenames.
 source_suffix = ".rst"

doc/source/license.rst

@@ -0,0 +1,47 @@
+:orphan:
+
+.. _license:
+
+
+.. include:: <isonum.txt>
+
+.. centered:: **LICENSE AGREEMENT FOR python-select-ai**
+
+Copyright (c) 2025, Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+END OF TERMS AND CONDITIONS

doc/source/user_guide/async_profile.rst

@@ -12,17 +12,19 @@ used with ``await``.
 .. autoclass:: select_ai.AsyncProfile
    :members:
 
+.. latex:clearpage::
+
 ***********************
 Async Profile creation
 ***********************
 
-.. literalinclude:: ../../../samples/async_samples/profile_create.py
+.. literalinclude:: ../../../samples/async/profile_create.py
    :language: python
 
 output::
 
-    Profile attributes are:  ProfileAttributes(annotations=None, case_sensitive_values=None, comments=None, constraints=None, conversation=None, credential_name='my_oci_ai_profile_key', enable_sources=None, enable_source_offsets=None, enforce_object_list=None, max_tokens=1024, object_list=[{'owner': 'SH'}], object_list_mode=None, provider=OCIGenAIProvider(embedding_model=None, model=None, provider_name='oci', provider_endpoint=None, region='us-chicago-1', oci_apiformat='GENERIC', oci_compartment_id=None, oci_endpoint_id=None, oci_runtimetype=None), seed=None, stop_tokens=None, streaming=None, temperature=None, vector_index_name=None)
-    Profile attributes as Python dict:  {'annotations': None,
+    Created async profile  async_oci_ai_profile
+    Profile attributes:  {'annotations': None,
      'case_sensitive_values': None,
      'comments': None,
      'constraints': None,
@@ -31,8 +33,8 @@ output::
      'enable_source_offsets': None,
      'enable_sources': None,
      'enforce_object_list': None,
-     'max_tokens': 1024,
-     'object_list': [{'owner': 'SH'}],
+     'max_tokens': '1024',
+     'object_list': '[{"owner":"SH"}]',
      'object_list_mode': None,
      'provider': OCIGenAIProvider(embedding_model=None,
                                   model=None,
@@ -50,11 +52,13 @@ output::
      'vector_index_name': None}
 
 
+.. latex:clearpage::
+
 ***********************
 Async explain SQL
 ***********************
 
-.. literalinclude:: ../../../samples/async_samples/profile_explain_sql.py
+.. literalinclude:: ../../../samples/async/profile_explain_sql.py
    :language: python
 
 output::
@@ -77,36 +81,41 @@ output::
 
     This query will return the total number of promotions in the `"PROMOTIONS"` table.
 
+.. latex:clearpage::
 
 ***********************
 Async run SQL
 ***********************
 
-.. literalinclude:: ../../../samples/async_samples/profile_run_sql.py
+.. literalinclude:: ../../../samples/async/profile_run_sql.py
    :language: python
 
 output::
 
        PROMOTION_COUNT
     0              503
 
+.. latex:clearpage::
+
 ***********************
 Async show SQL
 ***********************
 
-.. literalinclude:: ../../../samples/async_samples/profile_show_sql.py
+.. literalinclude:: ../../../samples/async/profile_show_sql.py
    :language: python
 
 output::
 
     SELECT COUNT("p"."PROMO_ID") AS "PROMOTION_COUNT" FROM "SH"."PROMOTIONS" "p"
 
 
+.. latex:clearpage::
+
 ***********************
 Async concurrent SQL
 ***********************
 
-.. literalinclude:: ../../../samples/async_samples/profile_sql_concurrent_tasks.py
+.. literalinclude:: ../../../samples/async/profile_sql_concurrent_tasks.py
    :language: python
 
 output::
@@ -135,11 +144,13 @@ output::
        PROMOTION_COUNT
     0              503
 
+.. latex:clearpage::
+
 **********
 Async chat
 **********
 
-.. literalinclude:: ../../../samples/async_samples/profile_chat.py
+.. literalinclude:: ../../../samples/async/profile_chat.py
    :language: python
 
 output::
@@ -158,11 +169,13 @@ output::
     ...
     ...
 
+.. latex:clearpage::
+
 *********************
 Async pipeline
 *********************
 
-.. literalinclude:: ../../../samples/async_samples/profile_pipeline.py
+.. literalinclude:: ../../../samples/async/profile_pipeline.py
    :language: python
 
 output::
@@ -188,13 +201,16 @@ output::
 
     Result 3 for prompt 'Explain the query: SELECT * FROM sh.products' is: ORA-20000: Invalid action - INVALID ACTION
 
+.. latex:clearpage::
+
 ****************************
 List profiles asynchronously
 ****************************
 
-.. literalinclude:: ../../../samples/async_samples/profiles_list.py
+.. literalinclude:: ../../../samples/async/profiles_list.py
    :language: python
 
 output::
 
+    OCI_VECTOR_AI_PROFILE
     OCI_AI_PROFILE

doc/source/user_guide/conversation.rst

@@ -1,6 +1,8 @@
 .. _conversation:
 
-Conversations in Select AI represent an interactive exchange between the user and the system, enabling users to query or interact with the database through a series of natural language prompts.
+Conversations in Select AI represent an interactive exchange between the user
+and the system, enabling users to query or interact with the database through
+a series of natural language prompts.
 
 *****************************
 ``Conversation Object model``
@@ -9,13 +11,16 @@ Conversations in Select AI represent an interactive exchange between the user an
 .. figure:: /image/conversation.png
    :alt: Select AI Conversation
 
+.. latex:clearpage::
+
 **************************
 ``ConversationAttributes``
 **************************
 
 .. autoclass:: select_ai.ConversationAttributes
    :members:
 
+.. latex:clearpage::
 
 ********************
 ``Conversation`` API
@@ -24,6 +29,8 @@ Conversations in Select AI represent an interactive exchange between the user an
 .. autoclass:: select_ai.Conversation
    :members:
 
+.. latex:clearpage::
+
 Create conversion
 ++++++++++++++++++
 
@@ -32,7 +39,9 @@ Create conversion
 
 output::
 
-    Created conversation with conversation id:  380A1601-182D-F329-E063-D81A000A2C93
+    Created conversation with conversation id:  3AB2ED3E-7E52-8000-E063-BE1A000A15B6
+
+.. latex:clearpage::
 
 Chat session
 +++++++++++++
@@ -55,6 +64,8 @@ output::
     ...
     ...
 
+.. latex:clearpage::
+
 List conversations
 ++++++++++++++++++
 
@@ -69,6 +80,7 @@ output::
     37DF777F-F3DA-F084-E063-D81A000A53BE
     ConversationAttributes(title='History of Science', description="LLM's understanding of history of science", retention_days=7)
 
+.. latex:clearpage::
 
 Delete conversation
 +++++++++++++++++++
@@ -81,6 +93,7 @@ output::
     Deleted conversation with conversation id:  37DDC22E-11C8-3D49-E063-D81A000A85FE
 
 
+.. latex:clearpage::
 
 *************************
 ``AsyncConversation`` API
@@ -89,11 +102,12 @@ output::
 .. autoclass:: select_ai.AsyncConversation
    :members:
 
+.. latex:clearpage::
 
 Async chat session
 ++++++++++++++++++
 
-.. literalinclude:: ../../../samples/async_samples/conversation_chat_session.py
+.. literalinclude:: ../../../samples/async/conversation_chat_session.py
    :language: python
 
 output::
@@ -111,10 +125,12 @@ output::
     ...
     ...
 
+.. latex:clearpage::
+
 Async list conversations
 ++++++++++++++++++++++++
 
-.. literalinclude:: ../../../samples/async_samples/conversations_list.py
+.. literalinclude:: ../../../samples/async/conversations_list.py
    :language: python
 
 output::

doc/source/user_guide/credential.rst

@@ -1,6 +1,36 @@
 .. _credential:
 
-Credential stores the API key from your AI provider for use by Oracle Database.
+Credential object securely stores API key from your AI provider for use by Oracle Database.
+The following table shows AI Provider and corresponding credential object format
+
+.. list-table:: AI Provider and expected credential format
+    :header-rows: 1
+    :widths: 30 70
+    :align: left
+
+    * - AI Provider
+      - Credential format
+    * - Anthropic
+      - .. code-block:: python
+
+            {"username": "anthropic", "password": "sk-xxx"}
+    * - HuggingFace
+      -  .. code-block:: python
+
+            {"username": "hf", "password": "hf_xxx"}
+    * - OCI Gen AI
+      - .. code-block:: python
+
+           {"user_ocid": "", "tenancy_ocid": "", "private_key": "", "fingerprint": ""}
+    * - OpenAI
+      - .. code-block:: python
+
+           {"username": "openai", "password": "sk-xxx"}
+
+
+
+
+.. latex:clearpage::
 
 **************************
 Create credential

doc/source/user_guide/installation.rst

@@ -48,11 +48,10 @@ To use ``select_ai`` you need:
   .. code-block:: python
 
      import select_ai
-     import getpass
 
-     username = ""
-     dsn = ""
-     password = getpass.getpass(f"Enter password for {username}@{dsn}")
+     user = "<your_db_user>"
+     password = "<your_db_password>"
+     dsn = "<your_db_dsn>"
      select_ai.connect(user=user, password=password, dsn=dsn)
      print("Connected to the Database")
 
@@ -67,3 +66,5 @@ To use ``select_ai`` you need:
   .. code-block:: shell
 
      Connected to the Database
+
+.. latex:clearpage::