WriterAgent

WriterAgent, LibrePy & LibreHarper

Página de status de CI

Python, NumPy e IA Agêntica para LibreOffice (Writer, Calc e Draw)

Execute Python e computação científica offline em fórmulas de planilhas, edite documentos com IA privada local-first — sem dependência de nuvem.

O projeto é distribuído como três pacotes de extensão independentes (instale apenas um por vez):

Pacote	O que está incluído
🤖 WriterAgent (WriterAgent.oxt) (Pilha completa, recomendado para a maioria dos usuários)	Tudo no LibrePy e LibreHarper + barra lateral de IA, =PROMPT(), pesquisa na web, conversor Calc → Python, servidor MCP
🐍 LibrePy (LibrePy.oxt)	Runtime Python, =PY(), NumPy, pandas, SymPy, Monaco, Jupyter Arquivo → Abrir .ipynb, auxiliares de domínio, OCR (sem IA/MCP — build de núcleo para inclusão no LO)
✍️ LibreHarper (LibreHarper.oxt)	Mecanismo de gramática offline Harper independente para o Writer

Baixar versões .oxt · Índice de Recursos · Guia NumPy no LibreOffice · Discussões

---

Principais Capacidades

🤖 IA Agêntica Local-First e Escrita (Writer)

• Chat na Barra Lateral com Chamada de Ferramentas em Múltiplas Etapas — Edite, reestruture ou expanda documentos usando linguagem natural. 9 ferramentas principais além de dezenas de subagentes especializados para layout de página, notas de rodapé, marcadores, revisões e formulários.
• Interação de Voz Bidirecional (STT & TTS) — Dite comandos diretamente ao seu agente de documentos e ouça as respostas em voz alta (local via Kokoro ou Piper, ou via seu endpoint de LLM).
• Edições que Preservam Formatação — Revisões cirúrgicas e reescritas de seções mantêm sua formatação existente (negrito, itálico, realces, tamanhos de fonte, tabelas e listas aninhadas) sem sobrescrever estilos.
• Pesquisa na Web — Loop integrado e privado de smolagents com DuckDuckGo. Sintetiza múltiplas fontes web e atualiza documentos abertos com fatos e citações em tempo real. Busca do Agente
• Gramática e Revisão em Tempo Real — Verificação gramatical local e privada via Harper (rápida, auto-instalável), LanguageTool ou endpoints de LLM com detecção de frases em múltiplos idiomas. Detalhes
• Importação de Matemática & LaTeX — Converte LaTeX e MathML em objetos Math nativos e editáveis do LibreOffice. Guia de Matemática

🐍 Python & Computação Científica (Calc & Writer)

• Fórmulas de Planilha =PY() Nativas — Execute expressões Python, NumPy e pandas diretamente em células do Calc com derramamento automático de arrays, kernels compartilhados de pasta de trabalho e scripts persistentes.
  • =PY("np.mean(data)"; A1:A10) — Calcule estatísticas de arrays diretamente em intervalos do Calc.
  • =PY("data.to_pandas(date_cols=True)"; A1:C10) — Carregue dados de planilha em pandas com análise automática de tipos e datas.
  • Guia NumPy no LibreOffice · Formas de Dados & Mapeamento de Tipos
• Editor de Código Monaco Embutido — Escreva, teste e depure scripts Python de múltiplas linhas diretamente em células ou através do ambiente Ferramentas → Executar Script Python com realce de sintaxe, autocompletar e diagnósticos.
• Domínios Científicos e Analíticos Integrados — Auxiliares prontos para EDA, detecção de outliers, regressão OLS, agrupamento KMeans, simulações de Monte Carlo, álgebra simbólica (SymPy), plotagem e conversões de unidades físicas (convert_quantity(60, "mph", "m/s") → 26.8224 m/s). Referência de Domínios · Auxiliares de Análise
• Conversor Planilha → Python (WriterAgent) — Traduza mais de 235 fórmulas clássicas do Calc/Excel em expressões Python limpas usando a biblioteca de paridade calc.* integrada, preservando constantes, datas e formatos de célula. Detalhes
• Visão Local & OCR — Extraia texto de imagens embutidas ou documentos digitalizados diretamente para o Writer e Calc via OCR Docling offline. Guia de Visão
• Suporte a Jupyter Notebook — Arquivo → Abrir… um .ipynb (ou clique duplo / soffice notebook.ipynb) cria um documento do Writer com markdown, campos de código editáveis e botões ▶ de execução contra um kernel Python compartilhado. Jupyter no Writer
• Seguro contra falhas por design — NumPy executa fora do processo em seu próprio venv, então um bug de script não pode travar o LibreOffice.

📊 Diagramas, Slides & Multimodal (Draw & Impress)

• Geração de Diagramas e Apresentações — Gere, ajuste e estilize fluxogramas, formas, conectores, notas do apresentador e transições de slides através de comandos de chat ou scripts Python. Detalhes
• Criação e Edição de Imagens — Gere uma nova imagem a partir de um prompt, ou edite um gráfico selecionado no lugar, no mesmo endpoint do chat. Insere no Writer, Calc, Draw e Impress. Geração de Imagens
• Árvore Semântica LO-DOM — Compreensão estrutural de títulos, seções, tabelas e relacionamentos em documentos inteiros. Árvore Semântica
• Busca Entre Documentos & Memória — Consulte outros documentos na mesma pasta via embeddings locais / busca híbrida, com memória persistente do agente entre sessões. Embeddings · Memória

🔌 Integrações & Extensibilidade

• Servidor Model Context Protocol (MCP) — Conecte IDEs e agentes externos (Cursor, Claude Desktop, LM Studio) para ler e editar documentos abertos do LibreOffice via http://localhost:18765/mcp. Protocolo MCP
• Backends de Agente Plugáveis — Alterne o mecanismo de chat para agentes externos como Hermes, Claude Code, Mistral Vibe, Grok Build ou OpenCode via ACP. Plugin Cursor · Habilidade LO

Catálogo completo de capacidades: docs/features.md.

---

Instalação & Configuração

1. Baixe o pacote .oxt de sua escolha nas Últimas Versões e clique duas vezes para instalar (ou abra o LibreOffice e vá em Ferramentas → Gerenciador de Extensões → Adicionar). Lembre-se de instalar apenas um pacote de extensão.
2. Reinicie o LibreOffice.
3. Configuração Rápida:
   • Usuários de Python / LibrePy: Abra o Calc, verifique Ferramentas → LibrePy (ou WriterAgent) → Configurações → Python e clique em Testar para verificar seu ambiente e a disponibilidade de NumPy/pandas.
   • Usuários de IA / WriterAgent: Abra WriterAgent → Configurações e insira seu endpoint (ex.: http://localhost:11434 para Ollama local (sem necessidade de chave), ou uma chave de API OpenRouter / Together.AI). Abra a barra lateral via Exibir → Barra Lateral → WriterAgent ou pressione Ctrl+Q / Ctrl+E.

Modos de Interface: No modo clássico de barra de ferramentas, acesse as ferramentas pelo menu superior. Em interfaces com abas/faixa de opções, use a barra lateral de chat WriterAgent e/ou a barra lateral Python (Writer + Calc): Configurações ⚙, Python 🐍, matemática LaTeX ou Editar célula, busca 🔍 (apenas chat WriterAgent) e menus completos via ☰.

Para instruções detalhadas de configuração, consulte o Guia de Instalação e Solução de Problemas.

---

Demonstrações

Python no LibreOffice Writer

Análise de Planilhas & Painel

Hermes + Opus 4.6 (Pesquisa na Web)

Expressões Matemáticas & LaTeX

Currículo Arch Linux

Diagramas no Draw

---

Benchmarks & Avaliação

A Suíte de Avaliação de LLM Eval-1 do WriterAgent executa modelos em tarefas reais de Writer, Calc e Draw através das mesmas ferramentas que a barra lateral usa, e então pontua o documento exportado. Tarefas típicas: reformatar documentos, recalcular impostos, desenhar diagramas como a bandeira americana usando formas. Cada execução é classificada por Valor (correção² ÷ dólares). A tabela abaixo é o painel completo de dupla via 29×19 de 2026-09-28 (flag-18 + org_chart_gen, com substituições de galeria de organograma pontuadas manualmente — 5 PASS visuais difíceis). Metodologia completa: docs/eval/benchmarks.md.

Visualização de distância até a fronteira: docs/eval/pareto-distance.svg.

Modelo	Correção pontuação média por tarefa (0–1)	Valor Correção² ÷ $/tarefa
openai/gpt-oss-120b	0.921	803
openai/gpt-oss-20b	0.759	524
poolside/laguna-xs-2.1	0.838	358
upstage/solar-pro4	0.716	352
google/gemma-4-31b-it	0.861	330
google/gemma-4-26b-a4b-it	0.701	216
bytedance-seed/seed-2.0-mini	0.861	179
poolside/laguna-s-2.1	0.732	160
meta/muse-spark-1.3-contributor	0.981	147
openai/gpt-6-luna	0.873	139
z-ai/glm-5.3-flash	0.856	87
nvidia/nemotron-3.5-super-vl	0.932	82
liquid/lfm-2.5-24b-a2b	0.589	82
prism-ml/ternary-bonsai-2-27b	0.543	78
deepseek/deepseek-v4.1-flash	0.883	77
qwen/qwen3.8-flash	0.792	65
mistralai/mistral-small-2603	0.583	64
meta/muse-glimmer-30b	0.923	60
inception/mercury-2.5-preview	0.817	56
ibm-granite/granite-4.2-8b	0.810	55
google/gemini-3.5-flash-lite	0.708	49
nvidia/nemotron-3.5-lightning	0.395	46
nvidia/nemotron-3-super-120b-a12b	0.854	38
reflection/beam-1.0-501b-a23b	0.879	18
cohere/command-a-plus	0.641	13
minimax/minimax-m3	0.780	11
x-ai/grok-4.6	0.918	9
qwen/qwen3.8-27b	0.917	9
nvidia/nemotron-3-ultra-550b-a55b	0.787	4

---

Documentação & Arquitetura

Tópico	Link de Documentação
Índice de Recursos	docs/features.md
NumPy & Python no Calc	docs/enabling_numpy_in_libreoffice.md · docs/calc/py-data-shapes.md
Arquitetura Principal do LibrePy	docs/scripting/librepy-split.md
Funções Auxiliares de Domínio	docs/scripting/numpy-domains.md · docs/calc/analysis-tools.md
Arquitetura Completa	docs/writeragent-architecture.md · docs/framework/formal-verification.md
Model Context Protocol (MCP)	docs/mcp-protocol.md
Embeddings & Busca	docs/embeddings.md
Benchmarks	docs/eval/benchmarks.md
Localização (35 Locais)	docs/framework/localization.md
Explorador de Código	DeepWiki
Cursor / Habilidades de Agente	cursor-libreoffice · libreoffice-skill

Nos bastidores, todas as operações são governadas por uma máquina de estados finita formalmente verificada, com verificação estrita de tipos e análise estática. Chamadas UNO não seguras para threads são detectadas em desenvolvimento via um proxy viral de proteção de thread, em vez de congelamentos aleatórios. A suíte de barra lateral com LLM simulado — o pior LLM do mundo — prova a recuperação de parada, suspensão e erros de ponta a ponta.

---

Evolução do Projeto

Uma crônica da construção de um runtime Python e suíte de IA dentro do LibreOffice:

• Semana 1: Fork inicial, chat na barra lateral, ferramentas de múltiplas etapas e streaming assíncrono
• Semanas 2 e 3: MCP, subagente de pesquisa, suporte a voz e painel de avaliação
• Semanas 4–6: Máquinas de estado, verificação formal e conjuntos de ferramentas especializados
• Semanas 6 e 7: Verificação gramatical assíncrona e suporte a importação TeX
• Semana 8+: Ponte de computação NumPy, =PY()

---

Contribuição & Desenvolvimento

Discussões Pré-requisitos: Python 3.11–3.13 para desenvolvimento (fixado na versão 3.13 via .python-version), uv. Execute make check-setup para verificar. No macOS: instale make, gettext.

git clone https://github.com/KeithCu/writeragent.git
cd writeragent
uv python install 3.13
uv sync
make deploy          # Builds & installs WriterAgent.oxt (or: make deploy writer)
make test
make help

Para compilar e testar as variantes de extensão independentes:

# Standalone Python / NumPy compute suite (LibrePy)
make build-core      # Produces build/LibrePy.oxt
make deploy-core     # Installs LibrePy.oxt (removes WriterAgent)

# Standalone Harper grammar checker (LibreHarper)
make build-harper    # Produces build/LibreHarper.oxt
make deploy-harper   # Installs LibreHarper.oxt

Consulte AGENTS.md (invariantes), docs/repo-map.md (pontos de entrada) e docs/scripting/librepy-split.md para detalhes de arquitetura.

---

Créditos

Projeto	Contribuição
localwriter	Extensão original do Writer LLM (John Balis)
LibreCalc AI Assistant	Base e inspiração da IA do Calc
LibreOffice MCP Extension	Padrões de servidor MCP, Makefile, registro de ferramentas
Hermes Agent	Parsers de chamadas de ferramentas, reparo de JSON, padrões de memória
latex2mathml	LaTeX → MathML
mathml-to-latex	MathML → LaTeX (exportação de fórmulas do Writer)
isodate	Análise/formatação de duração ISO 8601 (wire do Calc)

---

Licença

GNU GPL v3 (ou posterior) — consulte LICENSE. Originalmente MPL 2.0; relicenciado em 2026 para reciprocidade mais forte e compatibilidade de bibliotecas.

Ano	Contribuição	Contribuidor
2024	Lançamento original	John Balis
2025–2026	Configuração, registros, sistema de build	quazardous
2026	Integração com Calc (originalmente MIT)	LibreCalc AI Assistant
2026	Modificações e relicenciamento	KeithCu