### Setup pydgraph Project

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Initialize the project environment, including installing tools, setting up a virtual environment, and installing dependencies. Set INSTALL_MISSING_TOOLS=true to automatically install missing tools.

```sh
make setup
```

```sh
INSTALL_MISSING_TOOLS=true make setup
```

--------------------------------

### Run pydgraph TLS Example

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/tls/README.md

Execute the Python TLS example script using `uv run`. This command starts a development server for the Python application.

```bash
uv run python tls_example.py
```

--------------------------------

### Example queries and response generation

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This code snippet demonstrates how to use the 'reply' function with a list of example queries. It iterates through the queries, prints each query, calls the 'reply' function to get a response, and then prints the generated response.

```python
example_queries = [
    "Which pink items are suitable for children?",
    "Do you have a helmet with anti allergic padding?",
]
for q in example_queries:
    print()
    print(f"> {q}")
    print()
    r = reply(q)
    print(r)
```

--------------------------------

### Install python-graphql-client

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Use this command to install the python-graphql-client library, which is necessary for interacting with Dgraph's GraphQL endpoint.

```bash
%pip install python-graphql-client
```

--------------------------------

### Install Dependencies and Initialize Dgraph Clients

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-ai-classification.ipynb

Installs necessary libraries and sets up Dgraph clients for cloud and local use. Requires Dgraph Cloud credentials and API keys.

```python
!pip install pydgraph python-graphql-client ipycytoscape
import pydgraph
import json
import base64
import getpass
from python_graphql_client import GraphqlClient

# Dgraph cloud Admin API
# Don't change!
dgraph_cerebro = "https://cerebro.cloud.dgraph.io/graphql"

# copy your Dgraph cloud endpoints
# The GraphQL endpoint is found at https://cloud.dgraph.io/_/dashboard
dgraph_graphql_endpoint =
    "https://withered-thunder.us-east-1.aws.cloud.dgraph.io/graphql"
# The gRPC endpoint is found at https://cloud.dgraph.io/_/settings
dgraph_grpc = "withered-thunder.grpc.us-east-1.aws.cloud.dgraph.io:443"

# graph admin endpoint is /admin
dgraph_graphql_admin = dgraph_graphql_endpoint.replace("/graphql", "/admin")
```

--------------------------------

### Install uv using pip

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/simple/README.md

Installs the uv dependency manager via pip. Ensure pip is up-to-date.

```sh
pip install uv
```

--------------------------------

### Install pydgraph and other libraries

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-episode1.ipynb

Installs necessary Python libraries for interacting with Dgraph and other services. This is a prerequisite for running the subsequent code examples.

```python
!pip install pydgraph python-graphql-client ipycytoscape
import pydgraph
import json
import base64
import getpass
import os
```

--------------------------------

### Install and Register Graphistry

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Install the Graphistry library and register your account credentials. Replace placeholder values with your actual username and password.

```python
%pip install graphistry

import graphistry

print("Graphistry version", graphistry.__version__)

# replace these <place holders> with your credentials
graphistry_username = "<YOUR GRAPHISTRY USERNAME>"
graphistry_password = "<YOUR GRAPHISTRY PASSWORD>"
graphistry.register(
    api=3,
    protocol="https",
    server="hub.graphistry.com",
    username=graphistry_username,
    password=graphistry_password,
)
```

--------------------------------

### Check Project Setup and Hooks

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Run pre-commit hooks to verify code style and standards. This is a crucial step before submitting changes.

```sh
make check
```

--------------------------------

### Install uv on macOS/Linux

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/simple/README.md

Installs the uv dependency manager using a curl script. Ensure you have curl installed.

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install uv on Windows

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/simple/README.md

Installs the uv dependency manager using a PowerShell command. Requires PowerShell execution policy to allow scripts.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Start Self-Managed Dgraph Cluster with Docker

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

This command starts a Dgraph standalone instance using Docker. Ensure Docker is installed and running.

```sh
docker run --rm -it -p 8080:8080 -p 9080:9080 -p 5080:5080 dgraph/standalone:latest
```

--------------------------------

### Process Example Queries with Text to Intent

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This snippet demonstrates how to use the `text_to_intent` function with a list of example queries. It then prints the resulting list of extracted intents in a JSON format.

```python
example_queries = [
    "do you have clothes for teenagers in dark colors?",
    "Which pink items are suitable for children?",
    "Help me find gardening gear that is waterproof",
    "I'm looking for a bench with dimensions 100x50 for my living room",
]

intent_list = [text_to_intent(q) for q in example_queries]

print(json.dumps(intent_list, indent=4))
```

--------------------------------

### Install pydgraph Library

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Installs the pydgraph Python client library using pip. This is a prerequisite for interacting with Dgraph from Python.

```python
# Install pydgraph

%pip install pydgraph
```

--------------------------------

### Install pydgraph

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Install the pydgraph package using pip. Ensure your protobuf version is compatible.

```sh
pip install pydgraph
```

```sh
# For protobuf 4.x compatibility
pip install pydgraph "protobuf>=4.23.0,<5.0.0"

# For protobuf 5.x compatibility
pip install pydgraph "protobuf>=5.0.0,<6.0.0"
```

--------------------------------

### Python File Header Example

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

All new Python files must begin with SPDX headers and proper attribution. This ensures licensing and copyright compliance.

```python
# SPDX-FileCopyrightText: © 2017-2026 Istari Digital, Inc.
```

--------------------------------

### Native Async/Await Client with Connection Strings

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Demonstrates using the `async_open` function with a connection string to establish a connection to the Dgraph database using the native async client. This simplifies client setup.

```python
import asyncio
import pydgraph

async def main():
    # Using async_open with connection string
    async with await pydgraph.async_open(
        "dgraph://groot:password@localhost:9080"
    ) as client:
        version = await client.check_version()
        print(f"Connected to Dgraph version: {version}")

asyncio.run(main())
```

--------------------------------

### Install pandas

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Install the pandas library using pip. This is required for data manipulation and analysis, particularly for transforming Dgraph query results into DataFrames.

```bash
%pip install pandas
```

--------------------------------

### Start Dgraph Docker Compose

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/simple/README.md

Starts a local Dgraph cluster using Docker Compose. Note: uses a blanket whitelist for security, not suitable for production.

```sh
docker compose up
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for various types of changes.

```text
feat: add async client support
fix: resolve connection timeout issue
docs: update installation instructions
refactor: simplify error handling
test: add integration tests for ACL
```

--------------------------------

### Native Async/Await Client Basic Usage

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Provides a basic example of using the native `asyncio`-based Dgraph client. This includes creating an `AsyncDgraphClientStub`, logging in, altering the schema, performing a mutation, and running a query.

```python
import asyncio
import pydgraph

async def main():
    # Create async client
    client_stub = pydgraph.AsyncDgraphClientStub('localhost:9080')
    client = pydgraph.AsyncDgraphClient(client_stub)

    try:
        # Login
        await client.login("groot", "password")

        # Alter schema
        await client.alter(pydgraph.Operation(
            schema="name: string @index(term) ."
        ))

        # Run mutation
        txn = client.txn()
        response = await txn.mutate(
            set_obj={"name": "Alice"},
            commit_now=True
        )

        # Run query
        query = '{ me(func: has(name)) { name } }'
        txn = client.txn(read_only=True)
        response = await txn.query(query)
        print(response.json)

    finally:
        await client.close()

asyncio.run(main())
```

--------------------------------

### Sync Dependencies with uv

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/simple/README.md

Installs project dependencies, including pydgraph, into a virtual environment using uv.

```sh
uv sync
```

--------------------------------

### Install Python Packages for Dgraph and AI

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

Installs necessary Python libraries for interacting with Dgraph, OpenAI, Hugging Face, and other tools. Ensure you have Python 3.6+.

```python
# Optional script to install all the required packages
!pip3 install pydgraph
!pip3 install openai
!pip3 install sentence_transformers
!pip3 install pybars3
!pip3 install python-dotenv
```

--------------------------------

### Execute Mutation with Commit Now

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Execute a mutation and commit it immediately using `commit_now=True`. This example demonstrates creating a mutation with N-Quads and then executing it within a request.

```python
mutation = txn.create_mutation(set_nquads='_:alice <name> "Alice" .')
request = txn.create_request(mutations=[mutation], commit_now=True)
txn.do_request(request)
```

--------------------------------

### Clone pydgraph Repository

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Clone your forked repository locally to start development. Ensure you navigate into the cloned directory.

```sh
git clone https://github.com/YOUR-USERNAME/pydgraph.git
cd pydgraph
```

--------------------------------

### Perform GraphQL Query with pydgraph

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

This example demonstrates how to execute a GraphQL query against Dgraph to search for entities by name. It filters results and prints the names of matching entities.

```graphql
query ($filter: EntityFilter, $first: Int) {
  queryEntity(filter: $filter, first: $first) {
    id: nodeID
    type: __typename
    name
  }
}
```

```python
variables = {"filter": {"name": {"anyoftext": "living"}}, "first": 10}
data = gql_client.execute(query=ft_query, variables=variables)
for res in data["data"]["queryEntity"]:
    print(res["name"])
```

--------------------------------

### Similarity Search Result Example

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This is an example JSON output from a Dgraph similarity search query, showing categories that are similar to the input sentence and a list of the top 3 products within each category.

```json
{
    "result": [
        {
            "category": "wedding decor",
            "products": [
                {
                    "name": "Romantic LED Light Valentine's Day Sign"
                }
            ]
        },
        {
            "category": "home decor",
            "products": [
                {
                    "name": "Fall Pillow Covers"
                }
            ]
        },
        {
            "category": "home garden balcony decor",
            "products": [
                {
                    "name": "Flower Pot Stand"
                }
            ]
        }
    ]
}
```

--------------------------------

### Define Product Ontology for LLM Prompting

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This Python code defines the structure of a 'Product' entity, including its predicates and their descriptions. This information is used to guide the LLM in understanding the knowledge graph's schema.

```python
entities = [
    {
        "entity_name": "Product",
        "description": "Item detailed type",
        "predicates": {
            "category": {
                "description": "Item category, for example 'home decoration', 'women clothing', 'office supply'"
            },
            "color": {"description": "color of the item"},
            "brand": {"description": "if present, brand of the item"},
            "characteristic": {
                "description": "if present, item characteristics, for example 'waterproof', 'adhesive', 'easy to use'"
            },
            "measurement": {"description": "if present, dimensions of the item"},
            "age_group": {
                "description": "target age group for the product, one of 'babies', 'children', 'teenagers', 'adults'."
            },
        },
    }
]
```

--------------------------------

### Load Data into Dgraph Cluster

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Loads data into the Dgraph cluster using the Live Loader. It attempts to use Docker if available, otherwise falls back to the local 'dgraph' binary or installs Dgraph if on Linux.

```python
# Load data into the cluster

# download the rdf file
!curl -Ss https://raw.githubusercontent.com/dgraph-io/vlg/main/rdf-subset/data.rdf.gz --output data.rdf.gz

# find ways to load data into the cluster
import shutil
import os
import platform

pwd = os.getcwd()
if shutil.which("docker"):
    docker_host = dgraph_hostname
    if dgraph_hostname == "localhost":
        docker_host = "host.docker.internal"
    !docker run -it -v {pwd}:/data dgraph/standalone:latest dgraph live -f /data/data.rdf.gz --alpha {docker_host}:{dgraph_grpc_port} --zero {docker_host}:{dgraph_zero_port}
elif shutil.which("dgraph"):
    !dgraph live -f ./data.rdf.gz --alpha {dgraph_hostname}:{dgraph_grpc_port} --zero {dgraph_hostname}:{dgraph_zero_port}
elif platform.system() == "Linux":
    !curl https://get.dgraph.io -sSf | bash -s -- -y
    !dgraph live -f ./data.rdf.gz --alpha {dgraph_hostname}:{dgraph_grpc_port} --zero {dgraph_hostname}:{dgraph_zero_port}
else:
    raise Exception("Unable to find a way to load data into your cluster.")
```

--------------------------------

### Open Dgraph Connection with Connection String

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Use the `pydgraph.open` function with a connection string to establish a connection to a Dgraph cluster. This example shows connecting to an ACL-enabled, non-TLS cluster and logging in as 'groot'. Ensure the client is closed after use.

```python
client = pydgraph.open("dgraph://groot:password@localhost:8090")

# Use the client
...

client.close()
```

--------------------------------

### Generate Changelog Entry

Source: https://github.com/dgraph-io/pydgraph/blob/main/PUBLISHING.md

Use an AI model like Sonnet 4.5 to generate a new entry for the CHANGELOG.md file. The prompt specifies the release version and adheres to the 'Keep a Changelog' format, using past entries as a guide. It also includes running the trunk linter on the changes.

```text
I'm releasing vXX.X.X off the main branch, add a new entry for this release. Conform to the
"Keep a Changelog" format, use past entries as a formatting guide. Run the trunk linter on your changes.
```

--------------------------------

### Async Client Error Handling

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Implement error handling for async operations using standard Python `try...except` blocks. This example demonstrates catching login failures and attempting mutations in a read-only transaction.

```python
import pydgraph
import asyncio

async def main():
    async with await pydgraph.async_open("dgraph://localhost:9080") as client:
        try:
            await client.login("groot", "wrong_password")
        except Exception as e:
            print(f"Login failed: {e}")

        try:
            txn = client.txn(read_only=True)
            await txn.mutate(set_obj={"name": "Alice"})
        except pydgraph.errors.TransactionError as e:
            print(f"Cannot mutate in read-only transaction: {e}")

asyncio.run(main())
```

--------------------------------

### Display Makefile Help

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

View all available commands and their descriptions in the project's Makefile.

```sh
make help
```

--------------------------------

### Create a Dgraph Client

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Initialize a DgraphClient by providing a DgraphClientStub. Connecting to multiple Dgraph servers is supported for workload distribution.

```python
import pydgraph

client_stub = pydgraph.DgraphClientStub('localhost:9080')
client = pydgraph.DgraphClient(client_stub)
```

--------------------------------

### Initialize OpenAI Client

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This Python snippet shows how to initialize the OpenAI client. It retrieves the API key from the environment variable 'OPENAI_API_KEY' or uses a fallback placeholder. Ensure the API key is securely managed.

```python
from openai import OpenAI

llm = OpenAI(
    api_key=os.environ.get(
        "OPENAI_API_KEY", "<your OpenAI API key if not set as env var>"
    )
)

```

--------------------------------

### High-Contention Counter Example

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

This example demonstrates atomically incrementing a counter in a high-contention scenario using pydgraph.run_transaction. It configures specific retry parameters suitable for frequent conflicts.

```python
import json
import pydgraph

def increment_counter(client, counter_uid):
    """Atomically increment a counter, handling conflicts automatically."""

    def operation(txn):
        # Read current value
        query = f'{{ counter(func: uid({counter_uid})) {{ count }} }}'
        result = txn.query(query)
        data = json.loads(result.json)
        current = data.get("counter", [{}])[0].get("count", 0)

        # Increment
        txn.mutate(set_obj={"uid": counter_uid, "count": current + 1})
        txn.commit()
        return current + 1

    return pydgraph.run_transaction(
        client, operation,
        max_retries=10,   # More retries for high contention
        base_delay=0.05,  # Start with shorter delays
        max_delay=2.0,
        jitter=0.25       # Higher jitter to spread out retries
    )

# Usage
client = pydgraph.DgraphClient(pydgraph.DgraphClientStub("localhost:9080"))
new_value = increment_counter(client, "0x1")
print(f"Counter is now: {new_value}")

```

--------------------------------

### Run Full Test Suite

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Execute all tests in the project's test suite using the make test command.

```sh
make test
```

--------------------------------

### Run Sample Python Code with uv

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/simple/README.md

Executes the main Python script using uv to manage the environment and dependencies.

```sh
uv run python simple.py
```

--------------------------------

### Run Stress Tests (Quick Mode)

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Execute stress tests in quick mode, suitable for rapid checks. This mode uses fewer workers and iterations.

```sh
make test PYTEST_ARGS="tests/test_stress_sync.py tests/test_stress_async.py -v"
```

--------------------------------

### Create GraphQL Client for Dgraph

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Instantiate a GraphQL client to connect to your Dgraph instance's GraphQL endpoint. Ensure the endpoint URL is correctly formatted.

```python
from python_graphql_client import GraphqlClient

gql_client = GraphqlClient(
    endpoint=f"http://{dgraph_hostname}:{dgraph_http_port}/graphql"
)
```

--------------------------------

### Set Dgraph Hostname

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Configure the hostname for the Dgraph alpha service. This is typically 'localhost' for local setups.

```python
# Set the hostname of the Dgraph alpha service
dgraph_hostname = "localhost"
```

--------------------------------

### Construct System Prompt for LLM Analysis

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This Python code constructs a detailed system prompt for an LLM. It includes instructions for analyzing user prompts, a description of the knowledge graph's ontology (generated by `ontologyPrompt`), and the desired JSON output format for extracted information.

```python
system_prompt = f"""
    You are analyzing user prompt to fetch information from a knowledge graph. 

    {ontologyPrompt(entities)}

    Return a json object following the example:
    {{
        "entity": "product",
        "intent": "one of 'list', 'count'",
        criteria: [
        {{ "predicate": "category", "value": "clothing"}},
        {{ "predicate": "color", "value": "blue"}},
        {{ "predicate": "age_group", "value": "adults"}}   
        ]
    }}
    
    If there are no relevant entities in the user prompt, return an empty json object.
"""
print(system_prompt)
```

--------------------------------

### Delete Data using Mutation

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Delete data using `txn.mutate(del_obj=...)`. This example first queries for the node to be deleted and then uses `del_obj` to remove it.

```python
# Delete data

query = """query all($a: string)
 { 
   all(func: eq(name, $a)) 
    { 
      uid 
    } 
  }"""
variables = {'$a': 'Bob'}

res = txn.query(query, variables=variables)
ppl = json.loads(res.json)

# For a mutation to delete a node, use this:
txn.mutate(del_obj=person)
```

--------------------------------

### Use Context Manager for Resource Management

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Demonstrates using `pydgraph.client_stub` or `pydgraph.DgraphClientStub` as context managers to ensure resources are automatically released. The client instance is only usable within the `with-as` block.

```python
with pydgraph.client_stub(SERVER_ADDR) as stub1:
  with pydgraph.client_stub(SERVER_ADDR) as stub2:
    client = pydgraph.DgraphClient(stub1, stub2)
```

```python
with pydgraph.DgraphClientStub(SERVER_ADDR) as stub1:
  with pydgraph.DgraphClientStub(SERVER_ADDR) as stub2:
    client = pydgraph.DgraphClient(stub1, stub2)
```

--------------------------------

### Commit Changes with Conventional Commits

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Commit your changes using the Conventional Commits format for clear and consistent commit messages. Examples include 'feat:', 'fix:', and 'docs:'.

```sh
git commit -m "feat: add new feature"
```

```sh
git commit -m "fix: resolve issue with..."
```

```sh
git commit -m "docs: update README"
```

--------------------------------

### Sync Project Dependencies

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Update the project's virtual environment to reflect the latest dependencies. Run this after pulling changes or modifying dependency files.

```sh
make sync
```

--------------------------------

### Query Categories with Embeddings using DQL

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-episode1.ipynb

Query Dgraph for categories and their associated embeddings using a DQL query within a transaction. Ensure the client is initialized and a transaction is started.

```python
# Verify that we have a Category with  embedding information.

txn = client.txn()
try:
    # Run query.
    query = """
    {
       category(func: type(Category)){
        uid
        Category.name
        embedding
      }
    }
    """
    res = txn.query(query)
    data = json.loads(res.json)
    print(json.dumps(data["category"], indent=2))

finally:
    txn.discard()
```

--------------------------------

### Initialize pydgraph Client with Cloud Credentials

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-episode1.ipynb

This snippet demonstrates how to initialize a pydgraph client for Dgraph Cloud. It handles API key retrieval from environment variables or prompts the user if not found. Ensure you have your Dgraph Cloud API key and endpoint ready.

```python
# Cloud credentials
# we need the cloud login credential to upload the Lambda code.
# we need the an Admin API key generated at https://cloud.dgraph.io/_/settings?tab=api-keys for DQL alter and query


dgraph_grpc_endpoint = "withered-bird.grpc.us-east-1.aws.cloud.dgraph.io:443"
# ZTY5MWNjZmE0MTBkNmMyZjg3ZjUxYTI5NTRjZGMwMzE=

# verify if endpoint contains cloud.dgraph.io
if "cloud.dgraph.io" in dgraph_grpc_endpoint:
    if "DGRAPH_API_KEY" in os.environ:
        DGRAPH_API_KEY = os.environ["DGRAPH_API_KEY"]
    else:
        DGRAPH_API_KEY = getpass.getpass("Dgraph Cloud API KEY?")
        os.environ["DGRAPH_API_KEY"] = DGRAPH_API_KEY

    client_stub = pydgraph.DgraphClientStub.from_cloud(
        dgraph_grpc_endpoint,
        APIAdminKey
    )
else:
    client_stub = pydgraph.DgraphClientStub(dgraph_grpc_endpoint)

client = pydgraph.DgraphClient(client_stub)

#
# 3 -  Use pydgraph client to get DQL schema

```

--------------------------------

### Async Client JWT Refresh

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

The async client automatically handles JWT token refresh, ensuring uninterrupted operations even if the token expires during execution. This example shows establishing a connection with credentials.

```python
async with await pydgraph.async_open("dgraph://groot:password@localhost:9080") as client:
    # JWT will be automatically refreshed if it expires during operations
    response = await client.alter(pydgraph.Operation(schema="name: string ."))
```

--------------------------------

### Authenticate and Initialize Dgraph Clients

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-ai-classification.ipynb

Collects user credentials and API keys to initialize Dgraph clients for DQL, GraphQL, and Cloud Admin operations. It also performs an initial login to Dgraph Cloud.

```python
# Cloud credentials
# we need the cloud login credential to upload the Lambda code.
# we need the an Admin API key generated at https://cloud.dgraph.io/_/settings?tab=api-keys for DQL alter and query

dgraph_cloud_user = input("Dgraph Cloud login?")
dgraph_cloud_passw = getpass.getpass("Dgraph Cloud password?")
APIAdminKey = getpass.getpass("API Admin key?")

OpenAIKey = getpass.getpass("Your OpenAI API key?")

# DQL Client
client_stub = pydgraph.DgraphClientStub.from_cloud(dgraph_grpc, APIAdminKey)
client = pydgraph.DgraphClient(client_stub)

# GraphQL client and admin client
gql_client = GraphqlClient(endpoint=dgraph_graphql_endpoint)
headers = {"Dg-Auth": APIAdminKey}
gql_admin_client = GraphqlClient(endpoint=dgraph_graphql_admin, headers=headers)
gql_cloud_client = GraphqlClient(endpoint=dgraph_cerebro)

# Testing all the clients

#
# 1 - Login to Dgraph Cloud
# Need to deploy lambda code

login = """
query  login($email: String!, $passw: String!){
  login(email: $email, password: $passw) {
    token
  }
}
"""
login_var = {"email": dgraph_cloud_user, "passw": dgraph_cloud_passw}
login_info = gql_cloud_client.execute(query=login, variables=login_var)

token = login_info["data"]["login"]["token"]
cerebro_headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + token,
}

print("Dgraph Cloud login succeeded.")
#
# 2 - Use GraphQL Admin to verify cluster health and delete all data including GraphQL schema
#
data = gql_admin_client.execute(query="{health {instance version status}}")
if "errors" in data:
    raise Exception(data["errors"][0]["message"])


print("Check cluster health:", json.dumps(data, indent=2))

#
# 3 -  Use pydgraph client to get DQL schema
#
txn = client.txn()
query = "schema{}"
res = txn.query(query)
dqlschema = json.loads(res.json)
txn.discard()
print("get DQL schema - succeeded")
```

--------------------------------

### Execute a Query using do_request

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

An alternative method to run a query by first creating a request object and then executing it with txn.do_request.

```python
request = txn.create_request(query=query)
txn.do_request(request)
```

--------------------------------

### Create pydgraph Client Instance

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

Initializes a pydgraph client to connect to the Dgraph cluster. It configures the gRPC client stub with a large message length to handle potentially large responses.

```python
# Create a pydgraph client

import pydgraph

client_stub = pydgraph.DgraphClientStub(
    addr=f"{dgraph_hostname}:{dgraph_grpc_port}",
    options=[("grpc.max_receive_message_length", 1024 * 1024 * 1024)],
)
pyd_client = pydgraph.DgraphClient(client_stub)
print("Dgraph Version:", pyd_client.check_version())
```

--------------------------------

### Set Dgraph Schema

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

To set the Dgraph types schema (DQL schema), create a `pydgraph.Operation` object with the schema string and pass it to the `client.alter` method. This example sets a simple 'name' field with an exact index.

```python
schema = 'name: string @index(exact) .'
op = pydgraph.Operation(schema=schema)
client.alter(op)
```

--------------------------------

### Create Alpha Server and Client Certificates

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/tls/README.md

Generate certificates for Dgraph Alpha nodes and client users. Ensure the Alpha server certificate is valid for the specified hostnames.

```bash
docker run -t --volume $PWD/tls:/dgraph-tls dgraph/dgraph:latest dgraph cert --nodes localhost --dir /dgraph-tls
```

```bash
docker run -t --volume $PWD/tls:/dgraph-tls dgraph/dgraph:latest dgraph cert --client user --dir /dgraph-tls
```

--------------------------------

### Perform Recursive DQL Query

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/self_managed_cluster.ipynb

This snippet shows how to perform a recursive DQL query to traverse a graph starting from a list of known records. The `@recurse` directive allows for depth-limited traversal, and specific predicates are returned for each node.

```python
highly_connected_records = [
    "236724",
    "230000018",
    "54662",
    "23000136",
    "240000001",
    "23000147",
    "81027146",
    "23000156",
    "23000330",
    "81027090",
    "23000133",
    "32000236",
    "11001746",
    "81029389",
    "23000213",
    "298333",
    "288469",
    "23000046",
    "23000280",
    "11011863",
    "12160432",
    "96909",
    "11008027",
    "298293",
    "23000381",
    "11001708",
    "285729",
    "11012037",
    "23000198",
    "23000219",
    "294268",
    "230000057",
    "49684",
    "23000362",
    "23000228",
    "11007372",
    "230000005",
    "80000191",
    "11009351",
    "23000400",
    "23000235",
    "23000406",
    "23000162",
    "23000365",
    "80011301",
    "23000281",
    "80011987",
    "58007938",
    "88002083",
    "11011539",
    "264051",
    "298258",
    "240230001",
    "297687",
    "230000038",
    "24000074",
    "20642",
    "230000007",
    "11010643",
    "23000222",
    "58922",
    "81027087",
    "279944",
    "23000377",
    "240360001",
    "298170",
    "24883",
    "11012290",
    "11009218",
    "23000130",
    "43724",
    "225000056",
    "11009139",
    "298147",
    "237148",
    "23000396",
    "230000054",
    "237076",
    "237583",
    "23000146",
    "11006103",
    "230000021",
    "11012118",
    "120001922",
    "230000066",
    "236748",
    "23000131",
    "295141",
    "298166",
    "230000025",
    "230000020",
    "11000489",
    "23000204",
    "23000260",
    "11012146",
    "56917",
    "11011469",
    "271169",
    "236832",
    "81001128",
    "33000151",
    "81073055",
    "11010502",
    "75595",
    "32000238",
    "240110001",
    "23000256",
    "23000001",
    "32000226",
    "23000237",
    "11014056",
    "56072048",
    "50622",
    "23000437",
    "23000307",
    "32000235",
    "24000031",
    "14025646",
    "263908",
    "11010460",
    "23000145",
    "230000070",
    "260937",
    "23000360",
    "23000166",
    "271677",
    "58009618",
    "297689",
    "263996",
    "14026068",
    "230000004",
    "230000016",
    "23000161",
    "23000157",
    "298020",
    "297596",
    "11003948",
    "230000017",
    "58044817",
    "23000141",
    "230000003",
    "290240",
    "58034506",
    "81038065",
    "88007148",
    "82019954",
    "23000343",
    "56072081",
    "80051573",
    "80086304",
]

recurse_query = """
{
    q(func: eq(Record.nodeID, {LIST})) @recurse(depth: 8) {
        # predicates to return for each recurse
        id: Record.nodeID
        name: Record.name
        type: <dgraph.type>
        # predicates to loop through
        hasaddress: Record.hasAddress
        addressFor: RecordRecord.addressFor
        hasOfficer: Record.hasOfficer
        officerFor: Record.officerFor
        hasIntermediary: Record.hasIntermediary
        intermediaryFor: Record.intermediaryFor
        connectedTo: RecordRecord.connectedTo  
  }
}
"""

recurse_query = recurse_query.replace("{LIST}", json.dumps(highly_connected_records))
res = pyd_client.txn(read_only=True).query(recurse_query)
data = json.loads(res.json)
```

--------------------------------

### Generate Protocol Buffers with uv

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

An alternative method to regenerate protobuf files using uv to run the generation script directly.

```sh
uv run python scripts/protogen.py
```

--------------------------------

### Define Text to Intent Function

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This function takes a user prompt and an LLM model name, then uses the LLM to generate a JSON object representing the extracted intent. It requires a system prompt to guide the LLM's response format.

```python
def text_to_intent(prompt, model="gpt-4o-mini"):
    completion = llm.chat.completions.create(
        model=model,
        temperature=0,
        response_format={"type": "json_object"},
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": prompt},
        ],
    )
    intent = json.loads(completion.choices[0].message.content)
    intent["prompt"] = prompt
    return intent
```

--------------------------------

### Async Client with Context Managers

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Use async context managers for automatic cleanup of the client and transactions. The client is automatically closed and transactions are discarded upon exiting the `async with` block.

```python
import asyncio
import pydgraph

async def main():
    # Client auto-closes on exit
    async with await pydgraph.async_open("dgraph://localhost:9080") as client:
        await client.login("groot", "password")

        # Transaction auto-discards on exit
        async with client.txn() as txn:
            response = await txn.query('{ me(func: has(name)) { name } }')
            print(response.json)

asyncio.run(main())
```

--------------------------------

### Run Stress Tests (Moderate Mode)

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Execute stress tests in moderate mode, which includes the movie dataset and runs for a longer duration than quick mode.

```sh
make test STRESS_TEST_MODE=moderate PYTEST_ARGS="tests/test_stress_sync.py tests/test_stress_async.py -v"
```

--------------------------------

### Generate Ontology Prompt for LLM

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

This Python function `ontologyPrompt` takes an ontology definition and creates a textual description. This description helps an LLM understand the entities and predicates available in the graph database for more accurate prompt analysis.

```python
def ontologyPrompt(ontology):
    # Create a textual description of the ontology to help prompting LLM
    # The graph database has the following entities and predicates:
    entities = [f"'{e['entity_name']}'" for e in ontology]
    list_entities = ", ".join(entities)
    s = f"Identify if the user question is about one of the entities {list_entities}."
    s += "\nIdentify criteria about predicates depending on the entity."
    for e in ontology:
        pred = [f"'{p}'" for p in e["predicates"]]
        pred_list = ", ".join(pred)
        s += f"\nFor '{e['entity_name']}' look for:"
        for p in e["predicates"]:
            s += f"\n- '{p}': {e['predicates'][p]['description']}"
    return s
```

--------------------------------

### Run Specific Tests

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Execute a specific test file or test case by providing arguments to make test.

```sh
make test PYTEST_ARGS="-v tests/test_connect.py::TestOpen"
```

```sh
make test PYTEST_ARGS="-v tests/test_connect.py::TestOpen::test_connection_with_auth"
```

--------------------------------

### Run an Upsert Block (Query + Mutation)

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Perform a query and mutation within a single request using txn.do_request. Variables from the query can be referenced in mutations using DQL functions like uid() and val().

```python
query = """{
  u as var(func: eq(name, "Alice"))
}"""

nquad = """
  uid(u) <name> "Alice" .
  uid(u) <age> "25" .
"""

mutation = txn.create_mutation(set_nquads=nquad)
request = txn.create_request(query=query, mutations=[mutation], commit_now=True)
txn.do_request(request)
```

--------------------------------

### Set Timeout for Client Operations

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Illustrates setting a timeout in seconds for `login`, `alter`, `query`, and `mutate` methods using the `timeout` keyword argument.

```python
dg.alter(op, timeout=10)
```

--------------------------------

### Upload to TestPyPI

Source: https://github.com/dgraph-io/pydgraph/blob/main/PUBLISHING.md

Perform a test upload of the distribution files to the TestPyPI repository. This step requires access to the TestPyPI token and is used to verify that the readme and metadata appear correctly.

```shell
twine upload --repository testpypi dist/*
```

--------------------------------

### Import Libraries and Load Environment Variables

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/RAG_with_Dgraph.ipynb

Imports essential Python libraries for Dgraph, OpenAI, sentence transformers, and environment variable management. It also asserts that the OPENAI_API_KEY is set in the .env file.

```python
import os
import json
import pydgraph
from pybars import Compiler

# Activate the provider you want to use for embeddings and LLM
# from openai import OpenAI
# from mistralai.client import MistralClient

from sentence_transformers import SentenceTransformer
from dotenv import load_dotenv

load_dotenv()

assert os.getenv("OPENAI_API_KEY") is not None, "Set OPENAI_API_KEY in your .env file"
```

--------------------------------

### Set Metadata Headers for Operations

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Shows how to set metadata, such as authentication tokens, for gRPC methods. The `metadata` argument accepts a list of key-value pairs.

```python
# The following piece of code shows how one can set metadata with
# auth-token, to allow Alter operation, if the server requires it.
# metadata is a list of arbitrary key-value pairs.
metadata = [("auth-token", "the-auth-token-value")]
dg.alter(op, metadata=metadata)
```

--------------------------------

### Generate Protobufs

Source: https://github.com/dgraph-io/pydgraph/blob/main/PUBLISHING.md

Regenerate protobufs using the 'protogen' make target. This command requires Python 3.13+ as specified in the .python-version file.

```shell
make protogen
```

--------------------------------

### Run Local Checks and Tests

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Execute all project checks and tests locally to ensure code quality and functionality before submitting a pull request. This command must succeed.

```sh
make check test
```

--------------------------------

### Create a Best-Effort Read-Only Transaction

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Create a read-only transaction with best-effort queries using `client.txn(read_only=True, best_effort=True)`. These queries are faster as they bypass consensus but may not return the latest data. Best-effort queries are only supported in read-only transactions.

```python
txn = client.txn(read_only=True, best_effort=True)
try:
  # Do some queries here
  # ...
finally:
  txn.discard()
  # ...
```

--------------------------------

### Create a Standard Transaction

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Create a new transaction object using `client.txn()`. It is recommended to call `txn.discard()` in a `finally` block to ensure proper cleanup, even after a commit.

```python
txn = client.txn()
try:
  # Do something here
  # ...
finally:
  txn.discard()
  # ...
```

--------------------------------

### Query Projects and their Categories with GraphQL

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-episode1.ipynb

Retrieve projects and their associated categories using a GraphQL query. This verifies the relationships established after project creation.

```graphql
query queryProjects {
    queryProject(first:100) {
        id title
        category {
            name
        }
    }
}

```

```python
data = gql_client.execute(query=queryProjects)

print(json.dumps(data["data"]["queryProject"], indent=2))
```

--------------------------------

### Execute GraphQL Query with pydgraph

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-episode1.ipynb

This snippet demonstrates how to execute a GraphQL query using the pydgraph client to search for deployments. It formats a query string and prints the JSON response.

```python
query = """
query {{
    searchDeployments(inputType: endpoint, searchText: \"{0}\") {{
        subdomain
        name
        uid
    }}
}}
""".format(dgraph_graphql_endpoint)

deployment_info = gql_cloud_client.execute(query=query, headers=cerebro_headers)
print(json.dumps(deployment_info, indent=2))
deploymentID = deployment_info["data"]["searchDeployments"][0]["uid"]

print("DeploymentID: " + deploymentID)
```

--------------------------------

### Execute GraphQL Query with pydgraph

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/dgraph-ai-classification.ipynb

This Python snippet demonstrates how to execute a GraphQL query using the pydgraph client to search for deployments. It formats a query string and prints the JSON response.

```python
query = """
query {{
    searchDeployments(inputType: endpoint, searchText: "{0}") {{
        subdomain
        name
        uid
    }}
}}
""".format(dgraph_graphql_endpoint)

deployment_info = gql_cloud_client.execute(query=query, headers=cerebro_headers)
print(json.dumps(deployment_info, indent=2))
deploymentID = deployment_info["data"]["searchDeployments"][0]["uid"]

print("DeploymentID: " + deploymentID)
```

--------------------------------

### Load JSON and Write RDF File

Source: https://github.com/dgraph-io/pydgraph/blob/main/examples/notebook/RAG/generateRDF.ipynb

Loads a JSON dataset from a specified file path and writes the converted RDF data to an output file. This script orchestrates the data loading and conversion process.

```python
# Loading a json dataset from a file
file_path = "data/amazon_product_kg.json"
output_path = "data/products.rdf"
df = pd.read_json(file_path)
with open(output_path, "w") as filehandle:
    filehandle.write("\n".join(toRDF(df)))
```

--------------------------------

### Handle Async Operations with Futures

Source: https://github.com/dgraph-io/pydgraph/blob/main/README.md

Demonstrates using asynchronous methods like `async_alter`, `async_query`, and `async_mutate` which return futures. The `handle_alter_future`, `handle_query_future`, and `handle_mutate_future` static methods can be used to process these futures and handle exceptions.

```python
alter_future = self.client.async_alter(pydgraph.Operation(schema="name: string @index(term) ."))
response = pydgraph.DgraphClient.handle_alter_future(alter_future)
```

```python
txn = client.txn()
query = "query body here"
future = txn.async_query()
response = pydgraph.Txn.handle_query_future(future)
```

```python
client = DgraphClient(client_stubs) # client_stubs is a list of gRPC stubs.
alter_future = client.async_alter()
try:
    response = alter_future.result()
except Exception as e:
  # You can use this function in the util package to check for JWT
    # expired errors.
    if pydgraph.util.is_jwt_expired(e):
        # retry your request here.
```

--------------------------------

### Run Stress Tests (Full Mode)

Source: https://github.com/dgraph-io/pydgraph/blob/main/CONTRIBUTING.md

Execute stress tests in full mode for maximum stress testing, involving a large number of workers, operations, and iterations.

```sh
make test STRESS_TEST_MODE=full PYTEST_ARGS="tests/test_stress_sync.py tests/test_stress_async.py -v"
```