1.0.0 beta release

README.md

@@ -15,20 +15,73 @@ python3 -m pip install select_ai
 
 ## Samples
 
-Examples can be found in the samples directory
+Examples can be found in the [/samples][samples] directory
 
-## Contributing
+### Basic Example
+
+```python
+import select_ai
+
+user = "<your_select_ai_user>"
+password = "<your_select_ai_password>"
+dsn = "<your_select_ai_db_connect_string>"
+
+select_ai.connect(user=user, password=password, dsn=dsn)
+profile = select_ai.Profile(profile_name="oci_ai_profile")
+# run_sql returns a pandas dataframe
+df = profile.run_sql(prompt="How many promotions?")
+print(df.columns)
+print(df)
+```
+
+### Async Example
+
+```python
+
+import asyncio
+
+import select_ai
 
+user = "<your_select_ai_user>"
+password = "<your_select_ai_password>"
+dsn = "<your_select_ai_db_connect_string>"
 
-This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)
+# This example shows how to asynchronously run sql
+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",
+    )
+    # run_sql returns a pandas df
+    df = await async_profile.run_sql("How many promotions?")
+    print(df)
+
+asyncio.run(main())
+
+```
+## Help
+
+Questions can be asked in [GitHub Discussions][ghdiscussions].
+
+Problem reports can be raised in [GitHub Issues][ghissues].
+
+## Contributing
+
+This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide][contributing]
 
 ## Security
 
-Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process
+Please consult the [security guide][security] for our responsible security vulnerability disclosure process
 
 ## License
 
 Copyright (c) 2025 Oracle and/or its affiliates.
 
 Released under the Universal Permissive License v1.0 as shown at
 <https://oss.oracle.com/licenses/upl/>.
+
+[contributing]: https://github.com/oracle/python-select-ai/blob/main/CONTRIBUTING.md
+[ghdiscussions]: https://github.com/oracle/python-select-ai/discussions
+[ghissues]: https://github.com/oracle/python-select-ai/issues
+[samples]: https://github.com/oracle/python-select-ai/tree/main/samples
+[security]: https://github.com/oracle/python-select-ai/blob/main/SECURITY.md

doc/source/user_guide/async_profile.rst

@@ -20,6 +20,7 @@ Async Profile creation
 
 .. literalinclude:: ../../../samples/async/profile_create.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -60,6 +61,7 @@ Async explain SQL
 
 .. literalinclude:: ../../../samples/async/profile_explain_sql.py
    :language: python
+   :lines: 12-
 
 output::
 
@@ -89,6 +91,7 @@ Async run SQL
 
 .. literalinclude:: ../../../samples/async/profile_run_sql.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -103,6 +106,7 @@ Async show SQL
 
 .. literalinclude:: ../../../samples/async/profile_show_sql.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -117,6 +121,7 @@ Async concurrent SQL
 
 .. literalinclude:: ../../../samples/async/profile_sql_concurrent_tasks.py
    :language: python
+   :lines: 15-
 
 output::
 
@@ -152,6 +157,7 @@ Async chat
 
 .. literalinclude:: ../../../samples/async/profile_chat.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -177,6 +183,7 @@ Async pipeline
 
 .. literalinclude:: ../../../samples/async/profile_pipeline.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -209,6 +216,7 @@ List profiles asynchronously
 
 .. literalinclude:: ../../../samples/async/profiles_list.py
    :language: python
+   :lines: 14-
 
 output::
 

doc/source/user_guide/conversation.rst

@@ -36,6 +36,7 @@ Create conversion
 
 .. literalinclude:: ../../../samples/conversation_create.py
    :language: python
+   :lines: 15-
 
 output::
 
@@ -48,6 +49,7 @@ Chat session
 
 .. literalinclude:: ../../../samples/conversation_chat_session.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -71,6 +73,7 @@ List conversations
 
 .. literalinclude:: ../../../samples/conversations_list.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -87,6 +90,7 @@ Delete conversation
 
 .. literalinclude:: ../../../samples/conversation_delete.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -109,6 +113,7 @@ Async chat session
 
 .. literalinclude:: ../../../samples/async/conversation_chat_session.py
    :language: python
+   :lines: 13-
 
 output::
 
@@ -132,6 +137,7 @@ Async list conversations
 
 .. literalinclude:: ../../../samples/async/conversations_list.py
    :language: python
+   :lines: 14-
 
 output::
 

doc/source/user_guide/credential.rst

@@ -39,8 +39,25 @@ Create credential
 In this example, we create a credential object to authenticate to OCI Gen AI
 service provider:
 
+Sync API
+++++++++
+
 .. literalinclude:: ../../../samples/create_ai_credential.py
    :language: python
+   :lines: 14-
+
+output::
+
+    Created credential:  my_oci_ai_profile_key
+
+.. latex:clearpage::
+
+Async API
++++++++++
+
+.. literalinclude:: ../../../samples/async/create_ai_credential.py
+   :language: python
+   :lines: 14-
 
 output::
 

doc/source/user_guide/profile.rst

@@ -39,6 +39,7 @@ Create Profile
 
 .. literalinclude:: ../../../samples/profile_create.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -79,6 +80,7 @@ Narrate
 
 .. literalinclude:: ../../../samples/profile_narrate.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -93,6 +95,7 @@ Show SQL
 
 .. literalinclude:: ../../../samples/profile_show_sql.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -108,6 +111,7 @@ Run SQL
 
 .. literalinclude:: ../../../samples/profile_run_sql.py
    :language: python
+   :lines: 14-
 
 output::
 
@@ -123,7 +127,8 @@ Chat
 **************************
 
 .. literalinclude:: ../../../samples/profile_chat.py
-       :language: python
+   :language: python
+   :lines: 14-
 
 output::
 
@@ -139,7 +144,9 @@ List profiles
 **************************
 
 .. literalinclude:: ../../../samples/profiles_list.py
-       :language: python
+   :language: python
+   :lines: 14-
+
 
 output::
 

doc/source/user_guide/provider.rst

@@ -103,13 +103,28 @@ Enable AI service provider
        export SELECT_AI_DB_CONNECT_STRING=<db_connect_string>
        export TNS_ADMIN=<path/to/dir_containing_tnsnames.ora>
 
+Sync API
+++++++++
+
 This method grants execute privilege on the packages
 ``DBMS_CLOUD``, ``DBMS_CLOUD_AI`` and ``DBMS_CLOUD_PIPELINE``. It
-also enables the user to invoke the AI(LLM) endpoint hosted at a
-certain domain
+also enables the database user to invoke the AI(LLM) endpoint
 
 .. literalinclude:: ../../../samples/enable_ai_provider.py
    :language: python
+   :lines: 15-
+
+output::
+
+    Enabled AI provider for user: <select_ai_db_user>
+
+.. latex:clearpage::
+
+Async API
++++++++++
+.. literalinclude:: ../../../samples/async/enable_ai_provider.py
+   :language: python
+   :lines: 14-
 
 output::
 
@@ -121,8 +136,25 @@ output::
 Disable AI service provider
 ***************************
 
+Sync API
+++++++++
+
 .. literalinclude:: ../../../samples/disable_ai_provider.py
    :language: python
+   :lines: 14-
+
+output::
+
+    Disabled AI provider for user:  <select_ai_db_user>
+
+.. latex:clearpage::
+
+Async API
++++++++++
+
+.. literalinclude:: ../../../samples/async/disable_ai_provider.py
+   :language: python
+   :lines: 14-
 
 output::