Select AI for Python

Use the select_ai client library to access DBMS_CLOUD_AI capabilities in Autonomous AI Database from Python applications.

Select AI for Python generates SQL from natural-language prompts, runs and explains generated SQL, maintains contextual conversations, summarizes and translates content, generates synthetic data, and builds Retrieval-Augmented Generation (RAG) workflows.

Select AI for Python also supports streamed text responses, synchronous and asynchronous programming, external host network access management, connection pooling, and an optional command-line interface.

Supported Platforms

Select AI for Python is certified for Autonomous AI Database 26ai and 19c. Other platforms might work with the library but are not certified.

Report product issues in the python-select-ai GitHub repository.

Install Select AI for Python

Install the Select AI for Python package with pip:

python3 -m pip install select_ai

To install the optional command-line interface dependencies, use:

python3 -m pip install 'select_ai[cli]'

Select AI for Python supports Python 3.11, 3.12, 3.13, and 3.14.

Manage Database Privileges and Network Access

Select AI for Python separates database package privileges, HTTP access, and external host network access.

Database Package Privileges

Use the following APIs to grant or revoke database package privileges:

select_ai.grant_privileges(...)
select_ai.revoke_privileges(...)

These APIs support the following database package privileges:

DBMS_CLOUD
DBMS_CLOUD_AI
DBMS_CLOUD_AI_AGENT
DBMS_CLOUD_PIPELINE

HTTP Access

Use the following APIs to manage HTTP access:

select_ai.grant_http_access(...)
select_ai.revoke_http_access(...)

External Host Network Access

Use the network access APIs to manage host access control list entries for external hosts. Specify the host, required privileges, and an optional port range.

Synchronous APIs:

select_ai.grant_network_access(...)
select_ai.revoke_network_access(...)

Asynchronous APIs:

await select_ai.async_grant_network_access(...)
await select_ai.async_revoke_network_access(...)

What You Can Do

The following table summarizes the primary Select AI for Python capabilities:

Capability	Description
Natural-language-to-SQL	Generate SQL from natural-language prompts, run generated SQL, explain SQL, and describe query results in natural language.
Retrieval-Augmented Generation	Create and manage vector indexes that retrieve relevant content for generative AI responses.
Conversations	Maintain prompt history and conversational context across related requests.
AI profiles	Configure AI providers, credentials, model parameters, database objects, and vector indexes.
Synthetic data	Generate synthetic data based on specified attributes.
Summarization	Summarize text or database query results.
Translation	Translate text from a source language to a target language.
Feedback	Record positive or negative feedback for generated SQL and remove existing feedback.
Synchronous and asynchronous APIs	Use synchronous APIs or Python `async` and `await` constructs based on application requirements.
Connection pooling	Create shared synchronous or asynchronous connection pools for concurrent applications.
Streaming responses	Receive generated CLOB text in configurable chunks from supported profile methods.
Command-line interface	Work with chats, SQL operations, profiles, summaries, and translations from a terminal.
External host network access	Grant or revoke access to external hosts with synchronous or asynchronous APIs.
AI Agents	See Select AI Agent for Python for agent-specific classes and operations.

Supported Classes

The following table summarizes the primary Select AI for Python classes:

Class or class group	Purpose
Provider classes	Define the AI provider associated with a profile.
`Profile` and `AsyncProfile`	Create and manage AI profiles and process prompts.
`ProfileAttributes`	Define profile settings such as provider, credential, maximum tokens, temperature, object list, and vector index.
`Conversation` and `AsyncConversation`	Create and manage contextual conversations.
`ConversationAttributes`	Define conversation settings and context.
`VectorIndex` and `AsyncVectorIndex`	Create and manage vector indexes for RAG.
`VectorIndexAttributes`	Define vector index settings. For a vector index with a scheduled refresh, use `vector_index.get_next_refresh_timestamp()` to retrieve the UTC timestamp of the next refresh.
`SyntheticDataAttributes`	Define synthetic data generation settings.

Provider Classes

Select AI for Python includes the following provider classes:

OpenAIProvider
AzureProvider
OCIGenAIProvider
AWSProvider
GoogleProvider
AnthropicProvider
CohereProvider
HuggingFaceProvider

For provider-specific attributes and supported parameters, see the Select AI for Python API Reference.

Work with AI Profiles

An AI profile connects a Python application to an AI provider and defines how Select AI processes prompts. A profile can include provider information, credentials, model settings, database objects, and vector indexes.

Select AI for Python provides synchronous and asynchronous profile classes:

Processing	Class
Synchronous	`Profile`
Asynchronous	`AsyncProfile`

Use a synchronous profile in applications that process one operation at a time. Use an asynchronous profile in applications that process concurrent requests or use an event loop.

The following table describes commonly used profile functions:

Function	Description
`create()`	Creates an AI profile in the database or replaces an existing profile. See create() GitHub documentation.
`delete()`	Removes an AI profile. See delete() GitHub documentation.
`fetch()`	Retrieves an existing profile from the database.
`get_attributes()`	Returns the current profile attributes. See get_attributes() GitHub documentation.
`set_attribute()`	Updates one profile attribute.
`set_attributes()`	Updates multiple profile attributes.
`generate()`	Processes a prompt based on the specified action. See generate() GitHub documentation.
`run_sql()`	Generates and runs SQL. This is the default action. See run_sql() GitHub documentation.
`show_sql()`	Generates SQL without running it. See show_sql() GitHub documentation.
`explain_sql()`	Explains generated SQL. See explain_sql() GitHub documentation.
`narrate()`	Describes query results in natural language. See narrate() GitHub documentation.
`chat()`	Sends a free-form prompt to the generative AI model. See chat() GitHub documentation.
`show_prompt()`	Returns the constructed prompt sent to the generative AI model. See show_prompt() GitHub documentation.
`summarize()`	Summarizes the provided content. See summarize() GitHub documentation.
`translate()`	Translates text from a source language to a target language. See translate() GitHub documentation.
`generate_synthetic_data()`	Generates synthetic data based on the supplied attributes. See generate_synthetic_data() GitHub documentation.
`add_positive_feedback()`	Records positive feedback for generated SQL. See add_positive_feedback() GitHub documentation.
`add_negative_feedback()`	Records negative feedback for generated SQL. See add_negative_feedback() GitHub documentation.
`delete_feedback()`	Removes previously recorded feedback. See delete_feedback() GitHub documentation.

For the complete list of methods and parameters, see the Select AI for Python API Reference.

See also Use AI Keyword to Enter Prompts for information about Select AI actions.

Stream Profile Responses

Use streaming when an application must process generated text as it becomes available instead of waiting for the complete CLOB response.

The Profile and AsyncProfile classes support streaming through the following parameters:

Parameter	Description
`stream=True`	Returns generated text as a stream.
`chunk_size`	Sets the amount of generated text returned in each chunk.

Streaming is supported for the following profile methods:

Method	Streaming support
`chat()`	Yes
`narrate()`	Yes
`explain_sql()`	Yes
`show_sql()`	Yes
`show_prompt()`	Yes
`run_sql()`	No

The run_sql() method returns a database result and does not support streaming.

Work with Conversations

Use conversations to maintain context across related prompts. A conversation stores prompt history so that later requests can refer to information from earlier requests.

Select AI for Python provides synchronous and asynchronous conversation classes:

Processing	Class
Synchronous	`Conversation`
Asynchronous	`AsyncConversation`

Use ConversationAttributes to define conversation settings.

Use a conversation when an application requires contextual chat or a sequence of related natural-language requests. Use a profile directly when each request is independent.

Work with Vector Indexes

Use a vector index to support Retrieval-Augmented Generation. A vector index retrieves relevant content and adds that content to a prompt before the generative AI model produces a response.

Select AI for Python provides the following vector index classes:

Processing	Class
Synchronous	`VectorIndex`
Asynchronous	`AsyncVectorIndex`

Use VectorIndexAttributes to define the vector index configuration.

The VectorIndex.create() method supports the wait_for_completion parameter. Set this parameter to control whether the method waits for vector index creation to finish before returning.

Use vector_index.get_next_refresh_timestamp() to retrieve the UTC timestamp of the next scheduled refresh.

For database-side details, see CREATE_VECTOR_INDEX Procedure.

Generate Synthetic Data

Use generate_synthetic_data() to generate synthetic data based on supplied attributes.

Use SyntheticDataAttributes to define synthetic data settings. These settings describe the data to generate and the parameters used by the generative AI model.

Synthetic data can support development, demonstrations, and other scenarios that require representative data without using production records.

Retrieve and Update Existing Objects

Select AI for Python provides consistent methods for retrieving and updating database-backed proxy objects:

Method	Purpose
`fetch()`	Retrieves an existing database object and returns its corresponding proxy object.
`set_attribute()`	Updates one attribute on a proxy object.
`set_attributes()`	Updates multiple attributes on a proxy object.

These methods provide a consistent way to work with profiles, conversations, vector indexes, and other supported proxy objects.

Delete Objects with Class Methods

Use class-level delete methods when an application must delete an object without first creating or fetching a proxy object.

Profile.delete_profile(profile_name)
VectorIndex.delete_index(index_name)

Use Synchronous and Asynchronous APIs

Select AI for Python provides synchronous and asynchronous APIs for its primary operations.

The following table maps synchronous classes and operations to their asynchronous equivalents:

Synchronous class or operation	Asynchronous equivalent
`Profile`	`AsyncProfile`
`Conversation`	`AsyncConversation`
`VectorIndex`	`AsyncVectorIndex`
`select_ai.create_pool()`	`select_ai.create_pool_async()`
`select_ai.grant_network_access()`	`select_ai.async_grant_network_access()`
`select_ai.revoke_network_access()`	`select_ai.async_revoke_network_access()`

Use asynchronous APIs in applications that:

Process multiple prompts concurrently.
Use an event loop.
Integrate with asynchronous Python frameworks.
Must avoid blocking while waiting for database operations.

Use select_ai.create_pool_async() to create a shared connection pool for asynchronous workflows.

AsyncProfile supports streaming from the same supported text methods as Profile. Set stream=True and specify chunk_size when required.

For the complete asynchronous API reference, see the Select AI for Python API Reference.

Manage Connection Pools

Use a connection pool when an application processes repeated or concurrent database requests.

Select AI for Python provides the following pool creation functions:

Processing	Function
Synchronous	`select_ai.create_pool()`
Asynchronous	`select_ai.create_pool_async()`

A shared pool reduces the need to create a new database connection for every request and supports concurrent application workloads.

Use the Command-Line Interface

The optional select-ai command-line interface provides terminal access to common Select AI operations.

Install the CLI dependencies:

python3 -m pip install 'select_ai[cli]'

Run the command-line interface:

select-ai

The following table summarizes the supported commands:

Command	Purpose
`select-ai chat`	Starts an interactive, context-aware chat session.
`select-ai sql show`	Generates and displays SQL without running it.
`select-ai sql run`	Generates and runs SQL.
`select-ai sql explain`	Explains generated SQL.
`select-ai sql narrate`	Describes query results in natural language.
`select-ai profile list`	Lists AI profiles.
`select-ai profile summarize`	Summarizes content with an AI profile.
`select-ai profile translate`	Translates content with an AI profile.

Provide database connection values as command options or define the following environment variables:

Environment variable	Description
`SELECT_AI_USER`	Specifies the database user name.
`SELECT_AI_PASSWORD`	Specifies the database password.
`SELECT_AI_DB_CONNECT_STRING`	Specifies the database connection string.

Select AI Agent for Python

For Select AI Agent-specific classes, tool operations, instruction parameters, and class-level delete methods, see Select AI Agent for Python.

Oracle Cloud Infrastructure Documentation