Added detailed documentation and examples

aosingh · aosingh · commit c7d993221fd8 · 2025-06-10T17:41:57.000-07:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -6,6 +6,7 @@ repos:
     -   id: end-of-file-fixer
     -   id: check-yaml
     -   id: check-added-large-files
+        args: ['--maxkb=600']
 -   repo: https://github.com/psf/black-pre-commit-mirror
     rev: 24.4.2
     hooks:
diff --git a/doc/source/image/classes.png b/doc/source/image/classes.png
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -22,6 +22,15 @@ Getting Started
     user_guide/installation.rst
     user_guide/connection.rst
 
+Select AI classes
+=================
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/class_object_model.rst
+
 Actions
 =======
 
@@ -41,17 +50,17 @@ Provider
     user_guide/provider.rst
 
 
-Provider Attributes
-===================
+Profile Attributes
+==================
 
 .. toctree::
     :numbered:
     :maxdepth: 3
 
-    user_guide/provider_attributes.rst
+    user_guide/profile_attributes.rst
 
 Profile
-=======
+==================
 
 .. toctree::
     :numbered:
diff --git a/doc/source/user_guide/actions.rst b/doc/source/user_guide/actions.rst
@@ -4,4 +4,11 @@
 Supported AI Actions
 ********************
 
-TODO
+Following list of actions can be performed using ``select_ai``
+
+- ``select_ai.Action.RUNSQL``
+- ``select_ai.Action.SHOWSQL``
+- ``select_ai.Action.EXPLAINSQL``
+- ``select_ai.Action.NARRATE``
+- ``select_ai.Action.CHAT``
+- ``select_ai.Action.SHOWPROMPT``
diff --git a/doc/source/user_guide/async_profile.rst b/doc/source/user_guide/async_profile.rst
@@ -1,5 +1,10 @@
 .. _async_profile:
 
+An AsyncProfile object can be created with ``select_ai.AsyncProfile()``
+``AsyncProfile`` support use of concurrent programming with `asyncio <https://docs.python.org/3/library/asyncio.html>`__.
+Unless explicitly noted as synchronous, the ``AsyncProfile`` methods should be
+used with ``await``.
+
 ********************
 ``AsyncProfile`` API
 ********************
@@ -27,3 +32,10 @@ Async pipeline
 
 .. literalinclude:: ../../../examples/async_examples/3_pipeline.py
    :language: python
+
+****************************
+List profiles asynchronously
+****************************
+
+.. literalinclude:: ../../../examples/async_examples/5_list_profiles.py
+   :language: python
diff --git a/doc/source/user_guide/class_object_model.rst b/doc/source/user_guide/class_object_model.rst
@@ -0,0 +1,9 @@
+.. _object_model:
+
+********************
+select_ai classes
+********************
+
+.. _classesfig:
+.. figure:: /image/classes.png
+   :alt: Select AI classes
diff --git a/doc/source/user_guide/profile.rst b/doc/source/user_guide/profile.rst
@@ -1,8 +1,20 @@
 .. _profile:
 
-********************
-``Profile`` API
-********************
+An AI profile is a specification that includes the AI provider to use and other
+details regarding metadata and database objects required for generating
+responses to natural language prompts.
+
+An AI profile object can be created using ``select_ai.Profile()``
+
+*******************************
+Base ``Profile`` methods
+*******************************
+.. autoclass:: select_ai.BaseProfile
+   :members:
+
+*******************************
+Synchronous ``Profile`` methods
+*******************************
 
 .. autoclass:: select_ai.Profile
    :members:
diff --git a/doc/source/user_guide/profile_attributes.rst b/doc/source/user_guide/profile_attributes.rst
@@ -0,0 +1,12 @@
+.. _profile_attributes:
+
+*************************
+``ProfileAttributes``
+*************************
+
+This class helps defining  attributes to manage and configure the behavior of
+the AI profile. The ``ProfileAttributes`` objects are created
+by ``select_ai.ProfileAttributes()``
+
+.. autoclass:: select_ai.ProfileAttributes
+   :members:
diff --git a/doc/source/user_guide/provider.rst b/doc/source/user_guide/provider.rst
@@ -1,7 +1,66 @@
 .. _provider:
 
+An AI Provider in Select AI refers to the service provider that supplies the
+LLM or transformer or both for processing and generating responses to natural
+language prompts. These providers offer models that can interpret and convert
+natural language for the use cases highlighted under the LLM concept
+
+See `Select your AI Provider <https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-about.html#GUID-FDAEF22A-5DDF-4BAE-A465-C1D568C75812>`__
+for the supported providers
+
 **********************
-Supported AI Providers
+``Provider``
 **********************
 
-TODO
+.. autoclass:: select_ai.Provider
+   :members:
+
+*********************************
+``AnthropicAIProviderAttributes``
+*********************************
+.. autoclass:: select_ai.AnthropicAIProvider
+   :members:
+
+*****************************
+``AzureAIProviderAttributes``
+*****************************
+.. autoclass:: select_ai.AzureAIProvider
+   :members:
+
+*****************************
+``AWSAIProviderAttributes``
+*****************************
+.. autoclass:: select_ai.AWSAIProvider
+   :members:
+
+******************************
+``CohereAIProviderAttributes``
+******************************
+.. autoclass:: select_ai.CohereAIProvider
+   :members:
+
+*****************************
+``OpenAIProviderAttributes``
+*****************************
+.. autoclass:: select_ai.OpenAIProvider
+   :members:
+
+
+******************************
+``OCIGenAIProviderAttributes``
+******************************
+.. autoclass:: select_ai.OCIGenAIProvider
+   :members:
+
+
+******************************
+``GoogleAIProviderAttributes``
+******************************
+.. autoclass:: select_ai.GoogleAIProvider
+   :members:
+
+***********************************
+``HuggingFaceAIProviderAttributes``
+***********************************
+.. autoclass:: select_ai.HuggingFaceAIProvider
+   :members:
diff --git a/doc/source/user_guide/provider_attributes.rst b/doc/source/user_guide/provider_attributes.rst
diff --git a/doc/source/user_guide/vector_index.rst b/doc/source/user_guide/vector_index.rst
@@ -4,19 +4,35 @@
 ``VectorIndex``
 ********************
 
+A ``VectorIndex`` object can be created with ``select_ai.VectorIndex()``
+
 .. autoclass:: select_ai.VectorIndex
    :members:
 
 *************************
 ``VectorIndexAttributes``
 *************************
 
+A ``VectorIndexAttributes`` object can be created with
+``select_ai.VectorIndexAttributes()``
+
+
 .. autoclass:: select_ai.VectorIndexAttributes
    :members:
 
+Check the examples below to understand how to create vector indexes
+
 **************************
 Create Vector Index
 **************************
 
 .. literalinclude:: ../../../examples/7_vector_index.py
    :language: python
+
+
+*************************************
+Asynchronous support for Vector Index
+*************************************
+
+.. literalinclude:: ../../../examples/7_vector_index.py
+   :language: python
diff --git a/examples/async_examples/5_list_profiles.py b/examples/async_examples/5_list_profiles.py
@@ -0,0 +1,25 @@
+import asyncio
+import os
+
+import select_ai
+
+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)
+    async_profile = await select_ai.AsyncProfile(
+        profile_name="async_oci_ai_profile"
+    )
+    # matches the start of string
+    async for fetched_profile in async_profile.list(
+        profile_name_pattern="^oci"
+    ):
+        p = await fetched_profile
+        print(p)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/async_examples/6_vector_index.py b/examples/async_examples/6_vector_index.py
@@ -0,0 +1,37 @@
+import asyncio
+import os
+
+import select_ai
+
+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)
+    async_profile = await select_ai.AsyncProfile(
+        profile_name="async_oci_ai_profile"
+    )
+
+    vector_index_attributes = select_ai.VectorIndexAttributes(
+        location="https://objectstorage.us-ashburn-1.oraclecloud.com/n/dwcsdev/b/conda-environment/o/tenant1-pdb3/graph",
+        object_storage_credential_name="my_oci_ai_profile_key",
+    )
+
+    await async_profile.create_vector_index(
+        index_name="test_vector_index",
+        attributes=vector_index_attributes,
+        description="Vector index for conda environments",
+        replace=True,
+    )
+    print("created vector index: test_vector_index")
+
+    async for vector_index in async_profile.list_vector_indexes(
+        index_name_pattern="^test"
+    ):
+        print(vector_index)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/src/select_ai/__init__.py b/src/select_ai/__init__.py
@@ -5,7 +5,7 @@
     enable_provider,
 )
 from .async_profile import AsyncProfile
-from .base_profile import ProfileAttributes
+from .base_profile import BaseProfile, ProfileAttributes
 from .conversation import Conversation, ConversationAttributes
 from .db import (
     async_connect,
diff --git a/src/select_ai/async_profile.py b/src/select_ai/async_profile.py
diff --git a/src/select_ai/base_profile.py b/src/select_ai/base_profile.py
diff --git a/src/select_ai/provider.py b/src/select_ai/provider.py
diff --git a/src/select_ai/vector_index.py b/src/select_ai/vector_index.py
