Add async client support
- Add AsyncFastGPTClient, AsyncChatClient, AsyncAppClient classes - Implement async/await patterns with httpx.AsyncClient - Add async context manager support (async with, async for) - Add async retry logic with exponential backoff - Add 29 async unit tests covering all async client methods - Update __init__.py to export async clients 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Xin Wang
609
fastgpt_client/async_client.py
Normal file
609
fastgpt_client/async_client.py
Normal file
@@ -0,0 +1,609 @@
|
||||
"""FastGPT Async Client - Asynchronous client for FastGPT API."""
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import weakref
|
||||
from typing import Any, Dict, Literal, Union
|
||||
|
||||
import httpx
|
||||
|
||||
from .base_client import BaseClientMixin
|
||||
from .exceptions import APIError, AuthenticationError, RateLimitError, ValidationError
|
||||
|
||||
|
||||
class AsyncFastGPTClient(BaseClientMixin):
|
||||
"""Asynchronous FastGPT API client.
|
||||
|
||||
This client uses httpx.AsyncClient for efficient async connection pooling.
|
||||
It's recommended to use this client as an async context manager.
|
||||
|
||||
Example:
|
||||
async with AsyncFastGPTClient(api_key="your-key") as client:
|
||||
response = await client.get_app_info(app_id="app-123")
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
api_key: str,
|
||||
base_url: str = "http://localhost:3000",
|
||||
timeout: float = 60.0,
|
||||
max_retries: int = 3,
|
||||
retry_delay: float = 1.0,
|
||||
enable_logging: bool = False,
|
||||
):
|
||||
"""Initialize the Async FastGPT client.
|
||||
|
||||
Args:
|
||||
api_key: Your FastGPT API key
|
||||
base_url: Base URL for the FastGPT API
|
||||
timeout: Request timeout in seconds (default: 60.0)
|
||||
max_retries: Maximum number of retry attempts (default: 3)
|
||||
retry_delay: Delay between retries in seconds (default: 1.0)
|
||||
enable_logging: Whether to enable request logging (default: False)
|
||||
"""
|
||||
# Initialize base client functionality
|
||||
super().__init__(api_key, base_url, timeout, max_retries, retry_delay, enable_logging)
|
||||
|
||||
self._client = httpx.AsyncClient(
|
||||
base_url=base_url,
|
||||
timeout=httpx.Timeout(timeout, connect=5.0),
|
||||
)
|
||||
|
||||
async def __aenter__(self):
|
||||
"""Support async context manager protocol."""
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type, exc_val, exc_tb):
|
||||
"""Clean up resources when exiting async context."""
|
||||
await self.close()
|
||||
|
||||
async def close(self):
|
||||
"""Close the HTTP client and release resources."""
|
||||
if hasattr(self, "_client"):
|
||||
await self._client.aclose()
|
||||
|
||||
async def _send_request(
|
||||
self,
|
||||
method: str,
|
||||
endpoint: str,
|
||||
json: Dict[str, Any] | None = None,
|
||||
params: Dict[str, Any] | None = None,
|
||||
stream: bool = False,
|
||||
**kwargs,
|
||||
):
|
||||
"""Send an HTTP request to the FastGPT API with retry logic.
|
||||
|
||||
Args:
|
||||
method: HTTP method (GET, POST, PUT, PATCH, DELETE)
|
||||
endpoint: API endpoint path
|
||||
json: JSON request body
|
||||
params: Query parameters
|
||||
stream: Whether to stream the response
|
||||
**kwargs: Additional arguments to pass to httpx.request
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
# Validate parameters
|
||||
if json:
|
||||
self._validate_params(**json)
|
||||
if params:
|
||||
self._validate_params(**params)
|
||||
|
||||
headers = {
|
||||
"Authorization": f"Bearer {self.api_key}",
|
||||
"Content-Type": "application/json",
|
||||
}
|
||||
|
||||
async def make_request():
|
||||
"""Inner function to perform the actual HTTP request."""
|
||||
# Log request if logging is enabled
|
||||
if self.enable_logging:
|
||||
self.logger.info(f"Sending {method} request to {endpoint}")
|
||||
|
||||
# Debug logging for detailed information
|
||||
if self.logger.isEnabledFor(logging.DEBUG):
|
||||
if json:
|
||||
self.logger.debug(f"Request body: {json}")
|
||||
if params:
|
||||
self.logger.debug(f"Request params: {params}")
|
||||
|
||||
# httpx.AsyncClient automatically prepends base_url
|
||||
# For streaming, use stream() method; for non-streaming, use request()
|
||||
if stream:
|
||||
# httpx.stream() returns a context manager, enter it and return response
|
||||
stream_context = self._client.stream(
|
||||
method,
|
||||
endpoint,
|
||||
json=json,
|
||||
params=params,
|
||||
headers=headers,
|
||||
**kwargs,
|
||||
)
|
||||
response = await stream_context.__aenter__()
|
||||
|
||||
# Store the stream context on the response
|
||||
response._stream_context = stream_context
|
||||
response._stream_context_closed = False
|
||||
|
||||
# Override close() to also close the stream context
|
||||
original_close = response.close
|
||||
|
||||
async def close_with_context():
|
||||
"""Close both the response and the stream context."""
|
||||
if getattr(response, '_stream_context_closed', False):
|
||||
return
|
||||
|
||||
try:
|
||||
# Close the response first
|
||||
await original_close()
|
||||
finally:
|
||||
# Always close the stream context, even if response.close() fails
|
||||
if hasattr(response, '_stream_context') and response._stream_context is not None:
|
||||
try:
|
||||
await response._stream_context.__aexit__(None, None, None)
|
||||
except Exception:
|
||||
pass # Ignore errors during cleanup
|
||||
finally:
|
||||
response._stream_context = None
|
||||
response._stream_context_closed = True
|
||||
|
||||
response.close = close_with_context
|
||||
|
||||
# Safety net: ensure cleanup on garbage collection
|
||||
def cleanup_stream_context(stream_ctx_ref):
|
||||
"""Finalizer to close stream context if response is GC'd without being closed."""
|
||||
async def _cleanup():
|
||||
stream_ctx = stream_ctx_ref()
|
||||
if stream_ctx is not None:
|
||||
try:
|
||||
await stream_ctx.__aexit__(None, None, None)
|
||||
except Exception:
|
||||
pass # Ignore errors in finalizer
|
||||
|
||||
# Schedule cleanup on event loop
|
||||
try:
|
||||
loop = asyncio.get_running_loop()
|
||||
loop.create_task(_cleanup())
|
||||
except RuntimeError:
|
||||
pass # No running loop
|
||||
|
||||
# Use weakref to avoid circular references
|
||||
weakref.finalize(response, cleanup_stream_context, weakref.ref(stream_context))
|
||||
else:
|
||||
response = await self._client.request(
|
||||
method,
|
||||
endpoint,
|
||||
json=json,
|
||||
params=params,
|
||||
headers=headers,
|
||||
**kwargs,
|
||||
)
|
||||
|
||||
# Log response if logging is enabled
|
||||
if self.enable_logging:
|
||||
self.logger.info(f"Received response: {response.status_code}")
|
||||
|
||||
return response
|
||||
|
||||
# Use the retry mechanism from base client
|
||||
request_context = f"{method} {endpoint}"
|
||||
response = await self._retry_request_async(make_request, request_context)
|
||||
|
||||
# Handle error responses (API errors don't retry)
|
||||
self._handle_error_response(response)
|
||||
|
||||
return response
|
||||
|
||||
async def _retry_request_async(self, request_func, request_context: str):
|
||||
"""Execute a request with retry logic (async version).
|
||||
|
||||
Args:
|
||||
request_func: Async function that executes the HTTP request
|
||||
request_context: Description of the request for logging
|
||||
|
||||
Returns:
|
||||
Response from the request
|
||||
|
||||
Raises:
|
||||
APIError: If all retries are exhausted
|
||||
"""
|
||||
last_exception = None
|
||||
|
||||
for attempt in range(self.max_retries):
|
||||
try:
|
||||
response = await request_func()
|
||||
|
||||
# Success on non-5xx responses
|
||||
if response.status_code < 500:
|
||||
return response
|
||||
|
||||
# Server error - will retry
|
||||
if self.enable_logging:
|
||||
self.logger.warning(
|
||||
f"{request_context} failed with status {response.status_code} "
|
||||
f"(attempt {attempt + 1}/{self.max_retries})"
|
||||
)
|
||||
|
||||
if attempt < self.max_retries - 1:
|
||||
# Exponential backoff
|
||||
sleep_time = self.retry_delay * (2 ** attempt)
|
||||
await asyncio.sleep(sleep_time)
|
||||
|
||||
except Exception as e:
|
||||
last_exception = e
|
||||
if self.enable_logging:
|
||||
self.logger.warning(
|
||||
f"{request_context} raised exception: {e} "
|
||||
f"(attempt {attempt + 1}/{self.max_retries})"
|
||||
)
|
||||
|
||||
if attempt < self.max_retries - 1:
|
||||
sleep_time = self.retry_delay * (2 ** attempt)
|
||||
await asyncio.sleep(sleep_time)
|
||||
|
||||
# All retries exhausted
|
||||
if last_exception:
|
||||
from .exceptions import APIError
|
||||
raise APIError(f"Request failed after {self.max_retries} attempts: {last_exception}")
|
||||
|
||||
from .exceptions import APIError
|
||||
raise APIError(f"Request failed after {self.max_retries} attempts")
|
||||
|
||||
def _handle_error_response(self, response) -> None:
|
||||
"""Handle HTTP error responses and raise appropriate exceptions.
|
||||
|
||||
Args:
|
||||
response: httpx.Response object
|
||||
|
||||
Raises:
|
||||
AuthenticationError: If status code is 401
|
||||
RateLimitError: If status code is 429
|
||||
ValidationError: If status code is 422
|
||||
APIError: For other 4xx and 5xx errors
|
||||
"""
|
||||
# Check status code first (doesn't consume response body)
|
||||
if response.status_code < 400:
|
||||
return # Success response
|
||||
|
||||
# Try to parse error message (this will consume the body, but that's OK for errors)
|
||||
try:
|
||||
error_data = response.json()
|
||||
message = error_data.get("message", f"HTTP {response.status_code}")
|
||||
except (ValueError, KeyError, AttributeError):
|
||||
# If we can't parse JSON (e.g., streaming response or invalid JSON), use status code
|
||||
message = f"HTTP {response.status_code}"
|
||||
error_data = None
|
||||
|
||||
# Log error response if logging is enabled
|
||||
if self.enable_logging:
|
||||
self.logger.error(f"API error: {response.status_code} - {message}")
|
||||
|
||||
if response.status_code == 401:
|
||||
raise AuthenticationError(message, response.status_code, error_data)
|
||||
elif response.status_code == 429:
|
||||
retry_after = response.headers.get("Retry-After")
|
||||
raise RateLimitError(message, retry_after, response.status_code, error_data)
|
||||
elif response.status_code == 422:
|
||||
raise ValidationError(message, response.status_code, error_data)
|
||||
elif response.status_code >= 400:
|
||||
raise APIError(message, response.status_code, error_data)
|
||||
|
||||
|
||||
class AsyncChatClient(AsyncFastGPTClient):
|
||||
"""Async client for chat-related operations.
|
||||
|
||||
Example:
|
||||
async with AsyncChatClient(api_key="fastgpt-xxxxx") as client:
|
||||
response = await client.create_chat_completion(
|
||||
messages=[{"role": "user", "content": "Hello!"}],
|
||||
stream=False
|
||||
)
|
||||
"""
|
||||
|
||||
async def create_chat_completion(
|
||||
self,
|
||||
messages: list[dict],
|
||||
stream: bool = False,
|
||||
chatId: str | None = None,
|
||||
detail: bool = False,
|
||||
variables: dict[str, Any] | None = None,
|
||||
responseChatItemId: str | None = None,
|
||||
):
|
||||
"""Create a chat completion.
|
||||
|
||||
Args:
|
||||
messages: Array of message objects with role and content
|
||||
stream: Whether to stream the response
|
||||
chatId: Chat ID for conversation context (optional)
|
||||
detail: Whether to return detailed response data
|
||||
variables: Template variables for substitution
|
||||
responseChatItemId: Custom ID for the response message
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
self._validate_params(messages=messages)
|
||||
|
||||
data = {
|
||||
"messages": messages,
|
||||
"stream": stream,
|
||||
"detail": detail,
|
||||
}
|
||||
|
||||
if chatId:
|
||||
data["chatId"] = chatId
|
||||
if variables:
|
||||
data["variables"] = variables
|
||||
if responseChatItemId:
|
||||
data["responseChatItemId"] = responseChatItemId
|
||||
|
||||
return await self._send_request(
|
||||
"POST",
|
||||
"/api/v1/chat/completions",
|
||||
json=data,
|
||||
stream=stream,
|
||||
)
|
||||
|
||||
async def get_chat_histories(
|
||||
self,
|
||||
appId: str,
|
||||
offset: int = 0,
|
||||
pageSize: int = 20,
|
||||
source: Literal["api", "online", "share", "test"] = "api",
|
||||
):
|
||||
"""Get chat histories for an application.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
offset: Offset for pagination
|
||||
pageSize: Number of records per page
|
||||
source: Source filter (api, online, share, test)
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
data = {
|
||||
"appId": appId,
|
||||
"offset": offset,
|
||||
"pageSize": pageSize,
|
||||
"source": source,
|
||||
}
|
||||
|
||||
return await self._send_request("POST", "/api/core/chat/getHistories", json=data)
|
||||
|
||||
async def get_chat_init(self, appId: str, chatId: str):
|
||||
"""Get chat initialization information.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
params = {"appId": appId, "chatId": chatId}
|
||||
return await self._send_request("GET", "/api/core/chat/init", params=params)
|
||||
|
||||
async def get_chat_records(
|
||||
self,
|
||||
appId: str,
|
||||
chatId: str,
|
||||
offset: int = 0,
|
||||
pageSize: int = 10,
|
||||
loadCustomFeedbacks: bool = False,
|
||||
):
|
||||
"""Get chat records for a specific chat.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
offset: Offset for pagination
|
||||
pageSize: Number of records per page
|
||||
loadCustomFeedbacks: Whether to load custom feedbacks
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
data = {
|
||||
"appId": appId,
|
||||
"chatId": chatId,
|
||||
"offset": offset,
|
||||
"pageSize": pageSize,
|
||||
"loadCustomFeedbacks": loadCustomFeedbacks,
|
||||
}
|
||||
|
||||
return await self._send_request("POST", "/api/core/chat/getPaginationRecords", json=data)
|
||||
|
||||
async def get_record_detail(self, appId: str, chatId: str, dataId: str):
|
||||
"""Get detailed execution data for a specific record.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
dataId: Record ID
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
params = {"appId": appId, "chatId": chatId, "dataId": dataId}
|
||||
return await self._send_request("GET", "/api/core/chat/getResData", params=params)
|
||||
|
||||
async def update_chat_history(
|
||||
self,
|
||||
appId: str,
|
||||
chatId: str,
|
||||
customTitle: str | None = None,
|
||||
top: bool | None = None,
|
||||
):
|
||||
"""Update chat history (title or pin status).
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
customTitle: Custom title for the chat
|
||||
top: Whether to pin the chat
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
data = {
|
||||
"appId": appId,
|
||||
"chatId": chatId,
|
||||
}
|
||||
|
||||
if customTitle is not None:
|
||||
data["customTitle"] = customTitle
|
||||
if top is not None:
|
||||
data["top"] = top
|
||||
|
||||
return await self._send_request("POST", "/api/core/chat/updateHistory", json=data)
|
||||
|
||||
async def delete_chat_history(self, appId: str, chatId: str):
|
||||
"""Delete a chat history.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
params = {"appId": appId, "chatId": chatId}
|
||||
return await self._send_request("DELETE", "/api/core/chat/delHistory", params=params)
|
||||
|
||||
async def clear_chat_histories(self, appId: str):
|
||||
"""Clear all chat histories for an application.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
params = {"appId": appId}
|
||||
return await self._send_request("DELETE", "/api/core/chat/clearHistories", params=params)
|
||||
|
||||
async def delete_chat_record(self, appId: str, chatId: str, contentId: str):
|
||||
"""Delete a single chat record.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
contentId: Content ID of the record
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
params = {"appId": appId, "chatId": chatId, "contentId": contentId}
|
||||
return await self._send_request("DELETE", "/api/core/chat/item/delete", params=params)
|
||||
|
||||
async def send_feedback(
|
||||
self,
|
||||
appId: str,
|
||||
chatId: str,
|
||||
dataId: str,
|
||||
userGoodFeedback: str | None = None,
|
||||
userBadFeedback: str | None = None,
|
||||
):
|
||||
"""Send feedback for a chat message (like/dislike).
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
dataId: Message ID
|
||||
userGoodFeedback: Positive feedback text (pass None to cancel like)
|
||||
userBadFeedback: Negative feedback text (pass None to cancel dislike)
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
data = {
|
||||
"appId": appId,
|
||||
"chatId": chatId,
|
||||
"dataId": dataId,
|
||||
}
|
||||
|
||||
if userGoodFeedback is not None:
|
||||
data["userGoodFeedback"] = userGoodFeedback
|
||||
if userBadFeedback is not None:
|
||||
data["userBadFeedback"] = userBadFeedback
|
||||
|
||||
return await self._send_request("POST", "/api/core/chat/feedback/updateUserFeedback", json=data)
|
||||
|
||||
async def get_suggested_questions(
|
||||
self,
|
||||
appId: str,
|
||||
chatId: str,
|
||||
questionGuide: dict[str, Any] | None = None,
|
||||
):
|
||||
"""Get suggested questions based on chat context.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
chatId: Chat ID
|
||||
questionGuide: Optional custom configuration for question guide
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
data = {
|
||||
"appId": appId,
|
||||
"chatId": chatId,
|
||||
}
|
||||
|
||||
if questionGuide:
|
||||
data["questionGuide"] = questionGuide
|
||||
|
||||
return await self._send_request("POST", "/api/core/ai/agent/v2/createQuestionGuide", json=data)
|
||||
|
||||
|
||||
class AsyncAppClient(AsyncFastGPTClient):
|
||||
"""Async client for application analytics and logs.
|
||||
|
||||
Example:
|
||||
async with AsyncAppClient(api_key="fastgpt-xxxxx") as client:
|
||||
logs = await client.get_app_logs_chart(appId="app-123")
|
||||
"""
|
||||
|
||||
async def get_app_logs_chart(
|
||||
self,
|
||||
appId: str,
|
||||
dateStart: str,
|
||||
dateEnd: str,
|
||||
offset: int = 1,
|
||||
source: list[str] | None = None,
|
||||
userTimespan: str = "day",
|
||||
chatTimespan: str = "day",
|
||||
appTimespan: str = "day",
|
||||
):
|
||||
"""Get application analytics chart data.
|
||||
|
||||
Args:
|
||||
appId: Application ID
|
||||
dateStart: Start date (ISO 8601 format)
|
||||
dateEnd: End date (ISO 8601 format)
|
||||
offset: Offset value
|
||||
source: List of sources (test, online, share, api, etc.)
|
||||
userTimespan: User data timespan (day, week, month)
|
||||
chatTimespan: Chat data timespan (day, week, month)
|
||||
appTimespan: App data timespan (day, week, month)
|
||||
|
||||
Returns:
|
||||
httpx.Response object
|
||||
"""
|
||||
if source is None:
|
||||
source = ["api"]
|
||||
|
||||
data = {
|
||||
"appId": appId,
|
||||
"dateStart": dateStart,
|
||||
"dateEnd": dateEnd,
|
||||
"offset": offset,
|
||||
"source": source,
|
||||
"userTimespan": userTimespan,
|
||||
"chatTimespan": chatTimespan,
|
||||
"appTimespan": appTimespan,
|
||||
}
|
||||
|
||||
return await self._send_request("POST", "/api/proApi/core/app/logs/getChartData", json=data)
|
||||
Reference in New Issue
Block a user