# sylvianai/sv-excel-agent architecture

> Architecture diagram of the GitHub repository sylvianai/sv-excel-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sylvianai/sv-excel-agent
- Repository: https://github.com/sylvianai/sv-excel-agent

## Overview

This repository provides an AI-driven Excel editing workflow: a user supplies a workbook and instruction, an agent uses spreadsheet tools exposed over MCP, and the edited workbook is saved for download or returned through an integration. The core includes both the agent runner and the Excel MCP tool server, with documented web and Slack entry points. Tool-level behavior is only sampled in part, so the graph shows confirmed orchestration and broad tool responsibilities without asserting unsupported helper-to-tool wiring.

Main entry points: [`excel_agent/agent_runner.py`](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/agent_runner.py) (Agent runner), [`excel_mcp/excel_server.py`](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/excel_server.py) (Tool server), [`demo/SlackExcelWorkflow/excel_agent_bot.py`](https://github.com/sylvianai/sv-excel-agent/blob/main/demo/SlackExcelWorkflow/excel_agent_bot.py) (Slack bot), [`demo/ExcelAssistant/server.py`](https://github.com/sylvianai/sv-excel-agent/blob/main/demo/ExcelAssistant/server.py) (Web API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_agent_runner["Agent runner<br/>[agent_runner.py]"]
  node_agent_config["Prompt and config<br/>[config.py]"]
  node_reasoning_models["Reasoning models"]
end

subgraph group_mcp["Excel MCP"]
  node_mcp_server["Tool server<br/>[excel_server.py]"]
  node_sessions["Session management<br/>[sessions.py]"]
  node_models["Workbook state<br/>[models.py]"]
  node_schemas["Tool schemas<br/>[schemas.py]"]
  node_helpers["Workbook operations<br/>[helpers.py]"]
  node_formatting["Cell display<br/>[formatting.py]"]
end

subgraph group_web["Web assistant"]
  node_web_ui["Spreadsheet UI<br/>[App.jsx]"]
  node_web_api["Web API<br/>[server.py]"]
end

subgraph group_slack["Slack workflow"]
  node_slack_bot["Slack bot<br/>[excel_agent_bot.py]"]
end

node_user(("Excel user"))
node_workbook["Excel workbook"]
node_model(("AI model provider"))
node_slack(("Slack"))

node_user -->|"uploads and instructs"| node_web_ui
node_web_ui -->|"sends task"| node_web_api
node_web_api -->|"starts server"| node_mcp_server
node_web_api -->|"runs task"| node_agent_runner
node_agent_runner -->|"formats prompt"| node_agent_config
node_agent_runner -->|"selects model"| node_reasoning_models
node_agent_runner -->|"calls tools via MCP"| node_mcp_server
node_agent_runner -->|"requests completion"| node_model
node_agent_runner -->|"initializes and saves"| node_workbook
node_mcp_server -->|"injects session"| node_sessions
node_sessions -->|"manages workbook state"| node_models
node_mcp_server -->|"validates tool inputs"| node_schemas
node_mcp_server -->|"performs workbook operations"| node_helpers
node_mcp_server -->|"formats cell data"| node_formatting
node_web_api -->|"stores upload and output"| node_workbook
node_user -->|"sends workbook task"| node_slack
node_slack -->|"dispatches mention"| node_slack_bot
node_slack_bot -->|"downloads and stages"| node_workbook
node_slack_bot -->|"starts server"| node_mcp_server
node_slack_bot -->|"runs task"| node_agent_runner
node_slack_bot -->|"returns result"| node_slack

click node_agent_runner "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/agent_runner.py"
click node_agent_config "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/config.py"
click node_reasoning_models "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/reasoning_models.py"
click node_mcp_server "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/excel_server.py"
click node_sessions "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/sessions.py"
click node_models "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/models.py"
click node_schemas "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/schemas.py"
click node_helpers "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/helpers.py"
click node_formatting "https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/formatting.py"
click node_web_ui "https://github.com/sylvianai/sv-excel-agent/blob/main/demo/ExcelAssistant/src/App.jsx"
click node_web_api "https://github.com/sylvianai/sv-excel-agent/blob/main/demo/ExcelAssistant/server.py"
click node_slack_bot "https://github.com/sylvianai/sv-excel-agent/blob/main/demo/SlackExcelWorkflow/excel_agent_bot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_runner,node_agent_config,node_reasoning_models,node_user toneBlue
class node_mcp_server,node_sessions,node_models,node_schemas,node_helpers,node_formatting toneAmber
class node_web_ui,node_web_api toneMint
class node_slack_bot toneRose
class node_workbook,node_model,node_slack toneIndigo
```

## Components

### Agent runtime

- [Agent runner](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/agent_runner.py): `excel_agent/agent_runner.py`
- [Prompt and config](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/config.py): `excel_agent/config.py`
- [Reasoning models](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_agent/reasoning_models.py): `excel_agent/reasoning_models.py`

### Excel MCP

- [Tool server](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/excel_server.py): `excel_mcp/excel_server.py`
- [Session management](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/sessions.py): `excel_mcp/sessions.py`
- [Workbook state](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/models.py): `excel_mcp/models.py`
- [Tool schemas](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/schemas.py): `excel_mcp/schemas.py`
- [Workbook operations](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/helpers.py): `excel_mcp/helpers.py`
- [Cell display](https://github.com/sylvianai/sv-excel-agent/blob/main/excel_mcp/formatting.py): `excel_mcp/formatting.py`

### Web assistant

- [Spreadsheet UI](https://github.com/sylvianai/sv-excel-agent/blob/main/demo/ExcelAssistant/src/App.jsx): `demo/ExcelAssistant/src/App.jsx`
- [Web API](https://github.com/sylvianai/sv-excel-agent/blob/main/demo/ExcelAssistant/server.py): `demo/ExcelAssistant/server.py`

### Slack workflow

- [Slack bot](https://github.com/sylvianai/sv-excel-agent/blob/main/demo/SlackExcelWorkflow/excel_agent_bot.py): `demo/SlackExcelWorkflow/excel_agent_bot.py`

### Other components

- **Excel user**
- **Excel workbook**
- **AI model provider**
- **Slack**

## Connections

- Excel user → Spreadsheet UI: uploads and instructs
- Spreadsheet UI → Web API: sends task
- Web API → Tool server: starts server
- Web API → Agent runner: runs task
- Agent runner → Prompt and config: formats prompt
- Agent runner → Reasoning models: selects model
- Agent runner → Tool server: calls tools via MCP
- Agent runner → AI model provider: requests completion
- Agent runner → Excel workbook: initializes and saves
- Tool server → Session management: injects session
- Session management → Workbook state: manages workbook state
- Tool server → Tool schemas: validates tool inputs
- Tool server → Workbook operations: performs workbook operations
- Tool server → Cell display: formats cell data
- Web API → Excel workbook: stores upload and output
- Excel user → Slack: sends workbook task
- Slack → Slack bot: dispatches mention
- Slack bot → Excel workbook: downloads and stages
- Slack bot → Tool server: starts server
- Slack bot → Agent runner: runs task
- Slack bot → Slack: returns result