fastgpt-python-sdk/AGENTS.md

AGENTS.md — FastGPT Python SDK

Guidance for AI agents working in this repository.

What this repo is

Python client (fastgpt_client) for FastGPT OpenAPI. It wraps HTTP calls with httpx, returns httpx.Response objects, and provides sync/async clients plus streaming helpers.

Package layout

Path	Role
fastgpt_client/client.py	ChatClient, AppClient (sync)
fastgpt_client/async_client.py	AsyncChatClient, AsyncAppClient
fastgpt_client/base_client.py	Auth, retries, validation
fastgpt_client/streaming.py	iter_stream_events, aiter_stream_events
docs/	MkDocs user docs (source of truth for examples)
tests/	pytest suite

Official API reference

Use these when adding or verifying endpoints (do not guess paths or payloads):

Area	Interactive OpenAPI	Written docs
应用管理 (app logs, analytics)	cloud.fastgpt.cn/openapi — 应用管理	应用接口
Chat / conversations	Chat API	docs/api/chat_client.md

Auth: Authorization: Bearer {api_key} on every request.

Base URLs

• SaaS (cloud): https://cloud.fastgpt.cn — app analytics routes live under /api/proApi/...
• Self-hosted: your deployment origin (default in code: http://localhost:3000)

Pass base_url to the client; paths in code are relative (e.g. /api/proApi/core/app/logs/getChartData).

SDK ↔ API mapping

Chat (ChatClient / AsyncChatClient)

SDK method	HTTP	Notes
create_chat_completion	POST /api/v1/chat/completions	stream=True for SSE; optional chatId, variables, detail
get_chat_histories	POST /api/core/chat/getHistories	Requires appId
get_chat_init	GET /api/core/chat/init
get_chat_records	POST /api/core/chat/getPaginationRecords
get_record_detail	GET /api/core/chat/getResData
update_chat_history	POST /api/core/chat/updateHistory
delete_chat_history	DELETE /api/core/chat/delHistory
clear_chat_histories	DELETE /api/core/chat/clearHistories
delete_chat_record	DELETE /api/core/chat/item/delete
send_feedback	POST /api/core/chat/feedback/updateUserFeedback
get_suggested_questions	POST /api/core/ai/agent/v2/createQuestionGuide

App / 应用管理 (AppClient / AsyncAppClient)

SDK method	HTTP	OpenAPI tag
get_app_logs_chart	POST /api/proApi/core/app/logs/getChartData	应用管理 — log dashboard

Not implemented in SDK yet (see official app docs): e.g. GET /api/proApi/core/app/logs/getTotalData. Add methods in client.py and async_client.py, mirror in tests, and document in docs/api/app_client.md.

Conventions for changes

1. Match existing style: Google docstrings, type hints on public APIs, camelCase parameter names where the API uses them (appId, chatId, dateStart).
2. Responses: Methods return httpx.Response; callers use .raise_for_status() and .json(). Map HTTP errors via fastgpt_client.exceptions in _handle_error_response.
3. Sync + async: Implement both when adding a new endpoint.
4. Tests: Add/update tests under tests/test_*_client.py; run pytest before finishing.
5. Docs: Update docs/api/*.md and README.md only when behavior or public API changes.
6. Scope: Minimal diffs; no unrelated refactors. Do not commit secrets (.env, API keys).

Typical usage (for generated code)

from fastgpt_client import ChatClient, AppClient

with ChatClient(api_key="fastgpt-...", base_url="https://cloud.fastgpt.cn") as chat:
    r = chat.create_chat_completion(
        messages=[{"role": "user", "content": "Hello"}],
        stream=False,
    )
    r.raise_for_status()
    print(r.json()["choices"][0]["message"]["content"])

with AppClient(api_key="fastgpt-...", base_url="https://cloud.fastgpt.cn") as app:
    r = app.get_app_logs_chart(
        appId="your-app-id",
        dateStart="2025-01-01T00:00:00.000Z",
        dateEnd="2025-01-31T23:59:59.999Z",
        source=["api", "online"],
    )
    r.raise_for_status()

Streaming: prefer iter_stream_events / aiter_stream_events over hand-parsing SSE when possible (see docs/advanced/streaming_events.md).

Development commands

pip install -e ".[dev]"
pytest
ruff check fastgpt_client/
ruff format fastgpt_client/
mkdocs serve   # optional: local docs

When unsure

1. Read the matching method in fastgpt_client/client.py.
2. Cross-check the cloud OpenAPI or doc.fastgpt.io for request/response shapes.
3. Follow patterns in tests/ and examples/.