# Python

## 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:

```bash
pip install chaingpt
```

Or add to your `requirements.txt`:

```bash
chaingpt>=1.1.3
```

### Quick Start

#### Basic Client Initialization

```python
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)**

```python
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)**

```python
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

```python
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

```python
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:

```python
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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chaingpt.org/dev-docs-b2b-saas-api-and-sdk/web3-ai-chatbot-and-llm-api-and-sdk/python.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.