humanbehavior-js/src/wizard/README.md

SDK for HumanBehavior session and event recording

# HumanBehavior SDK Wizard Module

This module provides AI-enhanced auto-installation capabilities for the HumanBehavior SDK.

## 📁 Directory Structure

```
src/wizard/
├── core/           # Core installation wizard
│   └── install-wizard.ts
├── ai/             # AI-enhanced wizard components
│   └── ai-install-wizard.ts
├── cli/            # Command-line interfaces
│   ├── auto-install.ts
│   └── ai-auto-install.ts
├── services/       # AI service implementations
│   ├── remote-ai-service.ts
│   └── centralized-ai-service.ts
├── index.ts        # Main exports
└── README.md       # This file
```

## 🚀 Key Components

### Core (`core/`)
- **`install-wizard.ts`**: Traditional installation wizard
- Framework detection and code modification
- Environment variable management
- Package installation

### AI (`ai/`)
- **`ai-install-wizard.ts`**: AI-enhanced installation wizard
- AI-powered framework detection
- Intelligent code analysis
- Conflict resolution
- Learning system

### CLI (`cli/`)
- **`auto-install.ts`**: Traditional CLI interface
- **`ai-auto-install.ts`**: AI-enhanced CLI interface
- User interaction and command parsing
- Installation mode selection

### Services (`services/`)
- **`remote-ai-service.ts`**: Connects to deployed Lambda AI service
- **`centralized-ai-service.ts`**: Local AI service implementation
- Heuristic fallback when AI is unavailable

## 🔧 Usage

### Traditional Installation
```typescript
import { AutoInstallationWizard } from 'humanbehavior-js/wizard';

const wizard = new AutoInstallationWizard(apiKey, projectPath);
const result = await wizard.install();
```

### AI-Enhanced Installation
```typescript
import { AIEnhancedInstallationWizard, RemoteAIService } from 'humanbehavior-js/wizard';

const aiService = new RemoteAIService({
  apiEndpoint: 'https://your-lambda-api.execute-api.region.amazonaws.com/prod'
});

const wizard = new AIEnhancedInstallationWizard(apiKey, projectPath, aiService);
const result = await wizard.install();
```

### CLI Usage
```bash
# Traditional installation
npx humanbehavior-js auto-install YOUR_API_KEY

# AI-enhanced installation
npx humanbehavior-js ai-auto-install YOUR_API_KEY --ai
```

## 🧠 AI Features

- **Intelligent Framework Detection**: Beyond package.json analysis
- **Code Pattern Analysis**: Understands project structure and patterns
- **Conflict Resolution**: Smart handling of existing integrations
- **Future-Proofing**: Adaptive strategies for new frameworks
- **Learning System**: Improves over time with usage patterns

## 🔄 Backward Compatibility

All existing imports continue to work:
- `humanbehavior-js/install-wizard` → `humanbehavior-js/wizard`
- Traditional wizard functionality unchanged
- AI features are additive, not breaking

## 🚀 Lambda Deployment

The `lambda-deployment/` directory contains the AI service for AWS Lambda deployment. This is separate from the client-side wizard code and should not be modified unless deploying AI service updates.

### 📁 Lambda Deployment Structure
```
lambda-deployment/
├── index.js                    # Lambda entry point
├── ai-install-wizard.ts        # AI service implementation  
├── install-wizard.ts           # Core wizard logic
├── centralized-ai-service.ts   # AI service interface
└── README.md                   # Deployment documentation
```

### 🔗 Client-Server Relationship
- **Client**: `src/wizard/` - User-facing installation wizard
- **Server**: `lambda-deployment/` - AI service backend
- **Connection**: `RemoteAIService` connects client to Lambda

See `lambda-deployment/README.md` for detailed deployment instructions.