@tpmjs/official-survey-analyze 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 TPMJS
+
+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/dist/index.d.ts

@@ -0,0 +1,67 @@
+import * as ai from 'ai';
+
+/**
+ * Survey Analyze Tool for TPMJS
+ * Analyzes employee survey responses to extract themes, sentiment, and action items
+ */
+/**
+ * Sentiment score and analysis
+ */
+interface SentimentScore {
+    overall: number;
+    label: 'negative' | 'neutral' | 'positive';
+    confidence: number;
+}
+/**
+ * Theme extracted from survey responses
+ */
+interface Theme {
+    name: string;
+    description: string;
+    frequency: number;
+    sentiment: number;
+    examples: string[];
+}
+/**
+ * Action item suggested based on survey
+ */
+interface ActionItem {
+    priority: 'high' | 'medium' | 'low';
+    category: string;
+    recommendation: string;
+    rationale: string;
+}
+/**
+ * Per-question analysis
+ */
+interface QuestionAnalysis {
+    question: string;
+    sentiment: SentimentScore;
+    topThemes: string[];
+    responseCount: number;
+}
+/**
+ * Input interface for survey analysis
+ */
+interface SurveyAnalyzeInput {
+    responses: string[];
+    questions: string[];
+}
+/**
+ * Survey analysis output
+ */
+interface SurveyAnalysis {
+    overallSentiment: SentimentScore;
+    themes: Theme[];
+    actionItems: ActionItem[];
+    questionAnalysis: QuestionAnalysis[];
+    summary: string;
+    participationRate?: number;
+}
+/**
+ * Survey Analyze Tool
+ * Analyzes employee survey responses to extract themes, sentiment, and action items
+ */
+declare const surveyAnalyzeTool: ai.Tool<SurveyAnalyzeInput, SurveyAnalysis>;
+
+export { type SurveyAnalysis, surveyAnalyzeTool as default, surveyAnalyzeTool };

package/dist/index.js

@@ -0,0 +1,194 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var surveyAnalyzeTool = tool({
+  description: "Analyzes employee survey responses to extract key themes, assess sentiment (overall and per-question), and suggest actionable recommendations. Processes both structured and open-ended survey responses to provide comprehensive insights.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      responses: {
+        type: "array",
+        items: { type: "string" },
+        description: "Array of survey responses from employees",
+        minItems: 1
+      },
+      questions: {
+        type: "array",
+        items: { type: "string" },
+        description: "Array of survey questions that were asked",
+        minItems: 1
+      }
+    },
+    required: ["responses", "questions"],
+    additionalProperties: false
+  }),
+  execute: async ({ responses, questions }) => {
+    if (!Array.isArray(responses) || responses.length === 0) {
+      throw new Error("Responses must be a non-empty array");
+    }
+    if (!Array.isArray(questions) || questions.length === 0) {
+      throw new Error("Questions must be a non-empty array");
+    }
+    if (responses.some((r) => typeof r !== "string")) {
+      throw new Error("All responses must be strings");
+    }
+    if (questions.some((q) => typeof q !== "string")) {
+      throw new Error("All questions must be strings");
+    }
+    try {
+      const overallSentiment = analyzeSentiment(responses);
+      const themes = extractThemes(responses);
+      const actionItems = generateActionItems(themes, overallSentiment);
+      const questionAnalysis = questions.map((question, idx) => {
+        const questionResponses = responses.filter((_, i) => i % questions.length === idx);
+        const sentiment = analyzeSentiment(questionResponses);
+        const topThemes = extractThemes(questionResponses).slice(0, 3).map((t) => t.name);
+        return {
+          question,
+          sentiment,
+          topThemes,
+          responseCount: questionResponses.length
+        };
+      });
+      const summary = generateSummary(overallSentiment, themes, actionItems);
+      return {
+        overallSentiment,
+        themes,
+        actionItems,
+        questionAnalysis,
+        summary,
+        participationRate: void 0
+        // Requires additional context
+      };
+    } catch (error) {
+      throw new Error(
+        `Failed to analyze survey: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+});
+function analyzeSentiment(texts) {
+  const positiveWords = [
+    "good",
+    "great",
+    "excellent",
+    "love",
+    "amazing",
+    "fantastic",
+    "happy",
+    "satisfied",
+    "appreciate"
+  ];
+  const negativeWords = [
+    "bad",
+    "poor",
+    "terrible",
+    "hate",
+    "awful",
+    "disappointed",
+    "frustrated",
+    "unhappy",
+    "dissatisfied"
+  ];
+  let positiveCount = 0;
+  let negativeCount = 0;
+  let totalWords = 0;
+  for (const text of texts) {
+    const words = text.toLowerCase().split(/\s+/);
+    totalWords += words.length;
+    for (const word of words) {
+      if (positiveWords.some((pw) => word.includes(pw))) positiveCount++;
+      if (negativeWords.some((nw) => word.includes(nw))) negativeCount++;
+    }
+  }
+  const score = (positiveCount - negativeCount) / Math.max(totalWords / 10, 1);
+  const normalizedScore = Math.max(-1, Math.min(1, score));
+  let label;
+  if (normalizedScore < -0.2) label = "negative";
+  else if (normalizedScore > 0.2) label = "positive";
+  else label = "neutral";
+  const confidence = Math.min(1, Math.abs(normalizedScore) + 0.3);
+  return {
+    overall: normalizedScore,
+    label,
+    confidence
+  };
+}
+function extractThemes(responses) {
+  const themeKeywords = {
+    "Work-Life Balance": ["balance", "hours", "overtime", "flexible", "remote", "workload"],
+    Compensation: ["salary", "pay", "compensation", "bonus", "benefits", "equity"],
+    Management: ["manager", "leadership", "supervisor", "boss", "management"],
+    "Career Growth": ["growth", "promotion", "career", "development", "learning", "training"],
+    Culture: ["culture", "environment", "team", "collaboration", "values", "diversity"],
+    "Tools & Resources": ["tools", "resources", "equipment", "software", "technology"],
+    Communication: ["communication", "transparency", "feedback", "updates", "meetings"]
+  };
+  const themes = [];
+  for (const [themeName, keywords] of Object.entries(themeKeywords)) {
+    let frequency = 0;
+    const examples = [];
+    let sentimentSum = 0;
+    for (const response of responses) {
+      const lowerResponse = response.toLowerCase();
+      const hasKeyword = keywords.some((kw) => lowerResponse.includes(kw));
+      if (hasKeyword) {
+        frequency++;
+        if (examples.length < 3) {
+          examples.push(response.substring(0, 100) + (response.length > 100 ? "..." : ""));
+        }
+        const responseSentiment = analyzeSentiment([response]);
+        sentimentSum += responseSentiment.overall;
+      }
+    }
+    if (frequency > 0) {
+      themes.push({
+        name: themeName,
+        description: `Theme related to ${themeName.toLowerCase()}`,
+        frequency,
+        sentiment: sentimentSum / frequency,
+        examples
+      });
+    }
+  }
+  return themes.sort((a, b) => b.frequency - a.frequency);
+}
+function generateActionItems(themes, sentiment) {
+  const actionItems = [];
+  for (const theme of themes) {
+    if (theme.sentiment < -0.2 && theme.frequency >= 3) {
+      actionItems.push({
+        priority: theme.frequency > 10 ? "high" : theme.frequency > 5 ? "medium" : "low",
+        category: theme.name,
+        recommendation: `Address concerns related to ${theme.name.toLowerCase()}`,
+        rationale: `${theme.frequency} responses mentioned ${theme.name.toLowerCase()} with negative sentiment (${theme.sentiment.toFixed(2)})`
+      });
+    }
+  }
+  if (sentiment.overall < -0.3) {
+    actionItems.unshift({
+      priority: "high",
+      category: "Overall Satisfaction",
+      recommendation: "Conduct immediate follow-up to address widespread dissatisfaction",
+      rationale: `Overall sentiment is negative (${sentiment.overall.toFixed(2)})`
+    });
+  }
+  if (actionItems.length === 0) {
+    actionItems.push({
+      priority: "medium",
+      category: "Continuous Improvement",
+      recommendation: "Continue monitoring employee satisfaction trends",
+      rationale: "No major issues identified, maintain current practices"
+    });
+  }
+  return actionItems;
+}
+function generateSummary(sentiment, themes, actionItems) {
+  const sentimentDesc = sentiment.label === "positive" ? "positive" : sentiment.label === "negative" ? "negative" : "neutral";
+  const topThemes = themes.slice(0, 3).map((t) => t.name);
+  const highPriorityActions = actionItems.filter((a) => a.priority === "high").length;
+  return `Survey analysis reveals ${sentimentDesc} overall sentiment (${sentiment.overall.toFixed(2)}). Top themes: ${topThemes.join(", ")}. ${highPriorityActions} high-priority action items identified.`;
+}
+var index_default = surveyAnalyzeTool;
+
+export { index_default as default, surveyAnalyzeTool };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@tpmjs/official-survey-analyze",
+  "version": "0.1.0",
+  "description": "Analyzes employee survey responses to extract themes, sentiment, and action items",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "hr",
+    "survey",
+    "analysis",
+    "sentiment"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3",
+    "@tpmjs/tsconfig": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/tpmjs.git",
+    "directory": "packages/tools/official/survey-analyze"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "hr",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "surveyAnalyzeTool",
+        "description": "Analyzes employee survey responses to extract themes, sentiment, and action items",
+        "parameters": [
+          {
+            "name": "responses",
+            "type": "string[]",
+            "description": "Survey responses from employees",
+            "required": true
+          },
+          {
+            "name": "questions",
+            "type": "string[]",
+            "description": "Survey questions asked",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "SurveyAnalysis",
+          "description": "Survey analysis with themes, sentiment, and action items"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}