Updated docs and samples

Author: aosingh

MANIFEST.in

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

README.md

@@ -11,4 +11,4 @@ python3 -m pip install select_ai
 
 ## Samples
 
-Examples can be found in the examples directory
+Examples can be found in the samples directory

doc/source/image/profile_provider.png

@@ -22,32 +22,6 @@ Getting Started
     user_guide/installation.rst
     user_guide/connection.rst
 
-AI Profile Object Model
-==============================
-
-.. toctree::
-    :numbered:
-    :maxdepth: 3
-
-    user_guide/profile_provider_class.rst
-
-VectorIndex Object Model
-==================================
-
-.. toctree::
-    :numbered:
-    :maxdepth: 3
-
-    user_guide/vector_index_class.rst
-
-Conversation Object Model
-===================================
-
-.. toctree::
-    :numbered:
-    :maxdepth: 3
-
-    user_guide/conversation_class.rst
 
 Actions
 =======
@@ -67,6 +41,15 @@ Provider
 
     user_guide/provider.rst
 
+Credential
+==========
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/credential.rst
+
 
 Profile Attributes
 ==================
@@ -87,14 +70,15 @@ Profile
     user_guide/profile.rst
 
 
-Async Profile
-=============
+Conversation
+============
 
 .. toctree::
     :numbered:
     :maxdepth: 3
 
-    user_guide/async_profile.rst
+    user_guide/conversation.rst
+
 
 Vector Index
 ============
@@ -113,12 +97,3 @@ Synthetic Data
     :maxdepth: 3
 
     user_guide/synthetic_data.rst
-
-Conversation
-============
-
-.. toctree::
-    :numbered:
-    :maxdepth: 3
-
-    user_guide/conversation.rst

doc/source/image/vector_index.png

@@ -1,14 +1,36 @@
 .. _actions:
 
+An action in Select AI is a keyword that instructs Select AI to perform different behavior when acting on the prompt.
+
 ********************
-Supported AI Actions
+Supported Actions
 ********************
 
 Following list of actions can be performed using ``select_ai``
 
-- ``select_ai.Action.CHAT``
-- ``select_ai.Action.EXPLAINSQL``
-- ``select_ai.Action.NARRATE``
-- ``select_ai.Action.RUNSQL``
-- ``select_ai.Action.SHOWPROMPT``
-- ``select_ai.Action.SHOWSQL``
+.. 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.

doc/source/index.rst

@@ -16,7 +16,7 @@ used with ``await``.
 Async Profile creation
 ***********************
 
-.. literalinclude:: ../../../examples/async_examples/profile_create.py
+.. literalinclude:: ../../../samples/async_samples/profile_create.py
    :language: python
 
 output::
@@ -54,7 +54,7 @@ output::
 Async explain SQL
 ***********************
 
-.. literalinclude:: ../../../examples/async_examples/profile_explain_sql.py
+.. literalinclude:: ../../../samples/async_samples/profile_explain_sql.py
    :language: python
 
 output::
@@ -82,7 +82,7 @@ output::
 Async run SQL
 ***********************
 
-.. literalinclude:: ../../../examples/async_examples/profile_run_sql.py
+.. literalinclude:: ../../../samples/async_samples/profile_run_sql.py
    :language: python
 
 output::
@@ -94,7 +94,7 @@ output::
 Async show SQL
 ***********************
 
-.. literalinclude:: ../../../examples/async_examples/profile_show_sql.py
+.. literalinclude:: ../../../samples/async_samples/profile_show_sql.py
    :language: python
 
 output::
@@ -106,7 +106,7 @@ output::
 Async concurrent SQL
 ***********************
 
-.. literalinclude:: ../../../examples/async_examples/profile_sql_concurrent_tasks.py
+.. literalinclude:: ../../../samples/async_samples/profile_sql_concurrent_tasks.py
    :language: python
 
 output::
@@ -139,7 +139,7 @@ output::
 Async chat
 **********
 
-.. literalinclude:: ../../../examples/async_examples/profile_chat.py
+.. literalinclude:: ../../../samples/async_samples/profile_chat.py
    :language: python
 
 output::
@@ -162,7 +162,7 @@ output::
 Async pipeline
 *********************
 
-.. literalinclude:: ../../../examples/async_examples/profile_pipeline.py
+.. literalinclude:: ../../../samples/async_samples/profile_pipeline.py
    :language: python
 
 output::
@@ -192,11 +192,9 @@ output::
 List profiles asynchronously
 ****************************
 
-.. literalinclude:: ../../../examples/async_examples/profiles_list.py
+.. literalinclude:: ../../../samples/async_samples/profiles_list.py
    :language: python
 
 output::
 
-    AsyncProfile(profile_name=OCI_VECTOR_AI_PROFILE, attributes=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=None, 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='test_vector_index'), description=<oracledb.AsyncLOB object at 0x1056de150>)
-    AsyncProfile(profile_name=OCI_GEN_AI_PROFILE, attributes=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=None, object_list_mode=None, provider=OCIGenAIProvider(embedding_model=None, model=None, provider_name='oci', provider_endpoint=None, region='us-chicago-1', oci_apiformat='COHERE', oci_compartment_id=None, oci_endpoint_id=None, oci_runtimetype=None), seed=None, stop_tokens=None, streaming=None, temperature=None, vector_index_name=None), description=<oracledb.AsyncLOB object at 0x104b1f170>)
-    AsyncProfile(profile_name=OCI_AI_PROFILE, attributes=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), description=<oracledb.AsyncLOB object at 0x102625940>)
+    OCI_AI_PROFILE

doc/source/user_guide/actions.rst

@@ -18,6 +18,7 @@ To connect to an Oracle Database synchronously, use
 .. code-block:: python
 
    import select_ai
+
    user = "<your_db_user>"
    password = "<your_db_password>"
    dsn = "<your_db_dsn>"
@@ -34,6 +35,7 @@ with ``await`` keyword:
 .. code-block:: python
 
    import select_ai
+
    user = "<your_db_user>"
    password = "<your_db_password>"
    dsn = "<your_db_dsn>"

doc/source/user_guide/async_profile.rst

@@ -1,18 +1,13 @@
 .. _conversation:
 
-********************
-``Conversation``
-********************
-
-.. autoclass:: select_ai.Conversation
-   :members:
+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.
 
-*********************
-``AsyncConversation``
-*********************
-
-.. autoclass:: select_ai.AsyncConversation
-   :members:
+*****************************
+``Conversation Object model``
+*****************************
+.. _conversationfig:
+.. figure:: /image/conversation.png
+   :alt: Select AI Conversation
 
 **************************
 ``ConversationAttributes``
@@ -21,14 +16,18 @@
 .. autoclass:: select_ai.ConversationAttributes
    :members:
 
-************
-Conversation
-************
+
+********************
+``Conversation`` API
+********************
+
+.. autoclass:: select_ai.Conversation
+   :members:
 
 Create conversion
 ++++++++++++++++++
 
-.. literalinclude:: ../../../examples/conversation_create.py
+.. literalinclude:: ../../../samples/conversation_create.py
    :language: python
 
 output::
@@ -38,7 +37,7 @@ output::
 Chat session
 +++++++++++++
 
-.. literalinclude:: ../../../examples/conversation_chat_session.py
+.. literalinclude:: ../../../samples/conversation_chat_session.py
    :language: python
 
 output::
@@ -59,7 +58,7 @@ output::
 List conversations
 ++++++++++++++++++
 
-.. literalinclude:: ../../../examples/conversations_list.py
+.. literalinclude:: ../../../samples/conversations_list.py
    :language: python
 
 output::
@@ -74,23 +73,27 @@ output::
 Delete conversation
 +++++++++++++++++++
 
-.. literalinclude:: ../../../examples/conversation_delete.py
+.. literalinclude:: ../../../samples/conversation_delete.py
    :language: python
 
 output::
 
     Deleted conversation with conversation id:  37DDC22E-11C8-3D49-E063-D81A000A85FE
 
 
-*********************
-Async conversation
-*********************
 
+*************************
+``AsyncConversation`` API
+*************************
 
-Chat Session
-+++++++++++++
+.. autoclass:: select_ai.AsyncConversation
+   :members:
 
-.. literalinclude:: ../../../examples/async_examples/conversation_chat_session.py
+
+Async chat session
+++++++++++++++++++
+
+.. literalinclude:: ../../../samples/async_samples/conversation_chat_session.py
    :language: python
 
 output::
@@ -108,10 +111,10 @@ output::
     ...
     ...
 
-List conversations
-++++++++++++++++++
+Async list conversations
+++++++++++++++++++++++++
 
-.. literalinclude:: ../../../examples/async_examples/conversations_list.py
+.. literalinclude:: ../../../samples/async_samples/conversations_list.py
    :language: python
 
 output::