From 00b6c0b2328989d14b3ff81abbe0659d91d4bb32 Mon Sep 17 00:00:00 2001 From: Roger Date: Fri, 7 Aug 2026 08:48:52 +0000 Subject: [PATCH] SPEC-052: document delivered sandbox + how it works + pendencies --- ...PEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md | 197 +++++++++++++++--- 1 file changed, 163 insertions(+), 34 deletions(-) diff --git a/specs/052-trade-spec-exit-to-base-sandbox/SPEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md b/specs/052-trade-spec-exit-to-base-sandbox/SPEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md index 6c8c340..b358750 100644 --- a/specs/052-trade-spec-exit-to-base-sandbox/SPEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md +++ b/specs/052-trade-spec-exit-to-base-sandbox/SPEC-052-TRADE-SPEC-EXIT-TO-BASE-SANDBOX.md @@ -3,14 +3,64 @@ **SPEC-ID:** 052-MYVEXX **Vincula:** 049, 050, 051 **Org Forgejo:** `myvexx` (≠ ligbox) -**Status:** 🧪 Sandbox paper (2026-08-05) +**Status:** ✅ Sandbox paper operacional (actualizado 2026-08-07) **Para:** Roger +**Runtime:** CT124 (`invest.myvexx.com`) · Bridge `:3100` · OpenAlice `:47331` -## Objectivo +--- -Permitir: escolher índice/crypto → Alice investiga → **spec no Invest** (alvo, alavancagem simulada, modo de saída) → motor monitoriza → ao atingir alvo **fecha e volta à conta base** (paper). +## 1. Objectivo -## Contrato da Spec (Invest) +Escolher índice/crypto → (opcional) Alice investiga → **spec no Invest** (alvo, alavancagem simulada, modo de saída) → motor monitoriza → ao atingir alvo **fecha e volta à conta base** (paper). + +Fluxo: + +```text +Activo → OpenAlice (investigar) → Spec no Invest/bridge + ↓ + tick_live (preço real Yahoo) ou simulate + ↓ + alvo +1,20%? → aviso | semi | auto_paper → conta base +``` + +--- + +## 2. O que foi realizado (changelog) + +| Data | Entrega | Estado | +|------|---------|--------| +| 2026-08-05 | Motor sandbox no bridge (`sandbox.py`) | ✅ | +| 2026-08-05 | API criar/listar/tick/simulate/confirm_close | ✅ | +| 2026-08-05 | Testes dos 3 modos (aviso / semi / auto_paper) | ✅ | +| 2026-08-05 | **Opção 2:** `tick_live` + `markets/quote` (Yahoo) | ✅ | +| 2026-08-05 | UI Invest `/agents` (criar specs, OpenAlice link) | ✅ | +| 2026-08-05 | `GET /architecture` no bridge | ✅ | +| 2026-08-05 | Docs + Forgejo `myvexx/invest-myvexx` + vault | ✅ | + +### Ficheiros principais (CT124) + +| Path | Papel | +|------|--------| +| `/opt/invest/agents/bridge/main.py` | API bridge v0.2 | +| `/opt/invest/agents/bridge/sandbox.py` | Motor de specs / saída | +| `/opt/invest/agents/bridge/markets.py` | Quotes Yahoo (Index Hub mínimo) | +| `/opt/invest/invest.myvexx.com/frontend/src/pages/Agents.js` | UI `/agents` | +| `/opt/invest/agents/docs/ARCHITECTURE-INVEST-OPENALICE-OPTION2.md` | Diagrama arquitectura | + +### URLs + +| URL | Função | +|-----|--------| +| https://invest.myvexx.com/agents | UI specs paper | +| https://invest.myvexx.com/api/agents/health | Health bridge | +| https://invest.myvexx.com/api/agents/sandbox/specs | Specs API | +| https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA | Cotação real | +| https://openalice.myvexx.com/ | Investigação Alice | +| https://git.spec.ligbox.com.br/myvexx/invest-myvexx | Specs no Forgejo | + +--- + +## 3. Contrato da Spec (Invest / bridge) ```json { @@ -21,56 +71,135 @@ Permitir: escolher índice/crypto → Alice investiga → **spec no Invest** (al "leverage_sim": 1.0, "exit_mode": "aviso|semi|auto_paper", "stop_pct": null, - "fill_timeout_sec": 300, - "on_fill_fail": "abort_alert" + "note": "opcional" } ``` - `target_pct` = **+1,20%** sobre `entry_price` (lucro percentual). -- `leverage_sim` = factor só para P&L **simulado** (não broker live). -- `exit_mode`: ver tabela abaixo. +- `leverage_sim` = factor só para P&L **simulado**. +- `asset_class`: `equity` | `crypto` | `index` | `fx` (aliases: BTC→BTC-USD, SPX→^GSPC, IBOV→^BVSP…). -## Modos de saída (aplicar todos) +### Estados -| Modo | Comportamento sandbox | -|------|------------------------| +| Status | Significado | +|--------|-------------| +| `watching` | A monitorizar | +| `alerted` | Alvo atingido (modo aviso) | +| `ready_to_close` | Alvo atingido (modo semi — falta confirm) | +| `closed_to_base` | Fechado / voltou à base | +| `aborted` | Stop hit | + +--- + +## 4. Modos de saída + +| Modo | Comportamento | +|------|----------------| | **aviso** | Ao alvo → `alerted`; não fecha sozinho | -| **semi** | Ao alvo → `ready_to_close`; exige `POST .../confirm_close` | -| **auto_paper** | Ao alvo → fecha já → `closed_to_base` | +| **semi** | Ao alvo → `ready_to_close`; `POST .../confirm_close` | +| **auto_paper** | Ao alvo → `closed_to_base` automático | -Live broker: **proibido** neste bridge (`ALLOW_LIVE_BROKER=0`). +Live broker: **proibido** (`ALLOW_LIVE_BROKER=0`). -## Constraints (o “não realista” → regras) +--- -1. Alvo % = trigger, não garantia de fill. -2. Alavancagem = simulada até paper broker explícito. -3. Auto só em paper; live = degrau futuro + gate humano. -4. Spec no Invest/bridge = fonte da verdade (Alice lê, não inventa). -5. Equity vs crypto = mesmo contrato, adapters depois. -6. Polling sandbox; websocket = Fase B+. +## 5. Como funciona (passo a passo) -## API sandbox (bridge `:3100`) +1. Login em `invest.myvexx.com` → menu **Agents / Specs**. +2. (Opcional) **Abrir OpenAlice** e investigar o activo. +3. **Cotação real → entrada** (Yahoo via bridge). +4. Definir alvo `%`, alavancagem sim, modo de saída → **Criar spec paper**. +5. **tick_live** = puxa preço real e aplica regras; **simulate** = sobe preço artificial até ao alvo. +6. Se `semi` → **confirm_close**. Se `auto_paper` → já fica `closed_to_base`. + +### API (Traefik strip `/api/agents` → bridge `:3100`) | Método | Path | Função | |--------|------|--------| +| GET | `/health` | Saúde + contagem specs | +| GET | `/architecture` | Diagrama/fluxo opção 2 | +| GET | `/markets/quote?symbol=&asset_class=` | Preço real Yahoo | | POST | `/sandbox/specs` | Criar spec | | GET | `/sandbox/specs` | Listar | | GET | `/sandbox/specs/{id}` | Detalhe | -| POST | `/sandbox/specs/{id}/tick` | Actualizar preço (manual) | -| POST | `/sandbox/specs/{id}/simulate` | Simular path até alvo | +| POST | `/sandbox/specs/{id}/tick` | Preço manual | +| POST | `/sandbox/specs/{id}/tick_live` | **Opção 2** — preço real | +| POST | `/sandbox/specs/{id}/simulate` | Path artificial até alvo | | POST | `/sandbox/specs/{id}/confirm_close` | Semi: confirmar fecho | -Traefik: `https://invest.myvexx.com/api/agents/sandbox/...` (strip `/api/agents`). +### Teste rápido (CLI) -## Critério de done (sandbox) +```bash +# cotação +curl -sk 'https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA' -1. Criar spec NVDA alvo 1,20% modo `auto_paper`. -2. `simulate` sobe preço ≥ +1,20%. -3. Estado final `closed_to_base` + `pnl_pct` ≥ 1,20. -4. Modos `aviso` e `semi` testados no mesmo motor. +# criar + tick real +curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs \ + -H 'Content-Type: application/json' \ + -d '{"symbol":"NVDA","entry_price":221.0,"target_pct":1.20,"exit_mode":"aviso"}' -## Fora de escopo 052 +curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs//tick_live +``` -- Ordem live / UTA funded -- UI React completa `/agents` (pode seguir em paralelo Fase A 051) -- Fork profundo OpenAlice (bridge consome specs; Alice UI depois) +--- + +## 6. Arquitectura (opção 2) + +```text +invest.myvexx.com/agents + │ /api/agents/* + ▼ +Bridge :3100 ── markets/quote (Yahoo) + │ sandbox motor (alvo / saída) + │ research TradingAgents (opcional) + ▼ +OpenAlice :47331 — investigação / workspace (paper) +``` + +Detalhe: `ARCHITECTURE-INVEST-OPENALICE-OPTION2.md`. + +--- + +## 7. Constraints + +1. Alvo % = trigger, não garantia de fill. +2. Alavancagem = simulada (não broker). +3. Auto só em paper; live = futuro + gate humano. +4. Spec no Invest/bridge = fonte da verdade. +5. Equity/crypto = mesmo contrato; adapters depois. +6. Polling / tick manual; websocket = depois. + +--- + +## 8. Critério de done — sandbox (cumprido) + +| # | Critério | Resultado | +|---|----------|-----------| +| 1 | Spec NVDA alvo 1,20% `auto_paper` | ✅ | +| 2 | `simulate` ≥ +1,20% | ✅ `closed_to_base` | +| 3 | Modos `aviso` e `semi` | ✅ | +| 4 | `tick_live` com preço Yahoo | ✅ | +| 5 | UI `/agents` | ✅ | + +--- + +## 9. Pendente / próximo (fora do done 052) + +| Item | Notas | +|------|--------| +| LLM key TradingAgents | Research real (`dry_run:false`) | +| OpenAlice Claude/Codex OAuth | Agents a falar no container | +| Monitor automático (cron/loop) | Hoje tick é manual na UI | +| Alice ler spec via bridge | Sync Invest → workspace Alice | +| Index Hub completo (051 Fase B) | Histórico OHLC, +providers, cache KPI | +| SSO cookie OpenAlice | Ainda token admin separado | +| Paper broker real (Alpaca paper) | Só se ligar UTA — nunca live | +| Live trading | **Fora de escopo** até SPEC explícita | + +--- + +## 10. Fora de escopo permanente (até nova SPEC) + +- Ordem live / UTA com fundos reais +- Unificar senha Invest = token OpenAlice +- Patch OpenAlice para password fraca