substrai-promptops 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PromptOps client for runtime prompt invocation.
+ */
+import { PromptDefinition, Prompt } from "./prompt";
+export interface InvocationResult {
+    output: any;
+    promptName: string;
+    version: string;
+    model: string;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cost: number;
+    environment: string;
+    success: boolean;
+    errors: string[];
+}
+export declare class PromptClient {
+    private env;
+    private registry;
+    constructor(options?: {
+        env?: string;
+    });
+    register(definition: PromptDefinition): void;
+    invoke(promptName: string, inputs: Record<string, any>, options?: {
+        version?: string;
+        model?: string;
+    }): InvocationResult;
+    get(promptName: string, version?: string): Prompt;
+    listPrompts(): string[];
+}

package/dist/client.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * PromptOps client for runtime prompt invocation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptClient = void 0;
+const prompt_1 = require("./prompt");
+const version_1 = require("./version");
+class PromptClient {
+    constructor(options = {}) {
+        this.env = options.env || "dev";
+        this.registry = new Map();
+    }
+    register(definition) {
+        if (!this.registry.has(definition.name)) {
+            this.registry.set(definition.name, new Map());
+        }
+        this.registry.get(definition.name).set(definition.version.toString(), definition);
+    }
+    invoke(promptName, inputs, options = {}) {
+        const start = Date.now();
+        const version = options.version || "latest";
+        try {
+            const definitions = this.registry.get(promptName);
+            if (!definitions) {
+                throw new Error(`Prompt '${promptName}' not found`);
+            }
+            const range = new version_1.VersionRange(version);
+            let matched;
+            let matchedVersion;
+            for (const [verStr, def] of definitions) {
+                const ver = version_1.PromptVersion.parse(verStr);
+                if (range.matches(ver)) {
+                    if (!matchedVersion || ver.compareTo(matchedVersion) > 0) {
+                        matched = def;
+                        matchedVersion = ver;
+                    }
+                }
+            }
+            if (!matched || !matchedVersion) {
+                throw new Error(`No version matching '${version}' for prompt '${promptName}'`);
+            }
+            const rendered = matched.render(inputs);
+            const inputTokens = Math.ceil(rendered.length / 4);
+            const outputTokens = Math.floor(matched.defaultModel.maxTokens / 2);
+            const cost = matched.estimateCost(inputs);
+            const latencyMs = Date.now() - start;
+            return {
+                output: rendered,
+                promptName,
+                version: matchedVersion.toString(),
+                model: matched.defaultModel.provider,
+                latencyMs,
+                inputTokens,
+                outputTokens,
+                totalTokens: inputTokens + outputTokens,
+                cost,
+                environment: this.env,
+                success: true,
+                errors: [],
+            };
+        }
+        catch (e) {
+            return {
+                output: null,
+                promptName,
+                version: "0.0.0",
+                model: "unknown",
+                latencyMs: Date.now() - start,
+                inputTokens: 0,
+                outputTokens: 0,
+                totalTokens: 0,
+                cost: 0,
+                environment: this.env,
+                success: false,
+                errors: [e.message],
+            };
+        }
+    }
+    get(promptName, version = "latest") {
+        const definitions = this.registry.get(promptName);
+        if (!definitions) {
+            throw new Error(`Prompt '${promptName}' not found`);
+        }
+        const range = new version_1.VersionRange(version);
+        let matched;
+        for (const [verStr, def] of definitions) {
+            const ver = version_1.PromptVersion.parse(verStr);
+            if (range.matches(ver)) {
+                matched = def;
+            }
+        }
+        if (!matched) {
+            throw new Error(`No version matching '${version}' for prompt '${promptName}'`);
+        }
+        return new prompt_1.Prompt(matched);
+    }
+    listPrompts() {
+        return Array.from(this.registry.keys());
+    }
+}
+exports.PromptClient = PromptClient;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PromptOps - Infrastructure-as-Code for Prompt Engineering
+ *
+ * The first framework for managing prompts as versioned, tested,
+ * deployed infrastructure with semantic versioning, environment
+ * promotion, regression testing, and multi-model targeting.
+ *
+ * @packageDocumentation
+ */
+export { PromptVersion, VersionRange } from "./version";
+export { PromptDefinition, ModelConfig, Prompt } from "./prompt";
+export { InputSchema, OutputSchema, FieldSchema } from "./schema";
+export { PromptClient, InvocationResult } from "./client";
+export { TestRunner, TestResult, TestSuite } from "./testing";

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * PromptOps - Infrastructure-as-Code for Prompt Engineering
+ *
+ * The first framework for managing prompts as versioned, tested,
+ * deployed infrastructure with semantic versioning, environment
+ * promotion, regression testing, and multi-model targeting.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestRunner = exports.PromptClient = exports.OutputSchema = exports.InputSchema = exports.Prompt = exports.PromptDefinition = exports.VersionRange = exports.PromptVersion = void 0;
+var version_1 = require("./version");
+Object.defineProperty(exports, "PromptVersion", { enumerable: true, get: function () { return version_1.PromptVersion; } });
+Object.defineProperty(exports, "VersionRange", { enumerable: true, get: function () { return version_1.VersionRange; } });
+var prompt_1 = require("./prompt");
+Object.defineProperty(exports, "PromptDefinition", { enumerable: true, get: function () { return prompt_1.PromptDefinition; } });
+Object.defineProperty(exports, "Prompt", { enumerable: true, get: function () { return prompt_1.Prompt; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "InputSchema", { enumerable: true, get: function () { return schema_1.InputSchema; } });
+Object.defineProperty(exports, "OutputSchema", { enumerable: true, get: function () { return schema_1.OutputSchema; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "PromptClient", { enumerable: true, get: function () { return client_1.PromptClient; } });
+var testing_1 = require("./testing");
+Object.defineProperty(exports, "TestRunner", { enumerable: true, get: function () { return testing_1.TestRunner; } });

package/dist/prompt.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Prompt definition parser and model.
+ */
+import { PromptVersion } from "./version";
+import { InputSchema, OutputSchema } from "./schema";
+export interface ModelConfig {
+    provider: string;
+    template?: string;
+    temperature: number;
+    maxTokens: number;
+    topP: number;
+    stopSequences: string[];
+}
+export interface PromptDefinitionData {
+    name: string;
+    version: string;
+    description?: string;
+    template: string;
+    model?: {
+        default?: string;
+        fallback?: string;
+        variants?: Record<string, any>;
+    };
+    input?: {
+        schema?: Record<string, any>;
+    };
+    output?: {
+        schema?: Record<string, any>;
+    };
+    settings?: Record<string, any>;
+    metadata?: Record<string, any>;
+}
+export declare class PromptDefinition {
+    readonly name: string;
+    readonly version: PromptVersion;
+    readonly description: string;
+    readonly template: string;
+    readonly inputSchema: InputSchema;
+    readonly outputSchema: OutputSchema;
+    readonly defaultModel: ModelConfig;
+    readonly metadata: Record<string, any>;
+    constructor(data: PromptDefinitionData);
+    render(inputs: Record<string, any>): string;
+    estimateTokens(inputs: Record<string, any>): number;
+    estimateCost(inputs: Record<string, any>): number;
+}
+export declare class Prompt {
+    readonly definition: PromptDefinition;
+    readonly name: string;
+    readonly version: PromptVersion;
+    readonly template: string;
+    constructor(definition: PromptDefinition);
+    render(inputs: Record<string, any>): string;
+    validateInputs(inputs: Record<string, any>): string[];
+    estimateCost(inputs: Record<string, any>): number;
+}

package/dist/prompt.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Prompt definition parser and model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Prompt = exports.PromptDefinition = void 0;
+const version_1 = require("./version");
+const schema_1 = require("./schema");
+class PromptDefinition {
+    constructor(data) {
+        this.name = data.name;
+        this.version = version_1.PromptVersion.parse(data.version || "0.1.0");
+        this.description = data.description || "";
+        this.template = data.template || "";
+        this.inputSchema = schema_1.InputSchema.fromDict(data.input?.schema || {});
+        this.outputSchema = schema_1.OutputSchema.fromDict(data.output?.schema || {});
+        this.defaultModel = {
+            provider: data.model?.default || "bedrock/claude-3-haiku",
+            temperature: data.settings?.temperature || 0.7,
+            maxTokens: data.settings?.max_tokens || 2000,
+            topP: data.settings?.top_p || 1.0,
+            stopSequences: data.settings?.stop_sequences || [],
+        };
+        this.metadata = data.metadata || {};
+    }
+    render(inputs) {
+        const withDefaults = this.inputSchema.applyDefaults(inputs);
+        const errors = this.inputSchema.validate(withDefaults);
+        if (errors.length > 0) {
+            throw new Error(`Input validation failed: ${errors.join("; ")}`);
+        }
+        let rendered = this.template;
+        for (const [key, value] of Object.entries(withDefaults)) {
+            rendered = rendered.replace(new RegExp(`\\{${key}\\}`, "g"), String(value));
+        }
+        return rendered;
+    }
+    estimateTokens(inputs) {
+        const rendered = this.render(inputs);
+        return Math.ceil(rendered.length / 4);
+    }
+    estimateCost(inputs) {
+        const pricing = {
+            "bedrock/claude-3-haiku": { input: 0.00025, output: 0.00125 },
+            "bedrock/claude-3-sonnet": { input: 0.003, output: 0.015 },
+            "bedrock/amazon-titan-text-lite": { input: 0.00015, output: 0.00015 },
+            "openai/gpt-4o-mini": { input: 0.00015, output: 0.0006 },
+        };
+        const modelPricing = pricing[this.defaultModel.provider] || { input: 0.001, output: 0.002 };
+        const inputTokens = this.estimateTokens(inputs);
+        const outputTokens = Math.floor(this.defaultModel.maxTokens / 2);
+        return (inputTokens / 1000) * modelPricing.input + (outputTokens / 1000) * modelPricing.output;
+    }
+}
+exports.PromptDefinition = PromptDefinition;
+class Prompt {
+    constructor(definition) {
+        this.definition = definition;
+        this.name = definition.name;
+        this.version = definition.version;
+        this.template = definition.template;
+    }
+    render(inputs) {
+        return this.definition.render(inputs);
+    }
+    validateInputs(inputs) {
+        const withDefaults = this.definition.inputSchema.applyDefaults(inputs);
+        return this.definition.inputSchema.validate(withDefaults);
+    }
+    estimateCost(inputs) {
+        return this.definition.estimateCost(inputs);
+    }
+}
+exports.Prompt = Prompt;

package/dist/schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Schema validation for prompt inputs and outputs.
+ */
+export interface FieldSchema {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: any;
+    minValue?: number;
+    maxValue?: number;
+    minLength?: number;
+    maxLength?: number;
+    values?: string[];
+    items?: string;
+}
+export declare class InputSchema {
+    readonly fields: Map<string, FieldSchema>;
+    constructor(fields: Map<string, FieldSchema>);
+    static fromDict(schemaDict: Record<string, any>): InputSchema;
+    validate(inputs: Record<string, any>): string[];
+    applyDefaults(inputs: Record<string, any>): Record<string, any>;
+}
+export declare class OutputSchema {
+    readonly fields: Map<string, FieldSchema>;
+    constructor(fields: Map<string, FieldSchema>);
+    static fromDict(schemaDict: Record<string, any>): OutputSchema;
+    validate(output: Record<string, any>): string[];
+}

package/dist/schema.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Schema validation for prompt inputs and outputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputSchema = exports.InputSchema = void 0;
+class InputSchema {
+    constructor(fields) {
+        this.fields = fields;
+    }
+    static fromDict(schemaDict) {
+        const fields = new Map();
+        for (const [name, config] of Object.entries(schemaDict)) {
+            if (typeof config === "object" && config !== null) {
+                fields.set(name, {
+                    name,
+                    type: config.type || "string",
+                    required: config.required !== false,
+                    default: config.default,
+                    minValue: config.min,
+                    maxValue: config.max,
+                    minLength: config.min_length,
+                    maxLength: config.max_length,
+                    values: config.values,
+                    items: config.items,
+                });
+            }
+            else {
+                fields.set(name, { name, type: String(config), required: true });
+            }
+        }
+        return new InputSchema(fields);
+    }
+    validate(inputs) {
+        const errors = [];
+        for (const [name, field] of this.fields) {
+            const value = inputs[name] ?? field.default;
+            if (value === undefined || value === null) {
+                if (field.required && field.default === undefined) {
+                    errors.push(`Field '${name}' is required`);
+                }
+                continue;
+            }
+            if (field.type === "enum" && field.values && !field.values.includes(value)) {
+                errors.push(`Field '${name}' must be one of [${field.values.join(", ")}]`);
+            }
+            if (typeof value === "number") {
+                if (field.minValue !== undefined && value < field.minValue) {
+                    errors.push(`Field '${name}' must be >= ${field.minValue}`);
+                }
+                if (field.maxValue !== undefined && value > field.maxValue) {
+                    errors.push(`Field '${name}' must be <= ${field.maxValue}`);
+                }
+            }
+            if (typeof value === "string") {
+                if (field.maxLength !== undefined && value.length > field.maxLength) {
+                    errors.push(`Field '${name}' must be at most ${field.maxLength} chars`);
+                }
+            }
+        }
+        return errors;
+    }
+    applyDefaults(inputs) {
+        const result = { ...inputs };
+        for (const [name, field] of this.fields) {
+            if (!(name in result) && field.default !== undefined) {
+                result[name] = field.default;
+            }
+        }
+        return result;
+    }
+}
+exports.InputSchema = InputSchema;
+class OutputSchema {
+    constructor(fields) {
+        this.fields = fields;
+    }
+    static fromDict(schemaDict) {
+        const fields = new Map();
+        for (const [name, config] of Object.entries(schemaDict)) {
+            if (typeof config === "object" && config !== null) {
+                fields.set(name, { name, type: config.type || "string", required: false });
+            }
+            else {
+                fields.set(name, { name, type: String(config), required: false });
+            }
+        }
+        return new OutputSchema(fields);
+    }
+    validate(output) {
+        const errors = [];
+        for (const [name, field] of this.fields) {
+            if (field.required && !(name in output)) {
+                errors.push(`Missing required output field: '${name}'`);
+            }
+        }
+        return errors;
+    }
+}
+exports.OutputSchema = OutputSchema;

package/dist/testing.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Testing framework for PromptOps prompts.
+ */
+export interface TestCase {
+    name: string;
+    inputs: Record<string, any>;
+    assertions: AssertionConfig[];
+}
+export interface AssertionConfig {
+    type: string;
+    field?: string;
+    value?: any;
+    values?: string[];
+    keywords?: string[];
+    min?: number;
+    max?: number;
+    threshold?: number;
+}
+export interface AssertionResult {
+    passed: boolean;
+    assertionType: string;
+    message: string;
+}
+export interface TestResult {
+    testName: string;
+    promptName: string;
+    passed: boolean;
+    assertionResults: AssertionResult[];
+    error?: string;
+}
+export interface TestSuite {
+    promptName: string;
+    testCases: TestCase[];
+    passThreshold: number;
+}
+export declare class TestRunner {
+    runAssertion(config: AssertionConfig, output: any): AssertionResult;
+    private checkSchemaValid;
+    private checkMaxLength;
+    private checkContainsKeywords;
+    private checkDoesNotContain;
+}

package/dist/testing.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Testing framework for PromptOps prompts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestRunner = void 0;
+class TestRunner {
+    runAssertion(config, output) {
+        switch (config.type) {
+            case "schema_valid":
+                return this.checkSchemaValid(output);
+            case "max_length":
+                return this.checkMaxLength(config, output);
+            case "contains_keywords":
+                return this.checkContainsKeywords(config, output);
+            case "does_not_contain":
+                return this.checkDoesNotContain(config, output);
+            case "cost_under":
+                return { passed: true, assertionType: "cost_under", message: "Cost check passed" };
+            default:
+                return { passed: false, assertionType: config.type, message: `Unknown assertion: ${config.type}` };
+        }
+    }
+    checkSchemaValid(output) {
+        if (typeof output === "object" && output !== null) {
+            return { passed: true, assertionType: "schema_valid", message: "Valid object" };
+        }
+        if (typeof output === "string") {
+            try {
+                JSON.parse(output);
+                return { passed: true, assertionType: "schema_valid", message: "Valid JSON" };
+            }
+            catch {
+                return { passed: false, assertionType: "schema_valid", message: "Not valid JSON" };
+            }
+        }
+        return { passed: false, assertionType: "schema_valid", message: "Invalid output type" };
+    }
+    checkMaxLength(config, output) {
+        const text = config.field && typeof output === "object" ? output[config.field] : output;
+        const wordCount = String(text || "").split(/\s+/).length;
+        const maxWords = config.value || 100;
+        const passed = wordCount <= maxWords;
+        return {
+            passed,
+            assertionType: "max_length",
+            message: `Word count ${wordCount} ${passed ? "<=" : ">"} ${maxWords}`,
+        };
+    }
+    checkContainsKeywords(config, output) {
+        const text = config.field && typeof output === "object" ? output[config.field] : output;
+        const textLower = String(text || "").toLowerCase();
+        const keywords = config.keywords || [];
+        const missing = keywords.filter((kw) => !textLower.includes(kw.toLowerCase()));
+        return {
+            passed: missing.length === 0,
+            assertionType: "contains_keywords",
+            message: missing.length === 0 ? "All keywords found" : `Missing: ${missing.join(", ")}`,
+        };
+    }
+    checkDoesNotContain(config, output) {
+        const text = config.field && typeof output === "object" ? output[config.field] : output;
+        const textLower = String(text || "").toLowerCase();
+        const forbidden = config.values || [];
+        const found = forbidden.filter((v) => textLower.includes(v.toLowerCase()));
+        return {
+            passed: found.length === 0,
+            assertionType: "does_not_contain",
+            message: found.length === 0 ? "No forbidden content" : `Found: ${found.join(", ")}`,
+        };
+    }
+}
+exports.TestRunner = TestRunner;

package/dist/version.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Semantic versioning engine for prompts.
+ */
+export declare class PromptVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly prerelease?: string;
+    private static PATTERN;
+    constructor(major: number, minor: number, patch: number, prerelease?: string);
+    static parse(versionStr: string): PromptVersion;
+    bumpPatch(): PromptVersion;
+    bumpMinor(): PromptVersion;
+    bumpMajor(): PromptVersion;
+    isPrerelease(): boolean;
+    isCompatibleWith(other: PromptVersion): boolean;
+    compareTo(other: PromptVersion): number;
+    toString(): string;
+}
+export declare class VersionRange {
+    readonly spec: string;
+    constructor(spec: string);
+    static latest(): VersionRange;
+    static exact(version: string): VersionRange;
+    static compatible(version: string): VersionRange;
+    matches(version: PromptVersion): boolean;
+}

package/dist/version.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Semantic versioning engine for prompts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionRange = exports.PromptVersion = void 0;
+class PromptVersion {
+    constructor(major, minor, patch, prerelease) {
+        this.major = major;
+        this.minor = minor;
+        this.patch = patch;
+        this.prerelease = prerelease;
+    }
+    static parse(versionStr) {
+        const match = versionStr.trim().match(PromptVersion.PATTERN);
+        if (!match || !match.groups) {
+            throw new Error(`Invalid version string: '${versionStr}'`);
+        }
+        return new PromptVersion(parseInt(match.groups.major), parseInt(match.groups.minor), parseInt(match.groups.patch), match.groups.prerelease || undefined);
+    }
+    bumpPatch() {
+        return new PromptVersion(this.major, this.minor, this.patch + 1);
+    }
+    bumpMinor() {
+        return new PromptVersion(this.major, this.minor + 1, 0);
+    }
+    bumpMajor() {
+        return new PromptVersion(this.major + 1, 0, 0);
+    }
+    isPrerelease() {
+        return this.prerelease !== undefined;
+    }
+    isCompatibleWith(other) {
+        return this.major === other.major;
+    }
+    compareTo(other) {
+        if (this.major !== other.major)
+            return this.major - other.major;
+        if (this.minor !== other.minor)
+            return this.minor - other.minor;
+        return this.patch - other.patch;
+    }
+    toString() {
+        const base = `${this.major}.${this.minor}.${this.patch}`;
+        return this.prerelease ? `${base}-${this.prerelease}` : base;
+    }
+}
+exports.PromptVersion = PromptVersion;
+PromptVersion.PATTERN = /^(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)(?:-(?<prerelease>[0-9A-Za-z\-.]+))?$/;
+class VersionRange {
+    constructor(spec) {
+        this.spec = spec;
+    }
+    static latest() {
+        return new VersionRange("latest");
+    }
+    static exact(version) {
+        PromptVersion.parse(version);
+        return new VersionRange(version);
+    }
+    static compatible(version) {
+        return new VersionRange(`~${version}`);
+    }
+    matches(version) {
+        if (this.spec === "latest") {
+            return !version.isPrerelease();
+        }
+        if (this.spec.startsWith("~")) {
+            const base = this.spec.slice(1);
+            const parts = base.split(".");
+            const targetMajor = parseInt(parts[0]);
+            const targetMinor = parts.length > 1 ? parseInt(parts[1]) : 0;
+            return (version.major === targetMajor &&
+                version.minor >= targetMinor &&
+                !version.isPrerelease());
+        }
+        try {
+            const exact = PromptVersion.parse(this.spec);
+            return (version.major === exact.major &&
+                version.minor === exact.minor &&
+                version.patch === exact.patch);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.VersionRange = VersionRange;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "substrai-promptops",
+  "version": "0.1.0",
+  "description": "Infrastructure-as-Code framework for prompt engineering lifecycle management",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "prompt-engineering",
+    "llm",
+    "infrastructure-as-code",
+    "versioning",
+    "testing",
+    "deployment",
+    "serverless",
+    "aws-lambda",
+    "mlops",
+    "genai",
+    "prompts",
+    "semantic-versioning",
+    "regression-testing"
+  ],
+  "author": "Gaurav Singh <gaurav@substrai.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/substrai/promptops"
+  },
+  "homepage": "https://github.com/substrai/promptops",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}