H2O GPTe Python Client

Warnings

• breaking Specific versions of other h2oGPTe ecosystem components (e.g., h2oGPTe GitHub Action) may have strict compatibility requirements with particular client library versions. For instance, h2oGPTe Action v0.2.2-beta requires h2oGPTe versions 1.6.31 through 1.6.47.
  Fix: Always consult the documentation for other H2O.ai tools and integrations to ensure you are using a compatible version of the `h2ogpte` client library.
• gotcha There are two types of API keys: Global API keys and Collection-specific API keys. Global API keys grant full user impersonation and system-wide access, allowing creation, deletion, and interaction with all collections, documents, and chats. Collection-specific keys are restricted to chatting with the specified collection only. Misusing a global API key when only collection-level access is intended can pose a significant security risk.
  Fix: Always use the principle of least privilege. Generate and use collection-specific API keys for integrations that only need access to a particular collection. Only use global API keys for applications requiring full administrative access.
• gotcha The `H2OGPTE` client requires a valid `address` (URL of your h2oGPTe instance) and `api_key` for connection. Incorrect values, network issues, or firewall restrictions preventing access to the h2oGPTe server are common sources of connection errors.
  Fix: Double-check the `H2OGPTE_ADDRESS` and `H2OGPTE_API_KEY` values. Ensure your environment has network access to the h2oGPTe instance and no firewalls are blocking the connection. Consult h2oGPTe server documentation for deployment-specific troubleshooting.
• gotcha When interacting with underlying Large Language Models (LLMs) through h2oGPTe, some LLM-specific parameters (e.g., `system_prompt`, `temperature`, `max_tokens`) might not behave as expected or might have fixed defaults if the underlying LLM backend (like oLLaMa in h2oGPT OSS) does not support runtime parameter changes. This can lead to unexpected model responses if the user assumes full control over all LLM hyperparameters via the client.
  Fix: Understand the capabilities and configurations of the LLMs deployed on your h2oGPTe instance. Consult the h2oGPTe server documentation or an administrator regarding LLM-specific parameter control and any hardcoded defaults.

Install

• pip install h2ogpte Install latest version

Imports

• H2OGPTE

  from h2ogpte import H2OGPTE

Quickstart

This quickstart demonstrates how to connect to an h2oGPTe instance, create a collection, upload a document, create a chat session, and query the collection using the Python client. Ensure you have your h2oGPTe instance address and a valid API key set as environment variables or replaced in the code.

import os
from h2ogpte import H2OGPTE

# Replace with your h2oGPTe instance address and API key
# It's recommended to use environment variables for sensitive information
H2OGPTE_ADDRESS = os.environ.get('H2OGPTE_ADDRESS', 'https://your-h2ogpte-instance.h2o.ai')
H2OGPTE_API_KEY = os.environ.get('H2OGPTE_API_KEY', 'sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')

client = H2OGPTE(address=H2OGPTE_ADDRESS, api_key=H2OGPTE_API_KEY)

try:
    # Create a new collection
    collection_id = client.create_collection(
        name='My Contracts',
        description='Paper clip supply contracts and related documents',
    )
    print(f"Collection created with ID: {collection_id}")

    # Example: Upload a dummy document (in a real scenario, this would be a file)
    dummy_content = "There were 55 paper clips shipped, 22 to Scranton and 33 to Filmer."
    with open('paper_clips_report.txt', 'w') as f:
        f.write(dummy_content)

    client.sync_folder(collection_id=collection_id, folder_path='.')
    print("Dummy document uploaded and synchronized.")

    # Create a chat session with the collection
    chat_session_id = client.create_chat_session(collection_id=collection_id)
    print(f"Chat session created with ID: {chat_session_id}")

    # Query the collection
    with client.connect(chat_session_id) as session:
        response = session.query(
            'How many paper clips were shipped to Scranton?',
            timeout=60,
        )
        print(f"Response: {response.content}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up (optional) - delete the dummy file and collection
    if 'paper_clips_report.txt' in os.listdir('.'):
        os.remove('paper_clips_report.txt')
    # In a real application, you might also delete the collection and chat session
    # client.delete_collection(collection_id=collection_id)
    # client.delete_chat_session(chat_session_id=chat_session_id)