refactor(readme): adjust readme#2292
Conversation
WalkthroughREADME.md is substantially rewritten to present updated branding, a problem statement, a Quickstart centered on skills and ChangesREADME Rewrite and Reorganization
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
the
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 19-20: Replace the placeholder Discord server ID "0000000000" in
the badge URL (the Markdown line containing
https://img.shields.io/discord/0000000000?logo=discord&label=Discord) with the
real Discord server ID so the badge renders correctly; keep the surrounding
badge Markdown and the invite link (https://discord.gg/wrenai) intact and verify
the badge image loads after updating the ID.
- Around line 163-166: Update the "Concepts" markdown link so the link target
uses the correct path: replace the old URL
"https://docs.getwren.ai/oss/concepts/what_is_context" used for the "Concepts"
list item with the new URL
"https://docs.getwren.ai/oss/engine/concept/what_is_context" (leave the link
text "Concepts" and the other links unchanged).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: ea7a7129-721d-450b-96ed-7b7558cad3d5
⛔ Files ignored due to path filters (1)
misc/wren-ai-architecture.pngis excluded by!**/*.png
📒 Files selected for processing (1)
README.md
| <!-- TODO: replace 0000000000 with the real Discord server ID before publishing --> | ||
| [](https://discord.gg/wrenai) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Search for Discord invite links or server IDs in the repository
# Search for discord.gg invite links
rg -n 'discord\.gg/[a-zA-Z0-9]+' --type=md
# Search for Discord server ID patterns (typically 18-19 digit numbers)
rg -n 'discord.*[0-9]{17,19}' --type=mdRepository: Canner/WrenAI
Length of output: 2224
🏁 Script executed:
#!/bin/bash
# Search for Discord invite links
find . -type f -name "*.md" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.config.*" | xargs grep -l "discord" 2>/dev/null | head -20Repository: Canner/WrenAI
Length of output: 2205
🏁 Script executed:
#!/bin/bash
# Search for discord.gg links and server IDs in markdown files
grep -r "discord" . --include="*.md" --include="*.json" --include="*.yaml" --include="*.config.*" 2>/dev/null | grep -v "node_modules" | head -30Repository: Canner/WrenAI
Length of output: 2205
Replace placeholder Discord server ID in the badge before publishing.
Lines 19-20 contain a TODO comment indicating the Discord server ID placeholder (0000000000) needs to be replaced with the actual server ID. The Discord badge will display a broken image until this is updated.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 19 - 20, Replace the placeholder Discord server ID
"0000000000" in the badge URL (the Markdown line containing
https://img.shields.io/discord/0000000000?logo=discord&label=Discord) with the
real Discord server ID so the badge renders correctly; keep the surrounding
badge Markdown and the invite link (https://discord.gg/wrenai) intact and verify
the badge image loads after updating the ID.
| - [Quickstart](https://docs.getwren.ai/oss/get_started/quickstart) — from skill install to first answer | ||
| - [Concepts](https://docs.getwren.ai/oss/concepts/what_is_context) — what context is, what MDL is, how memory works | ||
| - [Connect a database](https://docs.getwren.ai/oss/guides/connect/overview) — Postgres, BigQuery, Snowflake, DuckDB, and more | ||
| - [Agent SDKs](https://docs.getwren.ai/oss/sdk/overview) — what's shipping today, what's next |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check if documentation URLs return successful responses
urls=(
"https://docs.getwren.ai/oss/get_started/quickstart"
"https://docs.getwren.ai/oss/concepts/what_is_context"
"https://docs.getwren.ai/oss/guides/connect/overview"
"https://docs.getwren.ai/oss/sdk/overview"
"https://docs.getwren.ai/oss/reference/skills"
)
for url in "${urls[@]}"; do
status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
if [ "$status" = "200" ]; then
echo "✓ $url (HTTP $status)"
else
echo "✗ $url (HTTP $status)"
fi
doneRepository: Canner/WrenAI
Length of output: 2224
🌐 Web query:
https://docs.getwren.ai/oss/get_started/quickstart documentation page
💡 Result:
The Wren AI OSS quickstart documentation provides a guide for using the Wren CLI to interact with datasets, such as the jaffle_shop example, using AI coding agents like Claude Code [1]. Prerequisites for this quickstart include: - Claude Code (installed and authenticated) [1] - Python 3.11+ [1] - Node.js / npm (required for installing skills) [1] - Git [1] The core steps outlined in the documentation are: 1. Create a Python virtual environment [1]. 2. Seed the jaffle_shop dataset [1]. 3. Install the wren-engine Python package [1]. 4. Install CLI skills (workflow guides for AI coding agents) using npx or a curl script [1]. 5. Set up a profile to store database connection information [1]. 6. Initialize a Wren project [1]. 7. Use Claude Code to explore the database and generate the MDL (Modeling Language) project [1]. 8. Begin asking natural-language questions against the dataset [1]. For users looking to connect their own data, separate documentation is available that covers loading CSV files through DuckDB and defining table relationships [2]. Additionally, general installation guides for Wren AI (using the Wren AI Launcher or shell) are provided for those who prefer a UI-based setup [3].
Citations:
- 1: https://docs.getwren.ai/oss/get_started/quickstart
- 2: https://docs.getwren.ai/oss/getting_started/own_data
- 3: https://docs.getwren.ai/oss/installation
🌐 Web query:
https://docs.getwren.ai/oss/concepts/what_is_context Wren AI concepts
💡 Result:
In the context of Wren AI, context refers to the structured business understanding that an AI agent requires to interact with data reliably and accurately [1][2]. It extends beyond raw database schemas and table access to provide a machine-readable, governed, and extensible layer that enables AI systems to reason, plan, and act on business data [1][3][2]. Key aspects of Wren AI context include: 1. Semantic Definitions: It encompasses the meaning of data, including metrics, entities, and their relationships [1][2]. 2. Operational Guidance: It provides the AI with source-of-truth guidance, modeling rules, reusable analytical logic, and governance expectations [1][2]. 3. Practical Instructions: It includes tribal knowledge and specific business conventions that shape how an agent should behave [1][2]. 4. Memory and Learning: Wren AI utilizes a memory layer that indexes schema context and stores confirmed natural language-to-SQL (NL-SQL) pairs, allowing agents to retrieve relevant information per question and learn from past interactions [1][4]. Wren AI Core (formerly Wren Engine) serves as the foundation for this context, utilizing Modeling Definition Language (MDL) to define models, relationships, calculations, and views [1][5][4]. By packaging this full business understanding, Wren AI shifts from traditional semantic layer thinking—which often focused solely on metric definitions—to a context-driven approach that makes metadata operational for AI agents [1][3][2]. This allows agents to move beyond simple SQL generation and instead perform reliable, explainable, and governed data interactions [6][2].
Citations:
- 1: https://docs.getwren.ai/oss/engine/concept/what_is_context
- 2: http://docs.getwren.ai/oss/engine/concept/what_is_context
- 3: https://medium.com/wrenai/the-missing-context-layer-for-ai-agents-over-business-data-03849b72f73d
- 4: https://docs.getwren.ai/oss/guides/modeling/overview
- 5: https://docs.getwren.ai/oss/concept/wren_engine
- 6: https://docs.getwren.ai/oss/concepts/benefits_llm
🌐 Web query:
https://docs.getwren.ai/oss/guides/connect/overview Wren AI database connection
💡 Result:
To connect a database to Wren AI, the process depends on whether you are using the open-source (OSS) version or the cloud-based (CP) version. For the open-source version, you typically manage connections via the Wren AI CLI [1]. The general workflow involves: 1. Installing the necessary connector extra for your specific database (e.g., pip install "wren-engine[postgres]" for PostgreSQL) [1]. 2. Creating a connection profile using the CLI command wren profile add <profile-name> --ui, which opens a browser-based form to input your database credentials [1]. 3. Verifying the connection using wren profile debug to check the configuration or wren --sql "SELECT 1" to test actual connectivity [1]. 4. You can view required connection fields for any supported data source by running wren docs connection-info <datasource-name> [1]. For the cloud-based version (Wren AI Cloud), you connect data sources directly through the web interface [2]. The process generally includes: 1. Navigating to the "Connect a data source" section in the UI [2]. 2. Selecting your database type (e.g., MySQL, PostgreSQL, SQL Server) [2][3][4][5]. 3. Providing the required connection details, such as host, port, username, password, and database name [3][4][5][6]. 4. Ensuring that the Wren AI service's outbound IP address is allowlisted in your database's firewall settings [3][4][5]. 5. Selecting the specific tables you wish to use and defining relationships between them [3][4][5]. For local databases (e.g., MySQL) when using the OSS version, you may use host.docker.internal as the host address [6]. Additionally, some databases require specific permissions (e.g., SELECT, CREATE TEMPORARY VIEW, and DROP VIEW for PostgreSQL) to ensure stable modeling and query execution [5]. Always check the official documentation for your specific database type, as connection settings and requirements can vary [1][2].
Citations:
- 1: https://docs.getwren.ai/oss/get_started/connect
- 2: https://docs.getwren.ai/cp/guide/connect/overview
- 3: https://docs.getwren.ai/cp/guide/connect/mysql
- 4: https://docs.getwren.ai/cp/guide/connect/sqlserver
- 5: https://docs.getwren.ai/cp/guide/connect/postgresql
- 6: https://docs.getwren.ai/oss/guide/connect/mysql
🌐 Web query:
https://docs.getwren.ai/oss/sdk/overview Wren AI SDK documentation
💡 Result:
The Wren AI SDKs are designed to integrate Wren AI Core—the system's semantic modeling and query execution layer—directly into popular AI agent frameworks [1]. By using these SDKs, developers can expose a CLI-prepared Wren project to their agents as a toolkit, enabling features like schema resolution, memory recall, and governed SQL execution without needing to re-implement the semantic layer [1]. Available SDKs include: - LangChain / LangGraph: Available as wren-langchain on PyPI [1]. - Pydantic AI: Available as wren-pydantic on PyPI [1]. Key capabilities provided by these SDKs include: - SQL Execution: Executing SQL through the semantic layer [2]. - Schema Awareness: Listing project models with descriptions and column counts [2]. - Context Retrieval: Fetching schema and business context for natural-language questions [2]. - Memory Recall: Surfacing similar past natural-language-to-SQL pairs as few-shot examples [2]. - Query Planning: Verifying that SQL targets Modeling Definition Language (MDL) models correctly without execution [2]. Important Usage Note: The Wren CLI must be used first to prepare the Wren project (including profile, MDL, and optional memory index) [1][2]. The SDKs act as thin adapters that attach to these pre-prepared projects; they will fail at construction if a project has not been initialized [2]. For users not utilizing these specific agent frameworks, Wren AI Core can also be accessed via the CLI, through skills compatible with AI coding agents (such as Claude Code or Cursor), or via the Model Context Protocol (MCP) [1].
Citations:
Fix incorrect documentation link path for "Concepts".
The Concepts documentation link at line 164 uses an incorrect URL path. Change:
https://docs.getwren.ai/oss/concepts/what_is_context
To:
https://docs.getwren.ai/oss/engine/concept/what_is_context
The other three documentation links (Quickstart, Connect a database, Agent SDKs) are correct and accessible.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 163 - 166, Update the "Concepts" markdown link so the
link target uses the correct path: replace the old URL
"https://docs.getwren.ai/oss/concepts/what_is_context" used for the "Concepts"
list item with the new URL
"https://docs.getwren.ai/oss/engine/concept/what_is_context" (leave the link
text "Concepts" and the other links unchanged).
PaulChen79
force-pushed
the
refactor/adjust-readme
branch
from
abb56d4 to
dc32d3f
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 159-160: The README currently links to a temporary file
vision_paper_en.md (linked as [vision paper](./vision_paper_en.md)) which will
break/publicly expose a TODO; either move the file to a permanent location (e.g.
docs/vision-paper.md or repo root) and update the link in README.md to point to
the new path, or remove/disable the [vision paper](./vision_paper_en.md) link
until the final file is published so the README no longer references the
temporary .tmp path.
- Around line 222-235: Update the fenced code block that displays the project
tree (the block beginning with the line showing "core/" followed by
"wren-core/", "wren-core-base/", etc.) so the opening fence includes a language
identifier (e.g., change ``` to ```text) to satisfy markdownlint MD040; keep the
block contents unchanged and only modify the opening fence token.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 5b37b529-2315-4ef7-90ac-3f68179c9056
⛔ Files ignored due to path filters (1)
misc/wren-ai-architecture.pngis excluded by!**/*.png
📒 Files selected for processing (1)
README.md
| <!-- TODO: vision_paper_en.md is currently at .tmp/roadmap-discuss/vision_paper_en.md — move to a published path (e.g. docs/vision-paper.md or repo root) and update this link before publishing. --> | ||
| Full roadmap and design notes: see the [vision paper](./vision_paper_en.md). |
There was a problem hiding this comment.
Resolve the vision-paper TODO before publishing README.
Line 159 indicates the linked file path is temporary, but Line 160 already exposes the link publicly. Please either publish the file at the linked path or update/remove the link until the final location exists.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 159 - 160, The README currently links to a temporary
file vision_paper_en.md (linked as [vision paper](./vision_paper_en.md)) which
will break/publicly expose a TODO; either move the file to a permanent location
(e.g. docs/vision-paper.md or repo root) and update the link in README.md to
point to the new path, or remove/disable the [vision
paper](./vision_paper_en.md) link until the final file is published so the
README no longer references the temporary .tmp path.
| ``` | ||
| core/ | ||
| wren-core/ Rust semantic engine (Apache DataFusion) | ||
| wren-core-base/ Shared manifest types + MDL builder | ||
| wren-core-py/ Python bindings (PyPI: wren-core) | ||
| wren-core-wasm/ WebAssembly build (npm: wren-core-wasm) | ||
| wren/ Python SDK and CLI (PyPI: wren-engine) | ||
| wren-mdl/ MDL JSON schema | ||
| sdk/ | ||
| wren-langchain/ Reference agent SDK integration | ||
| skills/ Agent skills for context authoring | ||
| docs/ Module documentation | ||
| examples/ Example projects | ||
| ``` |
There was a problem hiding this comment.
Add a language to the fenced project-structure block.
The code fence starts without a language identifier, which triggers markdownlint MD040.
Suggested minimal fix
-```
+```text
core/
wren-core/ Rust semantic engine (Apache DataFusion)
wren-core-base/ Shared manifest types + MDL builder
wren-core-py/ Python bindings (PyPI: wren-core)
wren-core-wasm/ WebAssembly build (npm: wren-core-wasm)
wren/ Python SDK and CLI (PyPI: wren-engine)
wren-mdl/ MDL JSON schema
sdk/
wren-langchain/ Reference agent SDK integration
skills/ Agent skills for context authoring
docs/ Module documentation
examples/ Example projects</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 222-222: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @README.md around lines 222 - 235, Update the fenced code block that displays
the project tree (the block beginning with the line showing "core/" followed by
"wren-core/", "wren-core-base/", etc.) so the opening fence includes a language
identifier (e.g., change totext) to satisfy markdownlint MD040; keep the
block contents unchanged and only modify the opening fence token.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
2 participants
Summary by CodeRabbit