Roger 03818f6725 Vault: SPEC-052 full delivery notes

2026-08-07 08:48:54 +00:00

6.6 KiB

Raw Blame History

SPEC-052 — Invest Trade Specs + Alice Monitor + Exit-to-Base (paper sandbox)

SPEC-ID: 052-MYVEXX
Vincula: 049, 050, 051
Org Forgejo: myvexx (≠ ligbox)
Status: ✅ Sandbox paper operacional (actualizado 2026-08-07)
Para: Roger
Runtime: CT124 (invest.myvexx.com) · Bridge :3100 · OpenAlice :47331

1. Objectivo

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:

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)

{
  "symbol": "NVDA",
  "asset_class": "equity",
  "entry_price": 100.0,
  "target_pct": 1.20,
  "leverage_sim": 1.0,
  "exit_mode": "aviso|semi|auto_paper",
  "stop_pct": null,
  "note": "opcional"
}

target_pct = +1,20% sobre entry_price (lucro percentual).
leverage_sim = factor só para P&L simulado.
asset_class: equity | crypto | index | fx (aliases: BTC→BTC-USD, SPX→^GSPC, IBOV→^BVSP…).

Estados

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`; `POST .../confirm_close`
auto_paper	Ao alvo → `closed_to_base` automático

Live broker: proibido (ALLOW_LIVE_BROKER=0).

5. Como funciona (passo a passo)

Login em invest.myvexx.com → menu Agents / Specs.
(Opcional) Abrir OpenAlice e investigar o activo.
Cotação real → entrada (Yahoo via bridge).
Definir alvo %, alavancagem sim, modo de saída → Criar spec paper.
tick_live = puxa preço real e aplica regras; simulate = sobe preço artificial até ao alvo.
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`	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

Teste rápido (CLI)

# cotação
curl -sk 'https://invest.myvexx.com/api/agents/markets/quote?symbol=NVDA'

# 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"}'

curl -sk -X POST https://invest.myvexx.com/api/agents/sandbox/specs/<ID>/tick_live

6. Arquitectura (opção 2)

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

Alvo % = trigger, não garantia de fill.
Alavancagem = simulada (não broker).
Auto só em paper; live = futuro + gate humano.
Spec no Invest/bridge = fonte da verdade.
Equity/crypto = mesmo contrato; adapters depois.
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

6.6 KiB Raw Blame History