Initial commit: FastGPT Python SDK Phase 1

Implement core infrastructure: - BaseClientMixin with retry logic and validation - FastGPTClient base class with httpx - ChatClient with 11 chat operation methods - AppClient for analytics and logs - Custom exceptions (APIError, AuthenticationError, etc.) - Package configuration (pyproject.toml, setup.py) - Documentation (README.md, CLAUDE.md) - Basic usage examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-06 14:38:32 +08:00
commit 0495dd4676
11 changed files with 1332 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,183 @@
+# 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)