human-in-the-loop 2.0.2 → 2.1.1

package/src/human.test.js

@@ -0,0 +1,333 @@
+/**
+ * Tests for human-in-the-loop primitives
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Human } from './human.js';
+import { InMemoryHumanStore } from './store.js';
+describe('Human-in-the-loop', () => {
+    let human;
+    let store;
+    beforeEach(() => {
+        store = new InMemoryHumanStore();
+        human = Human({ store });
+    });
+    describe('Role Management', () => {
+        it('should define and retrieve a role', () => {
+            const role = human.defineRole({
+                id: 'tech-lead',
+                name: 'Tech Lead',
+                description: 'Technical leadership',
+                capabilities: ['approve-prs', 'deploy-prod'],
+            });
+            expect(role.id).toBe('tech-lead');
+            expect(role.name).toBe('Tech Lead');
+            const retrieved = human.getRole('tech-lead');
+            expect(retrieved).toEqual(role);
+        });
+    });
+    describe('Team Management', () => {
+        it('should define and retrieve a team', () => {
+            const team = human.defineTeam({
+                id: 'engineering',
+                name: 'Engineering Team',
+                members: ['alice', 'bob'],
+                lead: 'alice',
+            });
+            expect(team.id).toBe('engineering');
+            expect(team.members).toHaveLength(2);
+            const retrieved = human.getTeam('engineering');
+            expect(retrieved).toEqual(team);
+        });
+    });
+    describe('Human Worker Management', () => {
+        it('should register and retrieve a human', () => {
+            const worker = human.registerHuman({
+                id: 'alice',
+                name: 'Alice Smith',
+                email: 'alice@example.com',
+                roles: ['tech-lead'],
+                teams: ['engineering'],
+            });
+            expect(worker.id).toBe('alice');
+            expect(worker.name).toBe('Alice Smith');
+            const retrieved = human.getHuman('alice');
+            expect(retrieved).toEqual(worker);
+        });
+    });
+    describe('Approval Requests', () => {
+        it('should create an approval request', async () => {
+            const requestPromise = human.approve({
+                title: 'Test Approval',
+                description: 'Test approval request',
+                subject: 'Test',
+                input: { data: 'test' },
+                assignee: 'alice@example.com',
+                priority: 'normal',
+            });
+            // The request should be pending in the store
+            const requests = await store.list({ status: ['pending'] });
+            expect(requests).toHaveLength(1);
+            expect(requests[0]?.type).toBe('approval');
+            expect(requests[0]?.title).toBe('Test Approval');
+        });
+        it('should complete an approval request', async () => {
+            // Create request
+            const request = await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'Test Approval',
+                description: 'Test',
+                subject: 'Test',
+                input: { data: 'test' },
+                priority: 'normal',
+            });
+            // Complete it
+            const response = {
+                approved: true,
+                comments: 'Looks good!',
+            };
+            const completed = await human.completeRequest(request.id, response);
+            expect(completed.status).toBe('completed');
+            expect(completed.response).toEqual(response);
+        });
+        it('should reject an approval request', async () => {
+            const request = await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'Test Approval',
+                description: 'Test',
+                subject: 'Test',
+                input: { data: 'test' },
+                priority: 'normal',
+            });
+            const rejected = await human.rejectRequest(request.id, 'Not ready yet');
+            expect(rejected.status).toBe('rejected');
+            expect(rejected.rejectionReason).toBe('Not ready yet');
+        });
+    });
+    describe('Question Requests', () => {
+        it('should create a question request', async () => {
+            const requestPromise = human.ask({
+                title: 'Test Question',
+                question: 'What is the answer?',
+                context: { topic: 'testing' },
+                assignee: 'alice@example.com',
+            });
+            const requests = await store.list({ status: ['pending'] });
+            expect(requests).toHaveLength(1);
+            expect(requests[0]?.type).toBe('question');
+        });
+    });
+    describe('Decision Requests', () => {
+        it('should create a decision request', async () => {
+            const requestPromise = human.decide({
+                title: 'Test Decision',
+                options: ['option1', 'option2', 'option3'],
+                context: { info: 'test' },
+                assignee: 'alice@example.com',
+            });
+            const requests = await store.list({ status: ['pending'] });
+            expect(requests).toHaveLength(1);
+            expect(requests[0]?.type).toBe('decision');
+        });
+    });
+    describe('Review Requests', () => {
+        it('should create a review request', async () => {
+            const requestPromise = human.review({
+                title: 'Test Review',
+                content: { code: 'console.log("test")' },
+                reviewType: 'code',
+                criteria: ['syntax', 'style', 'logic'],
+                assignee: 'alice@example.com',
+            });
+            const requests = await store.list({ status: ['pending'] });
+            expect(requests).toHaveLength(1);
+            expect(requests[0]?.type).toBe('review');
+        });
+        it('should complete a review request', async () => {
+            const request = await store.create({
+                type: 'review',
+                status: 'pending',
+                title: 'Code Review',
+                description: 'Review PR',
+                input: { code: 'test' },
+                content: { code: 'test' },
+                priority: 'normal',
+            });
+            const response = {
+                approved: true,
+                comments: 'Code looks good',
+                rating: 5,
+            };
+            const completed = await human.completeRequest(request.id, response);
+            expect(completed.status).toBe('completed');
+            expect(completed.response).toEqual(response);
+        });
+    });
+    describe('Notifications', () => {
+        it('should send a notification', async () => {
+            const notification = await human.notify({
+                type: 'info',
+                title: 'Test Notification',
+                message: 'This is a test',
+                recipient: 'alice@example.com',
+                channels: ['email'],
+                priority: 'normal',
+            });
+            expect(notification.id).toBeDefined();
+            expect(notification.type).toBe('info');
+            expect(notification.title).toBe('Test Notification');
+        });
+    });
+    describe('Review Queue', () => {
+        it('should create and filter a review queue', async () => {
+            // Create multiple requests
+            await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'High Priority',
+                description: 'Test',
+                subject: 'Test',
+                input: {},
+                priority: 'high',
+            });
+            await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'Normal Priority',
+                description: 'Test',
+                subject: 'Test',
+                input: {},
+                priority: 'normal',
+            });
+            await store.create({
+                type: 'approval',
+                status: 'completed',
+                title: 'Completed',
+                description: 'Test',
+                subject: 'Test',
+                input: {},
+                priority: 'normal',
+            });
+            // Get queue with filters
+            const queue = await human.getQueue({
+                name: 'High Priority Queue',
+                filters: {
+                    status: ['pending'],
+                    priority: ['high'],
+                },
+            });
+            expect(queue.items).toHaveLength(1);
+            expect(queue.items[0]?.priority).toBe('high');
+        });
+    });
+    describe('Goals and OKRs', () => {
+        it('should define goals', () => {
+            const goals = human.defineGoals({
+                id: 'q1-2024',
+                objectives: ['Launch v2.0', 'Improve performance'],
+                targetDate: new Date('2024-03-31'),
+            });
+            expect(goals.id).toBe('q1-2024');
+            expect(goals.objectives).toHaveLength(2);
+        });
+        it('should track KPIs', () => {
+            const kpi = human.trackKPIs({
+                id: 'response-time',
+                name: 'API Response Time',
+                value: 120,
+                target: 100,
+                unit: 'ms',
+                trend: 'down',
+            });
+            expect(kpi.id).toBe('response-time');
+            expect(kpi.value).toBe(120);
+        });
+        it('should define OKRs', () => {
+            const okr = human.defineOKRs({
+                id: 'q1-okr',
+                objective: 'Improve performance',
+                keyResults: [
+                    {
+                        description: 'Reduce response time to <100ms',
+                        progress: 0.75,
+                        current: 120,
+                        target: 100,
+                    },
+                ],
+                period: 'Q1 2024',
+            });
+            expect(okr.id).toBe('q1-okr');
+            expect(okr.keyResults).toHaveLength(1);
+        });
+    });
+    describe('Workflow Management', () => {
+        it('should create and retrieve a workflow', () => {
+            const workflow = human.createWorkflow({
+                id: 'approval-workflow',
+                name: 'Approval Workflow',
+                steps: [
+                    {
+                        name: 'Step 1',
+                        approvers: ['alice'],
+                        requireAll: true,
+                    },
+                    {
+                        name: 'Step 2',
+                        approvers: ['bob'],
+                        requireAll: true,
+                    },
+                ],
+                currentStep: 0,
+                status: 'pending',
+            });
+            expect(workflow.id).toBe('approval-workflow');
+            expect(workflow.steps).toHaveLength(2);
+            const retrieved = human.getWorkflow('approval-workflow');
+            expect(retrieved).toEqual(workflow);
+        });
+    });
+    describe('Request Operations', () => {
+        it('should get a request by ID', async () => {
+            const request = await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'Test',
+                description: 'Test',
+                subject: 'Test',
+                input: {},
+                priority: 'normal',
+            });
+            const retrieved = await human.getRequest(request.id);
+            expect(retrieved?.id).toBe(request.id);
+        });
+        it('should escalate a request', async () => {
+            const request = await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'Test',
+                description: 'Test',
+                subject: 'Test',
+                input: {},
+                priority: 'normal',
+                assignee: 'alice',
+            });
+            const escalated = await human.escalateRequest(request.id, 'bob');
+            expect(escalated.status).toBe('escalated');
+            expect(escalated.assignee).toBe('bob');
+        });
+        it('should cancel a request', async () => {
+            const request = await store.create({
+                type: 'approval',
+                status: 'pending',
+                title: 'Test',
+                description: 'Test',
+                subject: 'Test',
+                input: {},
+                priority: 'normal',
+            });
+            const cancelled = await human.cancelRequest(request.id);
+            expect(cancelled.status).toBe('cancelled');
+        });
+    });
+});

package/src/index.js

@@ -0,0 +1,50 @@
+/**
+ * human-in-the-loop - Primitives for integrating human oversight and intervention in AI workflows
+ *
+ * This package provides primitives for human oversight and intervention in AI workflows:
+ * - Approval gates and workflows
+ * - Review processes and queues
+ * - Escalation paths
+ * - Human intervention points
+ * - Role and team management
+ * - Goals, KPIs, and OKRs tracking
+ *
+ * Implements the digital-workers interface for humans operating within a company boundary.
+ *
+ * @packageDocumentation
+ * @example
+ * ```ts
+ * import { Human, approve, ask, notify } from 'human-in-the-loop'
+ *
+ * // Create a Human-in-the-loop manager
+ * const human = Human({
+ *   defaultTimeout: 3600000, // 1 hour
+ *   autoEscalate: true,
+ * })
+ *
+ * // Request approval
+ * const result = await approve({
+ *   title: 'Deploy to production',
+ *   description: 'Approve deployment of v2.0.0',
+ *   subject: 'Production Deployment',
+ *   assignee: 'tech-lead@example.com',
+ *   priority: 'high',
+ * })
+ *
+ * if (result.approved) {
+ *   await deploy()
+ *   await notify({
+ *     type: 'success',
+ *     title: 'Deployment complete',
+ *     message: 'v2.0.0 deployed to production',
+ *     recipient: 'team@example.com',
+ *   })
+ * }
+ * ```
+ */
+// Export main Human constructor and manager
+export { Human, HumanManager } from './human.js';
+// Export helper functions (convenience API)
+export { Role, Team, Goals, approve, ask, do, decide, generate, is, notify, kpis, okrs, registerHuman, getDefaultHuman, } from './helpers.js';
+// Export store implementations
+export { InMemoryHumanStore } from './store.js';

package/src/store.js

@@ -0,0 +1,161 @@
+/**
+ * In-memory store implementation for human requests
+ */
+/**
+ * Simple in-memory implementation of HumanStore
+ *
+ * For production use, implement a persistent store using:
+ * - Database (PostgreSQL, MongoDB, etc.)
+ * - Key-value store (Redis)
+ * - Message queue (RabbitMQ, AWS SQS)
+ */
+export class InMemoryHumanStore {
+    requests = new Map();
+    requestIdCounter = 0;
+    /**
+     * Generate a unique request ID
+     */
+    generateId() {
+        return `req_${Date.now()}_${++this.requestIdCounter}`;
+    }
+    /**
+     * Create a new request
+     */
+    async create(request) {
+        const now = new Date();
+        const fullRequest = {
+            ...request,
+            id: this.generateId(),
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.requests.set(fullRequest.id, fullRequest);
+        return fullRequest;
+    }
+    /**
+     * Get a request by ID
+     */
+    async get(id) {
+        const request = this.requests.get(id);
+        return request ? request : null;
+    }
+    /**
+     * Update a request
+     */
+    async update(id, updates) {
+        const request = this.requests.get(id);
+        if (!request) {
+            throw new Error(`Request not found: ${id}`);
+        }
+        const updated = {
+            ...request,
+            ...updates,
+            updatedAt: new Date(),
+        };
+        this.requests.set(id, updated);
+        return updated;
+    }
+    /**
+     * List requests with filters
+     */
+    async list(filters, limit) {
+        let requests = Array.from(this.requests.values());
+        // Apply filters
+        if (filters) {
+            if (filters.status) {
+                requests = requests.filter((r) => filters.status.includes(r.status));
+            }
+            if (filters.priority) {
+                requests = requests.filter((r) => filters.priority.includes(r.priority));
+            }
+            if (filters.assignee) {
+                requests = requests.filter((r) => {
+                    if (!r.assignee)
+                        return false;
+                    const assignees = Array.isArray(r.assignee) ? r.assignee : [r.assignee];
+                    return assignees.some((a) => filters.assignee.includes(a));
+                });
+            }
+            if (filters.role) {
+                requests = requests.filter((r) => r.role && filters.role.includes(r.role));
+            }
+            if (filters.team) {
+                requests = requests.filter((r) => r.team && filters.team.includes(r.team));
+            }
+        }
+        // Sort by creation date (newest first)
+        requests.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+        // Apply limit
+        if (limit && limit > 0) {
+            requests = requests.slice(0, limit);
+        }
+        return requests;
+    }
+    /**
+     * Complete a request
+     */
+    async complete(id, response) {
+        const request = await this.get(id);
+        if (!request) {
+            throw new Error(`Request not found: ${id}`);
+        }
+        return this.update(id, {
+            status: 'completed',
+            response,
+            completedAt: new Date(),
+        });
+    }
+    /**
+     * Reject a request
+     */
+    async reject(id, reason) {
+        const request = await this.get(id);
+        if (!request) {
+            throw new Error(`Request not found: ${id}`);
+        }
+        return this.update(id, {
+            status: 'rejected',
+            rejectionReason: reason,
+            completedAt: new Date(),
+        });
+    }
+    /**
+     * Escalate a request
+     */
+    async escalate(id, to) {
+        const request = await this.get(id);
+        if (!request) {
+            throw new Error(`Request not found: ${id}`);
+        }
+        return this.update(id, {
+            status: 'escalated',
+            assignee: to,
+        });
+    }
+    /**
+     * Cancel a request
+     */
+    async cancel(id) {
+        const request = await this.get(id);
+        if (!request) {
+            throw new Error(`Request not found: ${id}`);
+        }
+        return this.update(id, {
+            status: 'cancelled',
+            completedAt: new Date(),
+        });
+    }
+    /**
+     * Clear all requests (for testing)
+     */
+    clear() {
+        this.requests.clear();
+        this.requestIdCounter = 0;
+    }
+    /**
+     * Get total count of requests
+     */
+    count() {
+        return this.requests.size;
+    }
+}

package/src/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for human-in-the-loop workflows
+ */
+export {};