marcocosta10000
67e8df36ce
Initial implementation of MultiAgentsAI featuring: - Dynamic agent configuration via environment variables - SQLite database and JSON daily context storage - OpenRouter API integration for multiple AI models - Telegram bot with commands for control, history, and interaction - Autonomous conversation loop with pause/resume and agent silencing - Model testing and statistics commands
107 lines
4.6 KiB
Markdown
Executable File
107 lines
4.6 KiB
Markdown
Executable File
# RULES.md — Regras para IA Codificar no MultiAgentsAI
|
|
|
|
> **Autor:** Marco Costa — [www.syspanel.com.br](https://www.syspanel.com.br)
|
|
> **Criado em:** Setembro de 2026
|
|
|
|
Este arquivo define as regras que qualquer IA (incluindo agentes do próprio sistema) deve seguir ao modificar ou criar código dentro deste projeto.
|
|
|
|
---
|
|
|
|
## 1. Propriedade do Código
|
|
|
|
- Todo arquivo `.py` criado por uma IA deve conter o comentário `# Gerado por IA` na primeira linha, após o docstring ou shebang se houver.
|
|
- Nunca apagar comentários existentes sem justificativa explícita no commit.
|
|
|
|
## 2. Estrutura de Pastas
|
|
|
|
- Código fonte fica em `app/`.
|
|
- Scripts de shell ficam na raiz de `app/`.
|
|
- Dados gerados (SQLite, JSONs) ficam em `app/Contexts/` ou na raiz de `app/`.
|
|
- Nunca coloque arquivos `.env` ou com credenciais no versionamento.
|
|
- Nunca crie pastas novas sem necessidade explícita.
|
|
|
|
## 3. Convenções de Código Python
|
|
|
|
- Python 3.10+ mínimo.
|
|
- Type hints obrigatórios em funções públicas e métodos de classe.
|
|
- Docstrings em todas as classes e funções públicas (formato Google ou reStructuredText).
|
|
- Sem comentários inline desnecessários.
|
|
- Sem prints de debug deixados no código final.
|
|
- Tratamento de exceções explícito; nunca usar `except: pass` genérico.
|
|
- Constantes em `UPPER_SNAKE_CASE`, variáveis em `snake_case`, classes em `PascalCase`.
|
|
- Importações agrupadas: stdlib → terceiros → locais, separadas por uma linha em branco.
|
|
|
|
## 4. Configuração e Variáveis de Ambiente
|
|
|
|
- Toda configuração deve vir do arquivo `.env` carregado por `python-dotenv`.
|
|
- NUNCA hardcodar chaves de API, tokens ou credenciais.
|
|
- Variáveis novas no `.env` devem ser documentadas no `README.md` na tabela de variáveis.
|
|
|
|
## 5. Banco de Dados (SQLite)
|
|
|
|
- Usar `sqlite3.Row` como row_factory para acessar colunas por nome.
|
|
- Toda query parametrizada com `?` — nunca concatenar strings em SQL.
|
|
- Migrações de schema: se alterar a estrutura do banco, adicionar uma função `migrate_db()` em `database.py` chamada por `init_db()`.
|
|
- Nunca usar `DROP TABLE` sem backup explícito.
|
|
|
|
## 6. Manipulação de Contexto
|
|
|
|
- O arquivo JSON diário em `Contexts/` é a fonte da verdade para o contexto dos agentes.
|
|
- Toda mensagem de agente deve ser salva via `append_to_context()` (que grava no JSON e no SQLite simultaneamente).
|
|
- Nunca ler o JSON diretamente — sempre usar as funções de `context_manager.py`.
|
|
- O nome do arquivo JSON deve seguir o padrão `conversas_YYYY-MM-DD.json`.
|
|
|
|
## 7. API OpenRouter
|
|
|
|
- Toda chamada à API OpenRouter deve passar por `AIAgent.generate_response()` em `ai_agent.py`.
|
|
- Headers obrigatórios: `Authorization`, `Content-Type`, `HTTP-Referer`, `X-Title`.
|
|
- Timeout mínimo de 60 segundos.
|
|
- Respostas com erro devem retornar `[Erro ao gerar resposta por {nome}: {erro}]` — nunca lançar exceção para o caller.
|
|
|
|
## 8. Telegram Bot
|
|
|
|
- Toda resposta ao usuário no Telegram deve usar `_send_telegram()` de `telegram_bot.py`.
|
|
- Nunca chamar `python-telegram-bot` diretamente em outros módulos.
|
|
- Novos comandos devem ser adicionados como funções assíncronas com prefixo `cmd_` e registrados em `build_bot()`.
|
|
|
|
## 9. Orquestrador
|
|
|
|
- O loop principal está em `Orchestrator.run()` em `orchestrator.py`.
|
|
- O delay entre mensagens é controlado por `settings.CONVERSATION_DELAY` (segundos).
|
|
- A referência global `_orchestrator_ref` em `orchestrator_shared.py` é usada para pausar/retomar via comandos Telegram — nunca removê-la sem substituir por mecanismo equivalente.
|
|
- O sistema só para com `KeyboardInterrupt` (Ctrl+C) ou `self._running = False`.
|
|
|
|
## 10. Arquivos Gerados
|
|
|
|
Nunca commitar:
|
|
- `.env` (credenciais)
|
|
- `venv/` (ambiente virtual)
|
|
- `agents.db` (banco de dados local)
|
|
- Arquivos em `Contexts/` com dados reais de conversas
|
|
|
|
Esses arquivos devem estar listados no `.gitignore`.
|
|
|
|
## 11. Segurança
|
|
|
|
- Nunca logar chaves de API, tokens ou senhas.
|
|
- Validar entradas de usuário antes de enviar para a API.
|
|
- Limitar `max_tokens` em chamadas à API para evitar custos excessivos.
|
|
- Sanitizar texto antes de exibir no Telegram (evitar injeção de HTML malicioso).
|
|
|
|
## 12. Testes
|
|
|
|
- Qualquer nova função pública deve ter ao menos um teste básico.
|
|
- Testes ficam em `tests/` (criar a pasta se necessário).
|
|
- Usar `pytest` como framework de testes.
|
|
|
|
## 13. Commits
|
|
|
|
- Mensagens de commit em português, imperativo, curtas.
|
|
- Formato: `tipo: descrição curta`
|
|
- `feat:` nova funcionalidade
|
|
- `fix:` correção de bug
|
|
- `refactor:` refatoração sem mudança de comportamento
|
|
- `docs:` alteração em documentação
|
|
- `chore:` alterações de configuração, dependências
|
|
- Nunca commitar com `--amend` sem antes verificar o diff.
|