prisma/README.md

# Prisma Platform MVP

MVP-реализация сценарного раннера на Agno AgentOS.

Текущая схема исполнения:

- сценарий хранится в `scenarios/*.json`;
- исполнение идет через `src/mcp_workflow_runner.py`;
- каждый шаг вызывает MCP инструмент через `src/mcp_client.py`;
- для подготовки аргументов шага используется planner-агент с моделью через `polza.ai`.

## Требования

- Python 3.10+
- MCP endpoint (по умолчанию `http://127.0.0.1:8081/mcp`)
- доступ к модели через `polza.ai` (`POLZA_API_KEY`)

## Текущая структура

```text
prisma_platform/
├── .env
├── .env.example
├── requirements.txt
├── scenarios/
│   ├── index.json
│   └── news_source_discovery/
│       ├── v1.json
│       └── v1_planner_repair.json
└── src/
    ├── __init__.py
    ├── api_routes.py
    ├── agent_os.py
    ├── agent_runner.py
    ├── mcp_client.py
    ├── mcp_workflow_runner.py
    ├── observability.py
    ├── scenario_store.py
    ├── step_planner.py
    ├── template.py
    └── schemas.py
```

## Установка

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

## Запуск

1) Поднимите MCP stub (из соседнего репозитория):

```bash
cd /home/worker/projects/docker-service/mcp-stub
docker compose up --build -d
```

2) Запустите сервер AgentOS:

```bash
cd /home/worker/projects/prisma_platform
.venv/bin/python -m src.agent_os
```

По умолчанию приложение доступно на `http://127.0.0.1:7777`.

Документация API:

- `http://127.0.0.1:7777/docs`
- `http://127.0.0.1:7777/redoc`

## HTTP API

### Запуск сценария (async)

`POST /api/runs` — планирует выполнение сценария и **сразу** возвращает `run_id`. Само выполнение идёт в фоне.

```bash
curl -s -X POST "http://127.0.0.1:7777/api/runs" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "news_source_discovery_v1",
    "input": { "url": "https://example.com/news" }
  }'
```

Ответ (`202 Accepted`):

```json
{
  "run_id": "f3d9…",
  "scenario_id": "news_source_discovery_v1",
  "status": "queued",
  "input": { "url": "..." },
  "started_at": "2026-04-24T..."
}
```

### Снапшот состояния

`GET /api/runs/{run_id}` — текущее состояние: `status` (`queued|running|success|failed`), список `steps` со статусами (`success|failed|skipped|queued`), `result` и `output_summary` при завершении.

### Live-прогресс (SSE)

`GET /api/runs/{run_id}/events` — Server-Sent Events. Поздние подписчики получают replay уже накопленных событий, затем tail до завершения.

```bash
curl -N http://127.0.0.1:7777/api/runs/$RUN_ID/events
```

Типы событий:

- `run_started` — `{run_id, scenario_id, started_at}`
- `step_started` — `{run_id, step_name, index, started_at}`
- `step_finished` — `{run_id, step_name, index, status, started_at, finished_at, message}`
- `run_finished` — `{run_id, status, finished_at, message}` (терминальное, поток закрывается)

### Каталоги

- `GET /api/scenarios` — список сценариев с метаданными (`scenario_id`, `name`, `description`, `input_schema`).
- `GET /api/scenarios/{scenario_id}` — полное определение сценария (для визуализации графа в UI).
- `GET /api/tools` — MCP tool catalog: `[{name, description, input_schema}]` (проксируется на `MCP_BASE_URL`).

## Переменные окружения

Agent:

- `AGENT_ID` (default: `prisma-agent`)
- `AGENT_MARKDOWN` (default: `false`)
- `AGENT_DEBUG_MODE` (default: `true`)
- `AGENT_INSTRUCTIONS`
- `OLLAMA_MODEL_ID` (default: `gemma4:31b`)
- `OLLAMA_HOST` (default: `http://localhost:11435`)
- `OLLAMA_TEMPERATURE` (default: `0`)

API runtime:

- `AGENT_OS_HOST` (default: `127.0.0.1`)
- `AGENT_OS_PORT` (default: `7777`)

Planner:

- `PLANNER_ENABLED` (default: `false`)
- `PLANNER_REPAIR_ATTEMPTS` (default: `3`)

Planner model (`polza.ai`):

- `POLZA_BASE_URL` (default: `https://api.polza.ai/v1`)
- `POLZA_MODEL_ID` (default: `google/gemma-4-31b-it`)
- `POLZA_API_KEY` (required)
- `POLZA_TEMPERATURE` (default: `0`)

MCP:

- `MCP_BASE_URL` (default: `http://127.0.0.1:8081/mcp`)
- `MCP_TIMEOUT_SECONDS` (default: `10`)

Runtime caches:

- `WORKFLOW_CACHE_MAX_SIZE` (default: `64`) — лимит LRU кэша построенных workflow.
- `RUN_REGISTRY_MAX_SIZE` (default: `200`) — лимит LRU истории run'ов в памяти.

Phoenix tracing:

- `PHOENIX_TRACING_ENABLED` (default: `false`)
- `PHOENIX_COLLECTOR_ENDPOINT` (default: `http://localhost:6006`)
- `PHOENIX_PROJECT_NAME` (default: `prisma-platform`)

## Phoenix трассировка (локально)

1) Включите трассировку в `.env`:

```dotenv
PHOENIX_TRACING_ENABLED=true
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PHOENIX_PROJECT_NAME=prisma-platform
```

2) Запустите приложение:

```bash
.venv/bin/python -m src.agent_os
```