Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,25 +40,30 @@
> 📣 **2026-05-07** — Wren Engine has merged into this repo under [`core/`](./core). The previous `Canner/wren-engine` repo is archived. The previous WrenAI GenBI app is preserved on the [`legacy/v1`](https://github.com/Canner/WrenAI/tree/legacy/v1) branch (tag `v1-final`). [Read the announcement →](https://github.com/Canner/WrenAI/discussions/2205)
---

WrenAI is an open-source context layer for MCP clients and AI agents. It translates SQL queries through a semantic layer ([MDL](./core/wren-mdl/) — Modeling Definition Language) and executes them against 20+ data sources (PostgreSQL, BigQuery, Snowflake, Spark, etc.). The Rust engine is powered by [Apache DataFusion](https://datafusion.apache.org/). Use it as a Python SDK, a CLI, a WASM module in the browser, or as building blocks for AI-agent skills.
## Why WrenAI?

## Quick start
AI agents fail on business data not because they can't write SQL — they fail because they don't know what your warehouse means. Overlapping tables, inconsistent naming, metric definitions scattered across dashboards and SQL files: an LLM with raw database access guesses just as badly as a new hire on day one.

```bash
pip install wren-engine
WrenAI is the open context layer that fills that gap. You model your business in **[MDL](./core/wren-mdl/)** (Modeling Definition Language) — entities, relationships, calculations, governed access patterns — and any agent (Claude, Cursor, ChatGPT, internal copilots, customer-facing apps) queries through the same layer your analysts already use.

mkdir my-project && cd my-project
wren context init
A Rust engine powered by [Apache DataFusion](https://datafusion.apache.org/) translates the modeled SQL and runs it against 20+ data sources (PostgreSQL, BigQuery, Snowflake, Spark, etc.). Use it as a Python SDK, a CLI, a WASM module in the browser, or as building blocks for agent skills.

# add a connection profile (interactive)
wren profile add my-db --interactive
## Quick start

# prepare your MDL project (edit wren_project.yml and add models)
The fastest path is to let an AI coding agent (Claude Code, Cursor, Aider, etc.) drive the install:

wren --sql 'SELECT order_id FROM "orders" LIMIT 10'
```bash
# Install WrenAI skills into your AI agent
npx skills add Canner/WrenAI --skill '*'
```

Full CLI guide: [`core/wren/README.md`](./core/wren/README.md). Installable extras for each connector are listed there.
Start a new agent session and ask:

> Use the `wren-onboarding` skill to install and set up Wren AI Core.

The `wren-onboarding` skill walks the agent through environment checks, package install, project scaffolding, the first data source connection, and a first query.

Full CLI guide and manual install steps: [`core/wren/README.md`](./core/wren/README.md). Installable extras for each connector are listed there.


## Supported Data Sources
Expand Down
2 changes: 1 addition & 1 deletion docs/core/concepts/architecture.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Architecture

Wren Engine CLI is a modular Python application that transforms semantic SQL through an MDL layer before executing it against your database. This page explains how the components fit together.
Wren AI Core CLI is a modular Python application that transforms semantic SQL through an MDL layer before executing it against your database. This page explains how the components fit together.

## Overview

Expand Down
22 changes: 11 additions & 11 deletions docs/core/concepts/benefits_llm.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Why Wren Engine helps AI agents
# Why Wren AI Core helps AI agents

Wren Engine gives AI agents a reliable way to understand business data before they generate SQL or answer questions. Instead of asking an LLM to infer meaning directly from raw tables and column names, Wren Engine provides structured business context through MDL, relationships, metrics, and governed access patterns.
Wren AI Core gives AI agents a reliable way to understand business data before they generate SQL or answer questions. Instead of asking an LLM to infer meaning directly from raw tables and column names, Wren AI Core provides structured business context through MDL, relationships, metrics, and governed access patterns.

This matters because most failures in text-to-SQL systems do not come from SQL syntax alone. They come from missing context: unclear business definitions, ambiguous joins, inconsistent metric logic, and access to the wrong data. Wren Engine reduces those failures by acting as an open context layer between AI agents and your data sources.
This matters because most failures in text-to-SQL systems do not come from SQL syntax alone. They come from missing context: unclear business definitions, ambiguous joins, inconsistent metric logic, and access to the wrong data. Wren AI Core reduces those failures by acting as an open context layer between AI agents and your data sources.

## What Wren Engine provides to LLM workflows
## What Wren AI Core provides to LLM workflows

### 1. Shared business context

Expand All @@ -19,7 +19,7 @@ With that context in place, an agent has a better chance of mapping a question l

### 2. More reliable planning for text-to-SQL

LLMs are good at pattern matching, but they are weaker when a query depends on domain-specific modeling rules. Wren Engine improves planning by giving the agent explicit structure instead of forcing it to reconstruct business logic from raw schema alone.
LLMs are good at pattern matching, but they are weaker when a query depends on domain-specific modeling rules. Wren AI Core improves planning by giving the agent explicit structure instead of forcing it to reconstruct business logic from raw schema alone.

This helps reduce:

Expand All @@ -30,7 +30,7 @@ This helps reduce:

### 3. Better context for RAG and agent memory

RAG systems work best when the retrieved context is structured, relevant, and grounded in how the business actually defines data. Wren Engine gives retrieval systems higher-quality context by exposing modeled entities, documented relationships, and reusable logic instead of only raw database metadata.
RAG systems work best when the retrieved context is structured, relevant, and grounded in how the business actually defines data. Wren AI Core gives retrieval systems higher-quality context by exposing modeled entities, documented relationships, and reusable logic instead of only raw database metadata.

This makes it easier for an agent to retrieve the right context for:

Expand All @@ -43,11 +43,11 @@ This makes it easier for an agent to retrieve the right context for:

When multiple AI agents, MCP clients, or applications access the same modeled context, they can reason from the same definitions. That consistency is important for teams that want a single place to define how metrics, dimensions, and relationships should behave.

Instead of each agent inventing its own interpretation, Wren Engine helps standardize the context they operate on.
Instead of each agent inventing its own interpretation, Wren AI Core helps standardize the context they operate on.

### 5. Governed access to data

AI systems should not have unlimited freedom to reference every object in a warehouse. Wren Engine helps narrow and structure what an agent can work with by operating against modeled data definitions rather than arbitrary warehouse exploration alone.
AI systems should not have unlimited freedom to reference every object in a warehouse. Wren AI Core helps narrow and structure what an agent can work with by operating against modeled data definitions rather than arbitrary warehouse exploration alone.

That improves safety and governance by:

Expand All @@ -58,7 +58,7 @@ That improves safety and governance by:

### 6. Memory and self-learning

Most text-to-SQL systems treat every question as if it were the first. Wren Engine breaks that pattern with a built-in [memory layer](../guides/memory.md) that learns from successful queries and gets better over time.
Most text-to-SQL systems treat every question as if it were the first. Wren AI Core breaks that pattern with a built-in [memory layer](../guides/memory.md) that learns from successful queries and gets better over time.

The memory system works at two levels:

Expand All @@ -74,6 +74,6 @@ The practical effect is fewer wrong answers over time — without retraining a m

AI agents need more than schema access. They need context they can plan with.

Wren Engine is designed for that layer of the stack: it turns raw warehouse structure into usable business context, exposes that context through MCP-friendly workflows, and helps agents generate more accurate, explainable, and governable data interactions.
Wren AI Core is designed for that layer of the stack: it turns raw warehouse structure into usable business context, exposes that context through MCP-friendly workflows, and helps agents generate more accurate, explainable, and governable data interactions.

If you are building AI-native analytics, text-to-SQL experiences, or agent workflows over enterprise data, Wren Engine helps bridge the gap between raw data systems and trustworthy agent behavior.
If you are building AI-native analytics, text-to-SQL experiences, or agent workflows over enterprise data, Wren AI Core helps bridge the gap between raw data systems and trustworthy agent behavior.
8 changes: 4 additions & 4 deletions docs/core/concepts/what_is_context.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# What is context?

In Wren Engine, context is the structured business understanding an AI agent needs in order to work with data correctly. It goes beyond raw schemas and table access. Context helps an agent understand what your data means, which sources to trust, how entities relate to each other, how metrics should be calculated, and what rules or guidance should shape its behavior.
In Wren AI Core, context is the structured business understanding an AI agent needs in order to work with data correctly. It goes beyond raw schemas and table access. Context helps an agent understand what your data means, which sources to trust, how entities relate to each other, how metrics should be calculated, and what rules or guidance should shape its behavior.

For AI agents, this matters because answering a question is rarely just a SQL generation problem. The harder problem is knowing what the question means inside a business. Questions like "What is revenue growth last quarter?" depend on business definitions, trusted sources, time conventions, relationships, and sometimes team-specific instructions. Context is what makes those answers reliable.

Expand All @@ -16,7 +16,7 @@ Context helps agents:
- apply business rules consistently
- generate more reliable answers across multi-step workflows

This is why Wren Engine is positioned as an open context layer for AI agents: it helps turn raw data systems into usable context that agents can reason over.
This is why Wren AI Core is positioned as an open context layer for AI agents: it helps turn raw data systems into usable context that agents can reason over.

## Context vs. semantics

Expand Down Expand Up @@ -49,9 +49,9 @@ But for AI agents, a semantic layer alone is often not enough. Agents also need

This idea aligns with the argument in a16z's article [Your Data Agents Need Context](https://a16z.com/your-data-agents-need-context/): a modern context layer should be a superset of the traditional semantic layer, adding the business and operational grounding that autonomous agents need.

## What context includes in Wren Engine
## What context includes in Wren AI Core

Wren Engine builds context from structured modeling and execution primitives, including:
Wren AI Core builds context from structured modeling and execution primitives, including:

- MDL definitions for models, relationships, calculations, and views
- business-facing dataset structure
Expand Down
18 changes: 9 additions & 9 deletions docs/core/concepts/what_is_mdl.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# What is Modeling Definition Language (MDL)?

Modeling Definition Language (MDL) is the way Wren Engine describes business data in a structured, machine-readable form. It defines models, relationships, calculations, and views so that both humans and AI agents can work from the same business context.
Modeling Definition Language (MDL) is the way Wren AI Core describes business data in a structured, machine-readable form. It defines models, relationships, calculations, and views so that both humans and AI agents can work from the same business context.

Instead of exposing only raw tables and columns, MDL gives your data a logical shape. It tells Wren Engine how datasets relate to each other, how business metrics should be defined, and how analytical logic should be reused across queries.
Instead of exposing only raw tables and columns, MDL gives your data a logical shape. It tells Wren AI Core how datasets relate to each other, how business metrics should be defined, and how analytical logic should be reused across queries.

## Why MDL matters

Raw schemas are not enough for reliable analytics or AI-driven querying. A warehouse may contain hundreds of tables, inconsistent naming, and business logic scattered across dashboards or SQL scripts. MDL helps centralize that logic into a form that is easier to understand, review, and execute.

With MDL, Wren Engine can provide AI agents with the context they need to:
With MDL, Wren AI Core can provide AI agents with the context they need to:

- understand business entities and terminology
- follow defined relationships between datasets
Expand All @@ -25,11 +25,11 @@ MDL is used to model the business-facing structure of your data. Depending on yo
- calculated fields and reusable metrics
- views built on top of modeled datasets

This gives Wren Engine a consistent representation of how your data should behave, rather than forcing every user or agent to rediscover that logic from scratch.
This gives Wren AI Core a consistent representation of how your data should behave, rather than forcing every user or agent to rediscover that logic from scratch.

## How MDL helps AI agents

AI agents perform better when they can reason over structured context instead of guessing from raw schema alone. MDL helps by giving Wren Engine an explicit description of your business layer.
AI agents perform better when they can reason over structured context instead of guessing from raw schema alone. MDL helps by giving Wren AI Core an explicit description of your business layer.

That improves agent behavior in several ways:

Expand All @@ -38,7 +38,7 @@ That improves agent behavior in several ways:
- more consistent metric definitions across queries
- clearer grounding for text-to-SQL and RAG workflows

In this sense, MDL is one of the core building blocks that lets Wren Engine act as an open context layer for AI agents.
In this sense, MDL is one of the core building blocks that lets Wren AI Core act as an open context layer for AI agents.

## Benefits of MDL

Expand All @@ -56,12 +56,12 @@ Because MDL is structured and explicit, it is easier for data teams to review, m

### 4. More reliable execution

Wren Engine can plan and generate queries more reliably when it has modeled definitions to work from. This helps reduce errors caused by incomplete schema interpretation or one-off query logic.
Wren AI Core can plan and generate queries more reliably when it has modeled definitions to work from. This helps reduce errors caused by incomplete schema interpretation or one-off query logic.

### 5. A stronger foundation for agentic analytics

If you want AI agents to operate on business data safely and accurately, they need more than access. They need context. MDL gives Wren Engine that context in a durable, portable form.
If you want AI agents to operate on business data safely and accurately, they need more than access. They need context. MDL gives Wren AI Core that context in a durable, portable form.

## In short

MDL is the modeling language that powers Wren Engine. It turns raw data structures into usable business context, making analytics workflows easier to govern for people and easier to reason over for AI agents.
MDL is the modeling language that powers Wren AI Core. It turns raw data structures into usable business context, making analytics workflows easier to govern for people and easier to reason over for AI agents.
2 changes: 1 addition & 1 deletion docs/core/get_started/connect.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Connect Your Database

This guide walks you through connecting Wren Engine to your own database — from creating a profile to running your first query. If you haven't installed the CLI yet, see [Installation](./installation.md) first.
This guide walks you through connecting Wren AI Core to your own database — from creating a profile to running your first query. If you haven't installed the CLI yet, see [Installation](./installation.md) first.

---

Expand Down
14 changes: 8 additions & 6 deletions docs/core/get_started/quickstart.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Quick Start: Wren CLI with jaffle_shop

Use natural-language questions against the **jaffle\_shop** dataset using **Wren Engine CLI** and **Claude Code** — no cloud database, no Docker, no MCP server.
Use natural-language questions against the **jaffle\_shop** dataset using **Wren AI Core CLI** and **Claude Code** — no cloud database, no Docker, no MCP server.

> **Time:** ~15 minutes
>
Expand Down Expand Up @@ -80,23 +80,25 @@ wren version

## Step 3 — Install CLI skills

Skills are workflow guides that tell your AI coding agent how to use the Wren CLI effectively. Install both skills:
Skills are workflow guides that tell your AI coding agent how to use the Wren CLI effectively. Install the skill bundle:

```bash
npx skills add Canner/wren-engine --skill '*'
npx skills add Canner/WrenAI --skill '*'
# or:
curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/Canner/WrenAI/main/skills/install.sh | bash
```

The CLI auto-detects your installed agent. To target a specific one, add `--agent <name>` (e.g., `claude-code`, `cursor`, `windsurf`, `cline`).

This installs two skills:
This quickstart uses two of the installed skills:

| Skill | Purpose |
|-------|---------|
| **wren-usage** | Day-to-day workflow — gather context, recall past queries, write SQL, store results |
| **wren-generate-mdl** | One-time setup — explore database schema and generate the MDL project |

For the full skill list (including `wren-onboarding` and `wren-dlt-connector`), see [Installation](./installation.md#install-skills).

---

## Step 4 — Set up a profile
Expand Down Expand Up @@ -176,7 +178,7 @@ This creates:

The generated `wren_project.yml` contains default values for `catalog` and `schema`:

> **Note:** `catalog` and `schema` in `wren_project.yml` define the **Wren Engine namespace** — they have nothing to do with your database's catalog or schema. Keep the defaults (`wren` / `public`). The actual database location of each table is specified per-model in the `table_reference` section.
> **Note:** `catalog` and `schema` in `wren_project.yml` define the **Wren AI Core namespace** — they have nothing to do with your database's catalog or schema. Keep the defaults (`wren` / `public`). The actual database location of each table is specified per-model in the `table_reference` section.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/core/guides/memory.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Memory

Wren Engine includes a **memory layer** — a LanceDB-backed semantic index that gives AI agents the context they need to write accurate SQL. Instead of sending the entire schema to an LLM on every question, the memory layer provides targeted context: relevant tables, columns, and past query examples.
Wren AI Core includes a **memory layer** — a LanceDB-backed semantic index that gives AI agents the context they need to write accurate SQL. Instead of sending the entire schema to an LLM on every question, the memory layer provides targeted context: relevant tables, columns, and past query examples.

## Why memory matters

Expand Down
Loading
Loading