# TBox SDK Python

[![Python Version](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.0.10-orange.svg)](https://pypi.org/project/tboxsdk/)

English | [中文](README_CN.md)

TBox SDK is an open SDK tool for the TBox platform. It allows you to quickly integrate TBox's intelligent agent conversation and generation, knowledge base management, RAG, plugin invocation, and other capabilities into your code. This project is the Python version of TBox SDK.

## ✨ Key Features

- 🤖 **Intelligent Agent Chat** - Support for both streaming and non-streaming conversations, easy integration of AI chat capabilities
- 📚 **Knowledge Base Management** - Complete CRUD operations for knowledge bases with document upload and management
- 🔍 **RAG Retrieval** - Powerful Retrieval-Augmented Generation capabilities to improve AI response quality
- 🔌 **Plugin Invocation** - Rich official plugin ecosystem to extend AI capabilities
- 💬 **Conversation Management** - Complete conversation lifecycle management
- 📁 **File Processing** - Support for uploading and processing multiple file formats

## 🚀 Quick Start

### Installation

```bash
pip install tboxsdk
```

### Basic Usage

```python
from tboxsdk import TboxClient

# Initialize client
client = TboxClient(authorization="your_auth_token_here")

# Intelligent agent chat
response = client.chat(
    app_id="your_app_id",
    query="Hello, please introduce Python programming",
    user_id="user123"
)

print(response)
```

## 📖 Detailed Documentation

### Intelligent Agent Chat

Support for both streaming and non-streaming conversation modes:

```python
# Streaming chat
for chunk in client.chat_stream(
    app_id="your_app_id",
    query="Please write a Python function",
    user_id="user123"
):
    print(chunk, end="")

# Non-streaming chat
response = client.chat(
    app_id="your_app_id", 
    query="Please explain machine learning",
    user_id="user123",
    stream=False
)
```

### Knowledge Base Management

```python
# Create knowledge base
result = client.create_datasets(
    name="Python Knowledge Base",
    description="Contains Python programming related documents"
)

# Query knowledge base list
datasets = client.list_datasets()

# Upload document to knowledge base
file_result = client.upload_file(
    file_path="document.pdf",
    dataset_id="your_dataset_id"
)

# Delete knowledge base
client.delete_dataset(dataset_id="your_dataset_id")
```

### Plugin Invocation

```python
# Get official plugin list
plugins = client.get_official_plugins()

# Invoke plugin
result = client.invoke_plugin(
    plugin_tool_id="plugin_tool_id",
    params={"query": "search content"}
)
```

### Conversation Management

```python
# Create conversation
conversation = client.create_conversation(
    app_id="your_app_id",
    user_id="user123"
)

# Query conversation list
conversations = client.get_conversations(
    app_id="your_app_id",
    user_id="user123"
)

# Get conversation messages
messages = client.get_messages(
    conversation_id="conversation_id"
)
```

## 📁 Project Structure

```
tboxsdk/
├── core/           # Core modules
│   ├── httpclient.py    # HTTP client
│   └── exception.py     # Exception handling
├── model/          # Data models
│   ├── conversation.py  # Conversation model
│   ├── file.py         # File model
│   └── message.py      # Message model
└── tbox.py         # Main client class
```

## 📚 Example Code

The project provides rich example code in the `examples/` directory:

- `conversations_example.py` - Conversation management examples
- `datasets_basic_example.py` - Knowledge base basic operations
- `datasets_documents_example.py` - Document management examples
- `messages_example.py` - Message processing examples
- `plugins_example.py` - Plugin invocation examples

Run examples:

```bash
python examples/conversations_example.py
```

## 🛠️ Development Environment

- Python 3.6+
- httpx
- sseclient-py

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Issues and Pull Requests are welcome to help improve the project.

## 🔗 Related Links

- [TBox Platform](https://tbox.cn)
- [API Documentation](https://alipaytbox.yuque.com/sxs0ba/doc/tbox_open_overview)
- [Changelog](CHANGES.md)