human-in-the-loop 0.1.0 → 2.0.2

package/dist/human.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Human-in-the-loop primitives implementation
+ */
+import type { Role, Team, Human as HumanType, Goals, KPIs, OKRs, HumanOptions, ApprovalResponse, ReviewResponse, Notification, ReviewQueue, ApprovalWorkflow, Priority, HumanRequest } from './types.js';
+/**
+ * Human-in-the-loop manager
+ *
+ * Provides primitives for integrating human oversight and intervention
+ * in AI workflows.
+ *
+ * @example
+ * ```ts
+ * const human = Human({
+ *   defaultTimeout: 3600000, // 1 hour
+ *   autoEscalate: true,
+ * })
+ *
+ * // Request approval
+ * const approval = await human.approve({
+ *   title: 'Deploy to production',
+ *   description: 'Approve deployment of v2.0.0',
+ *   subject: 'Production Deployment',
+ *   assignee: 'tech-lead@example.com',
+ *   priority: 'high',
+ * })
+ *
+ * if (approval.approved) {
+ *   await deploy()
+ * }
+ * ```
+ */
+export declare class HumanManager {
+    private store;
+    private options;
+    private roles;
+    private teams;
+    private humans;
+    private escalationPolicies;
+    private workflows;
+    constructor(options?: HumanOptions);
+    /**
+     * Define a role
+     */
+    defineRole(role: Role): Role;
+    /**
+     * Get a role by ID
+     */
+    getRole(id: string): Role | undefined;
+    /**
+     * Define a team
+     */
+    defineTeam(team: Team): Team;
+    /**
+     * Get a team by ID
+     */
+    getTeam(id: string): Team | undefined;
+    /**
+     * Register a human worker
+     */
+    registerHuman(human: HumanType): HumanType;
+    /**
+     * Get a human by ID
+     */
+    getHuman(id: string): HumanType | undefined;
+    /**
+     * Request approval from a human
+     *
+     * @example
+     * ```ts
+     * const result = await human.approve({
+     *   title: 'Approve expense',
+     *   description: 'Employee expense claim for $150',
+     *   subject: 'Expense Claim #1234',
+     *   input: { amount: 150, category: 'Travel' },
+     *   assignee: 'manager@example.com',
+     *   priority: 'normal',
+     * })
+     * ```
+     */
+    approve<TData = unknown>(params: {
+        title: string;
+        description: string;
+        subject: string;
+        input: TData;
+        assignee?: string | string[];
+        role?: string;
+        team?: string;
+        priority?: Priority;
+        timeout?: number;
+        escalatesTo?: string | string[];
+        requiresApproval?: boolean;
+        approvers?: string[];
+        metadata?: Record<string, unknown>;
+    }): Promise<ApprovalResponse>;
+    /**
+     * Ask a question to a human
+     *
+     * @example
+     * ```ts
+     * const answer = await human.ask({
+     *   title: 'Product naming',
+     *   question: 'What should we name the new feature?',
+     *   context: { feature: 'AI Assistant' },
+     *   assignee: 'product-manager@example.com',
+     * })
+     * ```
+     */
+    ask(params: {
+        title: string;
+        question: string;
+        context?: unknown;
+        assignee?: string | string[];
+        role?: string;
+        team?: string;
+        priority?: Priority;
+        timeout?: number;
+        suggestions?: string[];
+        metadata?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Request a human to perform a task
+     *
+     * @example
+     * ```ts
+     * const result = await human.do({
+     *   title: 'Review code',
+     *   instructions: 'Review the PR and provide feedback',
+     *   input: { prUrl: 'https://github.com/...' },
+     *   assignee: 'senior-dev@example.com',
+     * })
+     * ```
+     */
+    do<TInput = unknown, TOutput = unknown>(params: {
+        title: string;
+        instructions: string;
+        input: TInput;
+        assignee?: string | string[];
+        role?: string;
+        team?: string;
+        priority?: Priority;
+        timeout?: number;
+        tools?: any[];
+        estimatedEffort?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<TOutput>;
+    /**
+     * Request a human to make a decision
+     *
+     * @example
+     * ```ts
+     * const choice = await human.decide({
+     *   title: 'Pick deployment strategy',
+     *   options: ['blue-green', 'canary', 'rolling'],
+     *   context: { risk: 'high', users: 100000 },
+     *   assignee: 'devops-lead@example.com',
+     * })
+     * ```
+     */
+    decide<TOptions extends string = string>(params: {
+        title: string;
+        description?: string;
+        options: TOptions[];
+        context?: unknown;
+        assignee?: string | string[];
+        role?: string;
+        team?: string;
+        priority?: Priority;
+        timeout?: number;
+        criteria?: string[];
+        metadata?: Record<string, unknown>;
+    }): Promise<TOptions>;
+    /**
+     * Request a human to review content
+     *
+     * @example
+     * ```ts
+     * const review = await human.review({
+     *   title: 'Review blog post',
+     *   content: { title: 'My Post', body: '...' },
+     *   reviewType: 'content',
+     *   criteria: ['Grammar', 'Tone', 'Accuracy'],
+     *   assignee: 'editor@example.com',
+     * })
+     * ```
+     */
+    review<TContent = unknown>(params: {
+        title: string;
+        description?: string;
+        content: TContent;
+        reviewType?: 'code' | 'content' | 'design' | 'data' | 'other';
+        criteria?: string[];
+        assignee?: string | string[];
+        role?: string;
+        team?: string;
+        priority?: Priority;
+        timeout?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<ReviewResponse>;
+    /**
+     * Send a notification to a human
+     *
+     * @example
+     * ```ts
+     * await human.notify({
+     *   type: 'info',
+     *   title: 'Deployment complete',
+     *   message: 'Version 2.0.0 deployed successfully',
+     *   recipient: 'team@example.com',
+     *   channels: ['slack', 'email'],
+     * })
+     * ```
+     */
+    notify(params: {
+        type: 'info' | 'warning' | 'error' | 'success';
+        title: string;
+        message: string;
+        recipient: string | string[];
+        channels?: ('slack' | 'email' | 'sms' | 'web')[];
+        priority?: Priority;
+        data?: unknown;
+    }): Promise<Notification>;
+    /**
+     * Get a review queue
+     *
+     * @example
+     * ```ts
+     * const queue = await human.getQueue({
+     *   name: 'Pending Approvals',
+     *   filters: {
+     *     status: ['pending'],
+     *     priority: ['high', 'critical'],
+     *   },
+     * })
+     * ```
+     */
+    getQueue(params: {
+        name: string;
+        description?: string;
+        filters?: ReviewQueue['filters'];
+        sortBy?: 'createdAt' | 'priority' | 'updatedAt';
+        sortDirection?: 'asc' | 'desc';
+        limit?: number;
+    }): Promise<ReviewQueue>;
+    /**
+     * Get a request by ID
+     */
+    getRequest<T extends HumanRequest = HumanRequest>(id: string): Promise<T | null>;
+    /**
+     * Complete a request with a response
+     */
+    completeRequest<T extends HumanRequest = HumanRequest>(id: string, response: T['response']): Promise<T>;
+    /**
+     * Reject a request
+     */
+    rejectRequest(id: string, reason: string): Promise<HumanRequest>;
+    /**
+     * Escalate a request
+     */
+    escalateRequest(id: string, to: string): Promise<HumanRequest>;
+    /**
+     * Cancel a request
+     */
+    cancelRequest(id: string): Promise<HumanRequest>;
+    /**
+     * Define or update goals
+     */
+    defineGoals(goals: Goals): Goals;
+    /**
+     * Track KPIs
+     */
+    trackKPIs(kpis: KPIs): KPIs;
+    /**
+     * Define or update OKRs
+     */
+    defineOKRs(okrs: OKRs): OKRs;
+    /**
+     * Create an approval workflow
+     */
+    createWorkflow(workflow: ApprovalWorkflow): ApprovalWorkflow;
+    /**
+     * Get a workflow by ID
+     */
+    getWorkflow(id: string): ApprovalWorkflow | undefined;
+    /**
+     * Wait for a human response
+     *
+     * In a real implementation, this would:
+     * 1. Poll the store for updates
+     * 2. Listen for webhooks/events
+     * 3. Handle timeouts and escalations
+     * 4. Return the response when available
+     *
+     * For now, this throws an error to indicate manual completion is needed
+     */
+    private waitForResponse;
+    /**
+     * Poll for request completion
+     */
+    private pollForCompletion;
+}
+/**
+ * Create a Human-in-the-loop manager instance
+ *
+ * @example
+ * ```ts
+ * import { Human } from 'human-in-the-loop'
+ *
+ * const human = Human({
+ *   defaultTimeout: 3600000, // 1 hour
+ *   autoEscalate: true,
+ * })
+ * ```
+ */
+export declare function Human(options?: HumanOptions): HumanManager;
+//# sourceMappingURL=human.d.ts.map

package/dist/human.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human.d.ts","sourceRoot":"","sources":["../src/human.ts"],"names":[],"mappings":"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"}