@aeratic/pagetailor 0.5.0 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aeratic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,7 @@
 # @aeratic/pagetailor
 
+[![npm](https://img.shields.io/npm/v/@aeratic/pagetailor)](https://www.npmjs.com/package/@aeratic/pagetailor) [![test](https://github.com/aeratic/pagetailor/actions/workflows/test.yml/badge.svg)](https://github.com/aeratic/pagetailor/actions/workflows/test.yml) [![license](https://img.shields.io/npm/l/@aeratic/pagetailor)](LICENSE)
+
 Pages as data. Define your app's pages in YAML, bind them to a typed catalog of components and data sources, tailor them per role and per person with small patches, and let an AI agent compose them through a validation gate. Rendering is done by [json-render](https://github.com/vercel-labs/json-render).
 
 ## Start here
@@ -18,8 +20,10 @@ npx pagetailor dev
 #   http://localhost:4747/?role=magazzino               the same page for the warehouse role
 #   http://localhost:4747/?view=studio                  visual editor of the whole project
 
-# 4. Enable the AI agent
+# 4. Enable the AI agent with any provider: Anthropic, OpenAI, Gemini, Groq, Mistral, DeepSeek, xAI, OpenRouter, Ollama…
 ANTHROPIC_API_KEY=sk-... npx pagetailor dev
+OPENAI_API_KEY=sk-... npx pagetailor dev
+PAGETAILOR_PROVIDER=ollama PAGETAILOR_MODEL=llama3.3 npx pagetailor dev
 
 # 5. After editing components/registry.yaml, regenerate the component index
 npx pagetailor registry
@@ -169,9 +173,17 @@ A user asks in natural language ("put the KPI at the top"); the agent turns it i
 3. `runAgent(root, { page, user, role, request, complete })` appends the patches to the user's existing override for that page (same merge rule as the editor) and calls `propose` as `user-<user>`: applied at once for the own user, pending otherwise.
 4. If the gate rejects, the gate errors are sent back once ("The previous patch was rejected: ... Fix it.") and the result is proposed again. The result reports `attempts`.
 
-`complete` is any `async ({ system, user }) => text`, so any model or SDK works; pagetailor depends on none. `anthropicComplete({ apiKey, model })` is a built-in fetch call to the Anthropic Messages API (`claude-sonnet-5-5` by default).
+`complete` is any `async ({ system, user }) => text`, so any model or SDK works; pagetailor depends on none. Built-in adapters over plain `fetch`: `anthropicComplete`, `openaiComplete` (OpenAI and every provider speaking its chat-completions format), `googleComplete` (Gemini). `createComplete({ provider, model, apiKey, baseUrl })` picks one by name: `anthropic`, `openai`, `google`, `groq`, `mistral`, `deepseek`, `xai`, `openrouter`, `ollama` (local, no key) or `compatible` (any URL). `completeFromEnv()` reads the same from the environment and is what `pagetailor dev` uses:
+
+| Variable | Meaning |
+| --- | --- |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `OPENROUTER_API_KEY` | the key of the provider to use; with one key set nothing else is needed |
+| `PAGETAILOR_PROVIDER` | force a provider when several keys are set, or choose `ollama` / `compatible` |
+| `PAGETAILOR_MODEL` | the model; defaults exist for anthropic, openai, google, mistral, deepseek, required for the others |
+| `PAGETAILOR_LLM_URL` | base URL for `compatible`, or to override a provider's URL (a proxy, an Ollama on another host) |
+| `PAGETAILOR_LLM_KEY` | the key for `compatible` |
 
-In `pagetailor dev`, set `ANTHROPIC_API_KEY` (and optionally `PAGETAILOR_MODEL`) and use the "Change this page…" box in the header: `POST /api/agent` with `{ page, user, role, request }` (503 without the key). `GET /api/agent/prompt?page=&user=&role=&request=` returns the built prompt for debugging.
+In `pagetailor dev`, set one of the variables above and use the "Change this page…" box in the header: `POST /api/agent` with `{ page, user, role, request }` (503 when no provider is configured). `GET /api/agent/prompt?page=&user=&role=&request=` returns the built prompt for debugging.
 
 ## Pages as answers
 
@@ -182,7 +194,7 @@ A user asks a question ("how did sales go this week?") and the agent composes a
 3. Keep as page: `keepAnswer(root, { user, role, title, tree, why })` writes `pages/<slug>.yaml` with `owner: <user>` and adds the slug to `manifest.pages` (slugs are made unique with `-2`, `-3`).
 4. Pin to home: `pinAnswer(root, { user, role, title, tree, why })` proposes, as `user-<user>`, an `insert` of a `layout/card` with the answer's widgets into the home's main container; on a grid it gets its own full-width row at the bottom. Same gate and proposal rules as any override.
 
-Both go through the gate with the user's role first. In `pagetailor dev` use the "Ask…" box: `POST /api/ask` `{ user, role, request }` (503 without `ANTHROPIC_API_KEY`), `POST /api/ask/keep` and `POST /api/ask/pin` with `{ user, role, title, tree, why }`.
+Both go through the gate with the user's role first. In `pagetailor dev` use the "Ask…" box: `POST /api/ask` `{ user, role, request }` (503 when no provider is configured), `POST /api/ask/keep` and `POST /api/ask/pin` with `{ user, role, title, tree, why }`.
 
 ## Studio
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Pages as data: declarative YAML pages, typed data catalog, per-user overrides, validated for AI agents. Renders with json-render.",
   "license": "MIT",
+  "author": "Aeratic <info@aeratic.com>",
   "type": "module",
   "bin": {
     "pagetailor": "bin/cli.js"
@@ -16,7 +17,8 @@
     "bin",
     "src",
     "templates",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"
@@ -53,6 +55,10 @@
     "react-dom": "19.2.3"
   },
   "scripts": {
-    "test": "node --no-deprecation --import ./test/jsx-loader.mjs --test test/"
+    "test": "node --no-deprecation --import ./test/jsx-loader.mjs --test test/*.test.js"
+  },
+  "homepage": "https://github.com/aeratic/pagetailor#readme",
+  "bugs": {
+    "url": "https://github.com/aeratic/pagetailor/issues"
   }
 }

package/src/dev.js

@@ -10,7 +10,7 @@ import { commitOverride, listHistory, rollback } from "./history.js";
 import { propose, listPending, approve, reject } from "./proposals.js";
 import { tokensToCss } from "./tokens.js";
 import { buildAgentPrompt, runAgent, runAsk, keepAnswer, pinAnswer } from "./agent.js";
-import { anthropicComplete } from "./llm.js";
+import { completeFromEnv, LLM_HELP } from "./llm.js";
 import { isProjectFile, readProjectFile, writeProjectFile, deleteProjectFile, listFileHistory, undoFile, readProject, scaffoldSource, scaffoldComponent } from "./files.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -101,16 +101,16 @@ export async function dev(cwd, { port = 4747, host = "127.0.0.1" } = {}) {
         return json(res, 200, await buildAgentPrompt(root, { page: q.page || "home", user: q.user || undefined, role: q.role || undefined, request: q.request ?? "" }));
       }
       if (url.pathname === "/api/agent" && req.method === "POST") {
-        if (!process.env.ANTHROPIC_API_KEY) return json(res, 503, { error: "set ANTHROPIC_API_KEY to use the agent" });
+        const complete = completeFromEnv();
+        if (!complete) return json(res, 503, { error: LLM_HELP });
         const b = await body(req);
-        const complete = anthropicComplete({ apiKey: process.env.ANTHROPIC_API_KEY, ...(process.env.PAGETAILOR_MODEL ? { model: process.env.PAGETAILOR_MODEL } : {}) });
         const r = await runAgent(root, { page: b.page, user: b.user, role: b.role || undefined, request: b.request, complete });
         return json(res, r.ok ? 200 : 400, r);
       }
       if (url.pathname === "/api/ask" && req.method === "POST") {
-        if (!process.env.ANTHROPIC_API_KEY) return json(res, 503, { error: "set ANTHROPIC_API_KEY to use the agent" });
+        const complete = completeFromEnv();
+        if (!complete) return json(res, 503, { error: LLM_HELP });
         const b = await body(req);
-        const complete = anthropicComplete({ apiKey: process.env.ANTHROPIC_API_KEY, ...(process.env.PAGETAILOR_MODEL ? { model: process.env.PAGETAILOR_MODEL } : {}) });
         const r = await runAsk(root, { user: b.user || undefined, role: b.role || undefined, request: b.request, complete });
         return json(res, r.ok ? 200 : 400, r);
       }

package/src/index.js

@@ -15,5 +15,5 @@ export async function dev(...args) {
 export { writeRegistryFile } from "./registry-file.js";
 export { tokensToCss } from "./tokens.js";
 export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent, buildAskPrompt, runAsk, keepAnswer, pinAnswer } from "./agent.js";
-export { anthropicComplete } from "./llm.js";
+export { anthropicComplete, openaiComplete, googleComplete, createComplete, completeFromEnv, PROVIDERS } from "./llm.js";
 export { readProjectFile, writeProjectFile, deleteProjectFile, listFileHistory, undoFile, scaffoldSource, scaffoldComponent, readProject } from "./files.js";

package/src/llm.js

@@ -1,14 +1,74 @@
-// Minimal Messages API call over global fetch; returns a `complete({ system, user })` for runAgent.
-export function anthropicComplete({ apiKey, model = "claude-sonnet-5-5" } = {}) {
-  if (!apiKey) throw new Error("anthropicComplete: apiKey is required");
+// Model adapters: each returns a `complete({ system, user }) => text` for runAgent / runAsk, over global fetch.
+// Any provider works with the same shape; pagetailor depends on no SDK.
+
+const post = async (url, headers, body) => {
+  const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body) });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${new URL(url).host} ${res.status}: ${text.slice(0, 500)}`);
+  return JSON.parse(text);
+};
+const need = (apiKey, name) => { if (!apiKey) throw new Error(`${name}: apiKey is required`); };
+
+export function anthropicComplete({ apiKey, model = "claude-sonnet-5-5", baseUrl = "https://api.anthropic.com", maxTokens = 2048 } = {}) {
+  need(apiKey, "anthropicComplete");
   return async ({ system, user }) => {
-    const res = await fetch("https://api.anthropic.com/v1/messages", {
-      method: "POST",
-      headers: { "content-type": "application/json", "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
-      body: JSON.stringify({ model, max_tokens: 1024, system, messages: [{ role: "user", content: user }] }),
-    });
-    const text = await res.text();
-    if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${text}`);
-    return (JSON.parse(text).content ?? []).filter(b => b.type === "text").map(b => b.text).join("");
+    const r = await post(`${baseUrl}/v1/messages`, { "x-api-key": apiKey, "anthropic-version": "2023-06-01" }, { model, max_tokens: maxTokens, system, messages: [{ role: "user", content: user }] });
+    return (r.content ?? []).filter(b => b.type === "text").map(b => b.text).join("");
   };
 }
+
+// OpenAI chat completions; also the wire format of Groq, Mistral, DeepSeek, xAI, OpenRouter, Ollama and many others.
+export function openaiComplete({ apiKey, model = "gpt-5.5", baseUrl = "https://api.openai.com/v1", maxTokens = 2048, headers = {} } = {}) {
+  if (baseUrl.includes("api.openai.com")) need(apiKey, "openaiComplete");
+  return async ({ system, user }) => {
+    const r = await post(`${baseUrl.replace(/\/$/, "")}/chat/completions`, { ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}), ...headers },
+      { model, max_tokens: maxTokens, messages: [{ role: "system", content: system }, { role: "user", content: user }] });
+    const c = r.choices?.[0]?.message?.content;
+    return Array.isArray(c) ? c.filter(p => p.type === "text").map(p => p.text).join("") : c ?? "";
+  };
+}
+
+export function googleComplete({ apiKey, model = "gemini-3.8-flash", baseUrl = "https://generativelanguage.googleapis.com/v1beta", maxTokens = 2048 } = {}) {
+  need(apiKey, "googleComplete");
+  return async ({ system, user }) => {
+    const r = await post(`${baseUrl}/models/${model}:generateContent`, { "x-goog-api-key": apiKey },
+      { system_instruction: { parts: [{ text: system }] }, contents: [{ role: "user", parts: [{ text: user }] }], generationConfig: { maxOutputTokens: maxTokens } });
+    return (r.candidates?.[0]?.content?.parts ?? []).map(p => p.text ?? "").join("");
+  };
+}
+
+// Known providers: env var holding the key, base URL and default model (null = PAGETAILOR_MODEL required).
+export const PROVIDERS = {
+  anthropic:  { key: "ANTHROPIC_API_KEY",  make: anthropicComplete },
+  openai:     { key: "OPENAI_API_KEY",     make: openaiComplete },
+  google:     { key: ["GEMINI_API_KEY", "GOOGLE_API_KEY"], make: googleComplete },
+  groq:       { key: "GROQ_API_KEY",       make: openaiComplete, baseUrl: "https://api.groq.com/openai/v1", model: null },
+  mistral:    { key: "MISTRAL_API_KEY",    make: openaiComplete, baseUrl: "https://api.mistral.ai/v1", model: "mistral-large-latest" },
+  deepseek:   { key: "DEEPSEEK_API_KEY",   make: openaiComplete, baseUrl: "https://api.deepseek.com/v1", model: "deepseek-chat" },
+  xai:        { key: "XAI_API_KEY",        make: openaiComplete, baseUrl: "https://api.x.ai/v1", model: null },
+  openrouter: { key: "OPENROUTER_API_KEY", make: openaiComplete, baseUrl: "https://openrouter.ai/api/v1", model: null },
+  ollama:     { key: null,                 make: openaiComplete, baseUrl: "http://localhost:11434/v1", model: null },
+  compatible: { key: "PAGETAILOR_LLM_KEY", make: openaiComplete, baseUrl: null, model: null },
+};
+
+// createComplete({ provider, model?, apiKey?, baseUrl? }): one call for every provider above.
+export function createComplete({ provider, model, apiKey, baseUrl, ...rest } = {}) {
+  const p = PROVIDERS[provider];
+  if (!p) throw new Error(`unknown LLM provider "${provider}" (known: ${Object.keys(PROVIDERS).join(", ")})`);
+  const url = baseUrl ?? p.baseUrl;
+  if (provider === "compatible" && !url) throw new Error("provider compatible: baseUrl is required (PAGETAILOR_LLM_URL)");
+  const m = model ?? ("model" in p ? p.model : undefined);
+  if (m === null) throw new Error(`provider ${provider}: model is required (PAGETAILOR_MODEL)`);
+  return p.make({ apiKey, ...(m ? { model: m } : {}), ...(url ? { baseUrl: url } : {}), ...rest });
+}
+
+// Reads the provider from the environment: PAGETAILOR_PROVIDER, or the first provider whose key is set.
+// PAGETAILOR_MODEL overrides the model, PAGETAILOR_LLM_URL the base URL. Returns null when nothing is configured.
+export function completeFromEnv(env = process.env) {
+  const keyOf = p => [].concat(PROVIDERS[p].key ?? []).map(k => env[k]).find(Boolean);
+  const provider = env.PAGETAILOR_PROVIDER || Object.keys(PROVIDERS).find(p => PROVIDERS[p].key && keyOf(p));
+  if (!provider) return null;
+  if (!PROVIDERS[provider]) throw new Error(`unknown LLM provider "${provider}" (known: ${Object.keys(PROVIDERS).join(", ")})`);
+  return createComplete({ provider, apiKey: keyOf(provider), model: env.PAGETAILOR_MODEL || undefined, baseUrl: env.PAGETAILOR_LLM_URL || undefined });
+}
+export const LLM_HELP = "set an LLM key (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY) or PAGETAILOR_PROVIDER=ollama|compatible, plus PAGETAILOR_MODEL";