From b7e9ed90be1c6bbb0c7e5700be0a0ecf6d8482c3 Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Fri, 30 Jan 2026 09:44:01 +0800 Subject: [PATCH] move CLAUDE.md --- CLAUDE.md | 194 ------------------------------------------------------ 1 file changed, 194 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 1bb9c40..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,194 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -This is the **FastGPT Python SDK**, a Python client library for interacting with FastGPT's OpenAPI. The SDK is designed following the architecture patterns from the [Dify Python SDK](https://github.com/langgenius/dify-python-sdk), adapted for FastGPT's API structure. - -### Key Design Principles - -1. **Base Client + Specialized Clients**: A `FastGPTClient` base class handles HTTP communication, retry logic, error handling, and validation. Specialized clients (`ChatClient`, `AppClient`) inherit from it. - -2. **Synchronous + Asynchronous**: All clients have async variants using `httpx.AsyncClient`. - -3. **Context Manager Support**: Clients should be usable with `with` statements for automatic resource cleanup. - -4. **OpenAI-Compatible API**: FastGPT's `/api/v1/chat/completions` endpoint is OpenAI-compatible, but with FastGPT-specific extensions. - -## API Architecture - -### FastGPT API Structure - -- **Base URL**: User-configured (default: `http://localhost:3000`) -- **Authentication**: `Authorization: Bearer {api_key}` -- **Chat Completions**: `/api/v1/chat/completions` (OpenAI-compatible) -- **Chat History**: `/api/core/chat/*` endpoints -- **App Analytics**: `/api/proApi/core/app/logs/*` endpoints - -### Key Concepts - -- **chatId**: Identifier for a conversation window (similar to Dify's `conversation_id`) -- **dataId**: Identifier for a specific message within a chat -- **appId**: Application identifier (from FastGPT app details URL) -- **variables**: Template variables that replace `[key]` placeholders in workflows -- **detail mode**: When `detail=true`, responses include `responseData` with module-level execution details - -### SSE Event Types - -FastGPT uses Server-Sent Events with multiple event types: - -- `answer` - Main chat response content -- `fastAnswer` - Quick reply content -- `flowNodeStatus` - Workflow node status (`running`, `completed`, `error`) -- `flowResponses` - Complete node response data (module execution details) -- `interactive` - Interactive node (user input/form selection) -- `updateVariables` - Variable updates during execution -- `error` - Error events -- `toolCall`, `toolParams`, `toolResponse` - Tool/agent operations - -## Project Structure - -``` -fastgpt-python-sdk/ -├── fastgpt_client/ -│ ├── __init__.py # Export all clients -│ ├── client.py # Base FastGPTClient -│ ├── async_client.py # AsyncFastGPTClient + async variants -│ ├── base_client.py # BaseClientMixin (retry, validation) -│ ├── chat_client.py # ChatClient (sync) -│ ├── app_client.py # AppClient for analytics/logs -│ ├── exceptions.py # Custom exceptions -│ └── utils/ -│ ├── validation.py # Parameter validation -│ ├── response_parser.py # Parse SSE events -│ └── types.py # Type definitions -├── tests/ -├── examples/ -├── setup.py -├── pyproject.toml -└── README.md -``` - -## Client Classes - -### FastGPTClient (Base) - -- Uses `httpx.Client` for connection pooling -- Implements retry logic with configurable `max_retries` and `retry_delay` -- Custom exceptions: `APIError`, `AuthenticationError`, `RateLimitError`, `ValidationError` -- Parameter validation via `_validate_params()` -- Methods: `_send_request()`, `_handle_error_response()`, `close()` - -### ChatClient - -Inherits from `FastGPTClient`. Key methods: - -- `create_chat_completion()` - Send messages (blocking/streaming), supports `chatId`, `variables`, `detail` -- `get_chat_histories()` - List chat histories for an app -- `get_chat_init()` - Get chat initialization info -- `get_chat_records()` - Get messages for a specific chat -- `get_record_detail()` - Get execution details for a message -- `update_chat_history()` - Update title or pin/unpin -- `delete_chat_history()` - Delete a chat -- `clear_chat_histories()` - Clear all histories -- `delete_chat_record()` - Delete a single message -- `send_feedback()` - Like/dislike a message -- `get_suggested_questions()` - Generate suggested questions - -### AppClient - -Inherits from `FastGPTClient`: - -- `get_app_logs_chart()` - Analytics data (users, chats, app metrics) -- `get_app_info()` - App metadata - -### Async Variants - -- `AsyncFastGPTClient`, `AsyncChatClient`, `AsyncAppClient` -- All methods are `async def` and use `await` -- Use `async with` for context manager support - -## Development Commands - -```bash -# Install package in development mode -pip install -e . - -# Run tests -pytest - -# Run single test file -pytest tests/test_chat_client.py - -# Run with coverage -pytest --cov=fastgpt_client - -# Lint with ruff -ruff check fastgpt_client/ - -# Format with ruff -ruff format fastgpt_client/ -``` - -## Key Differences from Dify SDK - -| Aspect | Dify SDK | FastGPT SDK | -|--------|----------|-------------| -| Chat ID | `conversation_id` | `chatId` | -| Message input | `inputs` + `query` | `messages` array (OpenAI format) | -| Variables | `inputs` dict | `variables` dict + `messages` | -| Streaming events | Single `data:` type | Multiple `event:` types | -| Detail mode | N/A | `detail=true` returns `responseData` | -| Response format | Custom Dify format | OpenAI-compatible (`choices`, `usage`) | - -## Request/Response Patterns - -### Chat Completion Request - -```python -{ - "chatId": "optional_chat_id", # Omit for stateless, provide for context - "stream": false, - "detail": false, - "variables": {"key": "value"}, # Template variable substitution - "messages": [ - {"role": "user", "content": "Hello"} - ] -} -``` - -### Chat Completion Response (blocking, detail=false) - -OpenAI-compatible format with `choices`, `usage`, `id`, `model`. - -### Chat Completion Response (detail=true) - -Includes `responseData` array with module execution details: -- `moduleName` - Node name -- `moduleType` - Node type (chatNode, datasetSearchNode, etc.) -- `tokens`, `price`, `runningTime` -- `quoteList` - Knowledge base citations -- `completeMessages` - Full context - -### Interactive Node Response - -When workflow hits an interactive node: -```python -{ - "interactive": { - "type": "userSelect" | "userInput", - "params": { - "description": "...", - "userSelectOptions": [...], # for userSelect - "inputForm": [...] # for userInput - } - } -} -``` - -## References - -- [FastGPT Chat API Documentation](https://doc.fastgpt.io/docs/introduction/development/openapi/chat) -- [FastGPT App Logs Documentation](https://doc.fastgpt.io/docs/introduction/development/openapi/app) -- [Dify Python SDK](https://github.com/langgenius/dify-python-sdk) (architecture reference)