@stackfactor/agent-utils 1.0.0

package/dist/cjs/logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Writes a structured log entry via Winston using the GCP-compatible format. The
+ * current OpenTelemetry span context is read to enrich the entry with `trace` and
+ * `spanId` fields when an active span is present. The user's email (if available on the
+ * request) is prepended to the message string along with an icon derived from the log
+ * level. Any additional fields supplied in `options` are merged into the log record.
+ * @param request - The HTTP request object; used to extract `request.user.email` for
+ *   the log message prefix; may be `null`
+ * @param level - The Winston log level string (e.g. `"info"`, `"error"`, `"warn"`);
+ *   must be one of the keys in the `levels` constant
+ * @param message - The primary log message string
+ * @param options - Additional key-value pairs merged into the log record for structured
+ *   logging (e.g. `{ service: "auth", requestId: "..." }`); defaults to `{}`
+ */
+type LogLevel = "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+declare const _default: {
+    log: (request: any, level: LogLevel, message: string, options?: any) => void;
+    levels: {
+        readonly error: "error";
+        readonly warn: "warn";
+        readonly info: "info";
+        readonly http: "http";
+        readonly verbose: "verbose";
+        readonly debug: "debug";
+        readonly silly: "silly";
+    };
+};
+export default _default;
+//# sourceMappingURL=logger.d.ts.map

package/dist/cjs/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;GAaG;AACH,KAAK,QAAQ,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,OAAO,GACP,OAAO,CAAC;;mBAGD,GAAG,SACL,QAAQ,WACN,MAAM,YACN,GAAG,KACX,IAAI;;;;;;;;;;;AA0BP,wBAGE"}

package/dist/cjs/logger.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const winston_1 = __importDefault(require("winston"));
+const api_1 = require("@opentelemetry/api");
+const { combine, timestamp, printf } = winston_1.default.format;
+const levels = {
+    error: "error",
+    warn: "warn",
+    info: "info",
+    http: "http",
+    verbose: "verbose",
+    debug: "debug",
+    silly: "silly",
+};
+const levelIcons = {
+    error: "❌",
+    warn: "⚠️",
+    info: "📝",
+    http: "🌐",
+    verbose: "📝",
+    debug: "🔍",
+    silly: "🎭",
+};
+/**
+ * Custom Winston printf formatter that serialises log records to a single-line JSON
+ * string compatible with Google Cloud Platform (GCP) structured logging. The `level`
+ * field is mapped to GCP's `severity` key (uppercased) and all standard fields plus any
+ * additional metadata are included in the output.
+ */
+const gcpFormat = printf((info) => {
+    const { level, message, timestamp: ts, service, environment, requestId, userId, trace, spanId, sourceLocation, ...rest } = info;
+    return JSON.stringify({
+        severity: level ? level.toUpperCase() : undefined,
+        message,
+        timestamp: ts,
+        service,
+        environment,
+        requestId,
+        userId,
+        trace,
+        spanId,
+        sourceLocation,
+        ...rest,
+    });
+});
+const logger = winston_1.default.createLogger({
+    format: combine(timestamp(), gcpFormat),
+    transports: [new winston_1.default.transports.Console()],
+});
+const log = (request, level, message, options = {}) => {
+    // Get current OpenTelemetry span context
+    const span = api_1.trace.getSpan(api_1.context.active());
+    let traceId, spanId;
+    if (span) {
+        const spanContext = span.spanContext();
+        traceId = spanContext.traceId;
+        spanId = spanContext.spanId;
+    }
+    // eslint-disable-next-line security/detect-object-injection
+    const icon = levelIcons[level] || "ℹ️";
+    logger.log({
+        level: level,
+        message: `${icon} ${request && request.user ? request.user.email + " - " : ""}${message}`,
+        trace: traceId
+            ? `projects/${process.env.GOOGLE_CLOUD_PROJECT}/traces/${traceId}`
+            : undefined,
+        spanId: spanId,
+        ...options,
+    });
+};
+exports.default = {
+    log,
+    levels,
+};

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/const.d.ts

@@ -0,0 +1,15 @@
+declare const _default: {
+    HTTP_CODES: {
+        BAD_REQUEST: number;
+        UNPROCESSABLE_ENTITY: number;
+        INTERNAL_SERVER_ERROR: number;
+        BAD_GATEWAY: number;
+    };
+    ERROR: {
+        UNABLE_TO_GENERATE_CONTENT: string;
+        UNEXPECTED_ERROR: string;
+        UNSUPPORTED_MODEL: string;
+    };
+};
+export default _default;
+//# sourceMappingURL=const.d.ts.map

package/dist/esm/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/const.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,wBAaE"}

package/dist/esm/const.js

@@ -0,0 +1,13 @@
+export default {
+    HTTP_CODES: {
+        BAD_REQUEST: 400,
+        UNPROCESSABLE_ENTITY: 422,
+        INTERNAL_SERVER_ERROR: 500,
+        BAD_GATEWAY: 502,
+    },
+    ERROR: {
+        UNABLE_TO_GENERATE_CONTENT: "Unable to generate content",
+        UNEXPECTED_ERROR: "An unexpected error occured. If the issue persists please contact the StackFactor support team at support@stackfactor.ai",
+        UNSUPPORTED_MODEL: "The specified model is not supported",
+    },
+};

package/dist/esm/errorHandling.d.ts

@@ -0,0 +1,20 @@
+declare const _default: {
+    /**
+     * Creates a structured error object with a code, message, and optional details.
+     * This is used as a convenience factory to produce consistently shaped error payloads
+     * that can be passed to other error-handling methods in this module.
+     *
+     * @param errorCode - The numeric HTTP status code or application error code representing the error.
+     * @param errorMessage - A human-readable description of the error.
+     * @param details - Optional supplementary information about the error, such as validation details.
+     * @returns A plain object with `code`, `message`, and `details` properties.
+     */
+    create: (errorCode: number, errorMessage: string, details?: any) => {
+        code: number;
+        message: string;
+        details: any;
+        stack: string;
+    };
+};
+export default _default;
+//# sourceMappingURL=errorHandling.d.ts.map

package/dist/esm/errorHandling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/errorHandling.ts"],"names":[],"mappings":";IACE;;;;;;;;;OASG;wBACiB,MAAM,gBAAgB,MAAM,YAAW,GAAG;;;;;;;AAXhE,wBAoBE"}

package/dist/esm/errorHandling.js

@@ -0,0 +1,21 @@
+export default {
+    /**
+     * Creates a structured error object with a code, message, and optional details.
+     * This is used as a convenience factory to produce consistently shaped error payloads
+     * that can be passed to other error-handling methods in this module.
+     *
+     * @param errorCode - The numeric HTTP status code or application error code representing the error.
+     * @param errorMessage - A human-readable description of the error.
+     * @param details - Optional supplementary information about the error, such as validation details.
+     * @returns A plain object with `code`, `message`, and `details` properties.
+     */
+    create: (errorCode, errorMessage, details = null) => {
+        const error = new Error(errorMessage);
+        return {
+            code: errorCode,
+            message: errorMessage,
+            details: details,
+            stack: error.stack,
+        };
+    },
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+import constants from "./const.js";
+import errorHandling from "./errorHandling.js";
+import langChain from "./langChain.js";
+import logger from "./logger.js";
+export { constants };
+export { errorHandling };
+export { langChain };
+export { logger };
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,MAAM,oBAAoB,CAAC;AAC/C,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,8 @@
+import constants from "./const.js";
+import errorHandling from "./errorHandling.js";
+import langChain from "./langChain.js";
+import logger from "./logger.js";
+export { constants };
+export { errorHandling };
+export { langChain };
+export { logger };

package/dist/esm/langChain.d.ts

@@ -0,0 +1,10 @@
+declare const _default: {
+    createAIAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any, onReportProgress?: Function | null, minPercent?: number, maxPercent?: number) => any;
+    runAIAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null) => Promise<any>;
+    runChatPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any) => any;
+    runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[]) => Promise<any>;
+    runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any) => Promise<any>;
+    throwErrorIfNotSuccessful: (response: any) => string;
+};
+export default _default;
+//# sourceMappingURL=langChain.d.ts.map

package/dist/esm/langChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":";0BAoaQ,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,qBACO,QAAQ,GAAG,IAAI,eACrB,MAAM,eACN,MAAM,KACjB,GAAG;wBAyCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,KAC1B,OAAO,CAAC,GAAG,CAAC;wCAioBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,KACpB,GAAG;oCApfO,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,KACX,OAAO,CAAC,GAAG,CAAC;sDAyyBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,KACX,OAAO,CAAC,GAAG,CAAC;0CAz2B8B,GAAG,KAAG,MAAM;;AAo6BzD,wBAOE"}