valem

Valem

AI エージェント向けのスプレッドシートエンジンです。 LLM がドメインを JSON 仕様（フィールド、数式、不変条件）として記述すると、Valem はそれをライブモデルにコンパイルします。変更のたびに依存するすべての値を再計算し、ルールに反する変更を拒否し、任意の数値の根拠を説明できます。

理由

LLM はドメインを 記述する のは得意ですが、その状態の 一貫性を保つ のは苦手です。見積もり、注文、ローン申請を 20 回のやり取りにわたって管理するよう頼むと、合計と明細が一致しなくなり、3 つ前のメッセージで確認した上限を忘れ、丸め誤差で計算がずれてしまいます。

Valem はルールを会話から取り出し、決定論的なランタイムに移します。

• 導出 は JSON パスに対する JSONata 数式で、依存関係の順に再計算されます（変更の影響を受けるもののみ）。
• 制約 は変更の確定前に確認される不変条件です。変更をロールバックするか、フラグを付けます。
• エフェクト（HTTP 呼び出し、LLM 呼び出し、タイマー）はデータとして出力され、確定後に実行されるため、リプレイで I/O が再実行されることはありません。
• 説明と監査：すべての値に導出トレースがあり、監査証跡はハッシュチェーンで連結されています。

エージェントが仕様を作成し、Valem がそれを検証・テストして、正しい状態に保ちます。

30 秒で試す

ブラウザーで、インストール不要です。 valem.run を開き、モデルを平易な言葉で説明します（「繰り上げ返済のある住宅ローン」「VAT と割引のある請求書」など）。その後、ライブフォームに入力して、導出値がすべて更新される様子を確認できます。

エージェントから（MCP、ホスト型、ダウンロード不要）：

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

Claude Desktop：設定 → コネクタ → カスタムコネクタを追加 → https://valem.run/mcp。次に、エージェントに pair_browser を呼び出すよう依頼すると、ブラウザーのタブでモデルをライブ表示できます。オーサリングツール（validate_spec、eval_expression、test_spec、dry_run）はペアリングなしで使用できます。ガイド：エージェントを接続する。

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 リファレンスをご覧ください。

実行方法

目的	使用するもの
構造化された状態を管理するエージェント	MCP サーバー。ホスト型（valem.run/mcp）またはセルフホスト型（リリースの stdio jar）
多数のクライアントで共有するバックエンド	valem-web：REST + WebSocket、プラグ可能なストレージ（ファイルシステム、Postgres、Mongo、Redis、S3）
JVM アプリ内のエンジン	valem-core/valem-service を組み込む
サーバーを使わないスクリプト実行	JSON コンソール（stdin で 1 行につき 1 つの JSON コマンド）
Web ページ内のライブモデル	ライブモデルを組み込む

クライアント：TypeScript および Java SDK。

ドキュメント

valem.run/docs で公開されています（ソースは docs/）。 次の6章で構成されています：はじめに、使用シナリオ、モデルガイド、リファレンス、 デプロイ、拡張。まずはこちらをご覧ください：

• Valem とは？：5分でわかる概要
• Valem と代替手段の比較：コードインタープリター、ルールエンジン、フォームライブラリ、スプレッドシートとの比較
• よくある質問と、Valem を使わないほうがよい場合
• ModelSpec 形式：唯一の信頼できる情報源となる仕様形式
• API リファレンス：REST、WebSocket、コンソールプロトコル
• MCP ツール：MCP サーバーが公開するすべてのツールとリソース
• 設定：すべての valem.* プロパティ
• セキュリティモデル：認証、エフェクトの外向き通信／SSRF、制限
• アーキテクチャ：コンポーネント構成、データフロー、設計上の判断
• エージェント向け：llms.txt

ソースからビルドする

前提条件

• Java 21+
• Maven 3.9+
• Node.js 20+ と npm 9+（UI のみ）

コンソールアプリの実行（HTTP サーバー不要）

コンソールアプリは、スクリプトや AI エージェントから Valem を使う最も手軽な方法です。stdin から1行につき1つの JSON コマンドを読み込み、stdout に1行につき1つの 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 をご覧ください。

LLM による仕様生成を有効にするには、起動前にプロバイダーを設定します（キーは 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 を返します。LLM に関するすべての設定項目（プロバイダー、ツールの予算、再試行、温度）については： configuration.md。

開発用 UI の実行

別のターミナルで実行します：

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

ブラウザーで http://localhost:5173 を開きます。

UI は /models および /blobs へのすべてのリクエスト（WebSocket 接続を含む）をバックエンドにプロキシします。バックエンドは起動している必要があります。

LLM でモデル仕様を生成する

UI の ✦ Generate ボタンでは、人間が確認しながら進めるワークフローを実行できます。モデル ID とプレーンテキストのドメイン説明を入力 → Preview Prompt（編集可能）→ LLM に送信 → 生成された仕様を確認・編集 → 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 モジュールには、フルスタック（バックエンド + UI）を操作する Playwright のブラウザテストが含まれています。

前提条件： バックエンドがポート 8080 で実行されている必要があります（バックエンドの実行を参照）。UI の開発サーバーは Playwright によって自動的に起動されます。

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を参照してください。