human-in-the-loop 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "human-in-the-loop",
+  "version": "0.1.0",
+  "description": "Strongly-typed interface for human functions across multiple platforms",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "human",
+    "in-the-loop",
+    "feedback",
+    "slack",
+    "teams",
+    "react",
+    "email"
+  ],
+  "author": "Drivly",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drivly/primitives.org.ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/drivly/primitives.org.ai/issues"
+  },
+  "homepage": "https://primitives.org.ai",
+  "dependencies": {
+    "zod": "^3.24.3",
+    "ai-providers": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-email": "^1.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.0.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  }
+}

package/src/core/factory.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { createHumanFunction } from './factory'
+import { SlackHumanFunction } from '../platforms/slack'
+import { TeamsHumanFunction } from '../platforms/teams'
+import { ReactHumanFunction } from '../platforms/react'
+import { EmailHumanFunction } from '../platforms/email'
+
+describe('createHumanFunction', () => {
+  it('should create a Slack human function', () => {
+    const humanFunction = createHumanFunction<{}, {}>({
+      platform: 'slack',
+      title: 'Test',
+      description: 'Test description'
+    })
+    
+    expect(humanFunction).toBeInstanceOf(SlackHumanFunction)
+  })
+  
+  it('should create a Teams human function', () => {
+    const humanFunction = createHumanFunction<{}, {}>({
+      platform: 'teams',
+      title: 'Test',
+      description: 'Test description'
+    })
+    
+    expect(humanFunction).toBeInstanceOf(TeamsHumanFunction)
+  })
+  
+  it('should create a React human function', () => {
+    const humanFunction = createHumanFunction<{}, {}>({
+      platform: 'react',
+      title: 'Test',
+      description: 'Test description'
+    })
+    
+    expect(humanFunction).toBeInstanceOf(ReactHumanFunction)
+  })
+  
+  it('should create an Email human function', () => {
+    const humanFunction = createHumanFunction<{}, {}>({
+      platform: 'email',
+      title: 'Test',
+      description: 'Test description',
+      to: 'test@example.com'
+    })
+    
+    expect(humanFunction).toBeInstanceOf(EmailHumanFunction)
+  })
+  
+  it('should throw an error for unsupported platforms', () => {
+    expect(() => {
+      createHumanFunction<{}, {}>({
+        platform: 'invalid' as any,
+        title: 'Test',
+        description: 'Test description'
+      })
+    }).toThrow('Unsupported platform: invalid')
+  })
+  
+  it('should throw an error for email platform without to field', () => {
+    expect(() => {
+      createHumanFunction<{}, {}>({
+        platform: 'email',
+        title: 'Test',
+        description: 'Test description'
+      })
+    }).toThrow('Email platform requires a "to" field in options')
+  })
+})

package/src/core/factory.ts

@@ -0,0 +1,30 @@
+import type { CreateHumanFunctionOptions, HumanFunction } from './types'
+import { SlackHumanFunction } from '../platforms/slack'
+import { TeamsHumanFunction } from '../platforms/teams'
+import { ReactHumanFunction } from '../platforms/react'
+import { EmailHumanFunction } from '../platforms/email'
+
+/**
+ * Create a strongly-typed human function
+ */
+export function createHumanFunction<TInput, TOutput>(
+  options: CreateHumanFunctionOptions
+): HumanFunction<TInput, TOutput> {
+  const { platform } = options
+  
+  switch (platform) {
+    case 'slack':
+      return new SlackHumanFunction<TInput, TOutput>(options)
+    case 'teams':
+      return new TeamsHumanFunction<TInput, TOutput>(options)
+    case 'react':
+      return new ReactHumanFunction<TInput, TOutput>(options)
+    case 'email':
+      if (!options.to) {
+        throw new Error('Email platform requires a "to" field in options')
+      }
+      return new EmailHumanFunction<TInput, TOutput>(options as any)
+    default:
+      throw new Error(`Unsupported platform: ${platform}`)
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,191 @@
+import { z } from 'zod'
+
+/**
+ * Supported platforms for human-in-the-loop interactions
+ */
+export type HumanPlatform = 'slack' | 'teams' | 'react' | 'email'
+
+/**
+ * Status of a human task
+ */
+export type HumanTaskStatus = 'pending' | 'completed' | 'timeout'
+
+/**
+ * Base configuration for Human Functions
+ */
+export interface HumanFunctionConfig {
+  /**
+   * Title of the request shown to humans
+   */
+  title: string
+  
+  /**
+   * Description of the task for humans
+   */
+  description: string
+  
+  /**
+   * Platform to use for human interaction
+   */
+  platform: HumanPlatform
+  
+  /**
+   * Timeout in milliseconds after which the task is marked as timed out
+   */
+  timeout?: number
+  
+  /**
+   * Additional platform-specific options
+   */
+  [key: string]: any
+}
+
+/**
+ * A request for human input
+ */
+export interface HumanTaskRequest {
+  /**
+   * Unique identifier for the task
+   */
+  taskId: string
+  
+  /**
+   * Current status of the task
+   */
+  status: HumanTaskStatus
+  
+  /**
+   * Platform-specific message ID
+   */
+  messageId?: Record<HumanPlatform, string>
+}
+
+/**
+ * Human Function interface with strongly-typed input and output
+ */
+export interface HumanFunction<TInput, TOutput> {
+  /**
+   * Request human input with the given input data
+   */
+  request(input: TInput): Promise<HumanTaskRequest>
+  
+  /**
+   * Get the human response for a given task
+   */
+  getResponse(taskId: string): Promise<TOutput | null>
+}
+
+/**
+ * Platform-specific configurations
+ */
+export interface PlatformConfigs {
+  slack?: SlackConfig
+  teams?: TeamsConfig
+  react?: ReactConfig
+  email?: EmailConfig
+}
+
+/**
+ * Slack-specific configuration
+ */
+export interface SlackConfig {
+  /**
+   * Slack channel to send the message to
+   */
+  channel?: string
+  
+  /**
+   * User IDs to mention in the message
+   */
+  mentions?: string[]
+  
+  /**
+   * Whether to use a modal dialog instead of a message
+   */
+  modal?: boolean
+  
+  /**
+   * Custom Slack blocks
+   */
+  blocks?: any[]
+  
+  /**
+   * Webhook URL for callbacks
+   */
+  webhookUrl?: string
+}
+
+/**
+ * Microsoft Teams specific configuration
+ */
+export interface TeamsConfig {
+  /**
+   * Teams webhook URL
+   */
+  webhookUrl?: string
+  
+  /**
+   * Whether to use adaptive cards
+   */
+  useAdaptiveCards?: boolean
+}
+
+/**
+ * React-specific configuration
+ */
+export interface ReactConfig {
+  /**
+   * Custom component styling
+   */
+  styles?: Record<string, any>
+  
+  /**
+   * Theme configuration
+   */
+  theme?: 'light' | 'dark' | 'system'
+}
+
+/**
+ * Email-specific configuration
+ */
+export interface EmailConfig {
+  /**
+   * Recipients of the email
+   */
+  to: string | string[]
+  
+  /**
+   * CC recipients
+   */
+  cc?: string | string[]
+  
+  /**
+   * BCC recipients
+   */
+  bcc?: string | string[]
+  
+  /**
+   * From address
+   */
+  from?: string
+  
+  /**
+   * Reply-to address
+   */
+  replyTo?: string
+  
+  /**
+   * Callback URL for email responses
+   */
+  callbackUrl?: string
+}
+
+/**
+ * Options for creating human functions
+ */
+export interface CreateHumanFunctionOptions extends HumanFunctionConfig, PlatformConfigs {
+  /**
+   * Optional validation schema for the output
+   */
+  outputSchema?: z.ZodType<any>
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './core/types'
+export { createHumanFunction } from './core/factory'
+
+export * from './platforms/slack'
+export * from './platforms/teams'
+export * from './platforms/react'
+export * from './platforms/email'

package/src/platforms/email/index.tsx

@@ -0,0 +1,137 @@
+import React from 'react'
+import type { HumanFunction, HumanTaskRequest, EmailConfig } from '../../core/types'
+
+/**
+ * Basic Email Template component
+ */
+export function EmailTemplate({
+  taskId,
+  title,
+  description,
+  options,
+  callbackUrl
+}: {
+  taskId: string
+  title: string
+  description: string
+  options?: string[] | Array<{ value: string; label: string }>
+  callbackUrl?: string
+}) {
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+      
+      {options && options.length > 0 && (
+        <div>
+          <p>Please select one of the following options:</p>
+          <ul>
+            {options.map((option, index) => {
+              const value = typeof option === 'string' ? option : option.value
+              const label = typeof option === 'string' ? option : option.label
+              const responseUrl = callbackUrl 
+                ? `${callbackUrl}?taskId=${taskId}&option=${encodeURIComponent(value)}`
+                : '#'
+              
+              return (
+                <li key={index}>
+                  <a href={responseUrl}>{label}</a>
+                </li>
+              )
+            })}
+          </ul>
+        </div>
+      )}
+      
+      <p>
+        Or, you can reply to this email with your response.
+      </p>
+    </div>
+  )
+}
+
+/**
+ * Mock function to send an email
+ */
+export async function sendEmail(
+  config: EmailConfig & {
+    title: string
+    description: string
+    options?: string[] | Array<{ value: string; label: string }>
+    taskId: string
+  }
+): Promise<{ messageId: string }> {
+  console.log(`Sending email to ${config.to}`)
+  console.log(`Title: ${config.title}`)
+  console.log(`Description: ${config.description}`)
+  
+  
+  return { messageId: `email-${config.taskId}-${Date.now()}` }
+}
+
+/**
+ * Get the response for an email task
+ */
+export async function getEmailResponse<TOutput>(taskId: string): Promise<TOutput | null> {
+  console.log(`Getting response for email task ${taskId}`)
+  
+  return null
+}
+
+/**
+ * Implementation of HumanFunction for Email
+ */
+export class EmailHumanFunction<TInput, TOutput> implements HumanFunction<TInput, TOutput> {
+  private config: EmailConfig & { 
+    title: string
+    description: string
+    options?: string[] | Array<{ value: string; label: string }>
+  }
+  
+  constructor(config: EmailConfig & { 
+    title: string
+    description: string
+    options?: string[] | Array<{ value: string; label: string }>
+  }) {
+    this.config = config
+  }
+  
+  async request(input: TInput): Promise<HumanTaskRequest> {
+    const taskId = `task-${Date.now()}`
+    
+    const { messageId } = await sendEmail({
+      ...this.config,
+      taskId
+    })
+    
+    return {
+      taskId,
+      status: 'pending',
+      messageId: {
+        slack: '',
+        teams: '',
+        react: '',
+        email: messageId
+      }
+    }
+  }
+  
+  async getResponse(taskId: string): Promise<TOutput | null> {
+    return getEmailResponse<TOutput>(taskId)
+  }
+  
+  /**
+   * Get a React component for this email template
+   */
+  getEmailComponent(taskId: string): React.ReactNode {
+    return (
+      <EmailTemplate
+        taskId={taskId}
+        title={this.config.title}
+        description={this.config.description}
+        options={this.config.options}
+        callbackUrl={this.config.callbackUrl}
+      />
+    )
+  }
+}