Oryntra AGENTS.md

AGENTS.md

Regras de projeto pra agentes de IA (Claude Code, Cursor, Copilot). Leitura obrigatória antes de qualquer tarefa.

Produto

Oryntra — plataforma open-source de agentes LLM pra Chatwoot. Painel Laravel/Filament + runtime Python/LangGraph. Multi-tenant via workspace_id. Detalhes completos em README.md.

Stack fixada

• Laravel 13 + PHP 8.3
• Filament 3 (admin painel + multi-tenancy)
• Fortify (auth: 2FA, recovery codes, password confirmation)
• Shield (roles/permissions Filament)
• Horizon + Redis (queues)
• Reverb (WebSocket real-time)
• Pail + Telescope (observabilidade dev)
• Spatie ActivityLog (audit)
• Pest (testes Laravel)
• Pint + Larastan level 8 + Rector (code quality)
• Postgres + pgvector (banco + embeddings)
• MinIO (S3-compatible storage)
• Python 3.12 + FastAPI + LangGraph (runtime de agente, privado)
• uv (gerenciador Python), ruff + mypy (Python quality), pytest
• Docker Compose (dev e prod)

Estrutura do monorepo

/                     # raiz: docs, docker, configs
├── laravel/          # app Laravel
├── agent-python/     # serviço Python privado
├── docker/           # Dockerfiles e configs
├── docs/             # docs, ADRs, runbooks, OpenAPI
└── .github/          # CI workflows

Comandos comuns

docker compose up -d                                # subir stack
docker compose exec laravel-app php artisan migrate
docker compose exec laravel-app php artisan make:filament-user
docker compose exec laravel-app php artisan pail   # tail logs
docker compose exec laravel-app ./vendor/bin/pest
docker compose exec laravel-app ./vendor/bin/pint
docker compose exec laravel-app ./vendor/bin/phpstan analyse
docker compose exec agent-python pytest
docker compose exec agent-python ruff check .
docker compose exec agent-python mypy src/

Regras de arquitetura (críticas)

1. Python nunca exposto publicamente. Acessível só pela rede interna Docker via http://agent-python:8000. Toda chamada exige header X-Internal-Token.
2. workspace_id em toda query de negócio. Sem exceção. Tabela sem workspace_id = bug de tenancy.
3. Tokens criptografados. API tokens Chatwoot, chaves LLM, recovery codes — sempre cast encrypted.
4. Idempotência por chatwoot_message_id. Webhooks repetidos não geram resposta duplicada.
5. Lock por conversation_id. Duas respostas simultâneas pra mesma conversa = bug.
6. Embeddings só no Python. Laravel nunca chama API de embedding direto.
7. BYOK (Bring Your Own Key). Workspace cadastra própria chave OpenAI/Anthropic/Gemini. Plataforma não cobra LLM.
8. thread_id do LangGraph composto: workspace:{ws_id}:account:{account_id}:conversation:{conv_id}.