anbaric 1.35.0 → 1.36.0

package/docs/README.md

@@ -27,6 +27,7 @@ What the framework gives you, one capability at a time.
 - [The SQL store](features/sql-store.md) — a relational database for structured data
 - [Auditing](features/auditing.md) — the record of who changed what
 - [Entitlements](features/entitlements.md) — what a user has been granted, checked per request
+- [Prompts](features/prompts.md) — versioned model instructions and schemas, saved at startup
 - [Serving a web UI](features/serving-a-web-ui.md) — putting your data on a page
 - [The admin console and widgets](features/admin-console-and-widgets.md) — dashboards and plugins
 - [Deploying](features/deploying.md) — from laptop to Anbaric Cloud

package/docs/api/environment.md

@@ -36,6 +36,7 @@ defaulting to a local implementation otherwise).
 | `ANBARIC_SQL_STORE_TYPE` | the SQL store (`sqlite` / `cloud`\|`postgres`) | SQLite |
 | `ANBARIC_SESSION_RESOLVER_TYPE` | how `Human.fromSession` resolves sessions | in-memory |
 | `ANBARIC_ENTITLEMENTS_TYPE` | how `hasEntitlement` is answered (`cloud` → platform) | permissive (always `true`) |
+| `ANBARIC_PROMPT_MANAGER_TYPE` | the [prompt manager](../features/prompts.md) | in-memory |
 
 ## Store configuration
 

package/docs/api/stores.md

@@ -86,6 +86,42 @@ const key = await secrets.retrieve("stripe-key", actor);
 
 ---
 
+## `PromptManager`
+
+Versioned prompts - instructions plus optional input and output schemas - owned
+by the calling app.
+
+```ts
+PromptManagerFactory.instance() : PromptManager
+
+// methods:
+save(promptId : string, instructions : string, inputSchema? : JsonSchema, outputSchema? : JsonSchema) : Promise<Prompt>
+retrieve(promptId : string, version? : number) : Promise<Prompt>
+list() : Promise<Array<Prompt>>
+history(promptId : string) : Promise<Array<Prompt>>
+
+type Prompt = {
+    appId : string, promptId : string, version : number, instructions : string,
+    inputSchema? : JsonSchema, outputSchema? : JsonSchema, createdAt : string,
+}
+```
+
+```ts
+const prompts = PromptManagerFactory.instance();
+await prompts.save("triage", "Decide the priority.", undefined, { type: "object", properties: { priority: { type: "string" } } });
+const latest   = await prompts.retrieve("triage");      // highest version
+const specific = await prompts.retrieve("triage", 1);
+const all      = await prompts.list();                  // latest of each prompt
+const versions = await prompts.history("triage");       // newest first
+```
+
+- `save` stores a new version only when the content differs from the latest; an identical save returns the existing version, so registering at every startup is safe.
+- Versions auto-increment from 1; there is no rollback or tagging.
+- `retrieve` of an unknown prompt throws `No prompt found with id "..."`.
+- Env var: **`ANBARIC_PROMPT_MANAGER_TYPE`** (`cloud` deployed; in-memory otherwise).
+
+---
+
 ## `SqlStore`
 
 A relational database — SQLite locally, PostgreSQL deployed.

package/docs/api/typescript.md

@@ -9,7 +9,7 @@ import {
     StateMachine, State, Terminal, Action, Await, Transition,
     Job, PropertyDefinition,
     Code, Human, SystemActor, Agent, OpenAIAgent, RemoteLLMAgenticAction,
-    JsonStoreFactory, SecretStoreFactory, SqlStoreFactory,
+    JsonStoreFactory, SecretStoreFactory, SqlStoreFactory, PromptManagerFactory,
     registerEntitlement, hasEntitlement,
 } from "anbaric";
 
@@ -27,8 +27,10 @@ An Anbaric app is a standard Node.js **ESM** program in TypeScript: set
   `Actor`.
 - **[Actors and agents](actors-and-agents.md)** — `Code`, `Human`,
   `SystemActor`, `Agent`, `RemoteLLMAgenticAction`, `OpenAIAgent`.
-- **[Stores](stores.md)** — `JsonStore`, `SecretStore`, `SqlStore` and their
-  factories, plus `JsonSchema`.
+- **[Stores](stores.md)** — `JsonStore`, `SecretStore`, `SqlStore`,
+  `PromptManager` and their factories, plus `JsonSchema`.
+- **[Entitlements](../features/entitlements.md)** — `registerEntitlement`,
+  `hasEntitlement`.
 - **[Environment and factories](environment.md)** — the `ANBARIC_*` variables
   the factories read.
 

package/docs/features/ai-agents.md

@@ -54,6 +54,25 @@ must return. The model is constrained to it (strict structured output), so you
 get well-typed properties back rather than free text. Keep the schema tight —
 only the properties you want written to the job.
 
+## Keep the prompt in the prompt manager
+
+Instructions change more often than code. Rather than a string literal, save
+the prompt with the [prompt manager](prompts.md) at startup and read the
+latest where the action is built - every edit is versioned and visible in the
+console's **Prompts** page:
+
+```ts
+import {PromptManagerFactory} from "anbaric";
+
+const prompts = PromptManagerFactory.instance();
+await prompts.save("triage", "Decide the priority of the support ticket from its subject.",
+    undefined, { type: "object", properties: { priority: { type: "string", enum: ["low", "high"] } } });
+
+const prompt = await prompts.retrieve("triage");
+const triage = new RemoteLLMAgenticAction("Triage the ticket", triager,
+    [{ role: "system", content: prompt.instructions }], prompt.outputSchema!);
+```
+
 ## Bring your own model
 
 `OpenAIAgent` targets any OpenAI-compatible endpoint. Configure it with a

package/docs/features/prompts.md

@@ -0,0 +1,78 @@
+# Prompts
+
+The instructions you give a model are part of your app, but they change more
+often than code and you want to see what was said when. The **prompt manager**
+keeps each prompt your app uses as a **versioned** record: save it at startup,
+fetch it where you call the model, and every change is kept in the console with
+its history. Like every other store, it's in-memory locally and platform-backed
+once deployed - no code change.
+
+## Register prompts at startup
+
+Save each prompt once when the app starts. If nothing changed since the last
+run, no new version is stored - so registering on every boot is free.
+
+```ts
+import {PromptManagerFactory} from "anbaric";
+
+const prompts = PromptManagerFactory.instance();
+
+await prompts.save(
+    "triage",
+    "Decide the priority of the support ticket from its subject and body. Escalate anything mentioning an outage.",
+    { type: "object", required: ["subject", "body"], properties: { subject: { type: "string" }, body: { type: "string" } } },
+    { type: "object", required: ["priority"], properties: { priority: { type: "string", enum: ["low", "high"] } } },
+);
+```
+
+A prompt has an **id**, its **instructions**, and optionally an **input
+schema** (the shape of what the model is given) and an **output schema** (what
+it must produce). Edit the instructions and redeploy: the next save stores
+version 2. There's no rollback and no tagging - an app always gets the latest.
+
+## Use the latest where you call the model
+
+```ts
+import {OpenAIAgent, RemoteLLMAgenticAction} from "anbaric";
+
+const triagePrompt = await prompts.retrieve("triage");
+
+const triage = new RemoteLLMAgenticAction(
+    "Triage the ticket",
+    new OpenAIAgent("triager", "support", { apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5.4-mini" }),
+    [{ role: "system", content: triagePrompt.instructions }],
+    triagePrompt.outputSchema!,
+);
+```
+
+`retrieve(id)` returns the latest version; `retrieve(id, 3)` a specific one.
+An unknown prompt throws `No prompt found with id "..."`.
+
+## Look back
+
+```ts
+const latest = await prompts.list();            // the latest version of every prompt this app has
+const versions = await prompts.history("triage"); // every version, newest first
+```
+
+The console's **Prompts** page shows the same for every app on the tenant: each
+prompt, its current instructions and schemas, and the full history to browse.
+
+## Everything is scoped to your app
+
+Deployed, prompts are **owned by your app** - two apps can both have a `triage`
+prompt without seeing each other's. The platform scopes every read and write to
+your app automatically.
+
+## Choosing an implementation
+
+You don't - the factory does, from the environment:
+
+| Factory | Env var | Local default | Deployed |
+| --- | --- | --- | --- |
+| `PromptManagerFactory.instance()` | `ANBARIC_PROMPT_MANAGER_TYPE` | in-memory | platform (`cloud`) |
+
+## Next
+
+- [AI agents](ai-agents.md) - putting a prompt to work in a state
+- [API: Stores](../api/stores.md#promptmanager)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "description": "Everything needed to write an Anbaric app: state machines, jobs, document and secret stores, local in-memory implementations and the Anbaric Cloud clients",
   "license": "MIT",
   "type": "module",
@@ -24,9 +24,9 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "anbaric-impl-cloud": "^1.35.0",
-    "anbaric-data-store": "^1.35.0",
-    "anbaric-state-machine": "^1.35.0",
-    "anbaric-tsapi": "^1.35.0"
+    "anbaric-impl-cloud": "^1.36.0",
+    "anbaric-data-store": "^1.36.0",
+    "anbaric-state-machine": "^1.36.0",
+    "anbaric-tsapi": "^1.36.0"
   }
 }