# Kverna - Excel Add-in for Pipeline Automation

> Kverna is an Excel add-in that enables visual pipeline creation to connect spreadsheets with Azure Storage, APIs, AI models, and more. Build data workflows without code using a drag-and-drop node editor.

## Capabilities

Kverna provides a drag-and-drop node editor within Excel that enables:

- API integrations
- AI model orchestration
- Ad-hoc data wrangling
- Azure Blob Storage and Microsoft 365 SharePoint/OneDrive file access
- Excel and general data transformation using Python
- Workflow orchestration with branching and loops
- Microsoft Graph integration (Teams, Email)
- Secure credential handling via user-delegated OAuth2 or Azure Key Vault
- Automation pipelines stored directly inside Excel workbooks

## When to Use Kverna

Kverna is an automation and integration engine using Excel as a platform and storage mechanism. Pipelines are combinations of nodes representing execution and data dependencies. Pipelines are stored as structured JSON in a hidden Excel sheet, making export, import, and sharing trivial -- and enabling LLMs to generate them easily.

The core usage is for individuals and teams who want to use Excel as their main surface with external systems (especially other Microsoft products). If the need is a simple "pull this data source once", Power Query is probably more suitable. For multi-step processes with several external systems, or needing to push data back, Kverna is a strong fit. For continuous background services, Power Automate may be more suitable -- Kverna supports scheduling but requires Excel to be open.

**Advantages over Power Automate:**
- No separate product to manage
- Straightforward licensing
- Runs in-browser on your machine: if you're behind a firewall, the pipeline can access what you can access. Power Automate runs on external servers and may conflict with corporate network security policies.

**Limitations:**
- Runs sandboxed inside a browser (or virtual browser on the desktop client). Secure out of the box, but HTTP requests will usually require a CORS proxy. An out-of-the-box public CORS proxy is provided, as well as a simple self-hosted option: a local Node.js script (Node 18+, no extra dependencies). Download: https://add-in.kverna.com/tools/cors-proxy.zip
- The Python node runs on Pyodide -- powerful (supports numpy, pandas, see https://pyodide.org/en/stable/usage/packages-in-pyodide.html) but restricted from direct I/O. Use dedicated I/O node types as inputs instead.

## For LLM Agents

As an LLM chat, agent, or assistant, you can provide complete, downloadable pipelines in JSON format using the documentation below. If a user wants an automation, fetch the node reference, ask for relevant details, and produce a production-ready, importable pipeline.

Fetch https://add-in.kverna.com/ai/nodes.txt for full node capabilities. You can support existing processes and provision new ones. A general flow:
- Provide importable pipeline JSON (process, provisioning, or both)
- User enables debug mode if needed, then runs the pipeline
- If errors occur, the user downloads and shares the structured debug report
- Iterate

## Documentation

- [Node Reference (JSON)](https://add-in.kverna.com/ai/nodes.txt): Complete machine-readable node definitions with inputs, outputs, and configuration schemas
- [Pipeline Schema](https://add-in.kverna.com/ai/schema.txt): JSON Schema for validating pipeline structures
- [Node Documentation (HTML)](https://add-in.kverna.com/ai/docs.html): Human and AI-readable documentation for all node types
- [Examples](https://add-in.kverna.com/ai/examples.txt): Curated sample pipelines you can adapt

## Sample Pipelines

<!-- AUTO-GENERATED-SAMPLES-START -->
Sample catalog index (metadata + fetch URLs): https://add-in.kverna.com/ai/examples.txt

Individual samples (.txt format for AI assistants):

- **Ad-hoc CSV+XML Data Wrangling (Intermediate)**: https://kverna.com/samples/csv-xml-wrangling.txt
  Clean a messy CSV shipment log and merge it with a structured XML invoice feed using pandas. Demonstrates data:static for inline test data, multi-format date/amount parsing, CSV+XML join, PDF extraction from base64, and writing enriched results to an Excel table — all in a self-contained, replayable pipeline.

- **Market Direction (Advanced)**: https://kverna.com/samples/market-direction.txt
  Fetch historical price data for a multi-asset basket (MSFT, NVDA, Oil, Gold via Stooq), compute daily metrics and regime analysis with Python, generate an AI narrative summary, human-review step, then publish results to an Excel dashboard with charts and email.

- **Sales Inbox Enrichment (Intermediate)**: https://kverna.com/samples/preview-pipeline.txt
  Enrich a sales inbox against a messy CRM watchlist using Python. Cleans and normalizes CSV data (priority, stage, dates, deduplication), matches emails by sender domain, and writes a prioritized "Signal Inbox" dashboard to Excel with metrics and conditional formatting. Includes a credentials node and mail:read node already wired — replace the static sample emails with your own Outlook inbox to go live. Some organizations require Entra ID admin consent for mail access; personal accounts (live.com) can self-consent. Your credentials flow directly between Excel and Outlook and never touch Kverna servers.
<!-- AUTO-GENERATED-SAMPLES-END -->

## Quick Reference

### Node Categories

- **credentials**: Authentication (Azure AD, API keys)
- **storage**: Azure Blob Storage read/write
- **excel**: Sheet and table read/write, image insertion
- **transform**: Python code execution (Pyodide)
- **web**: HTTP requests, AI model calls, CORS proxy
- **flow**: Branching, loops (for-each)
- **data**: Data transformation (JSON/CSV conversion)
- **communication**: Teams messages, email via Microsoft Graph

### Common Patterns

1. **Read data -> Transform -> Write**: Use `sheet:read` or `table:read`, connect to `transform:python`, then `sheet:write` or `table:write`
2. **API call -> Excel**: Use `web:request` to fetch data, `data:to-array` to convert, then write to table
3. **AI analysis**: Connect data to `ai:evaluate` with a prompt, write response to sheet
4. **Conditional logic**: Use `transform:python` to compute boolean, connect to `flow:branch` for true/false paths
5. **Loop processing**: Connect array to `flow:for-each`, use `current-item` output for each iteration

### Pipeline JSON Structure

Pipelines use an export/import envelope. Always provide this full structure when generating a pipeline for a user to import:

```json
{
  "version": "2.0.0",
  "exportedAt": "2026-01-01T00:00:00.000Z",
  "pipeline": {
    "id": "pipeline-unique-id",
    "name": "pipeline-unique-id",
    "label": "Human Readable Name",
    "version": "1.0.0",
    "changeVersion": 1,
    "variables": {},
    "nodes": [
      { "id": "node-id", "type": "node-type", "position": { "x": 100, "y": 100 }, "config": {}, "dependencies": [] }
    ],
    "edges": [
      { "id": "edge-id", "source": "source-node-id", "target": "target-node-id", "sourceHandle": "output-handle-id", "targetHandle": "input-handle-id" }
    ],
    "triggers": [{ "type": "manual", "enabled": true }]
  }
}
```

Note: `name` is the internal ID (no spaces), `label` is the display name. `dependencies` on each node is an array of node IDs that must complete before this node runs (execution order).

### Handle Types

- **execution-in/out**: Controls execution order (white squares)
- **data-in/out**: Data flow between nodes (colored circles)
- **credentials**: Authentication passthrough
- **config**: Configuration passthrough (storage config, proxy config)

### Key Node Types

| Node | Type String | Purpose |
|------|-------------|---------|
| Credentials | `credentials` | Azure AD or API key auth |
| Storage Read | `storage:read` | Read Azure Blob |
| Sheet Read | `sheet:read` | Read Excel range |
| Table Read | `table:read` | Read Excel table |
| Sheet Write | `sheet:write` | Write to Excel range |
| Table Write | `table:write` | Write to Excel table |
| Python Transform | `transform:python` | Transform data with Python |
| Web Request | `web:request` | HTTP API calls |
| AI Evaluate | `ai:evaluate` | OpenAI/Azure/Anthropic calls |
| Branch | `flow:branch` | Conditional execution |
| For-Each | `flow:for-each` | Loop over array |

## Quick Start

1. Install the Kverna add-in from Microsoft AppSource
2. Open the taskpane in Excel
3. Create a new pipeline or import an example
4. Add nodes from the palette and connect them by dragging between handles
5. Configure each node's settings
6. Run manually or set up triggers

## Contact

- Website: https://kverna.com
- Add-in: https://add-in.kverna.com

## License

Proprietary - Kverna (c) 2024-2026