# Mog — The Spreadsheet for Humans and Agents

> Mog is an open-source spreadsheet engine built from scratch in Rust.
> 582 Excel-compatible functions, CRDT collaboration, canvas rendering,
> and SDKs for Python, Node.js, and WebAssembly.

## Quick Start

### Node.js
```bash
npm install @mog-sdk/node
```
```typescript
import { createWorkbook } from "@mog-sdk/node";

const wb = await createWorkbook();
const ws = wb.getActiveSheet();

await ws.setCell("A1", "Revenue");
await ws.setCell("A2", 150000);
await ws.setCell("A3", "=A2 * 1.15");

await wb.calculate();
console.log(await ws.getValue("A3")); // 172500

await save(wb, "output.xlsx");
```

### Python
```bash
pip install mog
```
```python
import mog

# Create a new workbook
wb = mog.create_workbook()
ws = wb.active_sheet()

ws.set_cell("A1", "Revenue")
ws.set_cell("A2", 150000)
ws.set_cell("A3", "=A2 * 1.15")

wb.calculate()
df = ws.to_dataframe()  # pandas DataFrame
wb.save("output.xlsx")

# Open an existing file
wb = mog.open_workbook("input.xlsx")
ws = wb.active_sheet()
value = ws.get_value("A1")
```

### Browser (React)
```bash
npm install @mog-sdk/embed
```
```tsx
import { MogSheet } from "@mog-sdk/embed/react";

export function App() {
  return <MogSheet src="/data/sales.xlsx" width={1200} height={600} />;
}
```

## Documentation Map

- [Getting Started](https://sheetmog.ai/docs/getting-started): Install SDK, create workbook, embed, export
- [Documentation Index](https://sheetmog.ai/docs): All docs sections at a glance
- [Architecture](https://sheetmog.ai/docs/architecture): OS-style layering, Rust core, CRDT, canvas rendering
- [API Reference](https://sheetmog.ai/docs/api): 800+ methods — Workbook, Worksheet, Charts, Tables, Pivots
- [API Method Index](https://sheetmog.ai/api-index.json): Compact index of all methods with summaries (~15KB)
- [API Spec (JSON)](https://sheetmog.ai/api-spec.json): Machine-readable API specification
- [Full API Reference (text)](https://sheetmog.ai/llms-full.txt): Complete method signatures and docs for LLMs
- [AI Plugin Manifest](https://sheetmog.ai/.well-known/ai-plugin.json): Agent discovery manifest
- [Type Reference](https://sheetmog.ai/docs/api/types): All TypeScript type definitions
- [Tutorials](https://sheetmog.ai/docs/tutorials): Step-by-step guides
  - [Embed in Next.js](https://sheetmog.ai/docs/tutorials/embed-nextjs): Drop a spreadsheet into a React/Next.js app
  - [Server-Side XLSX](https://sheetmog.ai/docs/tutorials/server-side-xlsx): Read/write Excel files in Node.js
  - [Python Data Analysis](https://sheetmog.ai/docs/tutorials/python-data-analysis): Use Mog with pandas
  - [Budget Tracker](https://sheetmog.ai/docs/tutorials/budget-tracker): Build a complete app with formulas, charts, export
- [Examples](https://sheetmog.ai/examples): Copy-paste code recipes by category
- [FAQ](https://sheetmog.ai/faq): Common questions about Mog
- [Roadmap](https://sheetmog.ai/roadmap): What's done, in progress, and planned
- [Playground](https://sheetmog.ai/playground): Live interactive spreadsheet in browser

## API Overview

The SDK provides programmatic access to every spreadsheet feature. Two root objects:

### Workbook (wb) — 62 direct methods
Create, open, save, calculate, batch operations, undo/redo.

Sub-APIs: wb.sheets (10), wb.slicers (8), wb.slicerStyles (9),
wb.pivotTableStyles (5), wb.functions (8), wb.names (13),
wb.scenarios (6), wb.history (9), wb.styles (12), wb.properties (6),
wb.protection (2), wb.notifications (9), wb.theme (4), wb.viewport (5),
wb.changes (1)

### Worksheet (ws) — 64 direct methods
Read/write cells, formulas, ranges, formatting, selection.

Sub-APIs: ws.charts (50), ws.tables (53), ws.pivots (36),
ws.comments (29), ws.layout (24), ws.filters (22), ws.formats (19),
ws.print (19), ws.smartArt (18), ws.sparklines (18), ws.objects (16),
ws.structure (14), ws.view (14), ws.outline (14), ws.slicers (13),
ws.conditionalFormats (12), ws.protection (9), ws.validation (8),
ws.settings (7), ws.bindings (7), ws.names (6), ws.shapes (4),
ws.styles (3), ws.pictures (3), ws.textBoxes (3), ws.drawings (3),
ws.equations (3), ws.wordArt (3), ws.hyperlinks (3),
ws.formControls (3), ws.connectors (2), ws.whatIf (2), ws.changes (1)

## Common Patterns

### Read and modify an existing file
```typescript
import { openWorkbook, save } from "@mog-sdk/node";

const wb = await openWorkbook("input.xlsx");
const ws = wb.getActiveSheet();
const value = await ws.getValue("A1");
await ws.setCell("B1", `=${value} * 2`);
await wb.calculate();
await save(wb, "output.xlsx");
```

### Batch operations (single undo step)
```typescript
await wb.batch(async () => {
  await ws.setRange("A1:C1", [["Name", "Q1", "Q2"]]);
  await ws.setRange("A2:C2", [["Product A", 50000, 62000]]);
});
```

### Create a table with structured references
```typescript
await ws.tables.add({ range: "A1:C10", name: "Sales" });
await ws.setCell("D1", "=Sales[@Q1] + Sales[@Q2]");
```

### Dynamic arrays
```typescript
await ws.setCell("A1", '=FILTER(B1:B100, C1:C100 > 1000)');
// Spills automatically into A1:A{n}
```

### Python: open, filter with pandas, save
```python
import mog

wb = mog.open_workbook("sales.xlsx")
ws = wb.active_sheet()

# Convert to pandas, filter, write back
df = ws.to_dataframe()
filtered = df[df["revenue"] > 100000]

# Create new workbook from filtered data
out = mog.create_workbook()
out_ws = out.active_sheet()
out_ws.from_dataframe(filtered)
out.save("filtered.xlsx")
```

### Node.js: batch update with structured tables
```typescript
import { openWorkbook, save } from "@mog-sdk/node";

const wb = await openWorkbook("data.xlsx");
const ws = wb.getActiveSheet();

// Add a table and use structured references
await ws.tables.add({ range: "A1:D100", name: "Sales" });
await ws.setCell("E1", "=Sales[@Revenue] * Sales[@Quantity]");

// Batch updates for performance
await wb.batch(async () => {
  for (let i = 2; i <= 100; i++) {
    await ws.setCell(`F${i}`, `=IF(E${i}>10000, "High", "Low")`);
  }
});

await wb.calculate();
await save(wb, "updated.xlsx");
```

## Key Technologies

- **Rust**: 21 compute crates — formulas, parser, pivot tables, charts, XLSX I/O
- **WebAssembly**: Browser-side native-speed computation in a Web Worker
- **N-API**: Native Node.js bindings (macOS, Linux, Windows)
- **PyO3**: Native Python bindings, interop with pandas/numpy
- **Yrs/Yjs CRDTs**: Conflict-free real-time collaboration, offline-first
- **HTML Canvas**: Pixel-level rendering with binary wire protocol at 60fps

## Project Info

- License: Modified MIT
- Version: 0.1.0-alpha (pre-launch)
- Website: https://sheetmog.ai
- Repository: https://github.com/anthropics/mog
- Status: Pre-launch — SDK packages will be published at open-source release