movie-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wei Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,464 @@
+# Movie Agent
+
+An intelligent movie recommendation system that helps users discover movies based on their preferences and shows where they're available to stream in Canada.
+
+## Features
+
+- 🎬 Personalized movie recommendations based on mood, genre, and preferences
+- 📺 Real-time streaming availability for Canadian platforms
+- ⚡ Fast responses using TMDb API
+- 🎯 Smart filtering by runtime, release year, and streaming platforms
+- 📦 Easy integration into web applications and APIs
+
+## Prerequisites
+
+- Node.js (v18 or higher)
+- TMDb API key ([Get one here](https://www.themoviedb.org/settings/api))
+
+## Installation
+
+```bash
+npm install movie-agent
+```
+
+## Quick Start
+
+### Option 1: Using MovieAgentFactory.create() with explicit config (Recommended)
+
+```typescript
+import { MovieAgentFactory } from 'movie-agent';
+
+// Create agent with explicit configuration
+const agent = MovieAgentFactory.create({
+  tmdbApiKey: process.env.TMDB_API_KEY!,
+  tmdbRegion: 'CA',
+  debug: true, // Enable debug logging
+});
+
+// Get recommendations
+const recommendations = await agent.getRecommendations({
+  mood: 'excited',
+  genre: 'Action',
+  platforms: ['Netflix', 'Prime Video'],
+});
+
+console.log(recommendations);
+```
+
+### Option 2: Using MovieAgentFactory.fromEnv() convenience method
+
+```typescript
+import { MovieAgentFactory } from 'movie-agent';
+import dotenv from 'dotenv';
+
+// Load your .env file BEFORE creating the agent
+dotenv.config();
+
+// Create agent from environment variables
+const agent = MovieAgentFactory.fromEnv(true); // true = enable debug logging
+
+// Get recommendations
+const recommendations = await agent.getRecommendations({
+  mood: 'relaxed',
+  genre: ['Comedy', 'Romance'],
+  runtime: { max: 120 },
+});
+```
+
+## API Examples
+
+```typescript
+// Simple mood-based search
+await agent.getRecommendations({
+  mood: 'happy'
+});
+
+// Genre-specific with platform filter
+await agent.getRecommendations({
+  genre: 'Action',
+  platforms: ['Disney+']
+});
+
+// Complex filtering
+await agent.getRecommendations({
+  mood: 'adventurous',
+  platforms: ['Netflix', 'Prime Video'],
+  runtime: { min: 90, max: 150 },
+  releaseYear: { from: 2020, to: 2024 }
+});
+
+// Multiple genres
+await agent.getRecommendations({
+  genre: ['Comedy', 'Romance'],
+  platforms: ['Netflix'],
+  runtime: { max: 120 }
+});
+```
+
+## Integration Examples
+
+### Next.js API Route
+
+```typescript
+// pages/api/recommendations.ts
+import { MovieAgentFactory } from 'movie-agent';
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+const agent = MovieAgentFactory.create({
+  tmdbApiKey: process.env.TMDB_API_KEY!,
+  tmdbRegion: 'CA',
+});
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  try {
+    const { mood, genre, platforms } = req.body;
+    const recommendations = await agent.getRecommendations({ mood, genre, platforms });
+    res.status(200).json(recommendations);
+  } catch (error) {
+    console.error('Error getting recommendations:', error);
+    res.status(500).json({ error: 'Failed to get recommendations' });
+  }
+}
+```
+
+### Express Server
+
+```typescript
+import express from 'express';
+import { MovieAgentFactory } from 'movie-agent';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const app = express();
+app.use(express.json());
+
+const agent = MovieAgentFactory.create({
+  tmdbApiKey: process.env.TMDB_API_KEY!,
+  tmdbRegion: 'CA',
+});
+
+app.post('/api/recommendations', async (req, res) => {
+  try {
+    const recommendations = await agent.getRecommendations(req.body);
+    res.json(recommendations);
+  } catch (error) {
+    console.error(error);
+    res.status(500).json({ error: 'Failed to get recommendations' });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+TMDB_API_KEY=your_tmdb_api_key_here
+
+# Optional
+TMDB_REGION=CA
+CACHE_TTL=86400
+MAX_RECOMMENDATIONS=5
+MIN_RECOMMENDATIONS=3
+```
+
+### Input Parameters
+
+```typescript
+interface UserInput {
+  mood?: string;                    // e.g., 'excited', 'relaxed', 'thoughtful'
+  genre?: string | string[];        // e.g., 'Action' or ['Action', 'Thriller']
+  platforms?: string[];             // e.g., ['Netflix', 'Prime Video']
+  runtime?: {
+    min?: number;                   // Minimum runtime in minutes
+    max?: number;                   // Maximum runtime in minutes
+  };
+  releaseYear?: number | {          // Single year or range
+    from: number;
+    to: number;
+  };
+}
+```
+
+## Error Handling
+
+```typescript
+const result = await agent.getRecommendations(input);
+
+if ('error' in result) {
+  console.error(`Error: ${result.errorType} - ${result.message}`);
+  
+  switch (result.errorType) {
+    case 'INVALID_API_KEY':
+      // Handle invalid API key
+      break;
+    case 'RATE_LIMIT_EXCEEDED':
+      // Handle rate limit
+      break;
+    case 'NO_RESULTS':
+      // No movies found matching criteria
+      break;
+  }
+} else {
+  // Success! Use recommendations
+  console.log(result.recommendations);
+}
+```
+
+## Supported Streaming Platforms (Canada)
+
+- Netflix
+- Prime Video
+- Crave
+- Disney+
+- Apple TV+
+- Paramount+
+- And many more regional platforms
+
+## TypeScript Support
+
+The package is fully typed. Import types as needed:
+
+```typescript
+import {
+  MovieAgentFactory,
+  UserInput,
+  AgentResponse,
+  MovieRecommendation,
+  ErrorResponse,
+} from 'movie-agent';
+```
+
+## Response Format
+
+### Success Response
+
+```typescript
+interface AgentResponse {
+  recommendations: MovieRecommendation[];
+  metadata?: {
+    timestamp?: string;
+    inputParameters?: UserInput;
+  };
+}
+
+interface MovieRecommendation {
+  tmdbId: number;
+  title: string;
+  releaseYear: string;
+  runtime: number;
+  genres: string[];
+  overview: string;
+  streamingPlatforms: StreamingPlatform[];
+  matchReason: string;
+}
+```
+
+### Error Response
+
+```typescript
+interface ErrorResponse {
+  error: true;
+  errorType: 'VALIDATION_ERROR' | 'INVALID_API_KEY' | 'RATE_LIMIT_EXCEEDED' | 'NO_RESULTS' | 'UNKNOWN_ERROR';
+  message: string;
+  timestamp: string;
+}
+```
+
+## Development
+
+### For Contributors
+
+If you want to develop or modify this package:
+
+```bash
+# Clone the repository
+git clone https://github.com/imWayneWY/movie-agent.git
+cd movie-agent
+
+# Install dependencies
+npm install
+
+# Copy environment variables template
+cp .env.example .env
+
+# Add your API keys to .env
+```
+
+### Building
+
+```bash
+# Type checking
+npm run type-check
+
+# Lint code
+npm run lint
+
+# Fix linting issues automatically
+npm run lint:fix
+
+# Format code
+npm run format
+
+# Check formatting without modifying files
+npm run format:check
+
+# Run all validations (type-check + lint + coverage)
+npm run validate
+```
+
+### Building
+
+```bash
+# Clean build artifacts
+npm run clean
+
+# Build TypeScript to JavaScript
+npm run build
+
+# Clean and build (runs validation first)
+npm run prebuild && npm run build
+```
+
+## Testing
+
+The project follows Test-Driven Development (TDD) practices with comprehensive test coverage.
+
+### Running Tests
+
+```bash
+# Run all tests (unit + E2E)
+npm test
+
+# Run only unit tests (excludes E2E and live integration tests)
+npm run test:unit
+
+# Run E2E tests
+npm run test:e2e
+
+# Run live integration tests (requires API keys)
+npm run test:integration
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests in watch mode (for development)
+npm run test:watch
+
+# Run tests in CI mode (with coverage)
+npm run test:ci
+```
+
+### Test Structure
+
+- **Unit Tests** (`src/__tests__/*.test.ts`) - Test individual modules and functions
+- **E2E Tests** (`src/__tests__/e2e.test.ts`) - Test complete recommendation pipeline
+- **Integration Tests** (`src/__tests__/*.live.test.ts`) - Test with real APIs (requires credentials)
+
+### Coverage Requirements
+
+The project enforces minimum 90% code coverage across:
+- Branches: 90%
+- Functions: 90%
+- Lines: 90%
+- Statements: 90%
+
+View coverage report after running tests:
+```bash
+npm run test:coverage
+open coverage/lcov-report/index.html
+```
+
+## CI/CD Workflow
+
+### GitHub Actions Example
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm ci
+      - run: npm run type-check
+      - run: npm run lint
+      - run: npm run test:ci
+      - uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/lcov.info
+```
+
+### Pre-commit Workflow
+
+Recommended pre-commit hook (`.git/hooks/pre-commit`):
+```bash
+#!/bin/sh
+npm run type-check && npm run lint && npm run test:unit
+```
+
+### Development Workflow
+
+1. **Create a new branch**
+   ```bash
+   git checkout -b feature/your-feature
+   ```
+
+2. **Make changes with TDD**
+   ```bash
+   # Write tests first
+   npm run test:watch
+   # Implement feature
+   # Ensure tests pass
+   ```
+
+3. **Validate before commit**
+   ```bash
+   npm run validate
+   ```
+
+4. **Commit and push**
+   ```bash
+   git add .
+   git commit -m "feat: your feature description"
+   git push origin feature/your-feature
+   ```
+
+5. **Create Pull Request**
+   - Ensure CI passes
+   - Request code review
+   - Merge when approved
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT
+
+## Acknowledgments
+
+- [The Movie Database (TMDb)](https://www.themoviedb.org/) for movie data and streaming availability
+- [LangChain.js](https://js.langchain.com/) for agent framework
+- [OpenAI](https://openai.com/) for LLM capabilities

package/bin/movie-agent

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+// bin/movie-agent
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Parse command-line arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const input = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const nextArg = args[i + 1];
+
+    if (arg.startsWith('--') && nextArg && !nextArg.startsWith('--')) {
+      const key = arg.substring(2);
+      
+      switch (key) {
+        case 'mood':
+          input.mood = nextArg;
+          i++;
+          break;
+        
+        case 'platforms':
+          // Support comma-separated platforms
+          input.platforms = nextArg.split(',').map(p => p.trim());
+          i++;
+          break;
+        
+        case 'genre':
+          // Support comma-separated genres
+          const genres = nextArg.split(',').map(g => g.trim());
+          input.genre = genres.length === 1 ? genres[0] : genres;
+          i++;
+          break;
+        
+        case 'runtimeMax':
+          if (!input.runtime) input.runtime = {};
+          input.runtime.max = parseInt(nextArg, 10);
+          i++;
+          break;
+        
+        case 'runtimeMin':
+          if (!input.runtime) input.runtime = {};
+          input.runtime.min = parseInt(nextArg, 10);
+          i++;
+          break;
+        
+        case 'year':
+          input.releaseYear = parseInt(nextArg, 10);
+          i++;
+          break;
+        
+        case 'yearFrom':
+          if (typeof input.releaseYear !== 'object') {
+            input.releaseYear = {};
+          }
+          input.releaseYear.from = parseInt(nextArg, 10);
+          i++;
+          break;
+        
+        case 'yearTo':
+          if (typeof input.releaseYear !== 'object') {
+            input.releaseYear = {};
+          }
+          input.releaseYear.to = parseInt(nextArg, 10);
+          i++;
+          break;
+        
+        default:
+          console.error(`Unknown flag: ${arg}`);
+          printUsage();
+          process.exit(1);
+      }
+    } else if (arg === '--help' || arg === '-h') {
+      printUsage();
+      process.exit(0);
+    }
+  }
+
+  return input;
+}
+
+/**
+ * Print usage information
+ */
+function printUsage() {
+  console.log(`
+Usage: movie-agent [options]
+
+Options:
+  --mood <string>           User's mood (e.g., "happy", "excited", "thoughtful")
+  --platforms <list>        Comma-separated list of platforms (e.g., "Netflix,Prime Video")
+  --genre <list>            Genre or comma-separated genres (e.g., "Action" or "Action,Comedy")
+  --runtimeMax <number>     Maximum runtime in minutes
+  --runtimeMin <number>     Minimum runtime in minutes
+  --year <number>           Specific release year
+  --yearFrom <number>       Release year range start
+  --yearTo <number>         Release year range end
+  --help, -h                Show this help message
+
+Examples:
+  movie-agent --mood excited --platforms Netflix
+  movie-agent --genre Action,Thriller --runtimeMax 120
+  movie-agent --mood relaxed --yearFrom 2020 --yearTo 2023
+`);
+}
+
+/**
+ * Format recommendations for human-readable display
+ */
+function formatOutput(response) {
+  let output = '\n🎬 Movie Recommendations for You\n\n';
+
+  response.recommendations.forEach((movie, index) => {
+    output += `${index + 1}. **${movie.title}** (${movie.releaseYear}) • ${movie.runtime} min\n`;
+    output += `   Genres: ${movie.genres.join(', ')}\n\n`;
+    output += `   ${movie.description}\n\n`;
+    
+    // Format streaming platforms
+    const availablePlatforms = movie.streamingPlatforms
+      .filter(p => p.available)
+      .map(p => p.name);
+    
+    if (availablePlatforms.length > 0) {
+      output += `   📺 Available on: ${availablePlatforms.join(', ')}\n`;
+    } else {
+      output += `   📺 No streaming availability found\n`;
+    }
+    
+    output += `   ✨ Why: ${movie.matchReason}\n`;
+    
+    if (index < response.recommendations.length - 1) {
+      output += '\n───────────────────────────────────────────────────────────\n\n';
+    }
+  });
+
+  return output;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  try {
+    // Parse arguments first (for --help)
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+      printUsage();
+      process.exit(0);
+    }
+
+    // Check if .env file exists and load it
+    const envPath = path.resolve(__dirname, '../.env.development');
+    if (fs.existsSync(envPath)) {
+      require('dotenv').config({ path: envPath });
+    }
+
+    // Check for TMDb API key
+    if (!process.env.TMDB_API_KEY) {
+      console.error(`
+❌ Error: TMDb API key not found
+
+Please set the TMDB_API_KEY environment variable:
+  export TMDB_API_KEY=your_api_key_here
+
+Or create a .env.development file with:
+  TMDB_API_KEY=your_api_key_here
+`);
+      process.exit(1);
+    }
+
+    // Now it's safe to load the agent module
+    const { MovieAgent } = require('../dist/agent');
+
+    const input = parseArgs();
+
+    // Show help if no arguments provided
+    if (Object.keys(input).length === 0) {
+      printUsage();
+      process.exit(0);
+    }
+
+    console.log('\n🔍 Finding movie recommendations...\n');
+
+    const agent = new MovieAgent();
+    const response = await agent.getRecommendations(input);
+
+    const output = formatOutput(response);
+    console.log(output);
+
+  } catch (error) {
+    console.error('\n❌ Error:', error.message);
+    
+    if (error.message.includes('API') || error.message.includes('network')) {
+      console.error('\nPlease check your internet connection and TMDb API key.');
+    } else if (error.message.includes('Invalid') || error.message.includes('validation')) {
+      console.error('\nPlease check your input parameters and try again.');
+      console.error('Use --help for usage information.');
+    }
+    
+    process.exit(1);
+  }
+}
+
+main();