@tpmjs/official-ratio-analysis 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,135 @@
+import * as ai from 'ai';
+
+/**
+ * Ratio Analysis Tool for TPMJS
+ * Calculates key financial ratios from balance sheet and income statement data
+ */
+/**
+ * Financial statement data
+ */
+interface FinancialData {
+    currentAssets?: number;
+    totalAssets?: number;
+    currentLiabilities?: number;
+    totalLiabilities?: number;
+    totalEquity?: number;
+    cash?: number;
+    inventory?: number;
+    accountsReceivable?: number;
+    accountsPayable?: number;
+    longTermDebt?: number;
+    revenue?: number;
+    grossProfit?: number;
+    operatingIncome?: number;
+    netIncome?: number;
+    interestExpense?: number;
+    costOfGoodsSold?: number;
+}
+/**
+ * Liquidity ratios
+ */
+interface LiquidityRatios {
+    currentRatio?: {
+        value: number;
+        interpretation: string;
+    };
+    quickRatio?: {
+        value: number;
+        interpretation: string;
+    };
+    cashRatio?: {
+        value: number;
+        interpretation: string;
+    };
+}
+/**
+ * Profitability ratios
+ */
+interface ProfitabilityRatios {
+    grossProfitMargin?: {
+        value: number;
+        interpretation: string;
+    };
+    operatingMargin?: {
+        value: number;
+        interpretation: string;
+    };
+    netProfitMargin?: {
+        value: number;
+        interpretation: string;
+    };
+    returnOnAssets?: {
+        value: number;
+        interpretation: string;
+    };
+    returnOnEquity?: {
+        value: number;
+        interpretation: string;
+    };
+}
+/**
+ * Leverage ratios
+ */
+interface LeverageRatios {
+    debtToEquity?: {
+        value: number;
+        interpretation: string;
+    };
+    debtToAssets?: {
+        value: number;
+        interpretation: string;
+    };
+    equityMultiplier?: {
+        value: number;
+        interpretation: string;
+    };
+    interestCoverage?: {
+        value: number;
+        interpretation: string;
+    };
+}
+/**
+ * Efficiency ratios
+ */
+interface EfficiencyRatios {
+    assetTurnover?: {
+        value: number;
+        interpretation: string;
+    };
+    inventoryTurnover?: {
+        value: number;
+        interpretation: string;
+    };
+    receivablesTurnover?: {
+        value: number;
+        interpretation: string;
+    };
+}
+/**
+ * Input interface for ratio analysis
+ */
+interface RatioAnalysisInput {
+    financials: FinancialData;
+}
+/**
+ * Output interface for financial ratios
+ */
+interface FinancialRatios {
+    liquidity: LiquidityRatios;
+    profitability: ProfitabilityRatios;
+    leverage: LeverageRatios;
+    efficiency: EfficiencyRatios;
+    summary: {
+        totalRatiosCalculated: number;
+        overallHealth: 'strong' | 'moderate' | 'weak' | 'insufficient-data';
+        keyStrengths: string[];
+        keyWeaknesses: string[];
+    };
+}
+/**
+ * Ratio Analysis Tool
+ * Calculates financial ratios and provides interpretation
+ */
+declare const ratioAnalysisTool: ai.Tool<RatioAnalysisInput, FinancialRatios>;
+
+export { type FinancialRatios, ratioAnalysisTool as default, ratioAnalysisTool };

package/dist/index.js

@@ -0,0 +1,208 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var ratioAnalysisTool = tool({
+  description: "Calculates key financial ratios from balance sheet and income statement data. Includes liquidity, profitability, leverage, and efficiency ratios with interpretations.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      financials: {
+        type: "object",
+        description: "Financial statement data",
+        properties: {
+          currentAssets: { type: "number", description: "Current assets" },
+          totalAssets: { type: "number", description: "Total assets" },
+          currentLiabilities: { type: "number", description: "Current liabilities" },
+          totalLiabilities: { type: "number", description: "Total liabilities" },
+          totalEquity: { type: "number", description: "Total equity" },
+          cash: { type: "number", description: "Cash and cash equivalents" },
+          inventory: { type: "number", description: "Inventory" },
+          accountsReceivable: { type: "number", description: "Accounts receivable" },
+          accountsPayable: { type: "number", description: "Accounts payable" },
+          longTermDebt: { type: "number", description: "Long-term debt" },
+          revenue: { type: "number", description: "Total revenue" },
+          grossProfit: { type: "number", description: "Gross profit" },
+          operatingIncome: { type: "number", description: "Operating income (EBIT)" },
+          netIncome: { type: "number", description: "Net income" },
+          interestExpense: { type: "number", description: "Interest expense" },
+          costOfGoodsSold: { type: "number", description: "Cost of goods sold" }
+        }
+      }
+    },
+    required: ["financials"],
+    additionalProperties: false
+  }),
+  execute: async ({ financials }) => {
+    if (!financials || typeof financials !== "object") {
+      throw new Error("Financials must be a valid object");
+    }
+    const liquidity = {};
+    const profitability = {};
+    const leverage = {};
+    const efficiency = {};
+    const keyStrengths = [];
+    const keyWeaknesses = [];
+    let totalRatiosCalculated = 0;
+    if (financials.currentAssets && financials.currentLiabilities) {
+      const value = Math.round(financials.currentAssets / financials.currentLiabilities * 100) / 100;
+      liquidity.currentRatio = {
+        value,
+        interpretation: value >= 2 ? "Strong - Company can easily meet short-term obligations" : value >= 1 ? "Adequate - Company can meet short-term obligations" : "Weak - Company may struggle with short-term obligations"
+      };
+      if (value >= 2) keyStrengths.push("Strong liquidity position");
+      if (value < 1) keyWeaknesses.push("Insufficient liquidity");
+      totalRatiosCalculated++;
+    }
+    if (financials.currentAssets && financials.inventory !== void 0 && financials.currentLiabilities) {
+      const quickAssets = financials.currentAssets - financials.inventory;
+      const value = Math.round(quickAssets / financials.currentLiabilities * 100) / 100;
+      liquidity.quickRatio = {
+        value,
+        interpretation: value >= 1 ? "Strong - Can meet obligations without selling inventory" : value >= 0.5 ? "Moderate - Some reliance on inventory sales" : "Weak - Heavy reliance on inventory to meet obligations"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.cash && financials.currentLiabilities) {
+      const value = Math.round(financials.cash / financials.currentLiabilities * 100) / 100;
+      liquidity.cashRatio = {
+        value,
+        interpretation: value >= 0.5 ? "Strong - Substantial cash reserves" : value >= 0.2 ? "Adequate - Reasonable cash position" : "Low - Limited cash reserves"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.grossProfit && financials.revenue) {
+      const value = Math.round(financials.grossProfit / financials.revenue * 1e4) / 100;
+      profitability.grossProfitMargin = {
+        value,
+        interpretation: value >= 40 ? "Excellent - Strong pricing power and cost control" : value >= 20 ? "Good - Healthy profit margins" : "Low - Tight margins or pricing pressure"
+      };
+      if (value >= 40) keyStrengths.push("Excellent gross margins");
+      if (value < 20) keyWeaknesses.push("Low gross profit margins");
+      totalRatiosCalculated++;
+    }
+    if (financials.operatingIncome && financials.revenue) {
+      const value = Math.round(financials.operatingIncome / financials.revenue * 1e4) / 100;
+      profitability.operatingMargin = {
+        value,
+        interpretation: value >= 20 ? "Excellent - Very efficient operations" : value >= 10 ? "Good - Solid operational efficiency" : value >= 0 ? "Moderate - Room for operational improvement" : "Negative - Operating losses"
+      };
+      if (value >= 20) keyStrengths.push("High operational efficiency");
+      if (value < 0) keyWeaknesses.push("Operating losses");
+      totalRatiosCalculated++;
+    }
+    if (financials.netIncome && financials.revenue) {
+      const value = Math.round(financials.netIncome / financials.revenue * 1e4) / 100;
+      profitability.netProfitMargin = {
+        value,
+        interpretation: value >= 15 ? "Excellent - Strong bottom-line profitability" : value >= 5 ? "Good - Healthy net profitability" : value >= 0 ? "Moderate - Thin profit margins" : "Negative - Net losses"
+      };
+      if (value >= 15) keyStrengths.push("Strong net profitability");
+      if (value < 0) keyWeaknesses.push("Net losses");
+      totalRatiosCalculated++;
+    }
+    if (financials.netIncome && financials.totalAssets) {
+      const value = Math.round(financials.netIncome / financials.totalAssets * 1e4) / 100;
+      profitability.returnOnAssets = {
+        value,
+        interpretation: value >= 10 ? "Excellent - Efficient use of assets" : value >= 5 ? "Good - Adequate asset utilization" : value >= 0 ? "Moderate - Low asset efficiency" : "Negative - Assets not generating profit"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.netIncome && financials.totalEquity) {
+      const value = Math.round(financials.netIncome / financials.totalEquity * 1e4) / 100;
+      profitability.returnOnEquity = {
+        value,
+        interpretation: value >= 20 ? "Excellent - Strong returns for shareholders" : value >= 10 ? "Good - Solid shareholder returns" : value >= 0 ? "Moderate - Low shareholder returns" : "Negative - Destroying shareholder value"
+      };
+      if (value >= 20) keyStrengths.push("Excellent shareholder returns");
+      if (value < 0) keyWeaknesses.push("Negative shareholder returns");
+      totalRatiosCalculated++;
+    }
+    if (financials.totalLiabilities && financials.totalEquity) {
+      const value = Math.round(financials.totalLiabilities / financials.totalEquity * 100) / 100;
+      leverage.debtToEquity = {
+        value,
+        interpretation: value <= 1 ? "Low - Conservative capital structure" : value <= 2 ? "Moderate - Balanced leverage" : "High - Aggressive leverage, higher financial risk"
+      };
+      if (value <= 1) keyStrengths.push("Conservative leverage");
+      if (value > 2) keyWeaknesses.push("High financial leverage");
+      totalRatiosCalculated++;
+    }
+    if (financials.totalLiabilities && financials.totalAssets) {
+      const value = Math.round(financials.totalLiabilities / financials.totalAssets * 1e4) / 100;
+      leverage.debtToAssets = {
+        value,
+        interpretation: value <= 40 ? "Low - Most assets financed by equity" : value <= 60 ? "Moderate - Balanced financing mix" : "High - Heavy reliance on debt financing"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.totalAssets && financials.totalEquity) {
+      const value = Math.round(financials.totalAssets / financials.totalEquity * 100) / 100;
+      leverage.equityMultiplier = {
+        value,
+        interpretation: value <= 2 ? "Low - Conservative leverage" : value <= 3 ? "Moderate - Average leverage" : "High - Aggressive use of leverage"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.operatingIncome && financials.interestExpense) {
+      const value = Math.round(financials.operatingIncome / financials.interestExpense * 100) / 100;
+      leverage.interestCoverage = {
+        value,
+        interpretation: value >= 5 ? "Strong - Easily covers interest obligations" : value >= 2.5 ? "Adequate - Can comfortably cover interest" : value >= 1 ? "Weak - Barely covers interest payments" : "Critical - Cannot cover interest from operations"
+      };
+      if (value < 1.5) keyWeaknesses.push("Low interest coverage");
+      totalRatiosCalculated++;
+    }
+    if (financials.revenue && financials.totalAssets) {
+      const value = Math.round(financials.revenue / financials.totalAssets * 100) / 100;
+      efficiency.assetTurnover = {
+        value,
+        interpretation: value >= 2 ? "High - Efficient use of assets to generate revenue" : value >= 1 ? "Moderate - Average asset utilization" : "Low - Assets underutilized"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.costOfGoodsSold && financials.inventory) {
+      const value = Math.round(financials.costOfGoodsSold / financials.inventory * 100) / 100;
+      efficiency.inventoryTurnover = {
+        value,
+        interpretation: value >= 8 ? "High - Fast-moving inventory, efficient management" : value >= 4 ? "Moderate - Reasonable inventory turnover" : "Low - Slow-moving inventory, may indicate obsolescence"
+      };
+      totalRatiosCalculated++;
+    }
+    if (financials.revenue && financials.accountsReceivable) {
+      const value = Math.round(financials.revenue / financials.accountsReceivable * 100) / 100;
+      efficiency.receivablesTurnover = {
+        value,
+        interpretation: value >= 10 ? "High - Efficient collections" : value >= 6 ? "Moderate - Average collection efficiency" : "Low - Slow collections, may indicate credit issues"
+      };
+      totalRatiosCalculated++;
+    }
+    let overallHealth = "insufficient-data";
+    if (totalRatiosCalculated >= 5) {
+      const strengthScore = keyStrengths.length;
+      const weaknessScore = keyWeaknesses.length;
+      if (strengthScore > weaknessScore && strengthScore >= 2) {
+        overallHealth = "strong";
+      } else if (weaknessScore > strengthScore && weaknessScore >= 2) {
+        overallHealth = "weak";
+      } else {
+        overallHealth = "moderate";
+      }
+    }
+    return {
+      liquidity,
+      profitability,
+      leverage,
+      efficiency,
+      summary: {
+        totalRatiosCalculated,
+        overallHealth,
+        keyStrengths,
+        keyWeaknesses
+      }
+    };
+  }
+});
+var index_default = ratioAnalysisTool;
+
+export { index_default as default, ratioAnalysisTool };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@tpmjs/official-ratio-analysis",
+  "version": "0.1.0",
+  "description": "Calculates key financial ratios from balance sheet and income statement data",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "finance",
+    "ratios",
+    "analysis",
+    "financial-statements"
+  ],
+  "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/ratio-analysis"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "finance",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "ratioAnalysisTool",
+        "description": "Calculates key financial ratios from balance sheet and income statement data",
+        "parameters": [
+          {
+            "name": "financials",
+            "type": "object",
+            "description": "Financial statement data including balance sheet and income statement",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "FinancialRatios",
+          "description": "Calculated ratios with interpretations across liquidity, profitability, leverage, and efficiency"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}