@happyvertical/smrt-prompts 0.30.0

package/AGENTS.md

@@ -0,0 +1,36 @@
+# smrt-prompts
+
+SMRT prompt registry and tenant-aware prompt override package. Code defines defaults; config layers and DB-stored overrides personalize at app and tenant levels.
+
+## Core pieces
+
+- `definePrompt()` registers code defaults in a global process registry (`globalThis.__smrtPromptRegistry`)
+- `resolvePrompt()` merges code defaults, file/config overrides (via `@happyvertical/smrt-config`), stored app-level overrides, stored tenant-level overrides, and a runtime override
+- `PromptOverride` (`_smrt_prompt_overrides` table) stores partial app-level and tenant-level overrides with write-time validation
+- `PromptOverrideCollection` exposes the standard SmrtCollection CRUD surface
+
+## Resolution layers (priority low → high)
+
+1. Code default — registered via `definePrompt({ key, template, ai })`
+2. File/config override — `getPackageConfig<PromptPackageConfig>('prompts', defaults)`
+3. App-level stored override — `PromptOverride` row with `tenantId = null`
+4. Tenant-level stored override — `PromptOverride` row with current tenant
+5. Runtime override — passed to `resolvePrompt({ overrides })`
+
+Each layer can override any subset of fields (template, profile, model, params). Inheritance is field-by-field.
+
+## Conventions
+
+- **Namespace prompt keys** by package or domain: `projects.issue.incorporateFeedback`, `content.summarize.headline`
+- **Stored overrides use nullable fields** so inheritance stays field-by-field — null means "use the lower layer"
+- **Provider selection is indirect** in v1: prompts select named profiles, and profiles resolve to provider/model in `smrt-config`
+- **`editable` flags are enforced on `PromptOverride.save()`** — definitions can lock specific fields against tenant override
+
+## Caching
+
+`resolvePrompt()` results are cached per `(key, tenantId)` with a TTL. The cache is invalidated on `PromptOverride.save()` and `.delete()`. Use `clearPromptCache()` for manual invalidation in tests.
+
+## Related
+
+- `@happyvertical/smrt-languages` — parallel package for language strings (uses the same architecture pattern)
+- `@happyvertical/smrt-features` — parallel package for feature flags

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+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

@@ -0,0 +1,49 @@
+# @happyvertical/smrt-prompts
+
+Typed prompt definitions, tenant-aware prompt overrides, and runtime prompt resolution for SMRT applications.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-prompts
+```
+
+## Quick start
+
+```typescript
+import { definePrompt, resolvePrompt } from '@happyvertical/smrt-prompts';
+
+// 1. Register a prompt's defaults at startup
+definePrompt({
+  key: 'projects.issue.incorporateFeedback',
+  template: 'Rewrite the issue body incorporating this feedback: {feedback}',
+  ai: {
+    profile: 'default',
+    params: { temperature: 0.4 },
+  },
+});
+
+// 2. Resolve at runtime (auto-uses tenant context from AsyncLocalStorage)
+const resolved = await resolvePrompt('projects.issue.incorporateFeedback', {
+  vars: { feedback: '...' },
+});
+
+// resolved.template — the merged template with overrides applied
+// resolved.ai     — the merged AI configuration (profile, model, params)
+```
+
+## What this package provides
+
+- **`definePrompt()`** — code-first prompt registration in a global process registry
+- **`resolvePrompt()`** — layered resolution: code default → config override → stored app override → stored tenant override → runtime override
+- **`PromptOverride`** — CRUD model for app-level and tenant-level prompt settings, stored in `_smrt_prompt_overrides`
+- **Named AI profiles** loaded from `packages.prompts` config — prompts select profile names, profiles resolve to provider/model in config
+- **TTL cache** keyed by `(key, tenantId)`, invalidated on override save/delete
+
+Stored overrides support partial fields, so applications can override only the template, profile, model, or AI params without forking the rest of a prompt.
+
+## Documentation
+
+- See [`AGENTS.md`](./AGENTS.md) for package-internal patterns
+- See [`docs/standards.md`](../../docs/standards.md) for monorepo conventions
+- See related: [`@happyvertical/smrt-languages`](../languages) (mirrors this package for language strings), [`@happyvertical/smrt-features`](../features) (feature flags)

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+export declare function clearPromptCache(): void;
+
+export declare function definePrompt(input: PromptDefinitionInput): PromptDefinition;
+
+export declare function getPromptCacheTtlMs(): number;
+
+export declare interface NormalizedPromptAI {
+    profile?: string;
+    model?: string;
+    params: PromptParams;
+}
+
+/* Excluded from this release type: PACKAGE_VERSION_INITIALIZED */
+
+export declare interface PromptAIInput {
+    profile?: string | null;
+    model?: string | null;
+    params?: PromptParams | null;
+    temperature?: number;
+    maxTokens?: number;
+    [key: string]: unknown;
+}
+
+export declare interface PromptConfigOverrideInput {
+    template?: string | null;
+    profile?: string | null;
+    model?: string | null;
+    params?: PromptParams | null;
+    ai?: PromptAIInput | null;
+    temperature?: number;
+    maxTokens?: number;
+    [key: string]: unknown;
+}
+
+export declare interface PromptDefinition {
+    key: string;
+    template: string;
+    ai: NormalizedPromptAI;
+    editable: PromptEditableConfig;
+}
+
+export declare interface PromptDefinitionInput {
+    key: string;
+    template: string;
+    ai?: PromptAIInput;
+    editable?: Partial<PromptEditableConfig>;
+}
+
+export declare interface PromptEditableConfig {
+    template: boolean;
+    profile: boolean;
+    model: boolean;
+    params: boolean;
+}
+
+export declare interface PromptLayer {
+    template?: string | null;
+    profile?: string | null;
+    model?: string | null;
+    params?: PromptParams | null;
+}
+
+export declare class PromptOverride extends SmrtObject {
+    key: string;
+    tenantId: string | null;
+    template: string | null;
+    profile: string | null;
+    model: string | null;
+    params: string | null;
+    constructor(options?: PromptOverrideOptions);
+    getParams(): PromptParams;
+    setParams(params: PromptParams | null): void;
+    toPromptLayer(): PromptLayer;
+    save(): Promise<this>;
+    private saveAfterIdentityChange;
+    private saveAfterIdentityChangeInTransaction;
+    private saveAfterIdentityChangeWithDeferredDelete;
+    delete(): Promise<void>;
+    private validatePromptOverride;
+    private getLowerPrecedenceLayers;
+    private normalizeParamsForPersistence;
+    private getPersistedIdentity;
+}
+
+export declare class PromptOverrideCollection extends SmrtCollection<PromptOverride> {
+    static readonly _itemClass: typeof PromptOverride;
+    private excludeOverrideId;
+    getAppOverride(key: string, options?: {
+        excludeId?: string;
+    }): Promise<PromptOverride | null>;
+    getTenantOverride(key: string, tenantId: string, options?: {
+        excludeId?: string;
+    }): Promise<PromptOverride | null>;
+    getResolutionLayers(key: string, tenantId?: string | null, options?: {
+        excludeId?: string;
+    }): Promise<{
+        app: PromptOverride | null;
+        tenant: PromptOverride | null;
+    }>;
+}
+
+export declare interface PromptOverrideOptions extends SmrtObjectOptions {
+    key?: string;
+    tenantId?: string | null;
+    template?: string | null;
+    profile?: string | null;
+    model?: string | null;
+    params?: string | PromptParams | null;
+}
+
+export declare interface PromptPackageConfig {
+    profiles?: Record<string, PromptProfileConfig>;
+    prompts?: Record<string, PromptConfigOverrideInput>;
+    allowedProfileNames?: string[];
+    allowedModels?: string[];
+    [key: string]: unknown;
+}
+
+export declare type PromptParams = Record<string, unknown>;
+
+export declare interface PromptProfileConfig {
+    provider: string;
+    model: string;
+    params?: PromptParams | null;
+    temperature?: number;
+    maxTokens?: number;
+    [key: string]: unknown;
+}
+
+export declare const PromptRegistry: {
+    register(input: PromptDefinitionInput): PromptDefinition;
+    get(key: string): PromptDefinition | undefined;
+    has(key: string): boolean;
+    getAll(): PromptDefinition[];
+    clear(): void;
+};
+
+export declare interface ResolvedPrompt {
+    key: string;
+    template: string;
+    text: string;
+    ai: ResolvedPromptAI;
+}
+
+export declare interface ResolvedPromptAI extends PromptParams {
+    profile?: string;
+    provider?: string;
+    model?: string;
+    allowedModels?: string[];
+    params: PromptParams;
+    temperature?: number;
+    maxTokens?: number;
+}
+
+export declare function resolvePrompt(key: string, options?: ResolvePromptOptions): Promise<ResolvedPrompt>;
+
+export declare interface ResolvePromptOptions {
+    db?: SmrtClassOptions['db'];
+    tenantId?: string | null;
+    variables?: Record<string, unknown>;
+    override?: PromptConfigOverrideInput;
+}
+
+export { }