@tpmjs/tools-slo-draft 0.2.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/README.md

@@ -0,0 +1,87 @@
+# @tpmjs/tools-slo-draft
+
+Draft Service Level Objective (SLO) definitions for services with comprehensive documentation, error budgets, and alerting strategies.
+
+## Installation
+
+```bash
+npm install @tpmjs/tools-slo-draft
+```
+
+## Usage
+
+```typescript
+import { sloDraftTool } from '@tpmjs/tools-slo-draft';
+
+// Use with Vercel AI SDK
+const result = await sloDraftTool.execute({
+  serviceName: 'Payment API',
+  metrics: [
+    {
+      name: 'Availability',
+      target: 99.9,
+      window: '30d'
+    },
+    {
+      name: 'API Latency P99',
+      target: 95.0,
+      window: 'rolling 7 days'
+    },
+    {
+      name: 'Error Rate',
+      target: 99.5,
+      window: '30d'
+    }
+  ]
+});
+
+console.log(result.slo); // Markdown formatted SLO document
+console.log(result.summary); // Brief summary
+console.log(result.metrics); // Processed metrics with severity
+```
+
+## Input
+
+- `serviceName` (string, required): Name of the service
+- `metrics` (array, required): Array of metric objects with:
+  - `name` (string): Metric name (e.g., "Availability", "Latency P99")
+  - `target` (number): Target percentage (0-100)
+  - `window` (string): Time window (e.g., "30d", "7 days", "rolling 30 days")
+
+## Output
+
+Returns an object with:
+
+- `slo` (string): Comprehensive SLO document in markdown format
+- `metrics` (array): Processed metrics with additional metadata:
+  - Original name, target, window
+  - `windowType`: 'rolling' or 'calendar'
+  - `severity`: 'critical' (≥99.9%), 'high' (≥99%), or 'medium' (<99%)
+- `summary` (string): Brief summary of the SLO
+- `metadata` (object):
+  - `serviceName`: Service name
+  - `createdAt`: ISO timestamp
+  - `totalMetrics`: Total number of metrics
+  - `criticalMetrics`: Number of critical severity metrics
+
+## Features
+
+- **Automatic Severity Classification**: Metrics are classified as critical, high, or medium based on targets
+- **Error Budget Calculation**: Calculates allowed downtime for each metric
+- **Alerting Strategy**: Provides burn rate-based alerting recommendations
+- **Window Type Detection**: Automatically detects rolling vs calendar windows
+- **Comprehensive Documentation**: Generates full SLO document with monitoring and review processes
+
+## Example Output
+
+The tool generates a markdown document including:
+
+- SLO definitions with targets and allowed downtime
+- Error budget policies
+- Alerting strategies based on severity
+- Review processes and schedules
+- Links to related documentation
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import * as ai from 'ai';
+
+/**
+ * SLO Draft Tool for TPMJS
+ * Drafts Service Level Objective (SLO) definitions for services with metrics, targets, and time windows.
+ */
+/**
+ * Input metric definition
+ */
+interface MetricInput {
+    name: string;
+    target: number;
+    window: string;
+}
+/**
+ * Processed metric with additional metadata
+ */
+interface ProcessedMetric {
+    name: string;
+    target: number;
+    window: string;
+    windowType: 'rolling' | 'calendar';
+    severity: 'critical' | 'high' | 'medium';
+}
+/**
+ * Output interface for SLO draft
+ */
+interface SLODraft {
+    slo: string;
+    metrics: ProcessedMetric[];
+    summary: string;
+    metadata: {
+        serviceName: string;
+        createdAt: string;
+        totalMetrics: number;
+        criticalMetrics: number;
+    };
+}
+type SLODraftInput = {
+    serviceName: string;
+    metrics: MetricInput[];
+};
+/**
+ * SLO Draft Tool
+ * Generates a comprehensive SLO document for a service
+ */
+declare const sloDraftTool: ai.Tool<SLODraftInput, SLODraft>;
+
+export { type MetricInput, type ProcessedMetric, type SLODraft, sloDraftTool as default, sloDraftTool };

package/dist/index.js

@@ -0,0 +1,264 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+function determineWindowType(window) {
+  const lowerWindow = window.toLowerCase();
+  if (lowerWindow.includes("calendar") || lowerWindow.includes("month")) {
+    return "calendar";
+  }
+  return "rolling";
+}
+function determineSeverity(target) {
+  if (target >= 99.9) return "critical";
+  if (target >= 99) return "high";
+  return "medium";
+}
+function calculateAllowedDowntime(target, window) {
+  const lowerWindow = window.toLowerCase();
+  let totalMinutes = 0;
+  if (lowerWindow.includes("30d") || lowerWindow.includes("30 day")) {
+    totalMinutes = 30 * 24 * 60;
+  } else if (lowerWindow.includes("7d") || lowerWindow.includes("7 day")) {
+    totalMinutes = 7 * 24 * 60;
+  } else if (lowerWindow.includes("1d") || lowerWindow.includes("1 day")) {
+    totalMinutes = 24 * 60;
+  } else if (lowerWindow.includes("month")) {
+    totalMinutes = 30 * 24 * 60;
+  } else {
+    totalMinutes = 30 * 24 * 60;
+  }
+  const uptimePercentage = target / 100;
+  const allowedDowntimeMinutes = totalMinutes * (1 - uptimePercentage);
+  const hours = Math.floor(allowedDowntimeMinutes / 60);
+  const minutes = Math.floor(allowedDowntimeMinutes % 60);
+  if (hours >= 24) {
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+    return `${days}d ${remainingHours}h ${minutes}m`;
+  }
+  if (hours > 0) {
+    return `${hours}h ${minutes}m`;
+  }
+  return `${minutes}m`;
+}
+function generateSLOMarkdown(serviceName, metrics) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  let markdown = `# Service Level Objectives (SLO)
+
+`;
+  markdown += `**Service:** ${serviceName}
+`;
+  markdown += `**Date:** ${timestamp}
+`;
+  markdown += `**Status:** Draft
+
+`;
+  markdown += `## Overview
+
+`;
+  markdown += `This document defines the Service Level Objectives (SLOs) for ${serviceName}. `;
+  markdown += `These objectives represent the target reliability and performance metrics that the service commits to achieving.
+
+`;
+  markdown += `## SLO Definitions
+
+`;
+  for (const metric of metrics) {
+    const downtime = calculateAllowedDowntime(metric.target, metric.window);
+    const icon = metric.severity === "critical" ? "\u{1F534}" : metric.severity === "high" ? "\u{1F7E1}" : "\u{1F7E2}";
+    markdown += `### ${icon} ${metric.name}
+
+`;
+    markdown += `- **Target:** ${metric.target}%
+`;
+    markdown += `- **Window:** ${metric.window} (${metric.windowType})
+`;
+    markdown += `- **Severity:** ${metric.severity}
+`;
+    markdown += `- **Allowed Downtime:** ${downtime}
+
+`;
+    markdown += `**Description:** `;
+    const lowerName = metric.name.toLowerCase();
+    if (lowerName.includes("availability") || lowerName.includes("uptime")) {
+      markdown += `The service must be available and responding to requests ${metric.target}% of the time within the ${metric.window} window. `;
+    } else if (lowerName.includes("latency") || lowerName.includes("response")) {
+      markdown += `${metric.target}% of requests must complete within the defined latency threshold during the ${metric.window} window. `;
+    } else if (lowerName.includes("error") || lowerName.includes("success")) {
+      markdown += `The error rate must remain below ${100 - metric.target}% (success rate above ${metric.target}%) within the ${metric.window} window. `;
+    } else {
+      markdown += `This metric must achieve a ${metric.target}% target within the ${metric.window} window. `;
+    }
+    markdown += `
+
+`;
+  }
+  markdown += `## Monitoring & Alerting
+
+`;
+  markdown += `### Error Budget
+
+`;
+  markdown += `Each SLO has an associated error budget based on the allowed downtime. `;
+  markdown += `When the error budget is exhausted:
+
+`;
+  markdown += `- Halt non-critical deployments
+`;
+  markdown += `- Focus on reliability improvements
+`;
+  markdown += `- Conduct incident review
+
+`;
+  markdown += `### Alerting Strategy
+
+`;
+  const criticalMetrics = metrics.filter((m) => m.severity === "critical");
+  if (criticalMetrics.length > 0) {
+    markdown += `**Critical SLOs:** Alert immediately when burn rate indicates budget will be exhausted in <2 hours
+
+`;
+  }
+  markdown += `**High SLOs:** Alert when burn rate indicates budget will be exhausted in <24 hours
+
+`;
+  markdown += `**Medium SLOs:** Alert when burn rate indicates budget will be exhausted in <7 days
+
+`;
+  markdown += `## Review Process
+
+`;
+  markdown += `- **Frequency:** Quarterly
+`;
+  markdown += `- **Participants:** Engineering team, SRE, Product
+`;
+  markdown += `- **Review criteria:** User impact, operational cost, business requirements
+
+`;
+  markdown += `## Related Documents
+
+`;
+  markdown += `- Service Architecture
+`;
+  markdown += `- Incident Response Playbook
+`;
+  markdown += `- Monitoring Dashboard
+`;
+  markdown += `- On-call Runbook
+`;
+  return markdown;
+}
+function createSummary(serviceName, metrics) {
+  const criticalCount = metrics.filter((m) => m.severity === "critical").length;
+  const highCount = metrics.filter((m) => m.severity === "high").length;
+  const mediumCount = metrics.filter((m) => m.severity === "medium").length;
+  let summary = `SLO draft for ${serviceName} with ${metrics.length} metric${metrics.length !== 1 ? "s" : ""}`;
+  const parts = [];
+  if (criticalCount > 0) parts.push(`${criticalCount} critical`);
+  if (highCount > 0) parts.push(`${highCount} high`);
+  if (mediumCount > 0) parts.push(`${mediumCount} medium`);
+  if (parts.length > 0) {
+    summary += ` (${parts.join(", ")} severity)`;
+  }
+  summary += `. `;
+  const highestTarget = Math.max(...metrics.map((m) => m.target));
+  if (highestTarget >= 99.9) {
+    summary += `Includes stringent ${highestTarget}% availability targets requiring careful monitoring and error budget management.`;
+  } else if (highestTarget >= 99) {
+    summary += `Targets balanced reliability with ${highestTarget}% as the highest objective.`;
+  } else {
+    summary += `Focuses on achievable targets with ${highestTarget}% as the highest objective.`;
+  }
+  return summary;
+}
+var sloDraftTool = tool({
+  description: "Draft Service Level Objective (SLO) definitions for a service. Provide the service name and metrics (with name, target percentage, and time window) to generate a comprehensive SLO document in markdown format with error budgets, alerting strategies, and monitoring recommendations.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      serviceName: {
+        type: "string",
+        description: 'Name of the service (e.g., "API Gateway", "Payment Service")'
+      },
+      metrics: {
+        type: "array",
+        description: 'Array of SLO metrics with name, target (percentage), and window (e.g., "30d", "7d")',
+        items: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: 'Metric name (e.g., "Availability", "API Latency P99")'
+            },
+            target: {
+              type: "number",
+              description: "Target percentage (e.g., 99.9 for 99.9%)"
+            },
+            window: {
+              type: "string",
+              description: 'Time window for measurement (e.g., "30d", "7 days", "rolling 30 days")'
+            }
+          },
+          required: ["name", "target", "window"]
+        }
+      }
+    },
+    required: ["serviceName", "metrics"],
+    additionalProperties: false
+  }),
+  async execute({ serviceName, metrics }) {
+    if (!serviceName || typeof serviceName !== "string" || serviceName.trim().length === 0) {
+      throw new Error("Service name is required and must be a non-empty string");
+    }
+    if (!Array.isArray(metrics) || metrics.length === 0) {
+      throw new Error("Metrics array is required and must contain at least one metric");
+    }
+    const processedMetrics = [];
+    for (let i = 0; i < metrics.length; i++) {
+      const metric = metrics[i];
+      if (!metric) {
+        throw new Error(`Metric at index ${i}: is undefined`);
+      }
+      if (!metric.name || typeof metric.name !== "string" || metric.name.trim().length === 0) {
+        throw new Error(`Metric at index ${i}: name is required and must be a non-empty string`);
+      }
+      if (typeof metric.target !== "number") {
+        throw new Error(`Metric at index ${i}: target must be a number`);
+      }
+      if (metric.target < 0 || metric.target > 100) {
+        throw new Error(`Metric at index ${i}: target must be between 0 and 100`);
+      }
+      if (!metric.window || typeof metric.window !== "string" || metric.window.trim().length === 0) {
+        throw new Error(`Metric at index ${i}: window is required and must be a non-empty string`);
+      }
+      processedMetrics.push({
+        name: metric.name.trim(),
+        target: metric.target,
+        window: metric.window.trim(),
+        windowType: determineWindowType(metric.window),
+        severity: determineSeverity(metric.target)
+      });
+    }
+    processedMetrics.sort((a, b) => {
+      const severityOrder = { critical: 0, high: 1, medium: 2 };
+      return severityOrder[a.severity] - severityOrder[b.severity];
+    });
+    const sloMarkdown = generateSLOMarkdown(serviceName.trim(), processedMetrics);
+    const summary = createSummary(serviceName.trim(), processedMetrics);
+    const criticalMetrics = processedMetrics.filter((m) => m.severity === "critical").length;
+    return {
+      slo: sloMarkdown,
+      metrics: processedMetrics,
+      summary,
+      metadata: {
+        serviceName: serviceName.trim(),
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        totalMetrics: processedMetrics.length,
+        criticalMetrics
+      }
+    };
+  }
+});
+var index_default = sloDraftTool;
+
+export { index_default as default, sloDraftTool };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@tpmjs/tools-slo-draft",
+  "version": "0.2.0",
+  "description": "Draft SLO (Service Level Objective) definitions for services",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "ops",
+    "slo",
+    "monitoring",
+    "sre"
+  ],
+  "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/slo-draft"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "ops",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "sloDraftTool",
+        "description": "Draft SLO (Service Level Objective) definitions for services with metrics, targets, and windows",
+        "parameters": [
+          {
+            "name": "serviceName",
+            "type": "string",
+            "description": "Name of the service",
+            "required": true
+          },
+          {
+            "name": "metrics",
+            "type": "array",
+            "description": "Array of metrics with name, target, and window",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "SLODraft",
+          "description": "Object with slo (markdown), metrics array, and summary"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}