@bhaskarauthor/llm-spend 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Bhaskar Pandey
+
+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.

package/PRODUCT_CYCLE.md

@@ -0,0 +1,38 @@
+# Product cycle — llm-spend
+
+| Field | Value |
+|-------|--------|
+| **Track** | Alpha (`alpha`) |
+| **Version** | `0.1.0-alpha.1` |
+| **Cycle** | **CLOSED** (Alpha) |
+| **Closed at** | 2026-07-12T04:12:35.713Z |
+| **Publish** | **Not published** — local workspace only until explicit go-ahead |
+
+## Closed-cycle checklist
+
+- [x] `package.json` name + version set
+- [x] MIT LICENSE
+- [x] README documents scope + limitations
+- [x] Automated tests exist and pass under suite litmus
+- [x] Cycle smoke tests (`tests/cycle.test.mjs`) for core entrypoints
+- [x] Demo or usage path documented
+- [x] Zero runtime dependencies (suite convention)
+- [x] Known limitations listed (below)
+- [ ] npm publish (blocked until owner says go)
+- [ ] git remote push (blocked until owner says go)
+
+## Known limitations (Alpha)
+
+- Offline domain MVP — no live cloud / WhatsApp / payments integrations.
+- Litmus + cycle smoke tests, not full E2E or load tests.
+- Commercial hosted layers are future work; OSS core stays free.
+
+## How to verify
+
+```bash
+cd llm-spend
+npm test
+npm run cycle:check 2>/dev/null || node --test tests/*.test.mjs tests/**/*.test.mjs
+```
+
+Suite: `node scripts/suite-litmus.mjs` from workspace root.

package/README.md

@@ -0,0 +1,35 @@
+# llm-spend
+
+> P05 · AI Tooling / FinOps
+
+**Unified LLM cost, token, and budget observability across OpenAI, Anthropic, Google, Azure, open models**
+
+## Status
+
+Offline **MVP core** (v0.1.0-beta.0) — zero runtime dependencies, litmus-tested, demo-ready.
+Part of the Bhaskar Pandey product portfolio under `Documents/development`.
+
+## Quick start
+
+```bash
+cd llm-spend
+npm test
+npm run demo
+node src/cli.js --help
+```
+
+## MVP scope
+
+Proxy + per-key budgets + simple dashboard + alerts
+
+## Open source → commercial
+
+| Layer | Now | Later |
+|-------|-----|-------|
+| Core algorithms / CLI | OSS MIT | remains OSS |
+| Hosted / team / SSO | — | commercial |
+| Support / SLAs | community | paid |
+
+## License
+
+MIT

package/demo/DEMO.md

@@ -0,0 +1,24 @@
+# llm-spend (P05) — Demo
+
+Unified LLM cost, token, and budget observability across OpenAI, Anthropic, Google, Azure, open models
+
+## Run
+
+```bash
+cd llm-spend
+node demo/run-demo.mjs
+node src/cli.js --json fixtures/sample.json
+npm test
+```
+
+## MVP
+
+Proxy + per-key budgets + simple dashboard + alerts
+
+## Platforms
+
+Web,API,CLI
+
+## Commercial path (later)
+
+OSS core stays free; paid layer = team dashboard / hosted / compliance export.

package/demo/run-demo.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+console.log("=== DEMO P05 llm-spend ===");
+console.log("Unified LLM cost, token, and budget observability across OpenAI, Anthropic, Google, Azure, open models");
+const r = spawnSync(process.execPath, [path.join(root, "src/cli.js"), "--json", path.join(root, "fixtures/sample.json")], {
+  encoding: "utf8",
+});
+console.log(r.stdout || r.stderr);
+process.exit(r.status ?? 0);

package/fixtures/sample.json

@@ -0,0 +1,9 @@
+{
+  "events": [
+    {
+      "provider": "openai",
+      "tokens": 5000,
+      "pricePer1k": 0.01
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@bhaskarauthor/llm-spend",
+  "version": "0.1.0-alpha.1",
+  "private": false,
+  "description": "Unified LLM cost, token, and budget observability across OpenAI, Anthropic, Google, Azure, open models",
+  "type": "module",
+  "bin": {
+    "llm-spend": "src/cli.js",
+    "ai-llm-spend": "src/cli.js"
+  },
+  "scripts": {
+    "test": "node --test tests/litmus.test.mjs tests/cycle.test.mjs",
+    "demo": "node demo/run-demo.mjs",
+    "litmus": "node --test tests/litmus.test.mjs",
+    "cycle:check": "node --test tests/litmus.test.mjs tests/cycle.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "AI",
+    "FinOps",
+    "observability",
+    "cost"
+  ],
+  "license": "MIT",
+  "author": "Bhaskar Pandey <bhaskarauthor@gmail.com>",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "PRODUCT_CYCLE.md",
+    "demo",
+    "fixtures"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import * as core from "./core.js";
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`llm-spend (P05) — Unified LLM cost, token, and budget observability across OpenAI, Anthropic, Google, Azure, open models
+
+Usage:
+  llm-spend [--json] [fixture.json]
+  llm-spend --help
+
+Offline MVP core for OSS shipping; commercial layers later.
+`);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const file = args.find((a) => !a.startsWith("-"));
+let input = {};
+if (file && existsSync(file)) input = JSON.parse(readFileSync(resolve(file), "utf8"));
+else if (existsSync(new URL("../fixtures/sample.json", import.meta.url))) {
+  input = JSON.parse(readFileSync(new URL("../fixtures/sample.json", import.meta.url), "utf8"));
+}
+const result = typeof core.main === "function" ? core.main(input) : { ok: true };
+if (json) console.log(JSON.stringify({ product: "llm-spend", id: "P05", result }, null, 2));
+else {
+  console.log("llm-spend · P05");
+  console.log(JSON.stringify(result, null, 2));
+}

package/src/core.js

@@ -0,0 +1,28 @@
+/** P05 llm-spend — offline MVP core (zero deps) */
+export function main(input) {
+  const events = (Array.isArray(input.events) ? input.events : Array.isArray(input) ? input : []);
+  const usage = parseUsageEvents(Array.isArray(events) ? events : []);
+  const budget = input.budgetUsd || 100;
+  return { usage, budget: budgetStatus(usage.totalCostUsd, budget) };
+}
+export function parseUsageEvents(events) {
+  const byProvider = {};
+  let totalTokens = 0, totalCost = 0;
+  for (const e of (Array.isArray(events) ? events : [])) {
+    const p = e.provider || "unknown";
+    const tokens = Number(e.tokens || 0);
+    const cost = Number(e.costUsd ?? tokens * (e.pricePer1k || 0.002) / 1000);
+    byProvider[p] = byProvider[p] || { tokens: 0, costUsd: 0, calls: 0 };
+    byProvider[p].tokens += tokens;
+    byProvider[p].costUsd += cost;
+    byProvider[p].calls += 1;
+    totalTokens += tokens;
+    totalCost += cost;
+  }
+  return { byProvider, totalTokens, totalCostUsd: round(totalCost), eventCount: events.length };
+}
+export function budgetStatus(totalCostUsd, budgetUsd) {
+  const used = totalCostUsd / budgetUsd;
+  return { budgetUsd, totalCostUsd, usedPct: round(used * 100), over: totalCostUsd > budgetUsd };
+}
+function round(n) { return Math.round(n * 10000) / 10000; }