@od-oneapp/ai-platform 0.1.0

package/src/tools/advanced/llm-tool.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview LLM-powered tool utilities.
+ * @module @od-oneapp/ai-platform/tools/advanced
+ */
+
+import { z } from 'zod';
+
+import { tool, generateText, generateObject } from '../../shared';
+
+import type { SDKFlexibleSchema, SDKLanguageModel, SDKTool } from '../../shared';
+
+const validationInputSchema = z.object({
+  content: z.string().describe('Content to validate'),
+});
+
+const validationOutputSchema = z.object({
+  isValid: z.boolean(),
+  score: z.number().min(0).max(100),
+  violations: z.array(
+    z.object({
+      criterion: z.string(),
+      issue: z.string(),
+      severity: z.enum(['low', 'medium', 'high']),
+    }),
+  ),
+  suggestions: z.array(z.string()),
+});
+
+type ValidationInput = z.infer<typeof validationInputSchema>;
+
+/**
+ * Configuration for LLM-powered tool creation.
+ */
+export interface LLMToolConfig {
+  /** SDKTool name */
+  name: string;
+  /** SDKTool description */
+  description: string;
+  /** Input parameters schema */
+  parameters: SDKFlexibleSchema;
+  /** Output schema for structured output */
+  outputSchema: SDKFlexibleSchema;
+  /** System prompt for the LLM */
+  systemPrompt: string;
+  /** User prompt template - use {{param}} for interpolation */
+  userPromptTemplate: string;
+  /** Language model to use */
+  model: SDKLanguageModel;
+  /** Optional max tokens */
+  maxTokens?: number;
+  /** Optional temperature */
+  temperature?: number;
+}
+
+/**
+ * Creates a tool powered by an LLM with structured output.
+ *
+ * @param config - LLM tool configuration
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const summarizeTool = createLLMTool({
+ *   name: 'summarize',
+ *   description: 'Summarize text',
+ *   parameters: z.object({ text: z.string() }),
+ *   outputSchema: z.object({ summary: z.string(), keyPoints: z.array(z.string()) }),
+ *   systemPrompt: 'You are a summarization assistant.',
+ *   userPromptTemplate: 'Summarize: {{text}}',
+ *   model: openai('gpt-4o-mini'),
+ * });
+ * ```
+ */
+export function createLLMTool(config: LLMToolConfig): SDKTool {
+  const {
+    description,
+    parameters,
+    outputSchema,
+    systemPrompt,
+    userPromptTemplate,
+    model,
+    maxTokens,
+    temperature,
+  } = config;
+
+  return tool({
+    description,
+    inputSchema: parameters,
+    execute: async (input: Record<string, unknown>) => {
+      // Interpolate user prompt
+      const userPrompt = interpolatePrompt(userPromptTemplate, input);
+
+      const result = await generateObject({
+        model,
+        system: systemPrompt,
+        prompt: userPrompt,
+        schema: outputSchema,
+        ...(maxTokens && { maxOutputTokens: maxTokens }),
+        ...(temperature !== undefined && { temperature }),
+      });
+
+      return result.object;
+    },
+  }) as SDKTool;
+}
+
+/**
+ * Creates an LLM-powered validation tool.
+ *
+ * @param config - Validation tool configuration
+ * @returns SDKTool that validates input against criteria
+ *
+ * @example
+ * ```ts
+ * const validateTool = createValidationTool({
+ *   name: 'validateContent',
+ *   description: 'Validate content against guidelines',
+ *   criteria: ['No harmful content', 'Proper formatting', 'Factually accurate'],
+ *   model: openai('gpt-4o-mini'),
+ * });
+ * ```
+ */
+export function createValidationTool(config: {
+  name: string;
+  description: string;
+  criteria: string[];
+  model: SDKLanguageModel;
+  maxTokens?: number;
+}): SDKTool {
+  return tool({
+    description: config.description,
+    inputSchema: validationInputSchema,
+    execute: async (input: ValidationInput) => {
+      const { content } = input;
+      const result = await generateObject({
+        model: config.model,
+        system: `You are a content validator. Validate content against these criteria:
+${config.criteria.map((c, i) => `${i + 1}. ${c}`).join('\n')}
+
+Respond with JSON matching this schema:
+- isValid: boolean
+- score: 0-100
+- violations: array of {criterion, issue, severity: low|medium|high}
+- suggestions: array of improvement suggestions`,
+        prompt: `Validate this content:\n\n${content}`,
+        schema: validationOutputSchema,
+        ...(config.maxTokens && { maxOutputTokens: config.maxTokens }),
+      });
+
+      return result.object;
+    },
+  }) as SDKTool;
+}
+
+/**
+ * Creates an LLM-powered transformation tool.
+ *
+ * @param config - Transformation tool configuration
+ * @returns SDKTool that transforms input text
+ *
+ * @example
+ * ```ts
+ * const rewriteTool = createTransformTool({
+ *   name: 'rewrite',
+ *   description: 'Rewrite text in a different style',
+ *   styles: ['formal', 'casual', 'technical'],
+ *   model: openai('gpt-4o-mini'),
+ * });
+ * ```
+ */
+export function createTransformTool(config: {
+  name: string;
+  description: string;
+  styles: string[];
+  model: SDKLanguageModel;
+  maxTokens?: number;
+}): SDKTool {
+  const transformInputSchema = z.object({
+    text: z.string().describe('Text to transform'),
+    style: z.enum(config.styles as [string, ...string[]]).describe('Target style'),
+    preserveLength: z.boolean().optional().describe('Keep similar length'),
+  });
+
+  return tool({
+    description: config.description,
+    inputSchema: transformInputSchema,
+    execute: async (input: { text: string; style: string; preserveLength?: boolean }) => {
+      const { text, style, preserveLength } = input;
+      const { text: result } = await generateText({
+        model: config.model,
+        system: `You are a text transformation assistant. Transform text to the requested style.${preserveLength ? ' Keep the output approximately the same length as the input.' : ''}`,
+        prompt: `Transform this text to ${style} style:\n\n${text}`,
+      });
+
+      return { original: text, transformed: result, style };
+    },
+  }) as SDKTool;
+}
+
+/**
+ * Interpolates template strings with values.
+ */
+function interpolatePrompt(template: string, values: Record<string, unknown>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => {
+    const value = values[key];
+    return value !== undefined ? String(value) : `{{${key}}}`;
+  });
+}

package/src/tools/approval/FILES.md

@@ -0,0 +1,449 @@
+# HITL Approval System - File Structure
+
+Complete directory listing and file purposes.
+
+## Directory Structure
+
+```
+src/tools/approval/
+├── index.ts                      Core approval system
+├── queue.ts                      Queue implementations
+├── middleware.ts                 Middleware chain system
+├── usage-example.ts              Working examples
+├── testing.ts                    Testing utilities
+├── README.md                     Complete API documentation
+├── QUICK_START.md                Quick start guide
+├── IMPLEMENTATION_SUMMARY.md     Implementation overview
+└── FILES.md                      This file
+```
+
+## File Details
+
+### Implementation Files
+
+#### index.ts (19.5 KB)
+
+**Main approval orchestration module**
+
+Core exports:
+
+- `ApprovalRequest` - Request interface
+- `ApprovalResult` - Decision interface
+- `ApprovalRule` - Rule definition
+- `ApprovalOptions` - Configuration
+- `ApprovalHandler` - Handler interface
+- `ApprovalBackend` - Storage interface
+- `ApprovalQueue` - Queue interface
+- `Tool<T>` - Generic tool interface
+
+Main functions:
+
+- `withApproval()` - Tool wrapper
+- `needsApproval()` - Rule evaluation
+- `createApprovalQueue()` - Queue factory
+- `createApprovalQueueWithRedis()` - Redis factory
+- `createApprovalHandler()` - Handler factory
+- `createApprovalMiddleware()` - Middleware factory
+
+Features:
+
+- Pattern matching (wildcards, regex)
+- Conditional rules with custom logic
+- In-memory and Redis backends
+- Request expiration handling
+- Argument modifications
+- Unique ID generation
+
+#### queue.ts (19.8 KB)
+
+**Queue implementations and management**
+
+Classes:
+
+- `InMemoryApprovalQueue` - Fast local queue
+- `RedisApprovalQueue` - Distributed queue
+
+Interfaces:
+
+- `AdvancedQueueConfig` - Configuration
+- `QueueMetrics` - Performance metrics
+
+Features:
+
+- Priority-based ordering
+- Expiration handling
+- Dead letter queue (DLQ)
+- Metrics collection
+- Batch processing
+- Request retention
+- Automatic cleanup
+
+Factory functions:
+
+- `createInMemoryQueue()` - In-memory queue
+- `createRedisQueue()` - Redis queue
+
+#### middleware.ts (16.0 KB)
+
+**Middleware system for request interception**
+
+Classes:
+
+- `MiddlewareChain` - Middleware executor
+- `MiddlewareContext` - Execution context
+
+Interfaces:
+
+- `MiddlewareFunction` - Middleware signature
+- `AuditLogEntry` - Audit log format
+
+Middleware implementations:
+
+- `createApprovalMiddleware()` - Core approval
+- `createValidationMiddleware()` - Input validation
+- `createAuditMiddleware()` - Audit logging
+- `createRateLimitMiddleware()` - Rate limiting
+- `createRetryMiddleware()` - Retry logic
+- `createContextEnrichmentMiddleware()` - Metadata injection
+
+Utilities:
+
+- `buildApprovalChain()` - Complete chain builder
+- `createContext()` - Context generator
+
+#### usage-example.ts (400+ lines)
+
+**Comprehensive usage examples**
+
+Examples:
+
+1. Basic approval wrapper
+2. Approval queue management
+3. Complex approval rules
+4. Complete HITL workflow
+5. Rate limiting and retry
+6. Dead letter queue
+
+Includes:
+
+- Working code for each pattern
+- Mock data and configurations
+- Factory functions
+- Error handling demonstrations
+- Real-world scenarios
+
+#### testing.ts (350+ lines)
+
+**Testing utilities and helpers**
+
+Classes:
+
+- `MockApprovalHandler` - Mock handler
+- `MockTool` - Mock tool
+- `ApprovalTestBuilder` - Fluent builder
+
+Objects:
+
+- `testFixtures` - Common test data
+- `assertions` - Assertion helpers
+
+Functions:
+
+- `createTestBuilder()` - Builder factory
+- `runApprovalTest()` - Test runner
+- `exampleTestSuite()` - Example tests
+
+Features:
+
+- Mock approval tracking
+- Mock tool call tracking
+- Assertion helpers
+- Fluent test builder
+- Example test suite
+
+### Documentation Files
+
+#### README.md (550+ lines)
+
+**Complete API reference and documentation**
+
+Contents:
+
+- Feature overview
+- Installation instructions
+- Architecture overview
+- Component descriptions
+- Usage examples (5 detailed examples)
+- API reference for all functions
+- Complete type definitions
+- Configuration options
+- Pattern matching guide
+- Best practices (10 principles)
+- Performance considerations
+- Testing information
+- License reference
+
+Target audience: Developers implementing the system
+
+#### QUICK_START.md (350+ lines)
+
+**Quick start guide for rapid implementation**
+
+Contents:
+
+- 30-second overview
+- Architecture diagram
+- 5-minute setup (4 steps)
+- Common use cases (3 scenarios)
+- Approval rules patterns (3 types)
+- Queue operations reference
+- Priority levels table
+- Middleware features overview
+- Error handling guide
+- Debugging tips
+- Common issues and solutions
+- Next steps
+- Key files reference
+
+Target audience: New users wanting quick implementation
+
+#### IMPLEMENTATION_SUMMARY.md (400+ lines)
+
+**Comprehensive implementation overview**
+
+Contents:
+
+- Project overview
+- Files created list with details
+- Architecture diagrams
+- Key features list
+- Type system overview
+- Implementation statistics
+- File breakdown table
+- Design patterns used (6 patterns)
+- Integration points
+- Testing support description
+- Performance characteristics
+- Extensibility guide
+- Best practices implemented
+- Security considerations
+- Future enhancement ideas
+- Maintenance notes
+- Support and documentation index
+- Conclusion
+
+Target audience: Project leads and architects
+
+#### FILES.md
+
+**File structure and purposes (this file)**
+
+Contents:
+
+- Directory structure
+- File details with descriptions
+- Quick reference table
+- Related files mapping
+
+Target audience: All users for navigation
+
+## Quick Reference
+
+### By Use Case
+
+**I want to implement approval:**
+
+1. Start with: QUICK_START.md
+2. Then read: README.md API Reference
+3. Use: index.ts `withApproval()`
+
+**I want to manage queues:**
+
+1. Use: queue.ts classes
+2. Reference: README.md Queue Management
+3. Examples: usage-example.ts Example 2
+
+**I want to build middleware:**
+
+1. Start with: middleware.ts
+2. Reference: README.md Middleware section
+3. Examples: usage-example.ts Example 4
+
+**I want to test:**
+
+1. Use: testing.ts utilities
+2. Reference: testing.ts classes
+3. Examples: usage-example.ts code structure
+
+**I want to understand architecture:**
+
+1. Read: IMPLEMENTATION_SUMMARY.md
+2. Review: Architecture diagrams
+3. Study: Component interactions
+
+### By Role
+
+**Developer**
+
+- QUICK_START.md (5-min setup)
+- usage-example.ts (code examples)
+- testing.ts (test utilities)
+- index.ts (API reference)
+
+**Architect**
+
+- IMPLEMENTATION_SUMMARY.md (overview)
+- README.md (full spec)
+- Architecture diagrams
+- Design patterns section
+
+**QA/Tester**
+
+- testing.ts (test utilities)
+- README.md (testing section)
+- usage-example.ts (test scenarios)
+- FILES.md (file reference)
+
+**DevOps**
+
+- README.md (performance, Redis setup)
+- queue.ts (Redis implementation)
+- IMPLEMENTATION_SUMMARY.md (deployment)
+- testing.ts (integration tests)
+
+## File Statistics
+
+| File                      | Lines     | Bytes      | Purpose     |
+| ------------------------- | --------- | ---------- | ----------- |
+| index.ts                  | 690       | 19.5 KB    | Core system |
+| queue.ts                  | 560       | 19.8 KB    | Queues      |
+| middleware.ts             | 480       | 16.0 KB    | Middleware  |
+| usage-example.ts          | 400+      | —          | Examples    |
+| testing.ts                | 350+      | —          | Tests       |
+| README.md                 | 550+      | —          | API docs    |
+| QUICK_START.md            | 350+      | —          | Quick guide |
+| IMPLEMENTATION_SUMMARY.md | 400+      | —          | Overview    |
+| FILES.md                  | —         | —          | This file   |
+| **Total**                 | **3,883** | **55+ KB** | —           |
+
+## Dependencies
+
+### Built-in TypeScript
+
+- No external dependencies for core
+- Optional: Redis client for RedisApprovalQueue
+- Optional: TypeScript 4.8+ for full typing
+
+### Import Structure
+
+```typescript
+// Core system
+import { withApproval, needsApproval } from "./index";
+import type { ApprovalRequest, ApprovalResult } from "./index";
+
+// Queue management
+import { createInMemoryQueue, createRedisQueue } from "./queue";
+import type { ApprovalQueue } from "./index";
+
+// Middleware
+import { buildApprovalChain, createContext } from "./middleware";
+
+// Testing
+import { MockApprovalHandler, createTestBuilder } from "./testing";
+
+// Examples
+import { example1_basicApproval } from "./usage-example";
+```
+
+## Getting Started
+
+### For Beginners
+
+1. Read: QUICK_START.md (5 minutes)
+2. Run: usage-example.ts examples
+3. Copy: First example code
+4. Modify: For your use case
+
+### For Advanced Users
+
+1. Read: README.md Architecture section
+2. Study: middleware.ts implementation
+3. Review: Design patterns
+4. Extend: Create custom backends/middlewares
+
+### For Testers
+
+1. Review: testing.ts
+2. Study: usage-example.ts
+3. Use: MockApprovalHandler
+4. Build: Custom test scenarios
+
+## File Relationships
+
+```
+index.ts (Core)
+├── Used by: All other files
+└── Exports: Main interfaces and functions
+
+queue.ts (Queues)
+├── Uses: index.ts types
+├── Used by: index.ts, middleware.ts
+└── Exports: Queue implementations
+
+middleware.ts (Middleware)
+├── Uses: index.ts types
+├── Used by: Applications
+└── Exports: Middleware functions
+
+testing.ts (Testing)
+├── Uses: index.ts types
+├── Used by: Test suites
+└── Exports: Mock implementations
+
+usage-example.ts (Examples)
+├── Uses: All implementation files
+├── Reference: Learning resource
+└── Exports: Example functions
+
+Documentation (README, QUICK_START, etc.)
+├── Reference: All implementation files
+├── Purpose: Education and reference
+└── Audience: All users
+```
+
+## Maintenance Guide
+
+### Adding Features
+
+1. Update types in index.ts
+2. Implement in appropriate file
+3. Add examples to usage-example.ts
+4. Add tests to testing.ts
+5. Update documentation
+
+### Bug Fixes
+
+1. Add test case first (testing.ts)
+2. Fix in implementation file
+3. Add example if user-facing
+4. Update relevant docs
+
+### Documentation Updates
+
+1. Update README.md for API changes
+2. Update QUICK_START.md for common issues
+3. Update IMPLEMENTATION_SUMMARY.md for architecture changes
+4. Update this file if structure changes
+
+## Support Resources
+
+- **API Reference**: README.md
+- **Quick Start**: QUICK_START.md
+- **Working Examples**: usage-example.ts
+- **Test Examples**: testing.ts
+- **Architecture**: IMPLEMENTATION_SUMMARY.md
+- **File Guide**: FILES.md (this file)
+
+---
+
+**Total Package**: 3,883 lines, 55+ KB of production-ready code and documentation