Docs

# DEFINIÇÃO BASE DO PROJETO SELF_V2

## 1. Fonte de verdade

### 1.1 O que vem do `self`
Do projeto `self`, o `self_v2` herda apenas:

- definições da base de dados
- configuração de providers / models / secret refs / API keys
- checklists e documentos operacionais pedidos pelo utilizador
- definição funcional do chat e da interação por agentes

### 1.2 O que não vem do `self`
Não migrar do `self`:

- código
- estrutura de runtime
- classes
- admin atual
- api atual
- webchat atual
- backups
- remendos
- ficheiros legacy

### 1.3 Papel de cada projeto
- `self` = referência mínima (BD, providers, checklists, definição funcional)
- `self_llm` = blueprint estrutural / intenção do sistema
- `self_v2` = implementação nova, limpa, modular e coerente
- 


## 2. O que foi confirmado em `self_llm`

### 2.1 Papel do `self_llm`
O `self_llm` deve ser tratado como blueprint estrutural do sistema.

Foi concebido como plataforma de automação conversacional baseada em LLM, com estes componentes principais:

- WebChat
- Canvas Workspace
- Core Engine
- Tools System
- Executors
- Planner
- Auditoria global
- Integração MCP

### 2.2 Estrutura prevista no blueprint
Estrutura base prevista:

- `config/`
- `core/`
- `database/`
- `tools/`
- `executors/`
- `devices/`
- `llm/`
- `audit/`
- `events/`
- `api/`
- `admin/`
- `public/`
- `projects/`
- `docs/`
- `install/`
- `bootstrap/`

### 2.3 Conclusão
O `self_llm` é a base de arquitetura e intenção do sistema, não a base de runtime a copiar diretamente.





## 3. Regras funcionais dos agentes

### 3.1 Regra principal
- **Tozé** é o agente por defeito
- **Sara** só responde quando:
  - é chamada explicitamente
  - ou é selecionada no chat

### 3.2 Regra MCP
Quando o MCP server está ligado ao ChatGPT:

- o ChatGPT faz a vez do **Tozé**
- a **Sara** mantém-se disponível
- o comportamento default do Tozé passa a ser servido via MCP/ChatGPT

Quando o MCP não está ligado:

- o Tozé volta a ser o default local

### 3.3 Implicações
No chat tem de existir:

- um agente default global
- override por seleção manual
- override por chamada explícita no texto
- indicação visível do agente ativo
- possibilidade de trocar modelo por agente
- 





## 4. Agents e providers

### 4.1 Regras dos agents
A configuração de agents deve incluir, no mínimo:

- nome
- provider
- modelo default
- estado ativo/inativo
- estado default/non-default
- regras de seleção no chat
- eventual mapeamento MCP para o papel do Tozé

### 4.2 Regras de carregamento no chat
O chat, ou browser do chat, deve carregar apenas agents que estejam:

- configurados
- ativos

### 4.3 Persistência do agent ativo
Se o utilizador escolher manualmente um agent, esse agent ativo deve ficar persistente até ser alterado.

### 4.4 Providers base
Os providers base a considerar são:

- OpenAI
- Gemini
- Ollama
- Custom

### 4.5 Modelos por agent
Cada agent deve permitir:

- seleção de provider
- seleção de modelo
- ativação/desativação
- definição como default ou não

No chat, cada agent deve permitir seleção do modelo via dropdown.



## 5. Regra específica Tozé / Sara

### 5.1 Tozé
O Tozé é o agent principal por defeito.

### 5.2 Sara
A Sara é um agent separado e só responde quando:

- é chamada explicitamente
- ou é selecionada manualmente no chat

### 5.3 MCP
Quando o MCP estiver ligado:

- o ChatGPT substitui funcionalmente o Tozé
- a Sara continua separada e disponível
- o utilizador continua a poder selecionar a Sara

### 5.4 Modelos por agent
Cada agent deve ter o seu próprio dropdown de modelos no chat.





## 5. Regra específica Tozé / Sara

### 5.1 Tozé
O Tozé é o agent principal por defeito.

### 5.2 Sara
A Sara é um agent separado e só responde quando:

- é chamada explicitamente
- ou é selecionada manualmente no chat

### 5.3 MCP
Quando o MCP estiver ligado:

- o ChatGPT substitui funcionalmente o Tozé
- a Sara continua separada e disponível
- o utilizador continua a poder selecionar a Sara

### 5.4 Modelos por agent
Cada agent deve ter o seu próprio dropdown de modelos no chat.






## 6. Definição do chat

### 6.1 Objetivo visual e funcional
O chat deve ter comportamento e ergonomia semelhantes ao ChatGPT.

### 6.2 Posicionamento das mensagens
- mensagens do utilizador do lado direito
- mensagens do LLM do lado esquerdo

### 6.3 Informação por mensagem
Cada mensagem enviada e recebida deve mostrar:

- data
- hora

### 6.4 Ações nas mensagens
Deve ser possível clicar para copiar mensagens do LLM.

### 6.5 Input
- `Shift + Enter` = nova linha
- `Enter` = enviar mensagem

### 6.6 Foco
Ao clicar em qualquer parte do chat que não seja uma ação específica como copiar/código, o foco deve voltar à input box.

### 6.7 Visual
A formatação visual do chat deve ser semelhante ao ChatGPT.




## 7. Estrutura do ecrã

### 7.1 Layout principal
O sistema deve ter split screen:

- lado esquerdo = chat
- lado direito = workspace / browser interno

### 7.2 Lado esquerdo
O lado esquerdo deve incluir:

- sidebar de conversas
- painel principal de mensagens
- barra de agents no topo
- dropdown de modelos por agent
- botões rápidos / chat actions
- input
- botão Send

### 7.3 Lado direito
O lado direito deve incluir:

- workspace
- tabs tipo browser
- área de visualização de páginas internas/externas

### 7.4 Divider
A largura do chat deve ser redimensionável.





## 8. Tabs / browser interno

### 8.1 Regras gerais
Ao lado do chat deve existir um sistema de separadores tipo browser.

### 8.2 Tab base
- deve existir um separador base por defeito
- esse separador base é o admin interno do próprio sistema
- esse separador base não pode ser fechado

### 8.3 Restantes tabs
- os outros separadores podem ser abertos
- os outros separadores podem ser fechados
- todos os separadores devem ter refresh independente
- cada separador deve manter URL/estado próprio
- 



## 9. Persistências

### 9.1 Persistências obrigatórias
Devem ficar persistentes:

- conversa ativa
- largura do chat
- agent ativo escolhido pelo utilizador
- tabs abertas
- estado/url de cada tab
- modo claro/escuro

### 9.2 Objetivo
Ao recarregar a interface, o utilizador deve recuperar o seu contexto de trabalho.





## 10. Modo visual

### 10.1 Modo claro/escuro
Deve existir:

- modo claro
- modo escuro
- persistência da preferência escolhida

### 10.2 Fullscreen
Deve existir botão de fullscreen.

### 10.3 Objetivo visual
O chat e o admin devem ter aspeto moderno, limpo, premium e operacional.







## 11. Chat actions / botões rápidos

### 11.1 Regras gerais
O chat deve ter botões rápidos configuráveis.

### 11.2 Campos mínimos
Cada chat action deve permitir:

- label
- tipo de ação
- comando/prompt
- posição
- enabled/disabled

### 11.3 Tipos esperados
Os tipos devem suportar pelo menos:

- `prompt`
- `macro`
- `memory_paste_send`
- `client_action`
- `open_tab`
- `system_action`

### 11.4 Paste + Send
Deve existir uma ação especial `Paste + Send` que:

- vai buscar conteúdo à memória
- cola esse conteúdo no input/chat
- envia automaticamente para o chat
- 



## 12. Admin

### 12.1 Localização
O admin fica na raiz do projeto.

### 12.2 Papel
O admin é o centro de controlo do sistema e também a tab base fixa do workspace.

### 12.3 Áreas mínimas do admin
O admin deve ter, no mínimo:

- dashboard
- agents
- providers
- models
- routing/defaults
- chat actions
- chat layout config
- MCP settings/status
- database / install status
- docs / checklists

### 12.4 Estilo visual
O admin deve seguir uma linguagem visual moderna, inspirada em dashboards premium com:

- sidebar forte
- topo operacional
- cartões de métricas
- navegação limpa
- boa hierarquia visual
- 


## 13. Base de dados

### 13.1 Origem
Do `self` devem ser herdados apenas:

- convenção de ligação à BD
- prefixo de instância / naming das tabelas
- tabelas necessárias para agents, settings e chat actions
- estruturas relacionadas com providers/models, se aplicável

### 13.2 Tabelas mínimas de referência
Tomar como referência pelo menos:

- settings
- llm_agents
- chat_actions
- conversations
- messages
- tools
- tool_runs
- audit

### 13.3 Regra
As definições da BD podem ser herdadas como referência, mas a implementação do `self_v2` deve ser nova e limpa.



## 14. Resumo funcional do `self_v2`

O `self_v2` será uma implementação nova, limpa e modular.

Herdará do `self` apenas:
- definições da base de dados
- configuração de providers/API keys/secrets
- checklists/documentos relevantes
- definição funcional do chat

Herdará do `self_llm`:
- intenção estrutural
- arquitetura base
- blueprint do sistema

Regras centrais:
- Tozé é o agent default
- Sara só responde por chamada explícita ou seleção
- com MCP ligado, o ChatGPT substitui o papel do Tozé
- Sara mantém-se separada
- chat com UX semelhante ao ChatGPT
- workspace lateral com tabs tipo browser
- admin como tab base fixa
- modelos selecionáveis por agent
- botões rápidos configuráveis
- Paste + Send ligado à memória
-