Serviço de execução de código Python em subprocessos protegidos com análise heurística inteligente e chat contextual para resolução de bugs.
O PyFlow é uma API local desenvolvida por Alex Santos para viabilizar a execução segura de trechos de código Python solicitados por agentes ou interfaces gráficas. Em vez de rodar o código no processo principal com chamadas perigosas a `eval()` ou `exec()`, o PyFlow gera subprocessos descartáveis com limites rígidos de tempo e captura de stdout/stderr. Se ocorrer uma exceção não tratada, seu motor analisa a árvore sintática do traceback e invoca múltiplos provedores de IA para oferecer explicações claras e patches de correção.
Visão macro de como o projeto processa requisições, gerencia dados e entrega valor técnico com máxima eficiência.
+-----------------------+ +---------------------------+ +------------------------+
| Cliente (IDE / WebUI /| HTTP | PyFlow | fork | Subprocesso Python |
| Agente de Automação) | ===> | (FastAPI Async Controller)| ===> | (Isolado / Timeout) |
+-----------------------+ +---------------------------+ +------------------------+
| |
| <======== Captura Stdout/Stderr +
| (ou Traceback Exception)
v
+---------------------------+
| Motor de Diagnóstico AI |
| (Análise AST + Sugestões) |
+---------------------------+Decisões de design, algoritmos e técnicas aplicadas para garantir confiabilidade, segurança e excelência operacional.
Cada requisição de código é empacotada e despachada para um interpretador Python em processo separado via `asyncio.create_subprocess_exec`. É aplicado um timeout estrito (ex: 5 segundos por padrão), impedindo que laços infinitos como `while True: pass` ou chamadas bloqueantes congelem o servidor principal.
O PyFlow lê os streams de saída de maneira assíncrona, acumulando os logs em um buffer delimitado. Se o script testado tentar emitir milhões de linhas em loop, o buffer trunca graciosamente a saída, alertando o usuário sobre o limite de caracteres alcançado.
Ao interceptar erros como `KeyError`, `IndexError` ou `AttributeError`, o PyFlow contextualiza a linha exata do código onde a falha ocorreu e consulta o modelo de IA configurado para sugerir a correção mínima necessária.
Por utilizar FastAPI, o PyFlow disponibiliza automaticamente esquemas OpenAPI interativos (`/docs`), facilitando seu consumo por bibliotecas client em Python, JavaScript ou como MCP tool corporativa.
Exemplo concreto de uso, configuração e integração técnica.
import httpx
payload = {
"code": "valores = [10, 20, 30]\nprint(valores[5])",
"timeout": 3.0,
"ai_diagnosis": True
}
response = httpx.post("http://localhost:8000/execute", json=payload)
resultado = response.json()
# Retorno estruturado:
# {
# "status": "error",
# "exit_code": 1,
# "stderr": "IndexError: list index out of range",
# "diagnosis": "O código tentou acessar o índice 5 de uma lista que possui apenas 3 elementos (índices 0 a 2)."
# }Esclarecimentos detalhados sobre funcionamento, licenças, compatibilidade e privacidade.
Para ambientes multi-tenant de alto risco na nuvem, recomenda-se containers gVisor/Docker. O PyFlow é otimizado para desenvolvedores locais e agentes em máquinas de desenvolvimento.
Suporta qualquer endpoint compatível com OpenAI, além de Google Gemini e modelos locais via Ollama.
Por motivos de segurança e determinismo, os scripts utilizam os pacotes instalados no ambiente virtual do interpretador Python apontado pelo servidor.
Sim, o endpoint /ws/execute permite transmitir linhas de stdout e stderr em tempo real para dashboards e terminais web.