WriterAgent
Une extension LibreOffice qui ajoute des fonctionnalités d'IA agentique et NumPy.
Documentation
WriterAgent, LibrePy & LibreHarper
Python, NumPy, and Agentic AI for LibreOffice (Writer, Calc, and Draw)
Run Python and scientific compute offline in spreadsheet formulas, edit documents with private local-first AI — without cloud lock-in.
The project is distributed as three standalone extension packages (install only one at a time):
| Package | What's Included |
|---|---|
🤖 WriterAgent (WriterAgent.oxt) (Full stack, recommended for most users) | Everything in LibrePy and LibreHarper + AI sidebar, =PROMPT(), web research, Calc → Python converter, MCP server |
🐍 LibrePy (LibrePy.oxt) | Python runtime, =PY(), NumPy, pandas, SymPy, Monaco, Jupyter File → Open .ipynb, domain helpers, OCR (no AI/MCP — core-track build for LO inclusion) |
✍️ LibreHarper (LibreHarper.oxt) | Standalone offline Harper grammar engine for Writer |
Download .oxt Releases · Feature Index · NumPy in LibreOffice Guide · Discussions
Key Capabilities
🤖 Local-First Agentic AI & Writing (Writer)
- Sidebar Chat with Multi-turn Tool Calling — Edit, restructure, or expand documents using natural language. 9 core tools plus dozens of specialized sub-agents for page layout, footnotes, bookmarks, revisions, and forms.
- Two-Way Voice Interaction (STT & TTS) — Dictate prompts directly to your document agent and listen to responses spoken aloud (local via Kokoro or Piper, or via your LLM endpoint).
- Format-Preserving Edits — Surgical redlines and section rewrites maintain your existing formatting (bold, italics, highlights, font sizes, tables, and nested lists) without clobbering styles.
- Web Research — Integrated private smolagents loop with DuckDuckGo. Synthesizes multiple web sources and updates open documents with real-time facts and citations. Agent Search
- Real-Time Grammar & Proofreading — Local, privacy-preserving grammar checking via Harper (fast, auto-installing), LanguageTool, or LLM endpoints with mixed-language sentence detection. Details
- Math & LaTeX Import — Converts LaTeX and MathML into native, editable LibreOffice Math objects. Math Guide
🐍 Python & Scientific Computing (Calc & Writer)
- Native
=PY()Spreadsheet Formulas — Execute Python, NumPy, and pandas expressions directly inside Calc cells with automatic array spill, shared workbook kernels, and persistent scripts.=PY("np.mean(data)"; A1:A10)— Calculate array statistics directly on Calc ranges.=PY("data.to_pandas(date_cols=True)"; A1:C10)— Load sheet data into pandas with automatic type and date parsing.- NumPy in LibreOffice Guide · Data Shapes & Type Mapping
- Embedded Monaco Code Editor — Write, test, and debug multi-line Python scripts directly inside cells or through the Tools → Run Python Script environment with syntax highlighting, autocomplete, and diagnostics.
- Built-in Scientific & Analytics Domains — Ready-to-use helpers for EDA, outlier detection, OLS regression, KMeans clustering, Monte Carlo simulations, symbolic algebra (SymPy), plotting, and physical unit conversions (
convert_quantity(60, "mph", "m/s")→26.8224 m/s). Domain Reference · Analysis Helpers - Spreadsheet → Python Converter (WriterAgent) — Translate 235+ classic Calc/Excel formulas into clean Python expressions using the built-in
calc.*parity library while preserving constants, dates, and cell formats. Details - Local Vision & OCR — Extract text from embedded images or scanned documents directly into Writer and Calc via offline Docling OCR. Vision Guide
Jupyter Notebook Support — File → Open… a .ipynb(or double-click /soffice notebook.ipynb) creates a Writer document with markdown, editable code fields, and ▶ run buttons against a shared Python kernel. Jupyter in Writer- Crash-safe by design — NumPy runs out-of-process in your own venv, so a scripting bug can't crash LibreOffice.
📊 Diagrams, Slides & Multi-Modal (Draw & Impress)
- Diagram & Presentation Generation — Generate, adjust, and style flowcharts, shapes, connectors, speaker notes, and slide transitions through chat commands or Python scripts. Details
- Image Creation & Editing — Generate a new image from a prompt, or edit a selected graphic in place, on the same endpoint as chat. Inserts into Writer, Calc, Draw, and Impress. Image Generation
- LO-DOM Semantic Tree — Structural understanding of headings, sections, tables, and relationships across entire documents. Semantic Tree
- Cross-Document Search & Memory — Query other documents in the same folder via local embeddings / hybrid search, with persistent cross-session agent memory. Embeddings · Memory
🔌 Integrations & Extensibility
- Model Context Protocol (MCP) Server — Connect external IDEs and agents (Cursor, Claude Desktop, LM Studio) to read and edit open LibreOffice documents over
http://localhost:18765/mcp. MCP Protocol - Pluggable Agent Backends — Switch the chat engine to external agents such as Hermes, Claude Code, Mistral Vibe, Grok Build, or OpenCode via ACP. Cursor Plugin · LO Skill
Full catalog of capabilities: docs/features.md.
Installation & Setup
- Download your chosen
.oxtpackage from Latest Releases and double-click to install (or open LibreOffice and go to Tools → Extension Manager → Add). Remember to install only one extension package. - Restart LibreOffice.
- Quick Configuration:
- Python / LibrePy users: Open Calc, check Tools → LibrePy (or WriterAgent) → Settings → Python, and click Test to verify your environment and NumPy/pandas availability.
- AI / WriterAgent users: Open WriterAgent → Settings and enter your endpoint (e.g.
http://localhost:11434for local Ollama (no key needed), or an OpenRouter / Together.AI API key). Open the sidebar via View → Sidebar → WriterAgent or press Ctrl+Q / Ctrl+E.
UI Modes: In classic toolbar mode, access tools through the top menubar. In tabbed/ribbon interfaces, use the WriterAgent chat sidebar and/or the Python sidebar (Writer + Calc): Settings
⚙, Python🐍, LaTeX math or Edit cell, search🔍(WriterAgent chat only), and full menus via☰.
For detailed setup instructions, see the Install and Troubleshooting Guide.
Showcase
Python in LibreOffice Writer
Spreadsheet Analytics & Dashboard
Hermes + Opus 4.6 (Web Research)
Math Expressions & LaTeX
Arch Linux Resume
Diagrams in Draw
Benchmarks & Evaluation
WriterAgent's Eval-1 LLM Evaluation Suite runs models on real Writer, Calc, and Draw jobs through the same tools the sidebar uses, then scores the exported document. Typical tasks: reformatting documents, recalculating taxes, drawing diagrams like the American flag using shapes. Every run is ranked by Value (correctness² ÷ dollars). The table below is the 2026-09-28 complete 29×19 dual-lane board (flag-18 + org_chart_gen, with hand-scored org-chart gallery overrides — 5 visual hard PASS). Full methodology: docs/eval/benchmarks.md.
Distance-to-frontier view: docs/eval/pareto-distance.svg.
| Model | Correctness avg task score (0–1) | Value Correctness² ÷ $/task |
|---|---|---|
| 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 |
Documentation & Architecture
| Topic | Documentation Link |
|---|---|
| Feature Index | docs/features.md |
| NumPy & Python in Calc | docs/enabling_numpy_in_libreoffice.md · docs/calc/py-data-shapes.md |
| LibrePy Core Architecture | docs/scripting/librepy-split.md |
| Domain Helper Functions | docs/scripting/numpy-domains.md · docs/calc/analysis-tools.md |
| Full Architecture | docs/writeragent-architecture.md · docs/framework/formal-verification.md |
| Model Context Protocol (MCP) | docs/mcp-protocol.md |
| Embeddings & Search | docs/embeddings.md |
| Benchmarks | docs/eval/benchmarks.md |
| Localization (35 Locales) | docs/framework/localization.md |
| Code Explorer | DeepWiki |
| Cursor / Agent Skills | cursor-libreoffice · libreoffice-skill |
Under the hood, all operations are governed by a formally verified finite state machine, with strict type checking and static analysis. Thread-unsafe UNO calls are caught in dev via a viral thread guard proxy, instead of randomly freezing. The mock-LLM sidebar suite — the world's worst LLM — proves Stop, hang, and error recovery end-to-end.
Project Evolution
A chronicle of building a Python runtime and AI suite inside LibreOffice:
- Week 1: Initial fork, sidebar chat, multi-turn tools, and async streaming
- Week 2 & 3: MCP, research sub-agent, voice support, and evaluation dashboard
- Week 4–6: State machines, formal verification, and specialized toolsets
- Week 6 & 7: Async grammar checking and TeX import support
- Week 8+: NumPy compute bridge,
=PY()
Contributing & Development
Prerequisites: Python 3.11–3.13 for development (pinned to 3.13 via .python-version), uv. Run make check-setup to verify. On macOS: install 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
To build and test the standalone extension variants:
# 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
See AGENTS.md (invariants), docs/repo-map.md (entry points), and docs/scripting/librepy-split.md for architecture details.
Credits
| Project | Contribution |
|---|---|
| localwriter | Original Writer LLM extension (John Balis) |
| LibreCalc AI Assistant | Calc AI foundation and inspiration |
| LibreOffice MCP Extension | MCP server patterns, Makefile, tool registry |
| Hermes Agent | Tool-call parsers, JSON repair, memory patterns |
| latex2mathml | LaTeX → MathML |
| mathml-to-latex | MathML → LaTeX (Writer formula export) |
| isodate | ISO 8601 duration parse/format (Calc wire) |
License
GNU GPL v3 (or later) — see LICENSE. Originally MPL 2.0; relicensed in 2026 for stronger reciprocity and library compatibility.
| Year | Contribution | Contributor |
|---|---|---|
| 2024 | Original release | John Balis |
| 2025–2026 | Config, registries, build system | quazardous |
| 2026 | Calc integration (originally MIT) | LibreCalc AI Assistant |
| 2026 | Modifications and relicensing | KeithCu |