From 0abb9b63a4183693e4b2cbc5d74c3f68cf3a545c Mon Sep 17 00:00:00 2001 From: Xin Wang Date: Fri, 29 May 2026 17:09:07 +0800 Subject: [PATCH] docs: add AGENTS.md for AI agent guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document SDK layout, API mapping, and links to FastGPT OpenAPI (应用管理). Co-authored-by: Cursor --- AGENTS.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b61f796 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,112 @@ +# AGENTS.md — FastGPT Python SDK + +Guidance for AI agents working in this repository. + +## What this repo is + +Python client (`fastgpt_client`) for [FastGPT OpenAPI](https://doc.fastgpt.io/). 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 — 应用管理](https://cloud.fastgpt.cn/openapi#tag/%E5%BA%94%E7%94%A8%E7%AE%A1%E7%90%86) | [应用接口](https://doc.fastgpt.io/zh-CN/openapi/app) | +| Chat / conversations | [Chat API](https://doc.fastgpt.io/docs/introduction/development/openapi/chat) | `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) + +```python +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 + +```bash +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](https://cloud.fastgpt.cn/openapi) or [doc.fastgpt.io](https://doc.fastgpt.io/) for request/response shapes. +3. Follow patterns in `tests/` and `examples/`.