@vraj0703/ai-lib

Reusable Node utility libraries — logger, retry, ollama, json-extract, toml-parser, cost-tracker, task-state, timestamp, ground-truth, toon. Zero npm dependencies.

These are nine small, well-tested, dependency-free Node utilities that the ai-mind, ai-memory (planned), ai-knowledge (planned), and ai-dashboard (planned) repos all depend on. Splitting them out lets each consumer share one source of truth instead of copying utilities forward.

Status: v0.1.0. Lifted from raj-sadan's lib/ directory. Smoke tests cover the public surface; comprehensive per-utility tests are a v0.2 follow-up.

What's in it

| Utility | Purpose | Format | |---|---|---| | logger | Unified JSONL logging plus colored console plus optional PII redaction plus log rotation | CJS | | retry | Exponential backoff with jitter and per-operation policies | CJS | | ollama | Ollama host normalization (0.0.0.0 → localhost, add http:// if missing) | ESM | | json-extract | Robust JSON parsing from LLM output (handles ```json fences, trailing commas, comments) | CJS + ESM | | toml-parser | Zero-dep TOML parser/serializer (covers the 90% of TOML used for config files) | CJS + ESM | | cost-tracker | LLM token-usage JSONL logging plus cost aggregation | CJS | | task-state | Task execution state machine (pending / running / completed / failed / blocked) | CJS | | timestamp | IST timezone helpers plus ISO formatting | CJS + ESM | | ground-truth | Source-of-truth state validation plus ground-truth injection for LLM prompts | CJS + ESM | | toon | TOON format (Token-Oriented Object Notation) for cloud-LLM context, ~40% token savings vs JSON | CJS, optional |

Install

npm install @vraj0703/ai-lib

The package has zero npm dependencies. Two utilities have optional peer deps:

• toon falls back to JSON if @toon-format/toon isn't installed.
• logger falls back to identity (no PII redaction) if @vraj0703/node-security-toolkit isn't installed.

Use

Import the specific utility you need:

// CommonJS
const { calculateBackoff } = require("@vraj0703/ai-lib/retry");

// ESM
import { normalizeOllamaHost } from "@vraj0703/ai-lib/ollama";
import { parseTOML } from "@vraj0703/ai-lib/toml-parser";

Or grab everything via the barrel (less preferred — pulls all utilities):

const { retry, logger, jsonExtract } = require("@vraj0703/ai-lib");

Common patterns

Retry an HTTP call with backoff

const { calculateBackoff } = require("@vraj0703/ai-lib/retry");

async function fetchWithRetry(url, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fetch(url);
    } catch (err) {
      if (attempt === maxAttempts - 1) throw err;
      const delay = calculateBackoff({ attempt, baseMs: 500, maxMs: 30000 });
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Normalize an Ollama host

import { normalizeOllamaHost } from "@vraj0703/ai-lib/ollama";

normalizeOllamaHost(undefined);             // "http://localhost:11434"
normalizeOllamaHost("0.0.0.0:11434");       // "http://localhost:11434"
normalizeOllamaHost("http://192.168.1.5:11434"); // unchanged

Extract JSON from a fenced LLM response

const { extractJSON } = require("@vraj0703/ai-lib/json-extract");

const llmOutput = "Here's the answer:\n```json\n{\"score\": 0.92}\n```\nDone.";
const data = extractJSON(llmOutput); // → { score: 0.92 }

Parse a config TOML

import { parseTOML } from "@vraj0703/ai-lib/toml-parser";

const config = parseTOML(fs.readFileSync("./app-config.toml", "utf8"));
console.log(config.org.agent.name);

Why these utilities specifically

These accumulated organically across raj-sadan's organs — every organ ended up needing the same logger, the same retry shape, the same JSON-from-LLM extraction. Splitting them out into a shared package was overdue.

The selection bias is deliberate: nothing here is novel, but each utility is the boring-correct version a real consumer would have to write themselves. The savings is in the not-having-to-write-them.

Module format

Dual exports via package.json conditional exports. CJS consumers get .cjs; ESM consumers get .mjs. A few utilities (logger, retry, cost-tracker, task-state, toon) are CJS-only because they don't yet have an ESM port — the dual is opt-in per-utility.

What's not here (yet)

• Comprehensive per-utility test suites — current state is one smoke test per utility. v0.2 plan.
• TypeScript declarations — currently JSDoc only. Auto-generated .d.ts is a v0.1.x follow-up.
• A "secrets" utility (raj-sadan has one in node-security-toolkit, kept there because of the AES-256-GCM crypto surface).

See also

• ai-mind — the cognitive layer that uses ai-lib's logger and retry
• ai-constitution — the governance framework
• node-security-toolkit — the (separate) security utilities

License

MIT.