fathom-token-sdk

Typed programmatic API for Fathom's AI cost intelligence. Estimate tokens, recommend models, manage intent, and check budgets — all from your own code.

Install

npm install fathom-token-sdk

Quick Start

import { estimateFeature, createRouter, loadIntent } from "fathom-token-sdk";

// Estimate a feature's token cost
const estimate = await estimateFeature({
  description: "add OAuth login with Google and GitHub",
  complexity: "L",
});
console.log(estimate.totalTokens, estimate.estimatedCost);

// Get a model recommendation
const router = createRouter();
const rec = router.recommend({
  description: "refactor auth middleware",
  complexity: "M",
});
console.log(rec.model, rec.reasoning, rec.estimatedCost);

// Load project intent
const intent = await loadIntent(".fathom");
console.log(intent.purpose, intent.guardrails);

API Surface

Estimation (@fathom/core)

| Export | Description | |--------|-------------| | estimateFeature(opts) | Estimate tokens and cost for a single feature | | estimateAll(features) | Estimate an array of features | | loadData() | Load model pricing and complexity data | | getModelPricing(model) | Get pricing for a specific model | | getComplexityMultiplier(complexity) | Get the multiplier for S/M/L/XL |

Routing (@fathom/router)

| Export | Description | |--------|-------------| | createRouter(config?) | Create a model router with optional config | | scoreModelForTask(model, task) | Score a model for a specific task | | estimateTokensForTask(task) | Estimate tokens for a task context | | estimateCost(tokens, model) | Calculate cost from token count | | checkBudget(config) | Check budget status | | dailyBudgetRemaining(config) | Get remaining daily budget | | getDefaultModels() | List all known models | | getModelById(id) | Look up a model by ID | | getModelsByProvider(provider) | Filter models by provider | | getModelsByTier(tier) | Filter models by tier (frontier/mid/economy) |

Intent (@fathom/intent)

| Export | Description | |--------|-------------| | loadIntent(dir) | Load intent.yaml from a .fathom/ directory | | saveIntent(dir, intent) | Save intent.yaml | | detectIntent(description) | Auto-detect intent from a project description | | resolveGuardrails(intent) | Resolve guardrail templates to concrete rules | | loadTemplate(name) | Load a guardrail template (OWASP, WCAG, etc.) | | listTemplates() | List available guardrail templates |

Store (@fathom/store)

| Export | Description | |--------|-------------| | createStore(config) | Create a store instance from config | | createStoreFromConfig(path) | Create a store from a config file | | loadStoreConfig(path) | Load store configuration | | FileStore | File-based store implementation |

Types

All types are exported for TypeScript consumers:

import type {
  LoadedData,
  Router, RouterConfig, Recommendation, TaskContext, BudgetState,
  BudgetCheckResult,
  IntentConfig, ResolvedGuardrails, GuardrailTemplate,
  FathomStore, StoreConfig,
} from "fathom-token-sdk";

Requirements

• Node.js 20+
• TypeScript 5+ (for type exports)

Part of Fathom

fathom-token-sdk is a curated re-export of the Fathom workspace packages, bundled as a single dependency. Use it when you want programmatic access without importing individual @fathom/* packages.

License

MIT