@tpmjs/feedback-themes 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,50 @@
+import * as ai from 'ai';
+
+/**
+ * Feedback Themes Extraction Tool for TPMJS
+ * Extracts themes and sentiment from customer feedback
+ *
+ * This is a proper AI SDK v6 tool that can be used with streamText()
+ * Uses jsonSchema() to avoid Zod 4 JSON Schema conversion issues with OpenAI
+ */
+interface Theme {
+    name: string;
+    frequency: number;
+    sentiment: 'positive' | 'negative' | 'neutral' | 'mixed';
+    sentimentScore: number;
+    examples: string[];
+}
+interface FeedbackThemes {
+    themes: Theme[];
+    overallSentiment: 'positive' | 'negative' | 'neutral' | 'mixed';
+    totalFeedback: number;
+    summary: {
+        positiveCount: number;
+        negativeCount: number;
+        neutralCount: number;
+    };
+}
+/**
+ * Input type for Feedback Themes Tool
+ */
+type FeedbackThemesInput = {
+    feedback: string[];
+};
+/**
+ * Feedback Themes Tool
+ * Extracts themes and sentiment from customer feedback
+ *
+ * This is a proper AI SDK v6 tool that can be used with streamText()
+ */
+declare const feedbackThemesTool: ai.Tool<FeedbackThemesInput, {
+    themes: Theme[];
+    overallSentiment: "positive" | "negative" | "neutral" | "mixed";
+    totalFeedback: number;
+    summary: {
+        positiveCount: number;
+        negativeCount: number;
+        neutralCount: number;
+    };
+}>;
+
+export { type FeedbackThemes, type Theme, feedbackThemesTool as default, feedbackThemesTool };

package/dist/index.js

@@ -0,0 +1,183 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+function analyzeSentiment(text) {
+  const lowerText = text.toLowerCase();
+  const positiveKeywords = [
+    "great",
+    "excellent",
+    "amazing",
+    "fantastic",
+    "love",
+    "perfect",
+    "wonderful",
+    "awesome",
+    "best",
+    "good",
+    "helpful",
+    "easy",
+    "fast",
+    "impressed",
+    "thank",
+    "appreciate",
+    "satisfied"
+  ];
+  const negativeKeywords = [
+    "bad",
+    "terrible",
+    "awful",
+    "horrible",
+    "worst",
+    "hate",
+    "disappointing",
+    "poor",
+    "slow",
+    "difficult",
+    "confusing",
+    "frustrated",
+    "bug",
+    "broken",
+    "issue",
+    "problem",
+    "error",
+    "crash",
+    "fail"
+  ];
+  let positiveScore = 0;
+  let negativeScore = 0;
+  for (const keyword of positiveKeywords) {
+    if (lowerText.includes(keyword)) {
+      positiveScore++;
+    }
+  }
+  for (const keyword of negativeKeywords) {
+    if (lowerText.includes(keyword)) {
+      negativeScore++;
+    }
+  }
+  const totalScore = positiveScore - negativeScore;
+  const normalizedScore = Math.max(-1, Math.min(1, totalScore / 3));
+  if (normalizedScore > 0.2) {
+    return { sentiment: "positive", score: normalizedScore };
+  }
+  if (normalizedScore < -0.2) {
+    return { sentiment: "negative", score: normalizedScore };
+  }
+  return { sentiment: "neutral", score: normalizedScore };
+}
+function extractThemes(feedbackList) {
+  const themeMap = /* @__PURE__ */ new Map();
+  const themeKeywords = [
+    { name: "Performance", keywords: ["slow", "fast", "speed", "performance", "lag", "quick"] },
+    { name: "User Interface", keywords: ["ui", "interface", "design", "layout", "look", "visual"] },
+    {
+      name: "Ease of Use",
+      keywords: ["easy", "difficult", "simple", "complex", "intuitive", "confusing"]
+    },
+    { name: "Features", keywords: ["feature", "functionality", "capability", "option", "tool"] },
+    {
+      name: "Support",
+      keywords: ["support", "help", "customer service", "response", "assistance"]
+    },
+    { name: "Bugs", keywords: ["bug", "error", "crash", "broken", "issue", "problem"] },
+    { name: "Documentation", keywords: ["documentation", "docs", "guide", "tutorial", "help"] },
+    { name: "Pricing", keywords: ["price", "cost", "expensive", "cheap", "value", "pricing"] },
+    { name: "Integration", keywords: ["integration", "integrate", "api", "connect", "compatible"] },
+    { name: "Mobile", keywords: ["mobile", "app", "ios", "android", "phone", "tablet"] }
+  ];
+  for (const feedback of feedbackList) {
+    const lowerFeedback = feedback.toLowerCase();
+    for (const { name, keywords } of themeKeywords) {
+      if (keywords.some((keyword) => lowerFeedback.includes(keyword))) {
+        if (!themeMap.has(name)) {
+          themeMap.set(name, []);
+        }
+        themeMap.get(name)?.push(feedback);
+      }
+    }
+  }
+  return themeMap;
+}
+function determineOverallSentiment(sentiments) {
+  const counts = {
+    positive: sentiments.filter((s) => s === "positive").length,
+    negative: sentiments.filter((s) => s === "negative").length,
+    neutral: sentiments.filter((s) => s === "neutral").length
+  };
+  const total = sentiments.length;
+  const positiveRatio = counts.positive / total;
+  const negativeRatio = counts.negative / total;
+  if (positiveRatio > 0.6) return "positive";
+  if (negativeRatio > 0.6) return "negative";
+  if (positiveRatio > 0.3 && negativeRatio > 0.3) return "mixed";
+  return "neutral";
+}
+var feedbackThemesTool = tool({
+  description: "Extracts themes and sentiment from customer feedback text. Identifies recurring themes, scores sentiment per theme, and provides frequency counts.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      feedback: {
+        type: "array",
+        description: "Array of customer feedback entries (comments, reviews, survey responses)",
+        items: {
+          type: "string",
+          description: "Individual feedback text"
+        }
+      }
+    },
+    required: ["feedback"],
+    additionalProperties: false
+  }),
+  async execute({ feedback }) {
+    if (!Array.isArray(feedback) || feedback.length === 0) {
+      throw new Error("feedback must be a non-empty array");
+    }
+    const validFeedback = feedback.filter((f) => f && f.trim().length > 0);
+    if (validFeedback.length === 0) {
+      throw new Error("No valid feedback entries provided");
+    }
+    const themeMap = extractThemes(validFeedback);
+    const themes = [];
+    for (const [themeName, examples] of themeMap.entries()) {
+      const sentiments = examples.map((ex) => analyzeSentiment(ex));
+      const avgScore = sentiments.reduce((sum, { score }) => sum + score, 0) / sentiments.length;
+      let themeSentiment = "neutral";
+      const posCount = sentiments.filter((s) => s.sentiment === "positive").length;
+      const negCount = sentiments.filter((s) => s.sentiment === "negative").length;
+      const ratio = posCount / sentiments.length;
+      if (ratio > 0.6) {
+        themeSentiment = "positive";
+      } else if (negCount / sentiments.length > 0.6) {
+        themeSentiment = "negative";
+      } else if (posCount > 0 && negCount > 0) {
+        themeSentiment = "mixed";
+      }
+      themes.push({
+        name: themeName,
+        frequency: examples.length,
+        sentiment: themeSentiment,
+        sentimentScore: Math.round(avgScore * 100) / 100,
+        examples: examples.slice(0, 3)
+        // Top 3 examples
+      });
+    }
+    themes.sort((a, b) => b.frequency - a.frequency);
+    const allSentiments = validFeedback.map((f) => analyzeSentiment(f).sentiment);
+    const overallSentiment = determineOverallSentiment(allSentiments);
+    const summary = {
+      positiveCount: allSentiments.filter((s) => s === "positive").length,
+      negativeCount: allSentiments.filter((s) => s === "negative").length,
+      neutralCount: allSentiments.filter((s) => s === "neutral").length
+    };
+    return {
+      themes,
+      overallSentiment,
+      totalFeedback: validFeedback.length,
+      summary
+    };
+  }
+});
+var index_default = feedbackThemesTool;
+
+export { index_default as default, feedbackThemesTool };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tpmjs/feedback-themes",
+  "version": "0.1.0",
+  "description": "Extracts themes and sentiment from customer feedback text",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "cx",
+    "feedback",
+    "sentiment",
+    "analysis",
+    "customer-success"
+  ],
+  "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/ajaxdavis/tpmjs.git",
+    "directory": "packages/tools/official/feedback-themes"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "cx",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "exportName": "feedbackThemesTool",
+        "description": "Extracts themes and sentiment from customer feedback text. Identifies recurring themes, scores sentiment per theme, and provides frequency counts.",
+        "parameters": [
+          {
+            "name": "feedback",
+            "type": "string[]",
+            "description": "Array of customer feedback entries",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "FeedbackThemes",
+          "description": "Themes with sentiment scores, frequency counts, and example feedback"
+        },
+        "aiAgent": {
+          "useCase": "Use this tool to analyze customer feedback, identify common themes, track sentiment trends, and prioritize product improvements based on customer voice.",
+          "limitations": "Sentiment analysis is keyword-based. For complex sentiment, consider using an AI model. Requires sufficient feedback volume for meaningful themes.",
+          "examples": [
+            "Analyze product reviews to identify improvement areas",
+            "Extract themes from NPS survey comments",
+            "Track sentiment trends across feedback channels"
+          ]
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}