# 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/`.