valem

Valem

**面向 AI Agent 的电子表格引擎。**大模型用 JSON 规范（字段、公式、不变量）描述一个领域；Valem 会将其编译为实时模型，在每次变更时重新计算所有依赖值，拒绝会破坏规则的变更，并能解释任意数值的由来。

为什么

大模型擅长描述一个领域，却不擅长让其中的状态保持一致。让它在二十轮对话中维护报价、订单或贷款申请，总额就会与各个明细不符，三条消息前检查过的限额会被遗忘，计算也会出现舍入误差。

Valem 将规则从对话中移出，交由确定性运行时处理：

• 派生值是基于 JSON 路径的 JSONata 公式，按依赖顺序重新计算（仅计算受变更影响的部分）。
• 约束是在变更提交前检查的不变量：回滚变更或将其标记出来。
• 效果（HTTP 调用、大模型调用、计时器）会作为数据发出，并在提交后运行，因此重放不会再次触发 I/O。
• 解释与审计：每个值都有派生追踪记录，审计记录采用哈希链。

Agent 编写规范；Valem 对其进行验证和测试，并确保其始终有效。

30 秒快速体验

**在浏览器中使用，无需安装。**打开 valem.run，用自然语言描述模型（“带有超额还款的抵押贷款”“含增值税和折扣的发票”），然后在实时表单中输入内容，观察每个派生值随之更新。

通过你的 Agent 使用（MCP，托管版，无需下载）：

# Claude Code
claude mcp add --transport http valem https://valem.run/mcp

Claude Desktop：进入 Settings → Connectors → Add custom connector → https://valem.run/mcp。然后让 Agent 调用 pair_browser，它就会构建模型，并在浏览器标签页中实时显示。创作工具（validate_spec、eval_expression、test_spec、dry_run）无需配对即可使用。指南：连接你的 Agent。

使用 Docker 自托管：

docker run --rm -p 8080:8080 ghcr.io/vlad-public-code/valem:latest
# → http://localhost:8080 (management UI, REST + WebSocket API, and /mcp)

规范示例

{
  "id": "order",
  "version": "1.0.0",
  "schema": {},
  "derivations": [
    { "path": "$.order.items[*].lineTotal", "expr": "$parent.qty * $parent.price" },
    { "path": "$.order.total", "expr": "$sum(order.items.(qty * price))" }
  ],
  "constraints": [
    { "id": "max-order", "expr": "order.total <= 5000",
      "message": "Order exceeds the cap", "policy": "rollback" }
  ]
}

在任意明细行中写入 qty，lineTotal 和 total 就会重新计算；如果写入导致总额超过 5,000，变更会在提交前被拒绝。完整格式请参阅：ModelSpec 参考。

运行方式

你的需求	使用方式
让 Agent 维护结构化状态	MCP 服务，可使用托管版（valem.run/mcp）或自托管版（从 Releases 下载 stdio jar）
为多个客户端提供共享后端	valem-web：REST + WebSocket，可插拔存储（文件系统、Postgres、Mongo、Redis、S3）
在 JVM 应用中使用引擎	嵌入 valem-core/valem-service
无需服务端的脚本处理	JSON 控制台（在 stdin 上每行输入一条 JSON 命令）
在网页中嵌入实时模型	嵌入实时模型

客户端：TypeScript 和 Java SDK。

文档

发布于 valem.run/docs（源文件位于 docs/）， 分为六章：快速入门、使用场景、模型指南、参考、部署、扩展。建议先阅读：

• 什么是 Valem？：五分钟了解其理念
• Valem 与其他方案的比较：了解它与代码解释器、规则引擎、表单库和电子表格的比较
• 常见问题，以及何时不应使用 Valem
• ModelSpec 格式：规范格式，唯一事实来源
• API 参考：REST、WebSocket 和控制台协议
• MCP 工具：MCP 服务公开的所有工具和资源
• 配置：所有 valem.* 属性
• 安全模型：身份验证、效果外发/SSRF、限制
• 架构：组件图、数据流和设计决策
• 面向 Agent：llms.txt

从源代码构建

前置条件

• Java 21+
• Maven 3.9+
• Node.js 20+ 和 npm 9+（仅 UI）

运行控制台应用（无需 HTTP 服务）

控制台应用是在脚本或 AI Agent 中使用 Valem 的最快方式。它从 stdin 按行读取 JSON 命令，并向 stdout 按行写入 JSON 响应。无需 HTTP、无需浏览器、无需服务进程。整个进程的 运行期间，所有状态都保存在内存中。

# Build the fat jar (first time)
mvn install -pl valem-core,valem-service -q
mvn package -pl valem-console -q

# Run interactively
java -jar valem-console/target/valem-console-1.0.0-SNAPSHOT.jar

# Or pipe commands
echo '{"cmd":"list-models"}' | java -jar valem-console/target/valem-console-1.0.0-SNAPSHOT.jar

会话示例：

// stdin
{"cmd":"create-model","spec":{"id":"order","version":"1.0.0","schema":{},"derivations":[{"path":"$.total","expr":"subtotal + tax"}]}}
{"cmd":"mutate","id":"order","mutations":{"$.subtotal":100,"$.tax":8}}
{"cmd":"get-state","id":"order"}

// stdout
{"ok":true,"result":{"id":"order","status":"created"}}
{"ok":true,"result":{"success":true,"mutatedPaths":["$.subtotal","$.tax"],"derivedUpdated":["$.total"],...}}
{"ok":true,"result":{"subtotal":100,"tax":8,"total":108}}

完整命令列表：控制台 JSON 协议。

运行后端

# From the repo root — build and start the Spring Boot server on port 8080.
# valem-web is the runnable deployable; valem-api is the headless library it wraps.
mvn install -pl valem-core,valem-service -q
mvn spring-boot:run -pl valem-web

API 现已在 http://localhost:8080 上可用，管理 UI 则通过 / 提供。默认使用内存存储；其他后端 采用按需选择的适配器 JAR（mvn -Pweb-postgres -pl valem-web package，然后使用 --valem.storage.type=postgres）——参见 configuration.md。关于持久化 部署、持久化布局和加固清单，请参阅 operations.md。

若要启用由大模型驱动的规范生成，请在启动前配置提供方（密钥从 valem.llm.api-key 读取，可通过 VALEM_LLM_API_KEY 设置；没有提供方专用的环境变量回退机制）：

# Anthropic (default provider)
export VALEM_LLM_API_KEY=sk-ant-...
mvn spring-boot:run -pl valem-web

# OpenAI
VALEM_LLM_PROVIDER=openai VALEM_LLM_MODEL=gpt-4o \
  VALEM_LLM_API_KEY=$OPENAI_API_KEY mvn spring-boot:run -pl valem-web

# Ollama (local, no API key needed; start `ollama serve` first)
VALEM_LLM_PROVIDER=ollama VALEM_LLM_MODEL=llama3 mvn spring-boot:run -pl valem-web

未配置任何提供方时，服务仍会正常启动；/models/generate* 端点会返回 503。所有大模型相关 选项（提供方、工具预算、重试、温度）： configuration.md。

运行开发者 UI

在单独的终端中：

cd valem-ui
npm install        # first time only
npm run dev

在浏览器中打开 http://localhost:5173。

UI 会将所有 /models 和 /blobs 请求（包括 WebSocket 连接）代理到后端，因此后端必须 处于运行状态。

使用大模型生成模型规范

UI 中的 ✦ Generate 按钮会启动一个有人参与的工作流：输入模型 ID 和纯文本领域描述 → Preview Prompt（可编辑）→ 发送给大模型 → 审核/编辑生成的规范 → Register Model。通过 REST 也可使用相同工作流 （POST /models/generate/preview → /models/generate → /models）。

有关工作流和提供方配置，请参阅 generating-specs-with-llm.md； 有关完整提示词和验证修复循环，请参阅 llm-prompts.md。

示例：通过 REST 创建和修改模型

# Create a model
curl -s -X POST http://localhost:8080/models \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "order",
    "version": "1.0.0",
    "schema": {},
    "derivations": [
      { "path": "$.order.total", "expr": "order.subtotal + order.tax" }
    ],
    "constraints": [
      { "id": "max-order", "expr": "order.total <= 5000",
        "message": "Order exceeds the cap", "policy": "rollback" }
    ]
  }'

# Mutate base fields — total is derived automatically
curl -s -X POST http://localhost:8080/models/order/mutations \
  -H 'Content-Type: application/json' \
  -d '{ "$.order.subtotal": 200, "$.order.tax": 20 }'

# Read merged state
curl -s http://localhost:8080/models/order/state | python -m json.tool

所有端点（审计、快照、视图、Blob、规范演进、组合，……）： api-reference.md。

运行测试

# All modules
mvn test

# Core only (faster — no Spring context)
mvn test -pl valem-core

运行端到端测试

valem-e2e 模块包含使用 Playwright 驱动完整技术栈（后端 + UI）的浏览器测试。

**前置条件：**后端必须运行在 8080 端口（参见 运行后端）。Playwright 会自动启动 UI 开发服务器。

cd valem-e2e
npm install              # first time only
npx playwright install   # download browser binaries (first time only)

npm test                 # headless Chromium
npm run test:headed      # watch the browser
npm run test:ui          # Playwright interactive UI mode
npm run report           # open the last HTML report

许可证

Apache-2.0 — 参见 LICENSE。