@tpmjs/official-budget-variance 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,63 @@
+import * as ai from 'ai';
+
+/**
+ * Budget Variance Tool for TPMJS
+ * Calculates budget vs actual variance with percentage and trend analysis
+ */
+/**
+ * Budget line item
+ */
+interface BudgetItem {
+    category: string;
+    amount: number;
+    period?: string;
+}
+/**
+ * Actual spending line item
+ */
+interface ActualItem {
+    category: string;
+    amount: number;
+    period?: string;
+}
+/**
+ * Variance analysis for a single category
+ */
+interface VarianceItem {
+    category: string;
+    budget: number;
+    actual: number;
+    variance: number;
+    percentageVariance: number;
+    trend: 'favorable' | 'unfavorable' | 'neutral';
+    status: 'over' | 'under' | 'on-track';
+}
+/**
+ * Input interface for budget variance calculation
+ */
+interface BudgetVarianceInput {
+    budget: BudgetItem[];
+    actual: ActualItem[];
+}
+/**
+ * Output interface for budget variance analysis
+ */
+interface BudgetVarianceResult {
+    variances: VarianceItem[];
+    summary: {
+        totalBudget: number;
+        totalActual: number;
+        totalVariance: number;
+        overallPercentageVariance: number;
+        categoriesOverBudget: number;
+        categoriesUnderBudget: number;
+        categoriesOnTrack: number;
+    };
+}
+/**
+ * Budget Variance Tool
+ * Calculates variance between budgeted and actual amounts with trend analysis
+ */
+declare const budgetVarianceTool: ai.Tool<BudgetVarianceInput, BudgetVarianceResult>;
+
+export { type BudgetVarianceResult, budgetVarianceTool, budgetVarianceTool as default };

package/dist/index.js

@@ -0,0 +1,142 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var budgetVarianceTool = tool({
+  description: "Calculates budget vs actual variance with percentage and trend analysis. Identifies favorable and unfavorable trends, and provides summary statistics.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      budget: {
+        type: "array",
+        description: "Budget line items with category and amount",
+        items: {
+          type: "object",
+          properties: {
+            category: {
+              type: "string",
+              description: "Budget category name"
+            },
+            amount: {
+              type: "number",
+              description: "Budgeted amount"
+            },
+            period: {
+              type: "string",
+              description: 'Optional budget period (e.g., "2024-Q1")'
+            }
+          },
+          required: ["category", "amount"]
+        }
+      },
+      actual: {
+        type: "array",
+        description: "Actual spending line items with category and amount",
+        items: {
+          type: "object",
+          properties: {
+            category: {
+              type: "string",
+              description: "Spending category name"
+            },
+            amount: {
+              type: "number",
+              description: "Actual amount spent"
+            },
+            period: {
+              type: "string",
+              description: 'Optional spending period (e.g., "2024-Q1")'
+            }
+          },
+          required: ["category", "amount"]
+        }
+      }
+    },
+    required: ["budget", "actual"],
+    additionalProperties: false
+  }),
+  execute: async ({ budget, actual }) => {
+    if (!Array.isArray(budget) || budget.length === 0) {
+      throw new Error("Budget must be a non-empty array");
+    }
+    if (!Array.isArray(actual) || actual.length === 0) {
+      throw new Error("Actual must be a non-empty array");
+    }
+    const budgetMap = /* @__PURE__ */ new Map();
+    const actualMap = /* @__PURE__ */ new Map();
+    for (const item of budget) {
+      if (!item.category || typeof item.amount !== "number") {
+        throw new Error("Each budget item must have a category and amount");
+      }
+      const current = budgetMap.get(item.category) || 0;
+      budgetMap.set(item.category, current + item.amount);
+    }
+    for (const item of actual) {
+      if (!item.category || typeof item.amount !== "number") {
+        throw new Error("Each actual item must have a category and amount");
+      }
+      const current = actualMap.get(item.category) || 0;
+      actualMap.set(item.category, current + item.amount);
+    }
+    const allCategories = /* @__PURE__ */ new Set([...budgetMap.keys(), ...actualMap.keys()]);
+    const variances = [];
+    let totalBudget = 0;
+    let totalActual = 0;
+    let categoriesOverBudget = 0;
+    let categoriesUnderBudget = 0;
+    let categoriesOnTrack = 0;
+    for (const category of allCategories) {
+      const budgetAmount = budgetMap.get(category) || 0;
+      const actualAmount = actualMap.get(category) || 0;
+      const variance = actualAmount - budgetAmount;
+      const percentageVariance = budgetAmount !== 0 ? variance / budgetAmount * 100 : actualAmount !== 0 ? 100 : 0;
+      let trend;
+      if (Math.abs(percentageVariance) < 5) {
+        trend = "neutral";
+      } else if (variance < 0) {
+        trend = "favorable";
+      } else {
+        trend = "unfavorable";
+      }
+      let status;
+      if (Math.abs(percentageVariance) < 5) {
+        status = "on-track";
+        categoriesOnTrack++;
+      } else if (variance > 0) {
+        status = "over";
+        categoriesOverBudget++;
+      } else {
+        status = "under";
+        categoriesUnderBudget++;
+      }
+      variances.push({
+        category,
+        budget: budgetAmount,
+        actual: actualAmount,
+        variance,
+        percentageVariance: Math.round(percentageVariance * 100) / 100,
+        trend,
+        status
+      });
+      totalBudget += budgetAmount;
+      totalActual += actualAmount;
+    }
+    variances.sort((a, b) => Math.abs(b.variance) - Math.abs(a.variance));
+    const totalVariance = totalActual - totalBudget;
+    const overallPercentageVariance = totalBudget !== 0 ? totalVariance / totalBudget * 100 : totalActual !== 0 ? 100 : 0;
+    return {
+      variances,
+      summary: {
+        totalBudget,
+        totalActual,
+        totalVariance,
+        overallPercentageVariance: Math.round(overallPercentageVariance * 100) / 100,
+        categoriesOverBudget,
+        categoriesUnderBudget,
+        categoriesOnTrack
+      }
+    };
+  }
+});
+var index_default = budgetVarianceTool;
+
+export { budgetVarianceTool, index_default as default };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@tpmjs/official-budget-variance",
+  "version": "0.1.0",
+  "description": "Calculates budget vs actual variance with percentage and trend analysis",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "finance",
+    "budget",
+    "variance",
+    "analysis"
+  ],
+  "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/budget-variance"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "finance",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "budgetVarianceTool",
+        "description": "Calculates budget vs actual variance with percentage and trend analysis",
+        "parameters": [
+          {
+            "name": "budget",
+            "type": "array",
+            "description": "Budget line items with category and amount",
+            "required": true
+          },
+          {
+            "name": "actual",
+            "type": "array",
+            "description": "Actual spending line items with category and amount",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "BudgetVarianceResult",
+          "description": "Variance analysis with trends and summary statistics"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}