sdk/KB_API_Guide.md

# Knowledge Base API — Руководство

Базовый URL: `https://api.er-gpt.ru`

Все запросы требуют авторизации (передавай токен в заголовке `Authorization: Bearer <token>`).

---

## 1. Базы знаний (Knowledge Base)

### 1.1 Создать базу знаний

```bash
curl -X POST https://api.er-gpt.ru/api/knowledge \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Моя база знаний",
    "description": "Описание базы",
    "config": {
      "chunk_size": 1000,
      "chunk_overlap": 200
    }
  }'
```

**Параметры тела запроса:**

| Поле | Тип | Обязательное | Описание |
|------|-----|-------------|----------|
| `name` | string | Да | Название базы знаний |
| `description` | string | Да | Описание базы знаний |
| `config.chunk_size` | integer | Да | Размер чанка (фрагмента текста) |
| `config.chunk_overlap` | integer | Да | Перекрытие между чанками |

**Ответ:** объект `KnowledgeBase`

```json
{
  "id": "uuid",
  "name": "Моя база знаний",
  "description": "Описание базы",
  "config": { "chunk_size": 1000, "chunk_overlap": 200 },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "user_id": "uuid",
  "documents_count": 0
}
```

### 1.2 Получить список баз знаний

```bash
curl -X GET "https://api.er-gpt.ru/api/knowledge?current=0&page_size=10" \
  -H "Authorization: Bearer <token>"
```

**Query-параметры:**

| Параметр | Тип | По умолчанию | Описание |
|----------|-----|-------------|----------|
| `search` | string | null | Поиск по названию/описанию |
| `current` | integer | 0 | Номер страницы (0-based) |
| `page_size` | integer | 10 | Количество элементов на странице |

**Ответ:**

```json
{
  "result": [ /* массив KnowledgeBase */ ],
  "total": 42
}
```

### 1.3 Получить одну базу знаний

```bash
curl -X GET https://api.er-gpt.ru/api/knowledge/{id} \
  -H "Authorization: Bearer <token>"
```

**Параметры пути:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | UUID | ID базы знаний |

**Ответ:** объект `QueryKnowledgeBaseAggregate` (включает `documents_count`)

### 1.4 Обновить базу знаний

```bash
curl -X PATCH https://api.er-gpt.ru/api/knowledge/{id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Новое название",
    "description": "Новое описание"
  }'
```

**Параметры тела запроса:**

| Поле | Тип | Обязательное | Описание |
|------|-----|-------------|----------|
| `name` | string | Да | Новое название |
| `description` | string | Да | Новое описание |

### 1.5 Удалить базу знаний

```bash
curl -X DELETE https://api.er-gpt.ru/api/knowledge/{id} \
  -H "Authorization: Bearer <token>"
```

> **Важно:** удаление базы знаний каскадно удаляет все связанные с ней документы и чанки.

---

## 2. Документы

### 2.1 Загрузить документ в базу знаний

```bash
curl -X POST https://api.er-gpt.ru/api/knowledge/upload/{kb_id} \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf"
```

**Параметры пути:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `kb_id` | UUID | ID базы знаний |

**Тело запроса:** `multipart/form-data` с полем `file` (бинарный файл)

**Ответ:** объект `DocumentWithContentUrl`

```json
{
  "id": "uuid",
  "filename": "document.pdf",
  "bucket": "documents",
  "kb_id": "uuid",
  "content_type": "application/pdf",
  "size": 123456,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "status": "PENDING",
  "error": null,
  "content_url": "https://..."
}
```

**Статусы документа:**
- `PENDING` — ожидает обработки
- `PROCESSING` — в процессе обработки
- `COMPLETED` — обработан успешно
- `FAILED` — ошибка обработки

### 2.2 Получить список документов базы знаний

```bash
curl -X GET "https://api.er-gpt.ru/api/knowledge/{kb_id}/documents?statuses=PENDING&statuses=FAILED&current=0&page_size=10" \
  -H "Authorization: Bearer <token>"
```

**Параметры пути:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `kb_id` | UUID | ID базы знаний |

**Query-параметры:**

| Параметр | Тип | По умолчанию | Описание |
|----------|-----|-------------|----------|
| `statuses` | string[] | null | Фильтр по статусам (можно несколько) |
| `current` | integer | 0 | Номер страницы |
| `page_size` | integer | 10 | Размер страницы |

**Ответ:**

```json
{
  "result": [ /* массив DocumentWithContentUrl */ ],
  "total": 15
}
```

### 2.3 Удалить документ

```bash
curl -X DELETE https://api.er-gpt.ru/api/knowledge/document/{document_id} \
  -H "Authorization: Bearer <token>"
```

### 2.4 Массовое удаление документов

```bash
curl -X DELETE "https://api.er-gpt.ru/api/knowledge/document/bulk?document_ids=uuid1&document_ids=uuid2&document_ids=uuid3" \
  -H "Authorization: Bearer <token>"
```

**Query-параметры:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `document_ids` | UUID[] | Массив ID документов для удаления |

### 2.5 Перезапустить обработку документа

```bash
curl -X POST https://api.er-gpt.ru/api/knowledge/{document_id}/retry \
  -H "Authorization: Bearer <token>"
```

> Полезно, если документ застрял в статусе `FAILED` или `PENDING`.

---

## 3. Чанки документов

### 3.1 Получить чанки документа

```bash
curl -X GET "https://api.er-gpt.ru/api/knowledge/documents/{document_id}/chunks?limit=10&cursor=<cursor>" \
  -H "Authorization: Bearer <token>"
```

**Параметры пути:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `document_id` | UUID | ID документа |

**Query-параметры:**

| Параметр | Тип | По умолчанию | Описание |
|----------|-----|-------------|----------|
| `search` | string | null | Поисковый запрос по тексту чанков |
| `cursor` | string | null | Курсор для пагинации |
| `limit` | integer | 10 | Количество чанков за запрос |

**Ответ:**

```json
{
  "pagination": {
    "cursor": "next_cursor_string",
    "has_more": true
  },
  "result": [
    {
      "text": "Содержимое чанка...",
      "document_id": "uuid",
      "filename": "document.pdf",
      "chunk_id": 0
    }
  ]
}
```

---

## 4. Поиск по базе знаний

### 4.1 Семантический поиск

```bash
curl -X POST https://api.er-gpt.ru/api/knowledge/{kb_id}/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Как настроить авторизацию?",
    "kb_id": "uuid",
    "limit": 5,
    "score_threshold": 0.2
  }'
```

**Параметры пути:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `kb_id` | UUID | ID базы знаний |

**Тело запроса:**

| Поле | Тип | Обязательное | По умолчанию | Описание |
|------|-----|-------------|-------------|----------|
| `query` | string | Да | — | Поисковый запрос |
| `kb_id` | UUID | Да | — | ID базы знаний (дублирует путь) |
| `limit` | integer / null | Нет | null | Максимальное количество результатов |
| `score_threshold` | number | Нет | 0.2 | Минимальный порог релевантности (0.0–1.0) |

**Ответ:**

```json
{
  "chunks": [
    {
      "id": "uuid",
      "filename": "document.pdf",
      "bucket": "documents",
      "kb_id": "uuid",
      "content_type": "application/pdf",
      "size": 123456,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "status": "COMPLETED",
      "error": null,
      "content_url": "https://...",
      "chunks": [
        {
          "text": "Релевантный фрагмент текста...",
          "score": 0.85
        }
      ]
    }
  ]
}
```

> Поиск возвращает документы с вложенными чанками, отсортированными по релевантности. Каждый чанк содержит `score` — степень соответствия запросу.

---

## 5. Полная схема KnowledgeBase

```json
{
  "id": "uuid",
  "name": "string",
  "description": "string",
  "config": {
    "chunk_size": 1000,
    "chunk_overlap": 200
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "user_id": "uuid",
  "documents_count": 0
}
```

## 6. Полная схема DocumentWithContentUrl

```json
{
  "id": "uuid",
  "filename": "string",
  "bucket": "string",
  "kb_id": "uuid",
  "content_type": "string",
  "size": 0,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "status": "PENDING | PROCESSING | COMPLETED | FAILED",
  "error": "string | null",
  "content_url": "string"
}
```

---

## 7. Обработка ошибок

Все эндпоинты возвращают `422 Unprocessable Entity` при валидационных ошибках:

```json
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

---

## 8. Quick Reference

| Действие | Метод | URL |
|----------|-------|-----|
| Создать базу знаний | `POST` | `/api/knowledge` |
| Получить список баз | `GET` | `/api/knowledge` |
| Получить базу | `GET` | `/api/knowledge/{id}` |
| Обновить базу | `PATCH` | `/api/knowledge/{id}` |
| Удалить базу | `DELETE` | `/api/knowledge/{id}` |
| Загрузить документ | `POST` | `/api/knowledge/upload/{kb_id}` |
| Получить документы базы | `GET` | `/api/knowledge/{kb_id}/documents` |
| Удалить документ | `DELETE` | `/api/knowledge/document/{document_id}` |
| Удалить документы bulk | `DELETE` | `/api/knowledge/document/bulk` |
| Перезапустить обработку | `POST` | `/api/knowledge/{document_id}/retry` |
| Получить чанки | `GET` | `/api/knowledge/documents/{document_id}/chunks` |
| Поиск | `POST` | `/api/knowledge/{kb_id}/search` |