SPEC-052: document delivered sandbox + how it works + pendencies
This commit is contained in:
parent
ce4ba15d50
commit
00b6c0b232
1 changed files with 163 additions and 34 deletions
|
|
@ -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/<ID>/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
|
||||
|
|
|
|||
Loading…
Reference in a new issue