Antigravity Excel Engine – Dual-Core Excel Automation for AI Agents

The Enterprise-Grade, AI-Native Excel Automation Engine for Autonomous Agents & Data Pipelines.

The Problem • Key Features • Quickstart • CLI Interface • Comparison Matrix • Contributing

Building autonomous AI agents (LangChain, AutoGen, CrewAI, MCP Sidecars) or robotic process automations that interact with Microsoft Excel is notoriously fragile:

• 💥 Interactive Freezes (0x8001010A): Classic COM libraries immediately crash with RPC_E_SERVERCALL_RETRYLATER if a user is actively typing in a cell.
• 💸 Token Context Window Exhaustion: Sending verbose JSON structures or raw matrices to LLMs burns through context windows and multiplies inference costs.
• 🧟 Zombie Process Nightmares: Unhandled exceptions frequently leave hidden, hungEXCEL.EXE processes in background memory, locking files forever.
• 🐢 OpenPyXL Blind Spots: Headless file manipulation cannot recalculate volatile formulas or evaluate live spreadsheets in real-time.

Antigravity Excel Engine completely eliminates these friction points with an adaptive Dual-Core runtime, automated Token Compression, self-healing COM lock recovery, and a guaranteed Zero-Leak process lifecycle.

• 🔄 Dual-Core Hybrid Runtime: Seamlessly detects whether the target spreadsheet is currently open in Microsoft Excel.
  • File Open? EngagesLive COM for real-time recalculation, dynamic formula evaluation, visual updates, and fullCtrl+Z Undo history.
  • File Closed? Switches automatically toHeadless OpenPyXL for maximum throughput and server-grade speed.
• 📉 75% LLM Token Compression: Packs tabular data into dense, normalized CSV streams designed specifically for LLM prompt context injection instead of wasteful JSON serialization.
• 🛡️ Self-Healing Cell Guardian: Employs exponential adaptive backoff to gracefully intercept interactive editing states, waiting for human input to finish instead of throwing COM errors.
• ⚡ Declarative Atomic Mapping: Update values, formulas, comments, RGB styles, borders, and column auto-fitting in a single atomic transaction.
• 🔍 Formula Error Sentinel: Automatically audits ranges for evaluation errors (#VALUE! ,#REF! ,#DIV/0! ,#N/A ,#NAME? ) before saving or reporting back to agents.
• 🤖 CLI with Deterministic JSON: Native command-line interface with--json flags for zero-friction integration into agentic workflows and tool-calling frameworks.

flowchart TD
    Agent[🤖 Autonomous AI Agent / Data Pipeline] --> Engine[Antigravity Excel Engine API]
    Engine --> Detector{Target Workbook Open in Excel?}
    
    Detector -- Yes --> COM[🚀 Live COM Engine\nwin32com.client]
    Detector -- No --> Headless[⚡ Headless Engine\nOpenPyXL]
    
    COM --> Guardian[🛡️ Self-Healing Backoff Guardian\n0x8001010A Auto-Recovery]
    Guardian --> LiveOps[Real-time Recalculation & Undo Support]
    
    Headless --> FastOps[High-Speed In-Memory File Processing]
    
    LiveOps --> Streamer[📉 Token-Optimized CSV Streamer\n-75% LLM Context Overhead]
    FastOps --> Streamer
    
    Streamer --> Agent
git clone https://github.com/FranciscoGrandon/antigravity-excel-engine.git
cd antigravity-excel-engine

pip install -r requirements.txt
python
from antigravity_excel_core import AntigravityExcelEngine

engine = AntigravityExcelEngine(mode="auto", file_path="financial_model.xlsx")

csv_stream = engine.get_range_as_csv("A1:D50")
print(csv_stream)

engine.set_cells({
    "A1": {
        "value": "Total Revenue",
        "cellStyles": {"fontWeight": "bold", "backgroundColor": "#0E2E63", "fontColor": "#FFFFFF"}
    },
    "B1": {
        "formula": "=SUM(B2:B10)",
        "cellStyles": {"numberFormat": "$#,##0.00"}
    },
    "A2": {
        "value": "Autonomous Agent Note",
        "note": "Audited and verified by Antigravity Engine"
    }
}, autofit=True)

errors = engine.check_formula_errors("A1:B10")
if errors:
    print(f"⚠️ Formula errors found: {errors}")

engine.save()

Every command supports deterministic --json output, making it directly compatible with subagents, bash scripts, and tool-calling orchestrators:

python antigravity_excel_cli.py status --json

python antigravity_excel_cli.py get-csv A1:D50 --file "data.xlsx" --json

python antigravity_excel_cli.py set-cells --input-file payload.json --autofit --json

python antigravity_excel_cli.py check-errors A1:Z100 --file "model.xlsx" --json

Contributions, issue reports, and feature suggestions are highly appreciated! Please consult our CONTRIBUTING.md guide before submitting a Pull Request.

Developed with pride by Francisco Grandón Vergara.

Released under the MIT License.