promptopskit 0.4.2 → 0.6.2

package/README.md

@@ -5,48 +5,40 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 
-**Centralize prompts, system instructions, tools, and model settings — without leaving your codebase.**
+**Turn hardcoded AI prompts into versioned, tested application assets.**
 
-Your prompts are already in Git. PromptOpsKit makes them manageable. It replaces hardcoded strings and scattered provider-specific glue with structured Markdown files where prompt text, model settings, sampling parameters, tool bindings, environment overrides, and composable shared instructions all live together — diffable, reviewable, and release-aware.
+Your prompts are already in Git. PromptOpsKit makes them manageable.
 
-Provider adapters for OpenAI, Anthropic, Gemini, and OpenRouter produce a ready-to-send **request body only** — no HTTP client, no auth, no headers. Your application owns transport, so PromptOpsKit slots into any stack without opinions about how you call the API.
+Keep prompts, model settings, tools, input validation, shared instructions, environment overrides, and tests together in Markdown files that live in Git and ship with your app. Render provider-ready request bodies without giving up your SDK, gateway, auth, retries, routing, observability, or billing.
 
-## How is this different from GitHub Models?
+PromptOpsKit is not a prompt dashboard, LLM gateway, or hosted runtime service. It is the repo-native layer between scattered prompt strings and production AI calls.
 
-GitHub Models is a great place to prototype prompts, compare models, and run evaluations inside GitHub.
+## Why PromptOpsKit?
 
-PromptOpsKit is focused on the application runtime layer.
+From scattered prompt glue:
 
-It helps you turn prompt behavior into repo-native assets that your application can load, validate, compose, compile, and render into provider-specific request bodies.
+- Prompt strings live inline in code
+- Model config and tools drift in separate files
+- Validation checks happen outside the prompt
+- Environment logic hides in if/else branches
+- Testing is ad hoc and hard to review
 
-Use GitHub Models when you want:
+To one reviewable asset:
 
-- a GitHub-hosted prompt editor and playground
-- side-by-side model comparisons
-- structured evaluations inside GitHub
-- `.prompt.yml` files for prompt experiments and evals
+- Prompt, model, tools, and input rules live together
+- `includes` and `defaults.md` avoid copy-paste drift
+- `environments` and `tiers` handle overrides cleanly
+- `.test.yaml` sidecars keep deterministic test behavior
+- Runtime rendering and compiled artifacts support production deployment
 
-Use PromptOpsKit when you want:
+Core capabilities:
 
-- Markdown prompt assets with YAML metadata
-- production input hardening and validation
-- environment-specific model and parameter overrides
-- reusable prompt composition
-- compiled artifacts for deployment
-- provider-specific request bodies for your own runtime code
-- control over SDKs, auth, retries, routing, observability, and billing
-
-### Why PromptOpsKit?
-
-- **Centralized, not scattered** — each prompt is a single Markdown file that captures prompt text, model config, tool bindings, and context rules together.
-- **Operational, not just templated** — model name, temperature, reasoning effort, tools, and response format are declared alongside the prompt they govern.
-- **Reusable, not duplicated** — `includes` lets you define shared tone, policy, or safety instructions once and compose them into any prompt.
-- **Layered defaults, not repetition** — `defaults.md` in any folder sets shared `provider`, `model`, `metadata`, and `# System instructions` for that subtree, with nearest-folder override behavior.
-- **Release-aware, not ad hoc** — environment and tier overrides swap models and parameters without forking prompt files.
-- **Provider-portable** — write once, render for OpenAI, Anthropic, Gemini, or OpenRouter with correct body shapes.
-- **Validate early** — Zod schema validation, Levenshtein-based "did you mean?" suggestions for typos, and variable usage checks catch mistakes before runtime.
-- **Compile for production** — pre-compile `.md` to JSON or ESM so deployments skip parsing entirely.
-- **Repo-native, not dashboard-native** — no hosted service, no external admin tool. Everything lives in source control.
+- **Markdown prompt assets** — capture prompt text, model config, tool bindings, context rules, and metadata together.
+- **Provider-ready output** — render request bodies for OpenAI Chat, OpenAI Responses, Anthropic, Gemini, OpenRouter, and LLMAsAService while your app owns transport.
+- **Input hardening** — define required values, size limits, allow/deny patterns, and secret rejection close to the prompt template.
+- **Reusable composition** — share tone, policy, and safety instructions with `includes`, and apply folder-level standards with `defaults.md`.
+- **Environment and tier overrides** — keep dev/prod and plan-specific behavior in one prompt source with explicit, reviewable overrides.
+- **Sidecar tests** — run deterministic prompt checks in local development and CI without calling a model.
 
 ## Install
 
@@ -67,7 +59,7 @@ This creates:
 
 ```
 prompts/
-├── defaults.md         # Folder-level defaults (provider, model, metadata, system instructions)
+├── defaults.md         # Folder-level defaults (provider, model, options, metadata, system instructions)
 ├── hello.md            # Sample prompt with variables
 ├── hello.test.yaml     # Test sidecar with sample inputs and hardcoded responses
 └── shared/
@@ -85,26 +77,21 @@ id: support/reply
 schema_version: 1
 provider: openai
 model: gpt-5.4
-reasoning:
-  effort: medium
-sampling:
-  temperature: 0.7
+includes:
+  - ./shared/tone.md
 context:
   inputs:
     - name: user_message
-      non_empty:
-        return_message: "Please enter a message before continuing."
+      non_empty: true
       reject_secrets: true
-    - name: app_context
-      max_size: 2000
-      allow_regex: /^[A-Za-z0-9 _-]+$/i
-includes:
-  - ./shared/tone.md
+environments:
+  dev:
+    model: gpt-5.4-mini
 ---
 
 # System instructions
 
-You are a helpful support assistant working in {{ app_context }}.
+You are a helpful support assistant.
 
 # Prompt template
 
@@ -116,14 +103,14 @@ You are a helpful support assistant working in {{ app_context }}.
 ```typescript
 import { createPromptOpsKit } from 'promptopskit';
 
-const kit = createPromptOpsKit();
+const kit = createPromptOpsKit({ sourceDir: './prompts' });
 
 const result = await kit.renderPrompt({
   path: 'support/reply',
   provider: 'openai',
+  environment: 'prod',
   variables: {
     user_message: 'How do I reset my password?',
-    app_context: 'Account settings page',
   },
 });
 
@@ -159,15 +146,16 @@ Supported values for `warnings.contextSize` are `auto`, `off`, `result-only`, `c
 - **Prompts as Markdown** — YAML front matter for settings, H1 headings for sections (`# System instructions`, `# Prompt template`, `# Notes`)
 - **Variable interpolation** — `{{ variable }}` syntax with strict and permissive modes
 - **Composition** — `includes` to share system instructions across prompts, with circular detection
-- **Folder defaults** — `defaults.md` inheritance for shared provider, model, metadata, and system instructions
+- **Folder defaults** — `defaults.md` inheritance for shared provider, model, options, metadata, and system instructions
 - **Overrides** — Environment and tier-based overrides (base → env → tier → runtime)
-- **5 provider adapters** — OpenAI (Chat), OpenAI (Responses), Anthropic, Gemini, OpenRouter — body-only output
+- **6 provider adapters** — OpenAI (Chat), OpenAI (Responses), Anthropic, Gemini, OpenRouter, LLMAsAService
 - **Provider-aware input caching controls** — optional `cache` front matter maps to OpenAI prompt cache hints, Anthropic `cache_control`, and Gemini `cachedContent`
 - **Vendor escape hatch** — optional `raw.<provider>` blocks shallow-merge unmodeled request-body fields into the final provider payload
 - **Validation** — Zod schema validation, Levenshtein-based "did you mean?" for typos, variable usage checks
 - **Context hardening** — copyable `/pattern/i` regex literals, structured regexes with `return_message`, and built-in `non_empty` / `reject_secrets` validators
 - **Optional short-circuit messages** — validators can return a structured `returnMessage` instead of throwing when configured
 - **Context size guardrails** — optional per-input `max_size` metadata with non-blocking render-time warnings
+- **History preservation** — optional `context.history.max_items` compacts older conversation turns into one preserved history item, with a runtime `onHistoryCompaction` hook for custom summaries
 - **Warning controls** — top-level config can suppress or emit context size warnings differently in dev and prod
 - **Caching** — LRU cache with mtime-based invalidation
 - **CLI** — init, validate, compile, render, inspect, skill
@@ -215,6 +203,24 @@ result = await kit.renderPrompt({
   variables: { name: 'World', app_context: 'Welcome screen' },
 });
 if (!result.request) throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+
+// LLMAsAService — OpenAI-compatible gateway with project and customer metadata
+result = await kit.renderPrompt({
+  path: 'hello',
+  provider: 'llmasaservice',
+  runtime: {
+    provider_options: {
+      llmasaservice: {
+        project_id: process.env.LLM_GATEWAY_PROJECT_ID,
+        customer: { customer_id: 'cust_123', customer_name: 'Acme' },
+      },
+    },
+  },
+  variables: { name: 'World', app_context: 'Welcome screen' },
+});
+if (!result.request) throw new Error(result.returnMessage ?? 'Prompt rendering failed.');
+// result.request.body → { model, messages, customer, ... }
+// result.request.headers → { 'x-project-id': '...' }
 ```
 
 Provider adapters are also available as direct imports:
@@ -225,6 +231,7 @@ import { openaiResponsesAdapter } from 'promptopskit/openai-responses';
 import { anthropicAdapter } from 'promptopskit/anthropic';
 import { geminiAdapter } from 'promptopskit/gemini';
 import { openrouterAdapter } from 'promptopskit/openrouter';
+import { llmasaserviceAdapter } from 'promptopskit/llmasaservice';
 ```
 
 Direct adapter rendering also accepts `environment` and `tier` selectors. This is useful for compiled JSON/ESM assets in browser, edge, or worker code:
@@ -254,9 +261,9 @@ In browser or client-side code, keep provider credentials on the server. Use the
 
 ### Provider-specific fields and raw passthrough
 
-Use normalized fields first (`sampling`, `response`, `cache`, `tools`) so prompts stay portable. `response.schema` is the neutral JSON Schema path; adapters emit it as OpenAI/OpenRouter `response_format`, OpenAI Responses `text.format`, Anthropic `output_config.format`, and Gemini `generationConfig.responseJsonSchema`.
+Use normalized fields first (`sampling`, `response`, `cache`, `tools`) so prompts stay portable. `response.schema` is the neutral JSON Schema path; adapters emit it as OpenAI/OpenRouter/LLMAsAService `response_format`, OpenAI Responses `text.format`, Anthropic `output_config.format`, and Gemini `generationConfig.responseJsonSchema`. You can also provide `response.schema_ref` to load schema from a prompt-relative `.json` file or `.js/.mjs/.cjs` zod module (mutually exclusive with `response.schema`).
 
-Use `provider_options` when PromptOpsKit has a known provider-specific mapping, such as Anthropic `top_k`, Gemini's native `response_schema`, or OpenRouter routing fields.
+Use `provider_options` when PromptOpsKit has a known provider-specific mapping, such as Anthropic `top_k`, Gemini's native `response_schema`, OpenRouter routing fields, or LLMAsAService gateway routing/customer metadata.
 
 ```yaml
 response:
@@ -273,8 +280,16 @@ provider_options:
     provider:
       order: ["anthropic", "openai"]
     transforms: ["middle-out"]
+  llmasaservice:
+    project_id: "llm-project-id"
+    # Optional default; usually pass the real customer at render time.
+    customer:
+      customer_id: "cust_123"
+      customer_name: "Acme"
 ```
 
+For LLMAsAService, `provider_options.llmasaservice.customer` is intended to be render-time attribution for the current account/user. A prompt can keep a default, but production calls should normally override it through `runtime.provider_options.llmasaservice.customer`.
+
 When a provider adds a body field PromptOpsKit does not model yet, use `raw`:
 
 ```yaml
@@ -290,6 +305,8 @@ raw:
   openrouter:
     usage:
       include: true
+  llmasaservice:
+    conversationId: "conv_123"
 ```
 
 Each adapter reads only its matching raw block and shallow-merges it into the generated request body after normalized mappings. This is intentionally an escape hatch; prefer first-class fields when they exist.
@@ -323,9 +340,32 @@ If you need a different layout, keep passing `sourceDir` and `compiledDir` expli
 
 `renderPrompt()` and `validatePrompt()` use the same source-versus-compiled resolution rules as `kit.renderPrompt()`. The existing synchronous `render()` and `validate()` methods still work for already-resolved compiled or inline assets.
 
+## How It Compares to GitHub Models
+
+GitHub Models is a good place to prototype prompts, compare models, and run evaluations inside GitHub.
+
+PromptOpsKit is focused on the application runtime layer. Use it when prompt behavior needs to live in your repo with validated inputs, reusable composition, environment and tier overrides, sidecar tests, compiled artifacts, and provider-ready request bodies.
+
+Use GitHub Models when you want:
+
+- A GitHub-hosted prompt playground
+- Side-by-side model comparison
+- Evaluation workflows inside GitHub
+- `.prompt.yml` files for prompt experiments and evals
+
+Use PromptOpsKit when you want:
+
+- Runtime-focused Markdown prompt assets
+- Production input hardening and validation
+- Reusable `includes` and folder-level `defaults.md`
+- Environment-specific model and parameter overrides
+- Deterministic local and CI testing without model calls
+- Provider-specific request bodies for your own runtime code
+- Control over SDKs, auth, retries, routing, observability, and billing
+
 ## Optional UsageTap Tracking
 
-PromptOpsKit can also help you track provider calls with UsageTap.com while keeping the core render API body-only.
+PromptOpsKit can also help you track provider calls with UsageTap.com while keeping the core render API transport-light.
 
 ```typescript
 import { createPromptOpsKit } from 'promptopskit';
@@ -389,7 +429,7 @@ const tracked = await runOpenAIWithUsageTap(usageTap, {
 
 Notes:
 - `entitlementMode` defaults to `'off'`. Set it to `'apply'` only when you want UsageTap allowances to mutate a cloned provider request.
-- `runOpenRouterWithUsageTap`, `runAnthropicWithUsageTap`, and `runGeminiWithUsageTap` follow the same pattern.
+- `runOpenRouterWithUsageTap`, `runLLMAsAServiceWithUsageTap`, `runAnthropicWithUsageTap`, and `runGeminiWithUsageTap` follow the same pattern.
 - `extractOpenAIUsage`, `extractAnthropicUsage`, and `extractGeminiUsage` are public if you want to manage UsageTap lifecycle yourself.
 
 For explicit lifecycle control, use `beginUsageTapCall`, `endUsageTapCall`, or `withUsageTapCall` from `promptopskit/usagetap`. Full documentation: [docs/usagetap.md](./docs/usagetap.md).
@@ -456,13 +496,15 @@ Handle support requests carefully.
 
 Define a `defaults.md` file in `prompts/` (and optional subfolders) to provide inherited defaults for prompts:
 
-- Shared `provider` and `model` in front matter
+- Shared `provider`, `model`, `fallback_models`, `reasoning`, `sampling`, `response`, `cache`, `provider_options`, `raw`, `tools`, `mcp`, `context`, `includes`, `environments`, and `tiers` in front matter
 - Shared `metadata` defaults in front matter
 - Shared `# System instructions` in body
 - Nearest subfolder `defaults.md` overrides parent defaults
 - Prompt-local values always win over defaults
 - Included files (`includes`) are not affected by folder defaults
 
+Scalars and arrays are replaced by nearer values. Object blocks are shallow-merged, including provider sub-blocks such as `provider_options.llmasaservice` and `cache.openai`.
+
 > `promptopskit init` scaffolds a starter `defaults.md` in the prompts root.
 
 ```text
@@ -582,14 +624,15 @@ Renders a prompt for a specific provider. Returns `{ resolved, request?, returnM
 |--------|------|-------------|
 | `path` | `string` | Prompt path (no extension), e.g. `'support/reply'` |
 | `source` | `string` | Inline prompt source (alternative to path) |
-| `provider` | `string` | `'openai'`, `'openai-responses'`, `'anthropic'`, `'gemini'`, `'openrouter'` |
+| `provider` | `string` | `'openai'`, `'openai-responses'`, `'anthropic'`, `'gemini'`, `'openrouter'`, `'llmasaservice'` |
 | `variables` | `Record<string, string>` | Template variables |
 | `onContextOverflow` | `(info) => string` | Optional callback to transform oversized context values before rendering |
+| `onHistoryCompaction` | `(info) => string \| { role, content }` | Optional callback to compact overflow history when `context.history.max_items` is exceeded |
 | `environment` | `string` | Environment override name |
 | `tier` | `string` | Tier override name |
-| `history` | `Array<{ role, content }>` | Conversation history |
+| `history` | `Array<{ role, content }>` | Conversation history. If the prompt declares `context.history.max_items`, older turns are compacted into one preserved history item before provider rendering. |
 | `toolRegistry` | `Record<string, unknown>` | Tool definitions for resolving string tool references |
-| `strict` | `boolean` | Fail on missing variables |
+| `strict` | `boolean` | Fail on missing variables except object-form inputs marked `optional: true` |
 | `openaiResponses` | `object` | Optional Responses API extras (`previous_response_id`, `conversation`, `instructions`, `parallel_tool_calls`, `max_tool_calls`, `store`, `metadata`, `include`, `background`) |
 
 ### `kit.loadPrompt(path)` / `kit.resolvePrompt(path, options)` / `kit.validatePrompt(path)`
@@ -610,18 +653,18 @@ Prompt files use YAML front matter with these fields:
 |-------|------|-------------|
 | `id` | `string` | Unique prompt identifier (required) |
 | `schema_version` | `number` | Schema version, currently `1` |
-| `provider` | `string` | `openai`, `openai-responses`, `anthropic`, `gemini` (or `google`), `openrouter`, `any` |
+| `provider` | `string` | `openai`, `openai-responses`, `anthropic`, `gemini` (or `google`), `openrouter`, `llmasaservice`, `any` |
 | `model` | `string` | Model name |
 | `fallback_models` | `string[]` | Fallback model list |
 | `reasoning` | `object` | `{ effort, budget_tokens }` |
 | `sampling` | `object` | `{ temperature, top_p, frequency_penalty, presence_penalty, stop, max_output_tokens }` |
-| `response` | `object` | `{ format, stream, schema, schema_name, schema_description, schema_strict }` |
+| `response` | `object` | `{ format, stream, schema, schema_ref, schema_name, schema_description, schema_strict }` |
 | `cache` | `object` | Provider-specific cache controls (`openai`, `anthropic`, `gemini`/`google`) |
 | `tools` | `array` | Tool references (string names or inline definitions) |
-| `provider_options` | `object` | Provider-specific non-portable options (`anthropic`, `gemini`, `openrouter`) |
-| `raw` | `object` | Provider-scoped request-body passthrough (`openai`, `openai-responses`, `anthropic`, `gemini`/`google`, `openrouter`) |
+| `provider_options` | `object` | Provider-specific non-portable options (`anthropic`, `gemini`, `openrouter`, `llmasaservice`) |
+| `raw` | `object` | Provider-scoped request-body passthrough (`openai`, `openai-responses`, `anthropic`, `gemini`/`google`, `openrouter`, `llmasaservice`) |
 | `mcp` | `object` | MCP server references |
-| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, and built-in `non_empty` / `reject_secrets` validators |
+| `context` | `object` | `{ inputs, history }` — declare expected variables, with optional per-input `optional`, `warnings`, `max_size`, `trim`, structured or literal `allow_regex`/`deny_regex`, built-in `non_empty` / `reject_secrets` validators, and `history.max_items` compaction |
 | `includes` | `string[]` | Paths to included prompt files |
 | `environments` | `object` | Named environment overrides |
 | `tiers` | `object` | Named tier overrides |