{
  "markdown": "# Valem\n\nDeterministic reactive computation runtime for AI-generated structured data models.\nA spreadsheet-like computation model for JSON-based agent systems.\n\n**▶ [Try the live sandbox](https://valem.run/)** — a zero-setup public demo: describe a\ndomain in plain language, watch an LLM generate a ModelSpec, then mutate fields and see derivations,\nconstraints, and effects react live.\n\n## Documentation\n\nFull docs live under [`docs/`](docs/README.md) — a task-keyed index, also published as a\n[documentation site](https://vlad-public-code.github.io/org.json-kula.valem/) organised in six\nchapters: **Getting started**, **Usage scenarios**, **Model guide**, **Reference**, **Deployment**,\n**Extending**. Canonical references (this README is a quickstart; the detail lives in these docs and\nis deliberately not duplicated here):\n\n- [What is Valem?](docs/getting-started/what-is-valem.md) — the idea in five minutes\n- [ModelSpec format](docs/reference/model-spec-format.md) — the spec format, single source of truth\n- [API reference](docs/reference/api-reference.md) — REST, WebSocket, and console protocol\n- [Configuration](docs/deployment/configuration.md) — every `valem.*` property\n- [Security model](docs/deployment/security-model.md) — auth, effect egress/SSRF, limits\n- [Architecture](docs/extending/architecture.md) — component map, data flow, design decisions\n- [Third-party libraries](docs/libraries.md) — what Valem builds on (Apache-2.0)\n\n## Prerequisites\n\n- Java 21+\n- Maven 3.9+\n- Node.js 20+ and npm 9+ (UI only)\n\n## Running the console app (no HTTP server required)\n\nThe console app is the fastest way to use Valem from a script or an AI agent. It reads one JSON\ncommand per line from `stdin` and writes one JSON response per line to `stdout`. No HTTP, no\nbrowser, no server process. All state is held in memory for the lifetime of the process.\n\n```bash\n# Build the fat jar (first time)\nmvn install -pl valem-core,valem-service -q\nmvn package -pl valem-console -q\n\n# Run interactively\njava -jar valem-console/target/valem-console-1.0.0-SNAPSHOT.jar\n\n# Or pipe commands\necho '{\"cmd\":\"list-models\"}' | java -jar valem-console/target/valem-console-1.0.0-SNAPSHOT.jar\n```\n\nExample session:\n\n```jsonc\n// stdin\n{\"cmd\":\"create-model\",\"spec\":{\"id\":\"order\",\"version\":\"1.0.0\",\"schema\":{},\"derivations\":[{\"path\":\"$.total\",\"expr\":\"subtotal + tax\"}]}}\n{\"cmd\":\"mutate\",\"id\":\"order\",\"mutations\":{\"$.subtotal\":100,\"$.tax\":8}}\n{\"cmd\":\"get-state\",\"id\":\"order\"}\n\n// stdout\n{\"ok\":true,\"result\":{\"id\":\"order\",\"status\":\"created\"}}\n{\"ok\":true,\"result\":{\"success\":true,\"mutatedPaths\":[\"$.subtotal\",\"$.tax\"],\"derivedUpdated\":[\"$.total\"],...}}\n{\"ok\":true,\"result\":{\"subtotal\":100,\"tax\":8,\"total\":108}}\n```\n\nFull command list: [console JSON protocol](docs/reference/api-reference.md#3-console-json-protocol).\n\n## Running the backend\n\n```bash\n# From the repo root — build and start the Spring Boot server on port 8080.\n# valem-web is the runnable deployable; valem-api is the headless library it wraps.\nmvn install -pl valem-core,valem-service -q\nmvn spring-boot:run -pl valem-web\n```\n\nThe API is now available at `http://localhost:8080`, with the management UI served at `/`. Storage\nis in-memory by default; other backends are à-la-carte adapter jars\n(`mvn -Pweb-postgres -pl valem-web package`, then `--valem.storage.type=postgres`) — see\n[configuration.md](docs/deployment/configuration.md#persistence-model-spec--state). For durable\nsetups, persistence layout, and the hardening checklist see\n[operations.md](docs/deployment/operations.md).\n\nTo enable LLM-powered spec generation, configure a provider before starting (the key is read from\n`valem.llm.api-key`, settable as `VALEM_LLM_API_KEY`; there is no provider-specific env fallback):\n\n```bash\n# Anthropic (default provider)\nexport VALEM_LLM_API_KEY=sk-ant-...\nmvn spring-boot:run -pl valem-web\n\n# OpenAI\nVALEM_LLM_PROVIDER=openai VALEM_LLM_MODEL=gpt-4o \\\n  VALEM_LLM_API_KEY=$OPENAI_API_KEY mvn spring-boot:run -pl valem-web\n\n# Ollama (local, no API key needed; start `ollama serve` first)\nVALEM_LLM_PROVIDER=ollama VALEM_LLM_MODEL=llama3 mvn spring-boot:run -pl valem-web\n```\n\nWithout any provider configured the server starts normally; the `/models/generate*` endpoints\nreturn 503. All LLM knobs (providers, tool budgets, retries, temperatures):\n[configuration.md](docs/deployment/configuration.md#llm-integration).\n\n## Running the developer UI\n\nIn a separate terminal:\n\n```bash\ncd valem-ui\nnpm install        # first time only\nnpm run dev\n```\n\nOpen `http://localhost:5173` in your browser.\n\nThe UI proxies all `/models` and `/blobs` requests (including WebSocket connections) to the\nbackend, which must be running.\n\n## Generating a model spec with an LLM\n\nThe UI's **✦ Generate** button drives a human-in-the-loop workflow: enter a model ID and a\nplain-text domain description → **Preview Prompt** (editable) → send to the LLM → review/edit the\ngenerated spec → **Register Model**. The same workflow is available over REST\n(`POST /models/generate/preview` → `/models/generate` → `/models`).\n\nSee [generating-specs-with-llm.md](docs/model-guide/generating-specs-with-llm.md) for the workflow and\nprovider setup, and [llm-prompts.md](docs/reference/llm-prompts.md) for the exact prompts and the\nvalidate-and-repair loop.\n\n## Example: create and mutate a model over REST\n\n```bash\n# Create a model\ncurl -s -X POST http://localhost:8080/models \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"id\": \"order\",\n    \"version\": \"1.0.0\",\n    \"schema\": {},\n    \"derivations\": [\n      { \"path\": \"$.order.total\", \"expr\": \"order.subtotal + order.tax\" }\n    ],\n    \"constraints\": [\n      { \"id\": \"max-order\", \"expr\": \"order.total <= 5000\",\n        \"message\": \"Order exceeds the cap\", \"policy\": \"rollback\" }\n    ]\n  }'\n\n# Mutate base fields — total is derived automatically\ncurl -s -X POST http://localhost:8080/models/order/mutations \\\n  -H 'Content-Type: application/json' \\\n  -d '{ \"$.order.subtotal\": 200, \"$.order.tax\": 20 }'\n\n# Read merged state\ncurl -s http://localhost:8080/models/order/state | python -m json.tool\n```\n\nEvery endpoint (audit, snapshots, views, blobs, spec evolution, composition, …):\n[api-reference.md](docs/reference/api-reference.md).\n\n## Running tests\n\n```bash\n# All modules\nmvn test\n\n# Core only (faster — no Spring context)\nmvn test -pl valem-core\n```\n\n## Running end-to-end tests\n\nThe `valem-e2e` module contains Playwright browser tests that drive the full stack (backend + UI).\n\n**Prerequisites:** the backend must be running on port 8080 (see\n[Running the backend](#running-the-backend)). The UI dev server is started automatically by\nPlaywright.\n\n```bash\ncd valem-e2e\nnpm install              # first time only\nnpx playwright install   # download browser binaries (first time only)\n\nnpm test                 # headless Chromium\nnpm run test:headed      # watch the browser\nnpm run test:ui          # Playwright interactive UI mode\nnpm run report           # open the last HTML report\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n",
  "bytes": 7011,
  "sha": "8cb4be4ba38a325b0bfe0f20b7dced7ec5b0da382201f76c20f3013aee72f892",
  "repo_slug": "vlad-public-code/org.json-kula.valem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vlad_public_code_valem_37d42c2f/readme"
}