How to access CoPilot via its API

After authentication you can access TigerGraph CoPilot via its API for both self-managed and TigerGraph Cloud managed services.

Two types of API access are provided:

REST HTTP endpoints
pyTigerGraph

Authentication

There are two options to authenticate with the TigerGraph Co-Pilot service.

The first way is with a username/password pair generated from the TigerGraph database.
The second way is a GSQL secret, also obtained from the database. When using the GSQL secret, the username field must be specified as __GSQL__secret, with the password field containing the secret. However, if pyTigerGraph v1.6+ is being used and a connection is created with the gsqlSecret parameter, then you don’t need to provide a username and password.

REST HTTP Endpoints

For self-managed services, the full list of available HTTP endpoints can be found at the /docs path on your host’s address, e.g., http://localhost:8000/docs.

SwaggerDocUX

It is a Swagger API doc, and you can even try out the endpoints on that page.

The Swagger API doc page is disabled on TigerGraph Cloud.

pyTigerGraph

This guide assumes you are already familiar with pyTigerGraph. If not, see our documentation Getting Started with pyTigerGraph.

First, make sure you have the latest version of pyTigerGraph as it is under active development for the CoPilot functions.
```
pip install -U pyTigerGraph
```

Next, configure the endpoints with a TigerGraphConnection. As in this example code snippets below:

Import TigerGraphConnection:

from pyTigerGraph import TigerGraphConnection

Create a connection to the database.

conn = TigerGraphConnection(host="DATABASE_HOST_HERE", graphname="GRAPH_NAME_HERE", username="USERNAME_HERE", password="PASSWORD_HERE")

Configure CoPilot host:

conn.ai.configureCoPilotHost("COPILOT_HOST_HERE")

Retrieve Top-K Docs from Library:

# `top_k` parameter optional
conn.ai.retrieveDocs("How many papers are there?", top_k = 5)

Run a natural language query:

print(conn.ai.query("How many papers are there?"))

# prints: {'natural_language_response': 'There are 736389 papers.', 'answered_question': True, 'query_sources': {'function_call': "getVertexCount('Paper')", 'result': 736389}}

# Prompt for PageRank query - could be read in as JSON file.
pr_prompt = {
    "function_header": "tg_pagerank",
    "description": "Determines the importance or influence of each vertex based on its connections to other vertices.",
    "docstring": "The PageRank algorithm measures the influence of each vertex on every other vertex. PageRank influence is defined recursively: a vertex’s influence is based on the influence of the vertices which refer to it. A vertex’s influence tends to increase if either of these conditions are met:\n* It has more referring vertices\n* Its referring vertices have higher influence\nTo run this algorithm, use `runInstalledQuery('tg_pagerank', params={'v_type': 'INSERT_V_TYPE_HERE', 'e_type': 'INSERT_E_TYPE_HERE', 'top_k': INSERT_TOP_K_HERE})`, where the parameters are:\n* 'v_type': The vertex type to run the algorithm on.\n* 'e_type': The edge type to run the algorithm on.\n* 'top_k': The number of top scoring vertices to return to the user.",
    "param_types": {
        "v_type": "str",
        "e_type": "str",
        "top_k": "int"
    }
}

conn.ai.registerCustomQuery(pr_prompt["function_header"], pr_prompt["description"], pr_prompt["docstring"], pr_prompt["param_types"])

Once registered, you can now run the query.

Run Query:

print(conn.ai.query("What are the 5 most influential papers by citations?"))

# prints: {'natural_language_response': 'The top 5 most cited papers are:\n\n1. [Title of paper with Vertex_ID 428523]\n2. [Title of paper with Vertex_ID 384889]\n3. [Title of paper with Vertex_ID 377502]\n4. [Title of paper with Vertex_ID 61855]\n5. [Title of paper with Vertex_ID 416200]', 'answered_question': True, 'query_sources': {'function_call': "runInstalledQuery('tg_pagerank', params={'v_type': 'Paper', 'e_type': 'CITES', 'top_k': 5})", 'result': [{'@@top_scores_heap': [{'Vertex_ID': '428523', 'score': 392.8731}, {'Vertex_ID': '384889', 'score': 251.8021}, {'Vertex_ID': '377502', 'score': 149.1018}, {'Vertex_ID': '61855', 'score': 129.7406}, {'Vertex_ID': '416200', 'score': 129.2286}]}]}}

For more examples with pyTigerGraph, please refer to the notebook tutorials here.

Next Steps

Next, go to Testing TigerGraph CoPilot to learn how to test TigerGraph CoPilot.

Return to TigerGraph CoPilot for a different topic.