@jaypie/mcp 0.2.2 → 0.2.4

package/prompts/Jaypie_Express_Package.md

@@ -406,3 +406,94 @@ expressHandler automatically sets these headers:
 ## Datadog Integration
 
 When Datadog environment variables are configured, expressHandler automatically submits metrics for each request including status code and path.
+
+## Streaming Responses
+
+Use `expressStreamHandler` for Server-Sent Events (SSE) streaming responses. Ideal for real-time updates, LLM streaming, and long-running operations.
+
+### Basic Streaming Usage
+
+```typescript
+import { expressStreamHandler } from "jaypie";
+import type { Request, Response } from "express";
+
+const streamRoute = expressStreamHandler(async (req: Request, res: Response) => {
+  // Write SSE events directly to response
+  res.write("event: message\ndata: {\"text\": \"Hello\"}\n\n");
+  res.write("event: message\ndata: {\"text\": \"World\"}\n\n");
+  // Handler automatically ends the stream
+});
+
+app.get("/stream", streamRoute);
+```
+
+### Streaming with LLM
+
+```typescript
+import { expressStreamHandler, Llm, createExpressStream } from "jaypie";
+
+const llmStreamRoute = expressStreamHandler(async (req: Request, res: Response) => {
+  const llm = new Llm("anthropic");
+  const stream = llm.stream(req.body.prompt);
+
+  // createExpressStream pipes LLM chunks as SSE events
+  await createExpressStream(stream, res);
+});
+
+app.post("/chat", llmStreamRoute);
+```
+
+### Stream Handler Options
+
+`expressStreamHandler` supports the same lifecycle options as `expressHandler`:
+
+```typescript
+import { expressStreamHandler } from "jaypie";
+import type { ExpressStreamHandlerOptions } from "jaypie";
+
+const options: ExpressStreamHandlerOptions = {
+  name: "myStreamHandler",      // Handler name for logging
+  contentType: "text/event-stream", // Default SSE content type
+  chaos: "low",                 // Chaos testing level
+  secrets: ["API_KEY"],         // Secrets to load
+  setup: [],                    // Setup function(s)
+  teardown: [],                 // Teardown function(s)
+  validate: [],                 // Validation function(s)
+  locals: {},                   // Values to set on req.locals
+  unavailable: false,           // Return 503 if true
+};
+
+const handler = expressStreamHandler(async (req, res) => {
+  // Streaming logic
+}, options);
+```
+
+### SSE Headers
+
+`expressStreamHandler` automatically sets SSE headers:
+- `Content-Type: text/event-stream`
+- `Cache-Control: no-cache`
+- `Connection: keep-alive`
+- `X-Accel-Buffering: no` (disables nginx buffering)
+
+### Error Handling in Streams
+
+Errors are formatted as SSE error events:
+
+```typescript
+// Jaypie errors and unhandled errors are written as:
+// event: error
+// data: {"errors":[{"status":500,"title":"Internal Error"}]}
+```
+
+### TypeScript Types
+
+```typescript
+import type {
+  ExpressStreamHandlerOptions,
+  ExpressStreamHandlerLocals,
+  JaypieStreamHandlerSetup,
+  JaypieStreamHandlerTeardown,
+  JaypieStreamHandlerValidate,
+} from "jaypie";
+```

package/prompts/Jaypie_Init_Lambda_Package.md

@@ -361,4 +361,137 @@ Deploy using AWS CDK or other deployment tool. The Lambda handler will be refere
 - Use double quotes, trailing commas, semicolons
 - Alphabetize imports and properties
 - Define constants for hard-coded values at file top
-- Never throw vanilla Error; use errors from `@jaypie/errors`
+- Never throw vanilla Error; use errors from `@jaypie/errors`
+
+## Streaming Lambda Functions
+
+Use `lambdaStreamHandler` for AWS Lambda Response Streaming. This enables real-time streaming responses for LLM interactions, large file processing, and SSE endpoints.
+
+### Lambda Streaming Setup
+
+Create a streaming Lambda handler with `awslambda.streamifyResponse`:
+
+```typescript
+// src/streamWorker.ts
+import { log } from "@jaypie/core";
+import { lambdaStreamHandler, createLambdaStream, Llm } from "jaypie";
+import type { StreamHandlerContext } from "@jaypie/lambda";
+
+export interface StreamWorkerEvent {
+  prompt?: string;
+}
+
+const streamWorker = lambdaStreamHandler(
+  async (event: StreamWorkerEvent, context: StreamHandlerContext) => {
+    log.trace("streamWorker: start");
+
+    const llm = new Llm("anthropic");
+    const stream = llm.stream(event.prompt || "Hello");
+
+    // createLambdaStream pipes LLM chunks as SSE events
+    await createLambdaStream(stream, context.responseStream);
+
+    log.trace("streamWorker: complete");
+  },
+  {
+    name: "streamWorker",
+    contentType: "text/event-stream",
+  }
+);
+
+// Wrap with AWS streamifyResponse
+declare const awslambda: { streamifyResponse: <T>(handler: T) => T };
+export const handler = awslambda.streamifyResponse(streamWorker);
+```
+
+### Manual Stream Writing
+
+Write directly to the response stream for custom SSE events:
+
+```typescript
+import { lambdaStreamHandler } from "jaypie";
+import type { StreamHandlerContext } from "@jaypie/lambda";
+
+const manualStreamHandler = lambdaStreamHandler(
+  async (event: unknown, context: StreamHandlerContext) => {
+    const { responseStream } = context;
+
+    // Write SSE events directly
+    responseStream.write("event: start\ndata: {\"status\": \"processing\"}\n\n");
+
+    // Process data in chunks
+    for (const item of items) {
+      const result = await process(item);
+      responseStream.write(`event: data\ndata: ${JSON.stringify(result)}\n\n`);
+    }
+
+    responseStream.write("event: done\ndata: {\"status\": \"complete\"}\n\n");
+    // Handler automatically calls responseStream.end()
+  },
+  {
+    name: "manualStream",
+  }
+);
+```
+
+### Stream Handler Options
+
+```typescript
+import type { LambdaStreamHandlerOptions } from "@jaypie/lambda";
+
+const options: LambdaStreamHandlerOptions = {
+  name: "myStreamHandler",          // Handler name for logging
+  contentType: "text/event-stream", // Response content type (default)
+  chaos: "low",                     // Chaos testing level
+  secrets: ["API_KEY"],             // AWS secrets to load into process.env
+  setup: [],                        // Setup function(s)
+  teardown: [],                     // Teardown function(s)
+  validate: [],                     // Validation function(s)
+  throw: false,                     // Re-throw errors instead of SSE error
+  unavailable: false,               // Return 503 if true
+};
+```
+
+### Stream Handler Types
+
+```typescript
+import type {
+  LambdaStreamHandlerOptions,
+  StreamHandlerContext,
+  ResponseStream,
+  AwsStreamingHandler,
+} from "@jaypie/lambda";
+```
+
+### CDK Configuration for Streaming
+
+Enable Lambda Response Streaming via Function URL in CDK:
+
+```typescript
+import { JaypieLambda } from "@jaypie/constructs";
+import { FunctionUrlAuthType, InvokeMode } from "aws-cdk-lib/aws-lambda";
+
+const streamingLambda = new JaypieLambda(this, "StreamingFunction", {
+  code: "dist",
+  handler: "streamWorker.handler",
+  timeout: Duration.minutes(5),
+});
+
+// Add Function URL with streaming enabled
+streamingLambda.addFunctionUrl({
+  authType: FunctionUrlAuthType.NONE, // or AWS_IAM for auth
+  invokeMode: InvokeMode.RESPONSE_STREAM,
+});
+```
+
+### Error Handling in Streams
+
+Errors are formatted as SSE error events:
+
+```typescript
+// Jaypie errors written as:
+// event: error
+// data: {"errors":[{"status":500,"title":"Internal Error"}]}
+```
+
+Set `throw: true` to re-throw errors instead of writing to stream.

package/prompts/Jaypie_Llm_Calls.md

@@ -12,7 +12,7 @@ Streamline API calls with multi-model capabilities
 ```
 export interface LlmProvider {
   operate(
-    input: string | LlmHistory | LlmInputMessage,
+    input: string | LlmHistory | LlmInputMessage | LlmOperateInput,
     options?: LlmOperateOptions,
   ): Promise<LlmOperateResponse>;
   send(
@@ -21,11 +21,29 @@ export interface LlmProvider {
   ): Promise<string | JsonObject>;
 }
 
+// Simplified input for files and images
+type LlmOperateInput = LlmOperateInputContent[];
+type LlmOperateInputContent = string | LlmOperateInputFile | LlmOperateInputImage;
+
+interface LlmOperateInputFile {
+  file: string;           // Path or filename
+  bucket?: string;        // S3 bucket (uses CDK_ENV_BUCKET if omitted)
+  pages?: number[];       // Extract specific PDF pages (omit = all)
+  data?: string;          // Base64 data (skips file loading)
+}
+
+interface LlmOperateInputImage {
+  image: string;          // Path or filename
+  bucket?: string;        // S3 bucket (uses CDK_ENV_BUCKET if omitted)
+  data?: string;          // Base64 data (skips file loading)
+}
+
 export interface LlmOperateOptions {
   data?: NaturalMap;
   explain?: boolean;
   format?: JsonObject | NaturalSchema | z.ZodType;
   history?: LlmHistory;
+  hooks?: LlmOperateHooks;
   instructions?: string;
   model?: string;
   placeholders?: {
@@ -35,26 +53,44 @@ export interface LlmOperateOptions {
   };
   providerOptions?: JsonObject;
   system?: string;
-  tools?: LlmTool[];
+  tools?: LlmTool[] | Toolkit;
   turns?: boolean | number;
   user?: string;
 }
 
+export interface LlmOperateHooks {
+  afterEachModelResponse?: (context: HookContext) => unknown | Promise<unknown>;
+  afterEachTool?: (context: ToolHookContext) => unknown | Promise<unknown>;
+  beforeEachModelRequest?: (context: HookContext) => unknown | Promise<unknown>;
+  beforeEachTool?: (context: ToolHookContext) => unknown | Promise<unknown>;
+  onRetryableModelError?: (context: ErrorHookContext) => unknown | Promise<unknown>;
+  onToolError?: (context: ToolErrorContext) => unknown | Promise<unknown>;
+  onUnrecoverableModelError?: (context: ErrorHookContext) => unknown | Promise<unknown>;
+}
+
 export interface LlmOperateResponse {
   content?: string | JsonObject;
   error?: LlmError;
   history: LlmHistory;
+  model?: string;
   output: LlmOutput;
+  provider?: string;
+  reasoning: string[];
   responses: JsonReturn[];
   status: LlmResponseStatus;
   usage: LlmUsage;
 }
 
-interface LlmUsage {
+// LlmUsage is an array of usage items (one per model call in multi-turn)
+type LlmUsage = LlmUsageItem[];
+
+interface LlmUsageItem {
   input: number;
   output: number;
   reasoning: number;
   total: number;
+  model?: string;
+  provider?: string;
 }
 ```
 
@@ -68,6 +104,63 @@ const llm = new Llm();
 const result = await llm.operate("Give me advice on Yahtzee");
 ```
 
+## Providers and Models
+
+Available providers: `anthropic`, `gemini`, `openai`, `openrouter`
+
+```typescript
+import { Llm, PROVIDER } from "jaypie";
+
+// Using provider name (uses provider's default model)
+const llm = new Llm("anthropic");
+
+// Using model name directly (provider auto-detected)
+const llm2 = new Llm("claude-sonnet-4-0");
+const llm3 = new Llm("gpt-4.1");
+const llm4 = new Llm("gemini-2.5-flash");
+
+// Using provider with specific model
+const llm5 = new Llm("openai", { model: "gpt-4.1" });
+
+// Using constants
+const llm6 = new Llm(PROVIDER.OPENAI.NAME, {
+  model: PROVIDER.OPENAI.MODEL.LARGE
+});
+```
+
+### Model Aliases
+
+Each provider has standard aliases: `DEFAULT`, `SMALL`, `LARGE`, `TINY`
+
+| Provider | DEFAULT | LARGE | SMALL | TINY |
+|----------|---------|-------|-------|------|
+| anthropic | claude-opus-4-1 | claude-opus-4-1 | claude-sonnet-4-0 | claude-3-5-haiku-latest |
+| gemini | gemini-3-pro-preview | gemini-3-pro-preview | gemini-3-flash-preview | gemini-2.0-flash-lite |
+| openai | gpt-4.1 | gpt-4.1 | gpt-4.1-mini | gpt-4.1-nano |
+| openrouter | z-ai/glm-4.7 | z-ai/glm-4.7 | z-ai/glm-4.7 | z-ai/glm-4.7 |
+
+### Provider Constants
+
+```typescript
+import { PROVIDER } from "jaypie";
+
+// Anthropic models
+PROVIDER.ANTHROPIC.MODEL.CLAUDE_OPUS_4      // claude-opus-4-1
+PROVIDER.ANTHROPIC.MODEL.CLAUDE_SONNET_4    // claude-sonnet-4-0
+PROVIDER.ANTHROPIC.MODEL.CLAUDE_3_HAIKU     // claude-3-5-haiku-latest
+
+// Gemini models
+PROVIDER.GEMINI.MODEL.GEMINI_3_PRO_PREVIEW  // gemini-3-pro-preview
+PROVIDER.GEMINI.MODEL.GEMINI_2_5_FLASH      // gemini-2.5-flash
+PROVIDER.GEMINI.MODEL.GEMINI_2_0_FLASH      // gemini-2.0-flash
+
+// OpenAI models
+PROVIDER.OPENAI.MODEL.GPT_4_1               // gpt-4.1
+PROVIDER.OPENAI.MODEL.GPT_4_O               // gpt-4o
+PROVIDER.OPENAI.MODEL.O3                    // o3
+PROVIDER.OPENAI.MODEL.O4_MINI               // o4-mini
+```
+
 ## "Operating" an Llm
 
 operate takes an optional second object of options
@@ -106,6 +199,249 @@ error will include any errors.
 output is just the output components of full responses.
 responses are the complete responses.
 
+## Files and Images
+
+Use `LlmOperateInput` array syntax to send files and images with automatic loading and provider translation:
+
+```javascript
+import { Llm } from "jaypie";
+
+const llm = new Llm("openai");
+
+// Image from local filesystem
+const imageResult = await llm.operate([
+  "Extract text from this image",
+  { image: "/path/to/photo.png" }
+]);
+
+// PDF from local filesystem
+const pdfResult = await llm.operate([
+  "Summarize this document",
+  { file: "/path/to/document.pdf" }
+]);
+
+// From S3 bucket (uses CDK_ENV_BUCKET if bucket omitted)
+const s3Result = await llm.operate([
+  "Analyze this file",
+  { file: "documents/report.pdf", bucket: "my-bucket" }
+]);
+
+// Extract specific PDF pages
+const pagesResult = await llm.operate([
+  "Read pages 1-3",
+  { file: "large-doc.pdf", pages: [1, 2, 3] }
+]);
+
+// With pre-loaded base64 data (skips file loading)
+const base64Result = await llm.operate([
+  "Describe this image",
+  { image: "photo.jpg", data: base64String }
+]);
+
+// Multiple files and text
+const multiResult = await llm.operate([
+  "Compare these documents",
+  { file: "doc1.pdf" },
+  { file: "doc2.pdf" },
+  "Focus on the methodology section"
+]);
+```
+
+### File Resolution Order
+
+1. If `data` is present → uses base64 directly
+2. If `bucket` is present → loads from S3
+3. If `CDK_ENV_BUCKET` env var exists → loads from that S3 bucket
+4. Otherwise → loads from local filesystem (relative to process.cwd())
+
+### Supported Image Extensions
+
+Files with these extensions are treated as images: `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`, `bmp`, `ico`, `tiff`, `avif`
+
+## Streaming
+
+Use `Llm.stream()` for real-time streaming responses:
+
+```javascript
+import { Llm } from "jaypie";
+
+const llm = new Llm("anthropic");
+
+// Basic streaming
+for await (const chunk of llm.stream("Tell me a story")) {
+  if (chunk.type === "text") {
+    process.stdout.write(chunk.content);
+  }
+}
+
+// Streaming with tools
+for await (const chunk of llm.stream("Roll 3d6", { tools: [roll] })) {
+  switch (chunk.type) {
+    case "text":
+      console.log("Text:", chunk.content);
+      break;
+    case "tool_call":
+      console.log("Calling tool:", chunk.toolCall.name);
+      break;
+    case "tool_result":
+      console.log("Tool result:", chunk.toolResult.result);
+      break;
+    case "done":
+      console.log("Usage:", chunk.usage);
+      break;
+    case "error":
+      console.error("Error:", chunk.error);
+      break;
+  }
+}
+
+// Static method
+for await (const chunk of Llm.stream("Hello", { llm: "openai" })) {
+  // ...
+}
+```
+
+### Stream Chunk Types
+
+```typescript
+type LlmStreamChunk =
+  | LlmStreamChunkText      // { type: "text", content: string }
+  | LlmStreamChunkToolCall  // { type: "tool_call", toolCall: { id, name, arguments } }
+  | LlmStreamChunkToolResult // { type: "tool_result", toolResult: { id, name, result } }
+  | LlmStreamChunkDone      // { type: "done", usage: LlmUsage }
+  | LlmStreamChunkError;    // { type: "error", error: { status, title, detail? } }
+```
+
+### Streaming to Express
+
+Use `createExpressStream` to pipe LLM streams to Express responses:
+
+```javascript
+import { expressStreamHandler, Llm, createExpressStream } from "jaypie";
+
+const chatRoute = expressStreamHandler(async (req, res) => {
+  const llm = new Llm("anthropic");
+  const stream = llm.stream(req.body.prompt);
+  await createExpressStream(stream, res);
+});
+
+app.post("/chat", chatRoute);
+```
+
+### Streaming to Lambda
+
+Use `createLambdaStream` with Lambda Response Streaming:
+
+```javascript
+import { lambdaStreamHandler, Llm, createLambdaStream } from "jaypie";
+
+const handler = awslambda.streamifyResponse(
+  lambdaStreamHandler(async (event, context) => {
+    const llm = new Llm("openai");
+    const stream = llm.stream(event.prompt);
+    await createLambdaStream(stream, context.responseStream);
+  })
+);
+```
+
+### JaypieStream Wrapper
+
+Use `JaypieStream` or `createJaypieStream` for fluent piping:
+
+```javascript
+import { createJaypieStream, Llm } from "jaypie";
+
+const llm = new Llm("gemini");
+const stream = createJaypieStream(llm.stream("Hello"));
+
+// Pipe to Express
+await stream.toExpress(res);
+
+// Or pipe to Lambda
+await stream.toLambda(responseStream);
+
+// Or iterate manually
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Hooks
+
+Use hooks to intercept and observe the LLM lifecycle:
+
+```javascript
+const result = await llm.operate("Process this", {
+  hooks: {
+    beforeEachModelRequest: ({ input, options, providerRequest }) => {
+      console.log("About to call model with:", providerRequest);
+    },
+    afterEachModelResponse: ({ content, usage, providerResponse }) => {
+      console.log("Model responded:", content);
+      console.log("Tokens used:", usage);
+    },
+    beforeEachTool: ({ toolName, args }) => {
+      console.log(`Calling tool ${toolName} with:`, args);
+    },
+    afterEachTool: ({ toolName, result }) => {
+      console.log(`Tool ${toolName} returned:`, result);
+    },
+    onToolError: ({ toolName, error }) => {
+      console.error(`Tool ${toolName} failed:`, error);
+    },
+    onRetryableModelError: ({ error }) => {
+      console.warn("Retrying after error:", error);
+    },
+    onUnrecoverableModelError: ({ error }) => {
+      console.error("Fatal error:", error);
+    },
+  },
+});
+```
+
+## Toolkit
+
+Group tools with `Toolkit` for additional features:
+
+```javascript
+import { Llm, Toolkit } from "jaypie";
+
+const toolkit = new Toolkit([roll, weather, time], {
+  explain: true,  // Add __Explanation param to tools
+  log: true,      // Log tool calls (default)
+});
+
+// Extend toolkit with more tools
+toolkit.extend([anotherTool], { replace: true });
+
+const result = await llm.operate("Roll dice and check weather", {
+  tools: toolkit,
+});
+```
+
+### Zod Schema Support
+
+Tool parameters can be defined using Zod schemas instead of JSON Schema:
+
+```javascript
+import { z } from "zod/v4";
+import { Llm, Toolkit } from "jaypie";
+
+const weatherTool = {
+  name: "get_weather",
+  description: "Get weather for a city",
+  parameters: z.object({
+    city: z.string().describe("City name"),
+    unit: z.enum(["celsius", "fahrenheit"]),
+  }),
+  type: "function",
+  call: async ({ city, unit }) => ({ city, temp: 72, unit }),
+};
+
+const toolkit = new Toolkit([weatherTool]);
+// Zod schemas are automatically converted to JSON Schema
+```
+
 ## Footnotes
 
 Llm.operate(input, options)