Python

CGPT SDK Docs

AI Chatbot & LLM SDK Documentation

The ChainGPT AI Chatbot & LLM feature allows you to integrate powerful conversational AI capabilities into your applications. You can send prompts, manage chat history, and customize the AI's responses using context injection.

Table of Contents

  1. Installation

  2. Quick Start

  3. ChainGPTClient Parameters

  4. LLM Service

    • LLMChatRequestModel Parameters

    • Basic LLM Usage

      • Buffered Chat (Complete Response)

      • Streaming Chat (Real-time Response)

  5. Context Injection

    • ContextInjectionModel Parameters

    • TokenInformationModel Parameters

    • SocialMediaUrlModel Parameters

    • Context Injection Example

  6. Enums and Constants

    • ChatHistoryMode

    • AITone Options

    • PresetTone Options

    • Supported Blockchain Networks

  7. Error Handling

    • Exception Types

    • Error Handling Example

  8. Complete Example

  9. Best Practices


Installation

Install via pip:

pip install chaingpt

Or add to your requirements.txt:

chaingpt>=1.1.3

Quick Start

Basic Client Initialization

client = ChainGPTClient(api_key=API_KEY)

# Always remember to close the client
await client.close()

# Or use as context manager (recommended)
async with ChainGPTClient(api_key=API_KEY) as client:
    # Your code here
    pass

ChainGPTClient Parameters

Parameter
Type
Default
Description

api_key

str

Required

Your ChainGPT API key

base_url

str

"https://api.chaingpt.org"

The base URL for the ChainGPT API

timeout

HTTPTimeout

DEFAULT_TIMEOUT

Default timeout for regular requests (seconds)

stream_timeout

HTTPTimeout

DEFAULT_STREAM_TIMEOUT

Default timeout for streaming requests (seconds)

LLM Service

The LLM service provides both buffered (complete response) and streaming chat capabilities.

LLMChatRequestModel Parameters

Parameter
Type
Default
Description

model

str

"general_assistant"

Model ID to use (currently only "general_assistant" supported)

question

str

Required

User's question or prompt (1-10,000 characters)

chat_history

ChatHistoryMode

ChatHistoryMode.OFF

Enable/disable chat history (ON or OFF)

sdk_unique_id

str

None

Unique session identifier (1-100 characters)

use_custom_context

bool

False

Whether to use custom context injection

context_injection

ContextInjectionModel

None

Custom context data (required if use_custom_context=True)

Basic LLM Usage

Buffered Chat (Complete Response)

from chaingpt.models import LLMChatRequestModel
from chaingpt.types import ChatHistoryMode

async def buffered_chat_example():
    client = ChainGPTClient(api_key=API_KEY)
    try:
        request = LLMChatRequestModel(
            question="What is blockchain technology?",
            chatHistory=ChatHistoryMode.OFF
        )
        response = await client.llm.chat(request)
        print(response.data.bot)
    finally:
        await client.close()

Streaming Chat (Real-time Response)

async def streaming_chat_example():
    client = ChainGPTClient(api_key=API_KEY)
    try:
        request = LLMChatRequestModel(
            question="Explain smart contracts in detail",
            chatHistory=ChatHistoryMode.ON,
            sdkUniqueId="unique-session-123"
        )
        
        print("AI Response:")
        async for chunk in client.llm.stream_chat(request):
            print(chunk.decode("utf-8"), end="", flush=True)
        print("\n--- Stream ended ---")
    finally:
        await client.close()

Context Injection

Context injection allows you to customize the AI's responses with specific company, project, or token information.

ContextInjectionModel Parameters

Parameter
Type
Default
Description

company_name

str

None

Company or project name

company_description

str

None

Brief description of the company/project

company_website_url

HttpUrl

None

Company website URL

white_paper_url

HttpUrl

None

Whitepaper URL

purpose

str

None

Purpose or role of the AI chatbot

crypto_token

bool

None

Whether the project has a crypto token

token_information

TokenInformationModel

None

Token details (required if crypto_token=True)

social_media_urls

List[SocialMediaUrlModel]

None

Social media URLs

limitation

bool

None

Content limitation flag

ai_tone

AITone

None

AI tone setting

selected_tone

PresetTone

None

Selected preset tone (required if ai_tone=PRE_SET_TONE)

custom_tone

str

None

Custom tone description (required if ai_tone=CUSTOM_TONE)

TokenInformationModel Parameters

Parameter
Type
Default
Description

token_name

str

None

Name of the token

token_symbol

str

None

Token symbol/ticker

token_address

str

None

Token contract address

token_source_code

str

None

Token source code or repository URL

token_audit_url

HttpUrl

None

URL to token audit report

explorer_url

HttpUrl

None

Block explorer URL for the token

cmc_url

HttpUrl

None

CoinMarketCap URL

coingecko_url

HttpUrl

None

CoinGecko URL

blockchain

List[BlockchainNetwork]

None

List of supported blockchain networks

SocialMediaUrlModel Parameters

Parameter
Type
Default
Description

name

str

Required

Name of the social media platform

url

HttpUrl

Required

URL to the social media profile

Context Injection Example

from chaingpt.models import (
    LLMChatRequestModel, 
    ContextInjectionModel, 
    TokenInformationModel, 
    SocialMediaUrlModel
)
from chaingpt.types import AITone, PresetTone, BlockchainNetwork

async def context_injection_example():
    client = ChainGPTClient(api_key=API_KEY)
    try:
        # Define token information
        token_info = TokenInformationModel(
            tokenName="MyAwesomeToken",
            tokenSymbol="MAT",
            blockchain=[BlockchainNetwork.ETHEREUM, BlockchainNetwork.POLYGON]
        )
        
        # Define social media
        social_media = [
            SocialMediaUrlModel(
                name="twitter", 
                url="https://twitter.com/myawesometoken"
            ),
            SocialMediaUrlModel(
                name="telegram", 
                url="https://t.me/myawesometoken"
            )
        ]
        
        # Create context injection
        context = ContextInjectionModel(
            companyName="Awesome Crypto Inc.",
            companyDescription="Leading DeFi protocol for yield farming",
            cryptoToken=True,
            tokenInformation=token_info,
            socialMediaUrls=social_media,
            aiTone=AITone.PRE_SET_TONE,
            selectedTone=PresetTone.PROFESSIONAL
        )
        
        # Make request with context
        request = LLMChatRequestModel(
            question="Tell me about our token and its utilities",
            useCustomContext=True,
            contextInjection=context,
            sdkUniqueId="context-session-456"
        )
        
        response = await client.llm.chat(request)
        print(response.data.bot)
    finally:
        await client.close()

Enums and Constants

ChatHistoryMode

  • ChatHistoryMode.ON: Enable chat history

  • ChatHistoryMode.OFF: Disable chat history

AITone Options

  • AITone.DEFAULT_TONE: Use default AI tone

  • AITone.CUSTOM_TONE: Use custom tone (requires custom_tone parameter)

  • AITone.PRE_SET_TONE: Use preset tone (requires selected_tone parameter)

PresetTone Options

Tone
Description

PROFESSIONAL

Professional business tone

FRIENDLY

Casual and friendly tone

INFORMATIVE

Educational and detailed tone

FORMAL

Formal and structured tone

CONVERSATIONAL

Natural conversation tone

AUTHORITATIVE

Expert and confident tone

PLAYFUL

Light and entertaining tone

INSPIRATIONAL

Motivational and uplifting tone

CONCISE

Brief and to-the-point tone

EMPATHETIC

Understanding and caring tone

ACADEMIC

Scholarly and research-focused tone

NEUTRAL

Balanced and objective tone

SARCASTIC_MEME_STYLE

Humorous and meme-like tone

Supported Blockchain Networks

Network
Value

Ethereum

ETHEREUM

Binance Smart Chain

BSC

Arbitrum

ARBITRUM

Base

BASE

Blast

BLAST

Avalanche

AVALANCHE

Polygon

POLYGON

Scroll

SCROLL

Optimism

OPTIMISM

Linea

LINEA

zkSync

ZKSYNC

Polygon zkEVM

POLYGON_ZKEVM

Gnosis

GNOSIS

Fantom

FANTOM

Moonriver

MOONRIVER

Moonbeam

MOONBEAM

Boba

BOBA

Metis

METIS

Lisk

LISK

Aurora

AURORA

Sei

SEI

Immutable zkEVM

IMMUTABLE_ZK

Gravity

GRAVITY

Taiko

TAIKO

Cronos

CRONOS

Fraxtal

FRAXTAL

Abstract

ABSTRACT

World Chain

WORLD_CHAIN

Mantle

MANTLE

Mode

MODE

Celo

CELO

Berachain

BERACHAIN

Error Handling

The SDK provides comprehensive error handling with specific exception types:

Exception Types

Exception
Description
When Raised

ChainGPTError

Base exception for all SDK errors

General SDK errors

APIError

API returned an error response

API-specific errors

AuthenticationError

Authentication failed (401)

Invalid API key

ValidationError

Request validation failed (400)

Invalid request parameters

InsufficientCreditsError

Account has insufficient credits (402/403)

No credits remaining

RateLimitError

Rate limit exceeded (429)

Too many requests

NotFoundError

Endpoint not found (404)

Invalid endpoint

ServerError

Server error (5xx)

API server issues

TimeoutError

Request timed out

Network timeout

StreamingError

Streaming encountered an error

Streaming-specific issues

ConfigurationError

SDK configuration is invalid

Invalid configuration

Error Handling Example

from chaingpt.exceptions import (
    ChainGPTError, 
    AuthenticationError, 
    ValidationError,
    RateLimitError
)

async def error_handling_example():
    client = ChainGPTClient(api_key=API_KEY)
    try:
        request = LLMChatRequestModel(
            question="What is DeFi?",
            chatHistory=ChatHistoryMode.OFF
        )
        response = await client.llm.chat(request)
        print(response.data.bot)
        
    except AuthenticationError:
        print("Authentication failed. Please check your API key.")
    except ValidationError as e:
        print(f"Validation error: {e.message}")
        if e.field:
            print(f"Field: {e.field}")
    except RateLimitError as e:
        print(f"Rate limit exceeded: {e.message}")
        if e.retry_after:
            print(f"Retry after: {e.retry_after} seconds")
    except ChainGPTError as e:
        print(f"ChainGPT error: {e.message}")
        if e.details:
            print(f"Details: {e.details}")
    except Exception as e:
        print(f"Unexpected error: {e}")
    finally:
        await client.close()

Complete Example

Here's a comprehensive example demonstrating various features:

import asyncio
import os
from chaingpt.client import ChainGPTClient
from chaingpt.models import (
    LLMChatRequestModel,
    ContextInjectionModel,
    TokenInformationModel,
    SocialMediaUrlModel,
)
from chaingpt.types import AITone, PresetTone, ChatHistoryMode, BlockchainNetwork
from chaingpt.exceptions import ChainGPTError

async def comprehensive_example():
    API_KEY = os.getenv("CHAINGPT_API_KEY")
    
    if not API_KEY:
        print("Please set your CHAINGPT_API_KEY environment variable")
        return
    
    async with ChainGPTClient(api_key=API_KEY) as client:
        try:
            # Example 1: Simple chat
            print("=== Simple Chat ===")
            simple_request = LLMChatRequestModel(
                question="Explain blockchain in simple terms"
            )
            response = await client.llm.chat(simple_request)
            print(response.data.bot)
            
            # Example 2: Chat with context injection
            print("\n=== Chat with Context ===")
            token_info = TokenInformationModel(
                tokenName="DemoToken",
                tokenSymbol="DEMO",
                blockchain=[BlockchainNetwork.ETHEREUM]
            )
            
            context = ContextInjectionModel(
                companyName="Demo Company",
                companyDescription="Blockchain innovation company",
                cryptoToken=True,
                tokenInformation=token_info,
                aiTone=AITone.PRE_SET_TONE,
                selectedTone=PresetTone.PROFESSIONAL
            )
            
            context_request = LLMChatRequestModel(
                question="What can you tell me about our company?",
                useCustomContext=True,
                contextInjection=context,
                chatHistory=ChatHistoryMode.ON,
                sdkUniqueId="demo-session-123"
            )
            
            response = await client.llm.chat(context_request)
            print(response.data.bot)
            
            # Example 3: Streaming chat
            print("\n=== Streaming Chat ===")
            stream_request = LLMChatRequestModel(
                question="Tell me about DeFi protocols",
                chatHistory=ChatHistoryMode.ON,
                sdkUniqueId="demo-session-123"  # Continue same session
            )
            
            print("Streaming response:")
            async for chunk in client.llm.stream_chat(stream_request):
                print(chunk.decode("utf-8"), end="", flush=True)
            print("\n--- Stream complete ---")
            
        except ChainGPTError as e:
            print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(comprehensive_example())

Best Practices

  1. Always use context managers or remember to call close() to properly clean up resources

  2. Handle exceptions appropriately - use specific exception types for better error handling

  3. Use unique session IDs when maintaining chat history across multiple requests

  4. Validate context injection - ensure required fields are provided when using custom context

  5. Consider rate limits - implement retry logic with exponential backoff for production use

  6. Use streaming for long responses - better user experience for lengthy AI responses

  7. Store API keys securely - use environment variables, not hardcoded values

This concludes the documentation for the AI Chatbot & LLM feature!

Last updated

Was this helpful?