human-in-the-loop 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# Human-in-the-Loop
+
+A strongly-typed interface for human functions across multiple platforms.
+
+## Installation
+
+```bash
+npm install human-in-the-loop
+# or
+yarn add human-in-the-loop
+# or
+pnpm add human-in-the-loop
+```
+
+## Features
+
+- Strongly-typed human functions with TypeScript generics
+- Support for multiple platforms:
+  - Slack (using Block Kit)
+  - Microsoft Teams
+  - React/ShadCN UI components
+  - Email (via React Email)
+- Simple, consistent API across all platforms
+- Type-safe inputs and outputs
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { createHumanFunction } from 'human-in-the-loop'
+
+// Define a strongly-typed human function for approval
+const getApproval = createHumanFunction<
+  { documentTitle: string, documentUrl: string },
+  { approved: boolean, comments?: string }
+>({
+  platform: 'slack',
+  title: 'Document Approval Request',
+  description: 'Please review and approve the following document:',
+  options: [
+    { value: 'approve', label: 'Approve' },
+    { value: 'reject', label: 'Reject' }
+  ],
+  freeText: true,
+  // Slack-specific options
+  channel: 'approvals'
+})
+
+// Request human input
+const task = await getApproval.request({
+  documentTitle: 'Q2 Financial Report',
+  documentUrl: 'https://example.com/docs/q2-finance'
+})
+
+console.log(`Task created with ID: ${task.taskId}`)
+
+// Later, get the response
+const response = await getApproval.getResponse(task.taskId)
+if (response?.approved) {
+  console.log('Document was approved!')
+  if (response.comments) {
+    console.log(`Comments: ${response.comments}`)
+  }
+} else {
+  console.log('Document was rejected or pending')
+}
+```
+
+### Platform-Specific Examples
+
+#### Slack
+
+```typescript
+import { createHumanFunction } from 'human-in-the-loop'
+
+const slackFeedback = createHumanFunction<
+  { featureDescription: string },
+  { rating: number, feedback?: string }
+>({
+  platform: 'slack',
+  title: 'Feature Feedback Request',
+  description: 'Please provide feedback on our new feature:',
+  options: [
+    { value: '1', label: '⭐ Poor' },
+    { value: '2', label: '⭐⭐ Fair' },
+    { value: '3', label: '⭐⭐⭐ Good' },
+    { value: '4', label: '⭐⭐⭐⭐ Very Good' },
+    { value: '5', label: '⭐⭐⭐⭐⭐ Excellent' }
+  ],
+  freeText: true,
+  channel: 'product-feedback'
+})
+```
+
+#### Microsoft Teams
+
+```typescript
+import { createHumanFunction } from 'human-in-the-loop'
+
+const teamsApproval = createHumanFunction<
+  { requestDetails: string },
+  { approved: boolean }
+>({
+  platform: 'teams',
+  title: 'Approval Request',
+  description: 'Please review and approve this request:',
+  options: [
+    { value: 'approve', label: 'Approve' },
+    { value: 'reject', label: 'Reject' }
+  ],
+  webhookUrl: process.env.TEAMS_WEBHOOK_URL,
+  useAdaptiveCards: true
+})
+```
+
+#### React
+
+```tsx
+import { createHumanFunction, ReactHumanFunction } from 'human-in-the-loop'
+import React, { useState } from 'react'
+
+// Create the human function
+const reactFeedback = createHumanFunction<
+  { productName: string },
+  { rating: number, comments?: string }
+>({
+  platform: 'react',
+  title: 'Product Feedback',
+  description: 'Please rate this product and provide any comments:',
+  options: [
+    { value: '1', label: '1 - Poor' },
+    { value: '2', label: '2 - Fair' },
+    { value: '3', label: '3 - Good' },
+    { value: '4', label: '4 - Very Good' },
+    { value: '5', label: '5 - Excellent' }
+  ],
+  freeText: true,
+  theme: 'light'
+}) as ReactHumanFunction<{ productName: string }, { rating: number, comments?: string }>
+
+// In your React component
+function FeedbackComponent() {
+  const [taskId, setTaskId] = useState<string | null>(null)
+  
+  const handleRequestFeedback = async () => {
+    const task = await reactFeedback.request({ productName: 'Super Product' })
+    setTaskId(task.taskId)
+  }
+  
+  return (
+    <div>
+      <button onClick={handleRequestFeedback}>Request Feedback</button>
+      
+      {taskId && reactFeedback.getComponent(taskId, { productName: 'Super Product' })}
+    </div>
+  )
+}
+```
+
+#### Email
+
+```typescript
+import { createHumanFunction, EmailHumanFunction } from 'human-in-the-loop'
+import React from 'react'
+import { render } from 'react-email'
+
+// Create the human function
+const emailSurvey = createHumanFunction<
+  { surveyTopic: string },
+  { response: string }
+>({
+  platform: 'email',
+  title: 'Customer Survey',
+  description: 'Please complete our customer satisfaction survey:',
+  options: [
+    { value: 'very-satisfied', label: 'Very Satisfied' },
+    { value: 'satisfied', label: 'Satisfied' },
+    { value: 'neutral', label: 'Neutral' },
+    { value: 'dissatisfied', label: 'Dissatisfied' },
+    { value: 'very-dissatisfied', label: 'Very Dissatisfied' }
+  ],
+  to: 'customer@example.com',
+  from: 'surveys@company.com',
+  callbackUrl: 'https://example.com/api/survey-response'
+}) as EmailHumanFunction<{ surveyTopic: string }, { response: string }>
+
+// Get the email template as HTML
+const taskId = 'task-123'
+const emailComponent = emailSurvey.getEmailComponent(taskId)
+const emailHtml = render(emailComponent)
+```
+
+## API Reference
+
+### `createHumanFunction<TInput, TOutput>(options)`
+
+Creates a strongly-typed human function with the specified input and output types.
+
+#### Options
+
+- `platform`: The platform to use ('slack', 'teams', 'react', or 'email')
+- `title`: Title of the request shown to humans
+- `description`: Description of the task for humans
+- `options`: Array of options for the human to choose from
+- `freeText`: Whether to allow free text input
+- `timeout`: Timeout in milliseconds after which the task is marked as timed out
+
+Platform-specific options are also available based on the selected platform.
+
+### `HumanFunction<TInput, TOutput>`
+
+The interface for human functions.
+
+#### Methods
+
+- `request(input: TInput): Promise<HumanTaskRequest>`: Request human input with the given input data
+- `getResponse(taskId: string): Promise<TOutput | null>`: Get the human response for a given task
+
+## License
+
+MIT

package/TODO.md

@@ -0,0 +1,53 @@
+# Human-in-the-Loop Implementation Progress
+
+## Core Implementation
+- [x] Set up package structure
+- [x] Define core types and interfaces
+- [x] Implement factory function
+- [x] Create basic tests
+
+## Platform Implementations
+- [x] Slack implementation
+  - [x] Create SlackHumanFunction class
+  - [x] Implement request and getResponse methods
+  - [ ] Implement real Slack Block Kit integration
+- [x] Microsoft Teams implementation
+  - [x] Create TeamsHumanFunction class
+  - [x] Implement request and getResponse methods
+  - [ ] Implement real Teams Adaptive Cards integration
+- [x] React/ShadCN implementation
+  - [x] Create ReactHumanFunction class
+  - [x] Implement HumanFeedback component
+  - [x] Add styling and theming support
+  - [ ] Add ShadCN UI components
+- [x] Email (React Email) implementation
+  - [x] Create EmailHumanFunction class
+  - [x] Implement EmailTemplate component
+  - [ ] Implement real email sending functionality
+
+## Documentation
+- [x] Create README with usage examples
+- [x] Add JSDoc comments to public APIs
+- [ ] Create API reference documentation
+- [ ] Add more comprehensive examples
+
+## Technical Challenges and Blockers
+- [ ] Need to implement real platform integrations (currently mocked)
+- [ ] Need to add proper error handling and timeout mechanisms
+- [ ] Need to implement persistent storage for responses
+
+## Verification Requirements
+- [x] Basic unit tests for factory function
+- [ ] Integration tests for each platform
+- [ ] End-to-end tests with real platform integrations
+- [ ] Performance tests for large-scale usage
+
+## Future Enhancements
+- [ ] Add more comprehensive tests
+- [ ] Implement real platform integrations (currently mocked)
+- [ ] Add more customization options for each platform
+- [ ] Create example applications
+- [ ] Add support for more platforms (Discord, Telegram, etc.)
+- [ ] Implement webhook handlers for platform callbacks
+- [ ] Add authentication and authorization mechanisms
+- [ ] Implement rate limiting and throttling