mobile version styled -ready for new version 2.0.1

API_GUIDE.md

@@ -0,0 +1,259 @@
+# API Guide - Linux Command GPT
+
+## Обзор
+
+API позволяет выполнять запросы к Linux Command GPT через HTTP POST запросы с помощью curl. API принимает только запросы от curl (проверка User-Agent).
+
+## Endpoint
+
+``` curl
+POST /execute
+```
+
+## Запуск сервера
+
+```bash
+# Запуск сервера
+lcg serve
+
+# Запуск на другом порту
+lcg serve --port 9000
+
+# Запуск с автоматическим открытием браузера
+lcg serve --browser
+```
+
+## Структура запроса
+
+### JSON Payload
+
+```json
+{
+  "prompt": "создать директорию test",
+  "system_id": 1,
+  "system": "альтернативный системный промпт",
+  "verbose": "vv",
+  "timeout": 120
+}
+```
+
+### Поля запроса
+
+| Поле | Тип | Обязательное | Описание |
+|------|-----|--------------|----------|
+| `prompt` | string | ✅ | Пользовательский запрос |
+| `system_id` | int | ❌ | ID системного промпта (1-5) |
+| `system` | string | ❌ | Текст системного промпта (альтернатива system_id) |
+| `verbose` | string | ❌ | Степень подробности: "v", "vv", "vvv" |
+| `timeout` | int | ❌ | Таймаут в секундах (по умолчанию: 120) |
+
+### Структура ответа
+
+```json
+{
+  "success": true,
+  "command": "mkdir test",
+  "explanation": "Команда mkdir создает новую директорию...",
+  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
+  "elapsed": 2.34
+}
+```
+
+## Примеры использования
+
+### 1. Базовый запрос
+
+```bash
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "создать директорию test"
+  }'
+```
+
+**Ответ:**
+
+```json
+{
+  "success": true,
+  "command": "mkdir test",
+  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
+  "elapsed": 1.23
+}
+```
+
+### 2. Запрос с системным промптом по ID
+
+```bash
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "найти все файлы .txt",
+    "system_id": 2
+  }'
+```
+
+### 3. Запрос с кастомным системным промптом
+
+```bash
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "показать использование памяти",
+    "system": "Ты эксперт по Linux. Отвечай только командами без объяснений."
+  }'
+```
+
+### 4. Запрос с подробным объяснением
+
+```bash
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "архивировать папку documents",
+    "verbose": "vv",
+    "timeout": 180
+  }'
+```
+
+**Ответ:**
+
+```json
+{
+  "success": true,
+  "command": "tar -czf documents.tar.gz documents/",
+  "explanation": "Команда tar создает архив в формате gzip...",
+  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
+  "elapsed": 3.45
+}
+```
+
+### 5. Запрос с максимальной подробностью
+
+```bash
+curl -X POST http://localhost:8080/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "настроить SSH сервер",
+    "system_id": 3,
+    "verbose": "vvv",
+    "timeout": 300
+  }'
+```
+
+## Системные промпты
+
+| ID | Название | Описание |
+|----|----------|----------|
+| 1 | basic | Базовые команды Linux |
+| 2 | advanced | Продвинутые команды |
+| 3 | system | Системное администрирование |
+| 4 | network | Сетевые команды |
+| 5 | security | Безопасность |
+
+## Степени подробности
+
+| Уровень | Описание |
+|---------|----------|
+| `v` | Краткое объяснение |
+| `vv` | Подробное объяснение с альтернативами |
+| `vvv` | Максимально подробное объяснение с примерами |
+
+## Обработка ошибок
+
+### Ошибка валидации
+
+```json
+{
+  "success": false,
+  "error": "Prompt is required"
+}
+```
+
+### Ошибка AI
+
+```json
+{
+  "success": false,
+  "error": "Failed to get response from AI"
+}
+```
+
+### Ошибка доступа
+
+``` text
+HTTP 403 Forbidden
+Only curl requests are allowed
+```
+
+## Переменные окружения
+
+Убедитесь, что настроены необходимые переменные:
+
+```bash
+# Основные настройки
+export LCG_PROVIDER="ollama"
+export LCG_HOST="http://localhost:11434"
+export LCG_MODEL="hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M"
+
+# Для proxy провайдера
+export LCG_PROVIDER="proxy"
+export LCG_HOST="https://your-proxy-server.com"
+export LCG_JWT_TOKEN="your-jwt-token"
+```
+
+## Безопасность
+
+- ✅ **Только curl**: API принимает только запросы от curl
+- ✅ **POST только**: Только POST запросы к `/execute`
+- ✅ **JSON валидация**: Строгая проверка входных данных
+- ✅ **Таймауты**: Ограничение времени выполнения запросов
+
+## Примеры скриптов
+
+### Bash скрипт для автоматизации
+
+```bash
+#!/bin/bash
+
+API_URL="http://localhost:8080/execute"
+
+# Функция для выполнения запроса
+execute_command() {
+    local prompt="$1"
+    local verbose="${2:-}"
+    
+    curl -s -X POST "$API_URL" \
+        -H "Content-Type: application/json" \
+        -d "{\"prompt\": \"$prompt\", \"verbose\": \"$verbose\"}" | \
+        jq -r '.command'
+}
+
+# Использование
+echo "Команда: $(execute_command "создать директорию backup")"
+```
+
+### Python скрипт
+
+```python
+import requests
+import json
+
+def execute_command(prompt, system_id=None, verbose=None):
+    url = "http://localhost:8080/execute"
+    payload = {"prompt": prompt}
+    
+    if system_id:
+        payload["system_id"] = system_id
+    if verbose:
+        payload["verbose"] = verbose
+    
+    response = requests.post(url, json=payload)
+    return response.json()
+
+# Использование
+result = execute_command("показать использование диска", verbose="vv")
+print(f"Команда: {result['command']}")
+if 'explanation' in result:
+    print(f"Объяснение: {result['explanation']}")
+```