@stackfactor/agent-utils 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,293 @@
+# @stackfactor/agent-utils
+
+Shared utilities for StackFactor AI agent services — LangChain helpers, structured logging, error handling, and constants.
+
+## Installation
+
+```bash
+npm install @stackfactor/agent-utils
+```
+
+## Modules
+
+The package exports four modules:
+
+```typescript
+import { langChain, logger, errorHandling, constants } from "@stackfactor/agent-utils";
+```
+
+---
+
+## `langChain`
+
+Unified interface for running LLM prompts, managing LangChain agents, and generating images across OpenAI, Anthropic, and Google providers.
+
+### `langChain.runPromptWithModel(modelName, config, prompt, onProgressReport?, minPercent?, maxPercent?, expectsJsonResponse?, schema?, agentName?, tools?)`
+
+Sends a prompt to an LLM and returns the response. Supports three execution modes:
+
+- **Agentic** (`config.agentic === true`) — creates and runs a LangChain agent with tools.
+- **Streaming** (`onProgressReport` provided) — streams the response with progress callbacks. Uses native `response_format` for OpenAI+schema, or NDJSON for other providers.
+- **Non-streaming** — direct invocation with JSON extraction.
+
+When `expectsJsonResponse` is `true` (the default), JSON escape instructions are injected and the response is parsed. If a Zod `schema` is provided, the parsed result is validated.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `modelName` | `string` | — | Model identifier: `"gpt-4o"`, `"claude-3-5-sonnet"`, `"gemini-1.5-pro"`, etc. |
+| `config` | `object` | — | API keys (`openAIAPIKey`, `anthropicAPIKey`, `googleAPIKey`), `temperature`, `agentic`, `recursionLimit` |
+| `prompt` | `string \| object[]` | — | Plain string or array of `{ role, content }` message objects |
+| `onProgressReport` | `function \| null` | `null` | Async callback receiving `{ message, progress }` updates |
+| `minPercent` | `number` | `0` | Lower bound for progress percentage |
+| `maxPercent` | `number` | `100` | Upper bound for progress percentage |
+| `expectsJsonResponse` | `boolean` | `true` | Parse response as JSON |
+| `schema` | `ZodSchema \| null` | `null` | Zod schema for response validation |
+| `agentName` | `string` | `"StackFactor"` | Display name for the agent (agentic mode) |
+| `tools` | `any[]` | `[]` | LangChain tools available to the agent (agentic mode) |
+
+**Returns:** JSON string (when `expectsJsonResponse` is `true`) or raw content string.
+
+```typescript
+const result = await langChain.runPromptWithModel(
+  "gpt-4o",
+  { openAIAPIKey: "sk-..." },
+  "Generate a summary of this document.",
+);
+```
+
+---
+
+### `langChain.runChatPromptWithModel(modelName, config, prompt, onProgressReport?)`
+
+Sends a conversational chat prompt to an LLM and returns a plain HTML response. Built for the StackFactor Mentor chat feature — system messages are wrapped with topic-constraint instructions that decline off-topic questions.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `modelName` | `string` | — | Model identifier |
+| `config` | `object` | — | API keys and optional `temperature` |
+| `prompt` | `string \| object[]` | — | Plain string or array of `{ role, content }` messages |
+| `onProgressReport` | `function \| null` | `null` | Streaming progress callback |
+
+**Returns:** Raw HTML string.
+
+```typescript
+const html = await langChain.runChatPromptWithModel(
+  "claude-3-5-sonnet",
+  { anthropicAPIKey: "sk-ant-..." },
+  [
+    { role: "system", content: "Topic: JavaScript closures" },
+    { role: "user", content: "Explain closures with an example" },
+  ],
+);
+```
+
+---
+
+### `langChain.createAIAgent(name, modelName, systemPrompt, tools?, responseFormat?, config, onReportProgress?, minPercent?, maxPercent?)`
+
+Constructs a LangChain agent with a model, system prompt, and tools. When `onReportProgress` is provided, a `report_progress` tool is automatically added.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | Display name for the agent |
+| `modelName` | `string` | — | LLM identifier |
+| `systemPrompt` | `string` | — | System prompt describing agent behaviour |
+| `tools` | `any[]` | `[]` | LangChain tool instances |
+| `responseFormat` | `any` | — | Structured response format descriptor |
+| `config` | `object` | — | API keys, temperature, etc. |
+| `onReportProgress` | `Function \| null` | `null` | Progress callback |
+| `minPercent` | `number` | `0` | Minimum reportable progress |
+| `maxPercent` | `number` | `100` | Maximum reportable progress |
+
+**Returns:** A configured LangChain agent instance.
+
+---
+
+### `langChain.runAIAgent(agent, prompt, config, onProgress?)`
+
+Executes a LangChain agent with a user prompt. Registers callbacks for `tool_start`, `tool_end`, `agent_action`, and error events when `onProgress` is provided. Logs execution time on completion.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `agent` | `any` | — | Agent created by `createAIAgent` |
+| `prompt` | `string` | — | User message to send |
+| `config` | `object` | — | `recursionLimit` (default: `25`) |
+| `onProgress` | `Function \| null` | `null` | Progress event callback |
+
+**Returns:** Raw response from the agent's `invoke` method.
+
+```typescript
+const agent = langChain.createAIAgent(
+  "Summarizer",
+  "gpt-4o",
+  "You summarize documents concisely.",
+  [],
+  null,
+  { openAIAPIKey: "sk-..." },
+);
+
+const response = await langChain.runAIAgent(agent, "Summarize this text...", {});
+```
+
+---
+
+### `langChain.runPromptWithModelForImageGeneration(modelName, config, prompt, options?)`
+
+Generates an image using OpenAI or Google AI models.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `modelName` | `string` | — | Image model: `"dall-e-3"`, `"gpt-image-1.5"`, `"imagen-4.0-generate-001"`, `"gemini-3.0-pro-image"`, etc. |
+| `config` | `object` | — | `openAIAPIKey` or `googleAPIKey` |
+| `prompt` | `string` | — | Text prompt describing the image |
+| `options` | `object` | `{}` | Provider-specific options (see below) |
+
+**OpenAI options:** `size` (`"1024x1024"`, `"1792x1024"`, etc.), `style` (`"vivid"` or `"natural"`), `responseFormat` (`"url"` or `"b64_json"`), `n` (number of images).
+
+**Google options:** `aspectRatio` (`"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, `"16:9"`), `numberOfImages`, `negativePrompt`.
+
+**Returns:** `{ url?, b64_json?, revisedPrompt? }` for single images, or `{ images: [...] }` for multiple.
+
+```typescript
+const image = await langChain.runPromptWithModelForImageGeneration(
+  "dall-e-3",
+  { openAIAPIKey: "sk-..." },
+  "A futuristic city skyline at sunset",
+  { size: "1792x1024" },
+);
+```
+
+---
+
+### `langChain.throwErrorIfNotSuccessful(response)`
+
+Guards that a response is a non-empty string. Throws an `INTERNAL_SERVER_ERROR` if not.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `response` | `any` | Value to validate |
+
+**Returns:** The response string if valid.
+
+---
+
+## `logger`
+
+GCP-compatible structured logging via Winston with OpenTelemetry trace enrichment.
+
+### `logger.log(request, level, message, options?)`
+
+Writes a structured log entry. Automatically enriches with OpenTelemetry `traceId` and `spanId` when an active span exists. Prepends the user's email from the request object when available.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `request` | `any` | — | HTTP request object (reads `request.user.email`), or `null` |
+| `level` | `LogLevel` | — | `"error"`, `"warn"`, `"info"`, `"http"`, `"verbose"`, `"debug"`, `"silly"` |
+| `message` | `string` | — | Log message |
+| `options` | `object` | `{}` | Additional structured fields (`service`, `requestId`, etc.) |
+
+```typescript
+logger.log(req, logger.levels.info, "User signed in", { service: "auth" });
+logger.log(null, logger.levels.error, "Connection failed");
+```
+
+### `logger.levels`
+
+Enum-like object mapping level names to their string values:
+
+```typescript
+logger.levels.error   // "error"
+logger.levels.warn    // "warn"
+logger.levels.info    // "info"
+logger.levels.http    // "http"
+logger.levels.verbose // "verbose"
+logger.levels.debug   // "debug"
+logger.levels.silly   // "silly"
+```
+
+---
+
+## `errorHandling`
+
+Factory for consistently shaped error payloads.
+
+### `errorHandling.create(errorCode, errorMessage, details?)`
+
+Creates a structured error object with a stack trace.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `errorCode` | `number` | — | HTTP status code or application error code |
+| `errorMessage` | `string` | — | Human-readable error description |
+| `details` | `any` | `null` | Optional supplementary information |
+
+**Returns:** `{ code, message, details, stack }`
+
+```typescript
+throw errorHandling.create(404, "User not found");
+throw errorHandling.create(400, "Validation failed", { field: "email" });
+```
+
+---
+
+## `constants`
+
+Shared constants used across the package.
+
+### `constants.HTTP_CODES`
+
+| Constant | Value |
+|---|---|
+| `BAD_REQUEST` | `400` |
+| `UNPROCESSABLE_ENTITY` | `422` |
+| `INTERNAL_SERVER_ERROR` | `500` |
+| `BAD_GATEWAY` | `502` |
+
+### `constants.ERROR`
+
+| Constant | Value |
+|---|---|
+| `UNABLE_TO_GENERATE_CONTENT` | `"Unable to generate content"` |
+| `UNEXPECTED_ERROR` | `"An unexpected error occured..."` |
+| `UNSUPPORTED_MODEL` | `"The specified model is not supported"` |
+
+---
+
+## Supported Models
+
+### Text / Chat
+
+| Provider | Model Prefix | Example |
+|---|---|---|
+| OpenAI | `gpt-` | `gpt-4o`, `gpt-4o-mini` |
+| Anthropic | `claude-` | `claude-3-5-sonnet`, `claude-3-opus` |
+| Google | `gemini-` | `gemini-1.5-pro`, `gemini-2.0-flash` |
+
+### Image Generation
+
+| Provider | Model Prefix | Example |
+|---|---|---|
+| OpenAI | `dall-e-`, `gpt-image-` | `dall-e-3`, `gpt-image-1.5` |
+| Google | `imagen-`, `gemini-` | `imagen-4.0-generate-001`, `gemini-3.0-pro-image` |
+
+---
+
+## Config Object
+
+The `config` object accepted by LangChain methods supports the following keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `openAIAPIKey` | `string` | OpenAI API key |
+| `anthropicAPIKey` | `string` | Anthropic API key |
+| `googleAPIKey` | `string` | Google AI API key |
+| `temperature` | `number` | Sampling temperature |
+| `maxTokens` | `number` | Maximum output tokens (default: `200000`) |
+| `agentic` | `boolean` | Enable agentic mode in `runPromptWithModel` |
+| `recursionLimit` | `number` | Max agent steps (default: `25`) |
+
+---
+
+## License
+
+Not licensed — proprietary software of StackFactor Inc.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "restricted"
   },
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",