@tenhaw/ai-roi 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/LICENSE-CONTENT +15 -0
- package/README.md +33 -2
- package/dist/index.d.ts +123 -0
- package/dist/index.js +48 -0
- package/package.json +39 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tenhaw
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/LICENSE-CONTENT
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
Tenhaw AI Readiness Framework and authored framework content in spec/content
|
|
2
|
+
are licensed under the Creative Commons Attribution 4.0 International licence.
|
|
3
|
+
Copyright (c) 2026 Tenhaw.
|
|
4
|
+
|
|
5
|
+
Licence: https://creativecommons.org/licenses/by/4.0/
|
|
6
|
+
Legal code: https://creativecommons.org/licenses/by/4.0/legalcode.en
|
|
7
|
+
|
|
8
|
+
When sharing or adapting this content, provide appropriate credit, a licence
|
|
9
|
+
link, and an indication of changes. A suitable credit is:
|
|
10
|
+
"Tenhaw AI Readiness Framework, CC BY 4.0, https://tenhaw.com."
|
|
11
|
+
|
|
12
|
+
Numerical results and user-supplied evidence remain the user's material.
|
|
13
|
+
The optional audit promotion can be suppressed independently of applicable
|
|
14
|
+
framework-content credits. Code is MIT; third-party sources retain their own
|
|
15
|
+
rights and are summarised with links rather than relicensed here.
|
package/README.md
CHANGED
|
@@ -1,3 +1,34 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tenhaw/ai-roi
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Model AI investment cash flow while separating recovered capacity from cash benefits.
|
|
4
|
+
|
|
5
|
+
## When to use
|
|
6
|
+
|
|
7
|
+
- Use this when building an AI business case, comparing savings scenarios or estimating project costs.
|
|
8
|
+
- Do not use this for financial advice or treating retained staff time as cash savings.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install @tenhaw/ai-roi
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { estimateProjectCost } from '@tenhaw/ai-roi';
|
|
20
|
+
const cost = estimateProjectCost({ stage: 'poc' });
|
|
21
|
+
console.log(cost.low, cost.high); // 16000 32000
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## API
|
|
25
|
+
|
|
26
|
+
`calculateRoi(input)` (alias `estimateRoi`) validates `roi-input.schema.json`. Inputs explicitly define users, minutes per task, tasks per user per month, low/base/high savings fractions, hourly cost, build cost, monthly run cost, adoption months, horizon months, annual discount rate, cash-realisation fraction and currency. `estimateProjectCost({stage,people?,durationWeeks?,dayRate?,currency?})`. `renderRoiReport(report,format,options?)`.
|
|
27
|
+
|
|
28
|
+
## Methodology and sources
|
|
29
|
+
|
|
30
|
+
Monthly adoption rises linearly to full adoption. Benefit is time saved multiplied by hourly cost and the explicit cash-realisation fraction. The remaining time is recovered capacity. Full run cost applies from month one. Build cost occurs at month zero. Discounting uses `(1 + annualDiscountRate) ** (month / 12)`. A payback month is the first observed cumulative cash break-even; it is not a guarantee that later months stay positive. Null ratios represent zero denominators. Cost defaults are editable assumptions, not quotes. Model token prices must be supplied, never assumed current.
|
|
31
|
+
|
|
32
|
+
## Built by Tenhaw
|
|
33
|
+
|
|
34
|
+
Tenhaw is a founder-led UK AI consultancy and venture studio. For expert help applying this, [book an AI readiness audit](https://tenhaw.com/contact?utm_source=npm&utm_medium=readme&utm_campaign=tenhaw-kit&utm_content=ai-roi#book).
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { AttributionOptions } from '@tenhaw/core';
|
|
2
|
+
|
|
3
|
+
type RoiInput = {
|
|
4
|
+
useCase: string;
|
|
5
|
+
users: number;
|
|
6
|
+
minutesPerTask: number;
|
|
7
|
+
tasksPerUserPerMonth: number;
|
|
8
|
+
savings: {
|
|
9
|
+
low: number;
|
|
10
|
+
base: number;
|
|
11
|
+
high: number;
|
|
12
|
+
};
|
|
13
|
+
hourlyCost: number;
|
|
14
|
+
buildCost: number;
|
|
15
|
+
monthlyRunCost: number;
|
|
16
|
+
adoptionMonths: number;
|
|
17
|
+
horizonMonths: number;
|
|
18
|
+
annualDiscountRate: number;
|
|
19
|
+
cashRealisation: number;
|
|
20
|
+
currency: string;
|
|
21
|
+
};
|
|
22
|
+
declare function calculateRoi(input: RoiInput): {
|
|
23
|
+
currency: string;
|
|
24
|
+
assumptions: {
|
|
25
|
+
cashRealisation: number;
|
|
26
|
+
capacityIsCash: boolean;
|
|
27
|
+
};
|
|
28
|
+
scenarios: {
|
|
29
|
+
low: {
|
|
30
|
+
monthlyCashFlow: {
|
|
31
|
+
month: number;
|
|
32
|
+
adoption: number;
|
|
33
|
+
hoursSaved: number;
|
|
34
|
+
potentialValue: number;
|
|
35
|
+
cashBenefit: number;
|
|
36
|
+
runCost: number;
|
|
37
|
+
netCashFlow: number;
|
|
38
|
+
cumulativeCashFlow: number;
|
|
39
|
+
}[];
|
|
40
|
+
totalCashBenefit: number;
|
|
41
|
+
totalRunCost: number;
|
|
42
|
+
totalHoursSaved: number;
|
|
43
|
+
recoveredCapacityHours: number;
|
|
44
|
+
npv: number;
|
|
45
|
+
paybackMonth: null;
|
|
46
|
+
roiPercent: number | null;
|
|
47
|
+
costPerTask: number | null;
|
|
48
|
+
breakEvenAdoption: number | null;
|
|
49
|
+
};
|
|
50
|
+
base: {
|
|
51
|
+
monthlyCashFlow: {
|
|
52
|
+
month: number;
|
|
53
|
+
adoption: number;
|
|
54
|
+
hoursSaved: number;
|
|
55
|
+
potentialValue: number;
|
|
56
|
+
cashBenefit: number;
|
|
57
|
+
runCost: number;
|
|
58
|
+
netCashFlow: number;
|
|
59
|
+
cumulativeCashFlow: number;
|
|
60
|
+
}[];
|
|
61
|
+
totalCashBenefit: number;
|
|
62
|
+
totalRunCost: number;
|
|
63
|
+
totalHoursSaved: number;
|
|
64
|
+
recoveredCapacityHours: number;
|
|
65
|
+
npv: number;
|
|
66
|
+
paybackMonth: null;
|
|
67
|
+
roiPercent: number | null;
|
|
68
|
+
costPerTask: number | null;
|
|
69
|
+
breakEvenAdoption: number | null;
|
|
70
|
+
};
|
|
71
|
+
high: {
|
|
72
|
+
monthlyCashFlow: {
|
|
73
|
+
month: number;
|
|
74
|
+
adoption: number;
|
|
75
|
+
hoursSaved: number;
|
|
76
|
+
potentialValue: number;
|
|
77
|
+
cashBenefit: number;
|
|
78
|
+
runCost: number;
|
|
79
|
+
netCashFlow: number;
|
|
80
|
+
cumulativeCashFlow: number;
|
|
81
|
+
}[];
|
|
82
|
+
totalCashBenefit: number;
|
|
83
|
+
totalRunCost: number;
|
|
84
|
+
totalHoursSaved: number;
|
|
85
|
+
recoveredCapacityHours: number;
|
|
86
|
+
npv: number;
|
|
87
|
+
paybackMonth: null;
|
|
88
|
+
roiPercent: number | null;
|
|
89
|
+
costPerTask: number | null;
|
|
90
|
+
breakEvenAdoption: number | null;
|
|
91
|
+
};
|
|
92
|
+
};
|
|
93
|
+
topDrivers: {
|
|
94
|
+
name: string;
|
|
95
|
+
value: number;
|
|
96
|
+
}[];
|
|
97
|
+
limitations: string[];
|
|
98
|
+
};
|
|
99
|
+
declare const estimateRoi: typeof calculateRoi;
|
|
100
|
+
type RoiReport = ReturnType<typeof calculateRoi>;
|
|
101
|
+
declare function renderRoiReport(report: RoiReport, format: 'md' | 'html' | 'json', options?: AttributionOptions): string;
|
|
102
|
+
declare function estimateProjectCost(input: {
|
|
103
|
+
stage: 'poc' | 'pilot' | 'production';
|
|
104
|
+
people?: number;
|
|
105
|
+
durationWeeks?: number;
|
|
106
|
+
dayRate?: number;
|
|
107
|
+
currency?: string;
|
|
108
|
+
}): {
|
|
109
|
+
stage: "poc" | "pilot" | "production";
|
|
110
|
+
currency: string;
|
|
111
|
+
low: number;
|
|
112
|
+
high: number;
|
|
113
|
+
assumptions: {
|
|
114
|
+
people: number;
|
|
115
|
+
dayRate: number;
|
|
116
|
+
workingDaysPerWeek: number;
|
|
117
|
+
weeksLow: number;
|
|
118
|
+
weeksHigh: number;
|
|
119
|
+
};
|
|
120
|
+
limitations: string[];
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
export { type RoiInput, type RoiReport, calculateRoi, estimateProjectCost, estimateRoi, renderRoiReport };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// src/index.ts
|
|
2
|
+
import { invariant, round, validateInput, renderReport } from "@tenhaw/core";
|
|
3
|
+
function calculateRoi(input) {
|
|
4
|
+
const r = validateInput("roi-input", input);
|
|
5
|
+
invariant(r.savings.low <= r.savings.base && r.savings.base <= r.savings.high, "/savings", "Savings must be ordered low <= base <= high");
|
|
6
|
+
const scenario = (saving) => {
|
|
7
|
+
let cumulative = -r.buildCost, benefit = 0, runCost = 0, hours = 0, npv = -r.buildCost;
|
|
8
|
+
let payback = null;
|
|
9
|
+
const fullHours = r.users * r.tasksPerUserPerMonth * r.minutesPerTask * saving / 60;
|
|
10
|
+
const monthlyCashFlow = Array.from({ length: r.horizonMonths }, (_, i) => {
|
|
11
|
+
const month = i + 1;
|
|
12
|
+
const adoption = r.adoptionMonths === 0 ? 1 : Math.min(1, month / r.adoptionMonths);
|
|
13
|
+
const hoursSaved = fullHours * adoption;
|
|
14
|
+
const potentialValue = hoursSaved * r.hourlyCost;
|
|
15
|
+
const cashBenefit = potentialValue * r.cashRealisation;
|
|
16
|
+
const netCashFlow = cashBenefit - r.monthlyRunCost;
|
|
17
|
+
cumulative += netCashFlow;
|
|
18
|
+
benefit += cashBenefit;
|
|
19
|
+
runCost += r.monthlyRunCost;
|
|
20
|
+
hours += hoursSaved;
|
|
21
|
+
if (month === 1 && r.buildCost === 0 && netCashFlow >= 0) payback = 0;
|
|
22
|
+
npv += netCashFlow / (1 + r.annualDiscountRate) ** (month / 12);
|
|
23
|
+
if (payback === null && cumulative >= 0) payback = month;
|
|
24
|
+
return { month, adoption: round(adoption), hoursSaved: round(hoursSaved), potentialValue: round(potentialValue), cashBenefit: round(cashBenefit), runCost: round(r.monthlyRunCost), netCashFlow: round(netCashFlow), cumulativeCashFlow: round(cumulative) };
|
|
25
|
+
});
|
|
26
|
+
const totalCost = r.buildCost + runCost, totalTasks = r.users * r.tasksPerUserPerMonth * r.horizonMonths, fullCash = fullHours * r.hourlyCost * r.cashRealisation;
|
|
27
|
+
return { monthlyCashFlow, totalCashBenefit: round(benefit), totalRunCost: round(runCost), totalHoursSaved: round(hours), recoveredCapacityHours: round(hours * (1 - r.cashRealisation)), npv: round(npv), paybackMonth: payback, roiPercent: totalCost > 0 ? round((benefit - totalCost) / totalCost * 100) : null, costPerTask: totalTasks > 0 ? round(totalCost / totalTasks) : null, breakEvenAdoption: fullCash > 0 ? round(r.monthlyRunCost / fullCash) : null };
|
|
28
|
+
};
|
|
29
|
+
return { currency: r.currency, assumptions: { cashRealisation: r.cashRealisation, capacityIsCash: false }, scenarios: { low: scenario(r.savings.low), base: scenario(r.savings.base), high: scenario(r.savings.high) }, topDrivers: [{ name: "time-saving fraction", value: r.savings.base }, { name: "cash-realisation fraction", value: r.cashRealisation }, { name: "monthly task volume", value: r.users * r.tasksPerUserPerMonth }], limitations: ["Cash benefits require explicit cost-line removal or a justified cash-realisation assumption.", "Recovered capacity is reported separately and is not treated as cash.", "Editable assumptions, not a quote or financial advice."] };
|
|
30
|
+
}
|
|
31
|
+
var estimateRoi = calculateRoi;
|
|
32
|
+
function renderRoiReport(report, format, options = {}) {
|
|
33
|
+
return renderReport(report, format, { content: "ai-roi", ...options });
|
|
34
|
+
}
|
|
35
|
+
function estimateProjectCost(input) {
|
|
36
|
+
validateInput("project-cost-input", input);
|
|
37
|
+
const defaults = { poc: { people: 2, low: 2, high: 4 }, pilot: { people: 3, low: 4, high: 8 }, production: { people: 4, low: 8, high: 16 } };
|
|
38
|
+
invariant(Object.hasOwn(defaults, input.stage), "/stage", "Use poc, pilot or production");
|
|
39
|
+
const d = defaults[input.stage], people = input.people ?? d.people, dayRate = input.dayRate ?? 800, low = input.durationWeeks ?? d.low, high = input.durationWeeks ?? d.high;
|
|
40
|
+
for (const [key, value] of Object.entries({ people, dayRate, durationWeeks: low })) invariant(Number.isFinite(value) && value > 0, `/${key}`, "Use a finite positive number");
|
|
41
|
+
return { stage: input.stage, currency: input.currency ?? "GBP", low: round(people * low * 5 * dayRate), high: round(people * high * 5 * dayRate), assumptions: { people, dayRate, workingDaysPerWeek: 5, weeksLow: low, weeksHigh: high }, limitations: ["Editable assumptions, not a quote.", "Excludes model, infrastructure and ongoing support costs."] };
|
|
42
|
+
}
|
|
43
|
+
export {
|
|
44
|
+
calculateRoi,
|
|
45
|
+
estimateProjectCost,
|
|
46
|
+
estimateRoi,
|
|
47
|
+
renderRoiReport
|
|
48
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tenhaw/ai-roi",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Explicit cash-realisation and capacity modelling for AI investments",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"README.md",
|
|
17
|
+
"LICENSE",
|
|
18
|
+
"LICENSE-CONTENT"
|
|
19
|
+
],
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"@tenhaw/core": "1.0.0"
|
|
22
|
+
},
|
|
23
|
+
"author": "Tenhaw (https://tenhaw.com)",
|
|
24
|
+
"license": "MIT",
|
|
25
|
+
"repository": {
|
|
26
|
+
"type": "git",
|
|
27
|
+
"url": "https://github.com/Tenhaw/tenhaw-kit.git",
|
|
28
|
+
"directory": "packages/ai-roi"
|
|
29
|
+
},
|
|
30
|
+
"homepage": "https://kit.tenhaw.com/tools/ai-roi",
|
|
31
|
+
"publishConfig": {
|
|
32
|
+
"access": "public"
|
|
33
|
+
},
|
|
34
|
+
"engines": {
|
|
35
|
+
"node": ">=22"
|
|
36
|
+
},
|
|
37
|
+
"scripts": {
|
|
38
|
+
"build": "tsup src/index.ts --format esm --dts",
|
|
39
|
+
"test": "vitest run --passWithNoTests",
|
|
40
|
+
"typecheck": "tsc --noEmit"
|
|
41
|
+
}
|
|
6
42
|
}
|