fastgpt-python-sdk/README.md

# FastGPT Python SDK

Python SDK for FastGPT OpenAPI.

## Installation

```bash
pip install fastgpt-client
```

## Quick Start

### Basic Chat Completion

```python
from fastgpt_client import ChatClient

# Initialize client
with ChatClient(api_key="fastgpt-xxxxx", base_url="http://localhost:3000") as client:
    # Send a message
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Hello!"}],
        stream=False
    )
    response.raise_for_status()
    result = response.json()
    print(result['choices'][0]['message']['content'])
```

### Streaming Chat

```python
import json

with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Tell me a story"}],
        stream=True
    )

    for line in response.iter_lines():
        if line.startswith("data:"):
            data = line[5:].strip()
            if data and data != "[DONE]":
                chunk = json.loads(data)
                if "choices" in chunk and chunk["choices"]:
                    delta = chunk["choices"][0].get("delta", {})
                    content = delta.get("content", "")
                    if content:
                        print(content, end="", flush=True)
```

### Chat with Context (chatId)

```python
with ChatClient(api_key="fastgpt-xxxxx") as client:
    # First message
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "What's AI?"}],
        chatId="my_conversation_123",
        stream=False
    )

    # Second message (continues the conversation)
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Tell me more"}],
        chatId="my_conversation_123",  # Same chatId
        stream=False
    )
```

### Using Variables

```python
with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Hello [name]!"}],
        variables={"name": "Alice"},  # Replaces [name] placeholder
        stream=False
    )
```

### Get Chat Histories

```python
with ChatClient(api_key="fastgpt-xxxxx") as client:
    histories = client.get_chat_histories(
        appId="your-app-id",
        offset=0,
        pageSize=20,
        source="api"
    )
    histories.raise_for_status()
    data = histories.json()
    for chat in data['data']['list']:
        print(f"{chat['title']}: {chat['chatId']}")
```

### Send Feedback

```python
with ChatClient(api_key="fastgpt-xxxxx") as client:
    # Like a message
    client.send_feedback(
        appId="app-123",
        chatId="chat-123",
        dataId="msg-123",
        userGoodFeedback="Great answer!"
    )

    # Dislike a message
    client.send_feedback(
        appId="app-123",
        chatId="chat-123",
        dataId="msg-123",
        userBadFeedback="Not helpful"
    )
```

### App Analytics

```python
from fastgpt_client import AppClient

with AppClient(api_key="fastgpt-xxxxx") as client:
    logs = client.get_app_logs_chart(
        appId="your-app-id",
        dateStart="2024-01-01T00:00:00.000Z",
        dateEnd="2024-12-31T23:59:59.999Z",
        source=["api", "online"]
    )
    logs.raise_for_status()
    print(logs.json())
```

## API Reference

### ChatClient

| Method | Description |
|--------|-------------|
| `create_chat_completion()` | Create chat completion (blocking/streaming) |
| `get_chat_histories()` | List chat histories for an app |
| `get_chat_init()` | Get chat initialization info |
| `get_chat_records()` | Get messages for a chat |
| `get_record_detail()` | Get execution details |
| `update_chat_history()` | Update title or pin status |
| `delete_chat_history()` | Delete a chat |
| `clear_chat_histories()` | Clear all chats |
| `delete_chat_record()` | Delete single record |
| `send_feedback()` | Like/dislike a message |
| `get_suggested_questions()` | Get suggested questions |

### AppClient

| Method | Description |
|--------|-------------|
| `get_app_logs_chart()` | Get app analytics data |

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check fastgpt_client/

# Format
ruff format fastgpt_client/
```

## License

MIT

## Links

- [FastGPT Documentation](https://doc.fastgpt.io/)
- [Chat API Documentation](https://doc.fastgpt.io/docs/introduction/development/openapi/chat)