Snowflake Native Application

Overview and Installation

Contextual AI provides a platform for creating enterprise-grade AI agents, grounded in your documents and data. In a few simple steps, you can install Contextual AI as a Native Snowflake Application and create powerful AI agents in the security of your Snowflake environment.

1. Obtain Contextual AI from the Snowflake Marketplace

2. Install the application

   1. Grant create compute pool privilege to the application on Snowsight
   2. Grant bind service endpoint privilege to the application on Snowsight

3. Press "Activate" to begin activating the Contextual AI Application on Snowsight

   1. Please note, this step may require up to 1 hour.
      Once the application has been installed, the application's Snowsight/settings/security view will look like the image below, your application is now ready for use!
   
   

Using the application

1. Once you have installed the application, click "Launch App" to enter the Contextual AI Application.
   1. The first user to load into the application will be designated as the "Admin User" so it is highly recommended that your team's administrator be the first user to load the application.
2. Once you have logged in with your Snowflake credentials, you will be able to see the Contextual AI Dashboard and create your first AI Agent.

   1. The first time you use the application, you will need to create a new agent and create a new Datastore for it.

      
3. Click "Create" at the bottom of the Create Agents page to create and save your first AI Agent.
4. Adding Knowledge to Your Agent's Datastore
   1. Navigate to the Datastores tab and locate your agent's newly created Datastore.
   2. Open the "Documents" page within the Datastore.
   3. Select the "Ingest" tab to upload your PDF documents.
      Once you upload a document, the system will automatically begin processing it in the background. This process extracts information from your documents and prepares them for future retrieval by your agents.
5. After your documents are processed, return to the Agents page and click "Chat" to start interacting with your agent. Your agent can now access and reference the knowledge from your uploaded documents during conversations.

API (Programmatic) Access

Contextual AI's application provides a REST API for programmatic interaction with your agents and datastore. After you have created and configured an agent (and the agent's datastore) through the UI, you can integrate it into your applications and workflows using API endpoints. Below are the steps to get started with API access:

API Access in the Contextual AI Native App requires obtaining the API endpoint of your instance, which can be found by running this Snowflake query in a Snowflake worksheet or via the Snowflake CLI:
CALL CONTEXTUAL_NATIVE_APP.CORE.GET_API_ENDPOINT()

You will receive a response formatted as a URL: xxxxx-xxxxx-xxxxx.snowflakecomputing.app. This URL value is the backend API endpoint for your application.

To create the full API endpoint, you will need to prepend https:// to the backend API endpoint from your application and then append /v1 at the end.

An example of how to do this in Python:

SF_BASE_URL = 'xxxxx-xxxxx-xxxxx.snowflakecomputing.app' # what you will receive from GET_API_ENDPOINT()
BASE_URL = f'https://{SF_BASE_URL}/v1' # using python3 f-string formatting

For authentication, instead of using an API key, the Snowflake Native App version of Contextual AI uses a Snowflake token, which can be retrieved using the following Python code:

ctx = snowflake.connector.connect(
   user="",# snowflake account user
   password='', # snowflake account password
   account="organization-account", # format: <organization>-<account> (e.g., myorg-account123)
   session_parameters={
      'PYTHON_CONNECTOR_QUERY_RESULT_FORMAT': 'json'
   })

# Obtain a session token.
token_data = ctx._rest._token_request('ISSUE')
token_extract = token_data['data']['sessionToken']

# Create a request to the ingress endpoint with authz.
api_key = f'\"{token_extract}\"'

Once you have your API key, you can combine the steps above to create a Contextual AI client in Python that is configured to use your Contextual AI Native App in Snowflake to make programmatic queries to your agents.

SF_BASE_URL = 'xxxxx-xxxxx-xxxxx.snowflakecomputing.app' # what you will receive from GET_API_ENDPOINT()
BASE_URL = f'https://{SF_BASE_URL}/v1'

ctx = snowflake.connector.connect( # type: ignore
   user="",# snowflake account user
   password='', # snowflake account password
   account="organization-account", # snowflake organization and account <Organization>-<Account>
   session_parameters={
      'PYTHON_CONNECTOR_QUERY_RESULT_FORMAT': 'json'
   })

# Obtain a session token.
token_data = ctx._rest._token_request('ISSUE') # type: ignore
token_extract = token_data['data']['sessionToken'] # type: ignore

# Create a request to the ingress endpoint with authz.
api_key = f'\"{token_extract}\"'

client = ContextualAI(api_key=api_key, base_url=BASE_URL)

# get list of agents to test API
agents = [a for a in client.agents.list()]

It is recommended to use the Contextual AI Python SDK to interact with the API. An example script of our Python SDK and Snowflake Native App can be found here.