human-in-the-loop 2.0.2 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # human-in-the-loop
 
+## 2.1.1
+
+### Patch Changes
+
+- Updated dependencies [6beb531]
+  - ai-functions@2.1.1
+  - digital-workers@2.1.1
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - rpc.do@0.2.0
+  - ai-functions@2.0.3
+  - digital-workers@2.0.3
+
 ## 2.0.2
 
 ### Patch Changes

package/examples/basic-usage.js

@@ -0,0 +1,325 @@
+/**
+ * Basic usage examples for human-in-the-loop
+ *
+ * This file demonstrates common patterns and use cases
+ */
+import { Human, Role, Team, Goals, approve, ask, decide, notify, kpis, okrs, registerHuman, } from '../src/index.js';
+// ============================================================================
+// Setup: Define roles, teams, and humans
+// ============================================================================
+// Define roles
+const techLead = Role({
+    id: 'tech-lead',
+    name: 'Tech Lead',
+    description: 'Technical leadership and architecture decisions',
+    capabilities: ['approve-prs', 'deploy-prod', 'review-code'],
+    escalatesTo: 'engineering-manager',
+});
+const engineer = Role({
+    id: 'engineer',
+    name: 'Software Engineer',
+    description: 'Software development',
+    capabilities: ['write-code', 'review-code'],
+    escalatesTo: 'tech-lead',
+});
+// Define teams
+const engineeringTeam = Team({
+    id: 'engineering',
+    name: 'Engineering Team',
+    description: 'Product development team',
+    members: ['alice', 'bob', 'charlie'],
+    lead: 'alice',
+});
+// Register humans
+const alice = registerHuman({
+    id: 'alice',
+    name: 'Alice Smith',
+    email: 'alice@example.com',
+    roles: ['tech-lead'],
+    teams: ['engineering'],
+    channels: {
+        slack: '@alice',
+        email: 'alice@example.com',
+        web: true,
+    },
+});
+const bob = registerHuman({
+    id: 'bob',
+    name: 'Bob Johnson',
+    email: 'bob@example.com',
+    roles: ['engineer'],
+    teams: ['engineering'],
+    channels: {
+        slack: '@bob',
+        email: 'bob@example.com',
+    },
+});
+// ============================================================================
+// Example 1: Approval workflow
+// ============================================================================
+async function approvalExample() {
+    console.log('=== Approval Example ===\n');
+    try {
+        // Request approval for production deployment
+        const deployment = await approve({
+            title: 'Production Deployment',
+            description: 'Deploy version 2.0.0 to production',
+            subject: 'Production Deployment - v2.0.0',
+            input: {
+                version: '2.0.0',
+                environment: 'production',
+                changes: ['New AI features', 'Performance improvements', 'Bug fixes'],
+            },
+            assignee: alice.email,
+            priority: 'high',
+            timeout: 3600000, // 1 hour
+            escalatesTo: 'engineering-manager',
+        });
+        if (deployment.approved) {
+            console.log('✅ Deployment approved!');
+            console.log('Comments:', deployment.comments);
+            // Proceed with deployment
+            await deploy();
+            // Send success notification
+            await notify({
+                type: 'success',
+                title: 'Deployment Complete',
+                message: 'Version 2.0.0 successfully deployed to production',
+                recipient: [alice.email, engineeringTeam.id],
+                channels: ['slack', 'email'],
+                priority: 'normal',
+            });
+        }
+        else {
+            console.log('❌ Deployment rejected');
+            console.log('Reason:', deployment.comments);
+        }
+    }
+    catch (error) {
+        console.error('Approval failed:', error);
+    }
+}
+// ============================================================================
+// Example 2: Ask a question
+// ============================================================================
+async function questionExample() {
+    console.log('\n=== Question Example ===\n');
+    try {
+        const answer = await ask({
+            title: 'Product Naming Decision',
+            question: 'What should we name the new AI assistant feature?',
+            context: {
+                feature: 'AI-powered code assistant',
+                targetAudience: 'developers',
+                competitors: ['GitHub Copilot', 'Cursor', 'Tabnine'],
+            },
+            assignee: 'product-manager@example.com',
+            suggestions: ['CodeMate', 'DevAssist', 'SmartCode', 'AIHelper'],
+            priority: 'normal',
+        });
+        console.log('Answer received:', answer);
+    }
+    catch (error) {
+        console.error('Question failed:', error);
+    }
+}
+// ============================================================================
+// Example 3: Decision with options
+// ============================================================================
+async function decisionExample() {
+    console.log('\n=== Decision Example ===\n');
+    try {
+        const strategy = await decide({
+            title: 'Deployment Strategy',
+            description: 'Choose the deployment strategy for the new release',
+            options: ['blue-green', 'canary', 'rolling', 'all-at-once'],
+            context: {
+                riskLevel: 'high',
+                activeUsers: 100000,
+                deploymentWindow: '2 hours',
+                rollbackTime: '5 minutes',
+            },
+            criteria: [
+                'Minimize risk to users',
+                'Enable fast rollback',
+                'Complete within deployment window',
+            ],
+            assignee: alice.email,
+            priority: 'high',
+        });
+        console.log('Selected strategy:', strategy);
+    }
+    catch (error) {
+        console.error('Decision failed:', error);
+    }
+}
+// ============================================================================
+// Example 4: Goals and OKRs
+// ============================================================================
+function goalsExample() {
+    console.log('\n=== Goals and OKRs Example ===\n');
+    // Define team goals
+    const q1Goals = Goals({
+        id: 'engineering-q1-2024',
+        objectives: [
+            'Launch AI assistant v2.0',
+            'Improve system performance by 50%',
+            'Reduce bug count by 40%',
+        ],
+        successCriteria: [
+            'Release by March 31',
+            'Pass all performance benchmarks',
+            'Achieve customer satisfaction score of 4.5+',
+        ],
+        targetDate: new Date('2024-03-31'),
+    });
+    console.log('Q1 Goals:', q1Goals);
+    // Define OKRs
+    const q1OKRs = okrs({
+        id: 'engineering-okrs-q1-2024',
+        objective: 'Build world-class AI development tools',
+        keyResults: [
+            {
+                description: 'Increase active users by 50%',
+                progress: 0.3,
+                current: 13000,
+                target: 15000,
+            },
+            {
+                description: 'Achieve 95% uptime',
+                progress: 0.92,
+                current: 0.95,
+                target: 0.95,
+            },
+            {
+                description: 'Reduce average response time to <100ms',
+                progress: 0.75,
+                current: 120,
+                target: 100,
+            },
+        ],
+        period: 'Q1 2024',
+        owner: alice.email,
+    });
+    console.log('Q1 OKRs:', q1OKRs);
+    // Track KPIs
+    const performanceKPI = kpis({
+        id: 'api-response-time',
+        name: 'API Response Time',
+        value: 120,
+        target: 100,
+        unit: 'ms',
+        trend: 'down',
+    });
+    console.log('Performance KPI:', performanceKPI);
+}
+// ============================================================================
+// Example 5: Using Human instance for advanced operations
+// ============================================================================
+async function advancedExample() {
+    console.log('\n=== Advanced Example ===\n');
+    // Create a custom Human instance with specific configuration
+    const human = Human({
+        defaultTimeout: 7200000, // 2 hours
+        defaultPriority: 'high',
+        autoEscalate: true,
+        escalationPolicies: [
+            {
+                id: 'critical-approval',
+                name: 'Critical Approval Policy',
+                conditions: {
+                    timeout: 1800000, // 30 minutes
+                    minPriority: 'critical',
+                },
+                escalationPath: [
+                    {
+                        assignee: 'tech-lead',
+                        afterMs: 1800000, // 30 minutes
+                        notifyVia: ['slack', 'sms'],
+                    },
+                    {
+                        assignee: 'engineering-manager',
+                        afterMs: 3600000, // 1 hour
+                        notifyVia: ['slack', 'email', 'sms'],
+                    },
+                    {
+                        assignee: 'cto',
+                        afterMs: 7200000, // 2 hours
+                        notifyVia: ['slack', 'email', 'sms'],
+                    },
+                ],
+            },
+        ],
+    });
+    // Create an approval workflow
+    const deploymentWorkflow = human.createWorkflow({
+        id: 'prod-deployment-workflow',
+        name: 'Production Deployment Workflow',
+        steps: [
+            {
+                name: 'Code Review',
+                role: 'engineer',
+                approvers: [bob.id],
+                requireAll: true,
+            },
+            {
+                name: 'Security Review',
+                role: 'security-engineer',
+                approvers: ['security-team'],
+                requireAll: false,
+            },
+            {
+                name: 'Tech Lead Approval',
+                role: 'tech-lead',
+                approvers: [alice.id],
+                requireAll: true,
+            },
+        ],
+        currentStep: 0,
+        status: 'pending',
+    });
+    console.log('Created workflow:', deploymentWorkflow);
+    // Get the review queue
+    const queue = await human.getQueue({
+        name: 'High Priority Queue',
+        description: 'All high priority pending requests',
+        filters: {
+            status: ['pending', 'in_progress'],
+            priority: ['high', 'critical'],
+        },
+        sortBy: 'priority',
+        sortDirection: 'desc',
+        limit: 10,
+    });
+    console.log('Queue:', queue.name, 'Items:', queue.items.length);
+}
+// ============================================================================
+// Mock deployment function
+// ============================================================================
+async function deploy() {
+    console.log('🚀 Deploying to production...');
+    // Simulate deployment
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    console.log('✅ Deployment successful!');
+}
+// ============================================================================
+// Run examples
+// ============================================================================
+async function main() {
+    console.log('Human-in-the-Loop Examples\n');
+    console.log('Note: These examples demonstrate the API.');
+    console.log('Actual human responses would need to be provided via the store.\n');
+    // Run examples (most will timeout or error without actual human responses)
+    // In a real system, humans would respond via UI, webhooks, or API calls
+    goalsExample();
+    // Uncomment to test async examples (they will wait for human responses)
+    // await approvalExample()
+    // await questionExample()
+    // await decisionExample()
+    // await advancedExample()
+}
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch(console.error);
+}
+export { approvalExample, questionExample, decisionExample, goalsExample, advancedExample, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-in-the-loop",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Primitives for integrating human oversight and intervention in AI workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -20,9 +20,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "ai-functions": "2.0.2",
-    "digital-workers": "2.0.2",
-    "rpc.do": "^0.1.0"
+    "ai-functions": "2.1.1",
+    "digital-workers": "2.1.1"
   },
   "keywords": [
     "human",

package/src/helpers.js

@@ -0,0 +1,274 @@
+/**
+ * Helper functions for common human-in-the-loop patterns
+ */
+import { Human } from './human.js';
+/**
+ * Create a default Human instance for convenience
+ */
+const defaultHuman = Human();
+/**
+ * Define a human role
+ *
+ * @example
+ * ```ts
+ * const techLead = Role({
+ *   id: 'tech-lead',
+ *   name: 'Tech Lead',
+ *   capabilities: ['approve-prs', 'deploy-prod'],
+ *   escalatesTo: 'engineering-manager',
+ * })
+ * ```
+ */
+export function Role(role) {
+    return defaultHuman.defineRole(role);
+}
+/**
+ * Define a team
+ *
+ * @example
+ * ```ts
+ * const engineering = Team({
+ *   id: 'engineering',
+ *   name: 'Engineering Team',
+ *   members: ['alice', 'bob', 'charlie'],
+ *   lead: 'alice',
+ * })
+ * ```
+ */
+export function Team(team) {
+    return defaultHuman.defineTeam(team);
+}
+/**
+ * Define goals for a team or individual
+ *
+ * @example
+ * ```ts
+ * const q1Goals = Goals({
+ *   id: 'q1-2024',
+ *   objectives: [
+ *     'Launch v2.0',
+ *     'Improve performance by 50%',
+ *   ],
+ *   targetDate: new Date('2024-03-31'),
+ * })
+ * ```
+ */
+export function Goals(goals) {
+    return defaultHuman.defineGoals(goals);
+}
+/**
+ * Request approval from a human
+ *
+ * @example
+ * ```ts
+ * const result = await approve({
+ *   title: 'Deploy to production',
+ *   description: 'Deploy v2.0.0 to production',
+ *   subject: 'Production Deployment',
+ *   input: { version: '2.0.0', environment: 'prod' },
+ *   assignee: 'tech-lead@example.com',
+ *   priority: 'high',
+ * })
+ *
+ * if (result.approved) {
+ *   await deploy()
+ * }
+ * ```
+ */
+export async function approve(params) {
+    return defaultHuman.approve(params);
+}
+/**
+ * Ask a question to a human
+ *
+ * @example
+ * ```ts
+ * const answer = await ask({
+ *   title: 'Product naming',
+ *   question: 'What should we name the new feature?',
+ *   context: { feature: 'AI Assistant' },
+ *   assignee: 'product-manager@example.com',
+ * })
+ * ```
+ */
+export async function ask(params) {
+    return defaultHuman.ask(params);
+}
+/**
+ * Request a human to perform a task
+ *
+ * This uses the digital-workers interface for humans
+ *
+ * @example
+ * ```ts
+ * const result = await do({
+ *   title: 'Review code',
+ *   instructions: 'Review the PR and provide feedback',
+ *   input: { prUrl: 'https://github.com/...' },
+ *   assignee: 'senior-dev@example.com',
+ * })
+ * ```
+ */
+export async function do_(params) {
+    return defaultHuman.do(params);
+}
+// Export as 'do' for the API, but define as 'do_' to avoid reserved keyword
+export { do_ as do };
+/**
+ * Request a human to make a decision
+ *
+ * @example
+ * ```ts
+ * const choice = await decide({
+ *   title: 'Pick deployment strategy',
+ *   options: ['blue-green', 'canary', 'rolling'],
+ *   context: { risk: 'high', users: 100000 },
+ *   assignee: 'devops-lead@example.com',
+ * })
+ * ```
+ */
+export async function decide(params) {
+    return defaultHuman.decide(params);
+}
+/**
+ * Request generation/content creation from a human
+ *
+ * This is a specialized form of do() for content generation
+ *
+ * @example
+ * ```ts
+ * const content = await generate({
+ *   title: 'Write blog post',
+ *   instructions: 'Write a blog post about our new feature',
+ *   input: { topic: 'AI Assistant', targetAudience: 'developers' },
+ *   assignee: 'content-writer@example.com',
+ * })
+ * ```
+ */
+export async function generate(params) {
+    return defaultHuman.do(params);
+}
+/**
+ * Type checking/validation request
+ *
+ * Ask a human to validate data or check type compliance
+ *
+ * @example
+ * ```ts
+ * const valid = await is({
+ *   title: 'Validate user data',
+ *   question: 'Is this user data valid and complete?',
+ *   input: userData,
+ *   assignee: 'data-specialist@example.com',
+ * })
+ * ```
+ */
+export async function is(params) {
+    const result = await defaultHuman.decide({
+        title: params.title,
+        description: params.question,
+        options: ['true', 'false'],
+        context: params.input,
+        assignee: params.assignee,
+        role: params.role,
+        team: params.team,
+        priority: params.priority,
+        timeout: params.timeout,
+        metadata: params.metadata,
+    });
+    return result === 'true';
+}
+/**
+ * Send a notification to a human
+ *
+ * @example
+ * ```ts
+ * await notify({
+ *   type: 'info',
+ *   title: 'Deployment complete',
+ *   message: 'Version 2.0.0 deployed successfully',
+ *   recipient: 'team@example.com',
+ *   channels: ['slack', 'email'],
+ * })
+ * ```
+ */
+export async function notify(params) {
+    await defaultHuman.notify(params);
+}
+/**
+ * Track Key Performance Indicators
+ *
+ * @example
+ * ```ts
+ * kpis({
+ *   id: 'monthly-revenue',
+ *   name: 'Monthly Revenue',
+ *   value: 150000,
+ *   target: 200000,
+ *   unit: 'USD',
+ *   trend: 'up',
+ * })
+ * ```
+ */
+export function kpis(kpis) {
+    return defaultHuman.trackKPIs(kpis);
+}
+/**
+ * Define Objectives and Key Results
+ *
+ * @example
+ * ```ts
+ * okrs({
+ *   id: 'q1-2024-growth',
+ *   objective: 'Accelerate user growth',
+ *   keyResults: [
+ *     {
+ *       description: 'Increase active users by 50%',
+ *       progress: 0.3,
+ *       current: 13000,
+ *       target: 15000,
+ *     },
+ *     {
+ *       description: 'Achieve 95% customer satisfaction',
+ *       progress: 0.85,
+ *       current: 0.93,
+ *       target: 0.95,
+ *     },
+ *   ],
+ *   period: 'Q1 2024',
+ *   owner: 'ceo@example.com',
+ * })
+ * ```
+ */
+export function okrs(okrs) {
+    return defaultHuman.defineOKRs(okrs);
+}
+/**
+ * Register a human worker in the system
+ *
+ * @example
+ * ```ts
+ * const alice = registerHuman({
+ *   id: 'alice',
+ *   name: 'Alice Smith',
+ *   email: 'alice@example.com',
+ *   roles: ['tech-lead', 'developer'],
+ *   teams: ['engineering', 'frontend'],
+ *   channels: {
+ *     slack: '@alice',
+ *     email: 'alice@example.com',
+ *   },
+ * })
+ * ```
+ */
+export function registerHuman(human) {
+    return defaultHuman.registerHuman(human);
+}
+/**
+ * Get the default Human manager instance
+ *
+ * Use this to access the underlying HumanManager for advanced operations
+ */
+export function getDefaultHuman() {
+    return defaultHuman;
+}