# 🔥 Tier 1.5 — DX & Adoption

SDK, CLI, интеграции, документация — всё что снижает трение при внедрении.

### Python SDK-клиент для HTTP API 🔴

Сейчас пользователь пишет raw HTTP запросы. Должно быть:

```python
from policyshield.client import PolicyShieldClient

ps = PolicyShieldClient("http://localhost:8100")
result = ps.check("write_file", {"path": "/tmp/x"})
if result.verdict == "APPROVE":
    ps.wait_for_approval(result.approval_id, timeout=300)
```

- **Усилия**: Средние (~200 строк, обёртка над httpx)
- **Ценность**: 🔥🔥🔥 — убирает 80% трения при интеграции

### Готовые пресеты по ролям 🔴

`policyshield init --preset coding-agent`, `--preset data-analyst`, `--preset customer-support`. 90% пользователей хотят «включил и забыл», а не писать YAML.

- **Усилия**: Маленькие (YAML шаблоны)
- **Ценность**: 🔥🔥🔥 — zero-config для конкретного use case

### `policyshield quickstart` — интерактивный мастер 🔴

Спрашивает «какие инструменты использует ваш агент?», генерирует правила, запускает сервер, выводит код для интеграции. Одна команда от нуля до работающей защиты.

- **Усилия**: Средние (wizard CLI + template engine)
- **Ценность**: 🔥🔥🔥 — самый короткий путь к value

### Dry-run CLI (`policyshield check`) 🔴

Проверить один вызов без поднятия сервера:

```bash
policyshield check --tool exec --args '{"cmd":"rm -rf /"}' --rules rules.yaml
```

- **Усилия**: Маленькие (~30 строк)
- **Ценность**: 🔥🔥 — отладка правил без запуска сервера

### MCP (Model Context Protocol) интеграция 🔴

MCP — де-факто стандарт для tool calling. PolicyShield как MCP proxy/middleware перехватывает tool calls на уровне протокола. Killer feature: любой MCP-агент получает защиту автоматически.

```bash
# Вместо прямого подключения к MCP серверу:
# agent → mcp_server
# С PolicyShield:
# agent → policyshield_mcp_proxy → mcp_server
policyshield mcp-proxy --upstream stdio://my-mcp-server --rules rules.yaml
```

- **Усилия**: Средние (~400 строк, MCP protocol wrapper)
- **Ценность**: 🔥🔥🔥 — охват всей MCP экосистемы одной интеграцией

### Idempotency / Request Deduplication 🔴

Если агент retry'ит запрос к `/api/v1/check` — дублируются trace записи, rate limit счётчики растут, approval создаётся дважды. Нужен `idempotency_key` в запросе.

```python
result = ps.check("write_file", {"path": "/tmp/x"}, idempotency_key="req-abc-123")
# повторный вызов с тем же ключом = тот же результат, без side effects
```

- **Усилия**: Средние (~100 строк, LRU cache результатов по ключу)
- **Ценность**: 🔥🔥🔥 — без этого retry-логика ломает rate limits и approvals

### Retry/Backoff для Telegram и Webhook 🔴

Telegram API может быть недоступен. Без retry с экспоненциальным backoff — **потеря approval-уведомлений без ошибки.**

```python
# Сейчас: один запрос, при ошибке — silent fail
# Нужно: 3 повтора с backoff 1s → 2s → 4s
```

- **Усилия**: Маленькие (~30 строк, tenacity/простой цикл)
- **Ценность**: 🔥🔥🔥 — без этого approval flow ненадёжен

### Deep Health Checks (/livez + /readyz) 🔴

`/api/v1/health` возвращает `ok` если процесс жив. Не проверяет: доступен ли Telegram бот? Работает ли trace writer? Скомпилированы ли regex?

```
GET /livez  → 200 (процесс жив)
GET /readyz → 200 (правила загружены, detectors ok, approval backend доступен)
             → 503 (telegram down, rules broken, etc.)
```

- **Усилия**: Маленькие (~40 строк)
- **Ценность**: 🔥🔥🔥 — без deep check проблемы обнаруживаются только при первом запросе

### K8s Liveness & Readiness Probes 🟡

Один `/api/v1/health` недостаточно. K8s нужен `/livez` (процесс жив) и `/readyz` (правила загружены, бэкенды доступны).

- **Усилия**: Маленькие (~20 строк)
- **Ценность**: 🔥🔥 — стандарт для K8s деплоя

### Decorator/middleware API 🟡

Inline интеграция без отдельного сервера:

```python
from policyshield import shield

@shield(engine)
def my_tool(args):
    ...
```

- **Усилия**: Маленькие (~50 строк)
- **Ценность**: 🔥🔥 — для тех кто не хочет отдельный сервер

### JS/TS SDK 🟡

Python SDK — начало, но большинство агентов на Node.js. Без JS клиента теряем огромную аудиторию.

```typescript
import { PolicyShield } from '@policyshield/client';
const ps = new PolicyShield('http://localhost:8100');
const result = await ps.check('write_file', { path: '/tmp/x' });
```

- **Усилия**: Средние (~300 строк TypeScript)
- **Ценность**: 🔥🔥 — открывает Node.js аудиторию

### Slack/Webhook уведомления о нарушениях 🟡

Telegram есть, но Slack в корпоративном мире важнее. Webhook для кастомных интеграций.

```yaml
alerts:
  on_block: slack
  slack_webhook: ${SLACK_WEBHOOK_URL}
```

- **Усилия**: Маленькие (адаптер поверх alert engine)
- **Ценность**: 🔥🔥 — enterprise adoption

### Рабочие примеры интеграций 🟡

Не документация, а `git clone && python run.py`:

```
examples/
  langchain_agent/     # полный агент с PolicyShield
  crewai_workflow/     # CrewAI pipeline
  autogen_agent/       # AutoGen multi-agent
  fastapi_service/     # микросервис с check/approve
  docker_compose/      # сервер + агент + monitoring
```

- **Усилия**: Средние (5-6 рабочих примеров)
- **Ценность**: 🔥🔥 — proof of concept за 2 минуты

### Конфиг через env variables (12-factor) 🟡

Сейчас конфиг из YAML + отдельные `POLICYSHIELD_TELEGRAM_*` env vars. Нет полного `POLICYSHIELD_*` маппинга. Для Docker/K8s это стандарт.

```bash
POLICYSHIELD_PORT=8100
POLICYSHIELD_MODE=enforce
POLICYSHIELD_DEFAULT_VERDICT=block
POLICYSHIELD_RULES_PATH=/app/rules.yaml
```

- **Усилия**: Маленькие (~40 строк)
- **Ценность**: 🔥🔥 — 12-factor app, стандарт для контейнеров

### OpenAPI Schema & API Contract 🟡

FastAPI генерирует OpenAPI автоматически, но нет публикуемого стабильного API-контракта. Без него SDK-авторы и интеграторы не знают на что полагаться.

```bash
# Генерация и публикация спецификации
policyshield openapi --output openapi.json
```

- **Усилия**: Маленькие (FastAPI + endpoint)
- **Ценность**: 🔥🔥 — основа для SDK любого языка

### `policyshield test --coverage` 🟢

Показывает какие инструменты агента покрыты правилами:

```
$ policyshield test --coverage --tools exec,read_file,write_file,send_email
Coverage: 3/4 tools (75%)
  ✅ exec → block-exec
  ✅ read_file → allow-read-file
  ✅ send_email → redact-pii
  ❌ write_file → no matching rule (default: BLOCK)
```

- **Усилия**: Маленькие
- **Ценность**: 🔥 — уверенность что ничего не пропущено

### Web UI дашборд 🟢

Посмотреть что заблочено, одобрить/отклонить, статистика PII — прямо в браузере.

- **Усилия**: Большие (SPA + WebSocket)
- **Ценность**: 🔥 — визуализация для менеджеров
