@calcis/llamaindex

Calcis cost-estimation callback for LlamaIndex.

Live pricing for 25+ models, side-by-side comparisons, and a web estimator: https://calcis.dev

• Full price index: https://calcis.dev/models
• Compare models: https://calcis.dev/compare
• API reference: https://calcis.dev/api-docs

Subscribe the handler to LlamaIndex's CallbackManager and get a one-line cost estimate for every LLM call, plus a rolling session total.

Install

npm install @calcis/llamaindex llamaindex

You also need a Calcis API key (Pro tier or above). Get one at calcis.dev/dashboard. Browse every supported model at calcis.dev/models.

Usage

Global (simplest)

Attach once to Settings.callbackManager and every downstream chat engine, query engine, or agent inherits cost reporting.

import { Settings, SimpleChatEngine, Anthropic } from "llamaindex";
import { CalcisLlamaIndexHandler } from "@calcis/llamaindex";

Settings.llm = new Anthropic({ model: "claude-sonnet-4-6" });

const calcis = new CalcisLlamaIndexHandler({
  apiKey: process.env.CALCIS_API_KEY!,
});
calcis.attach(Settings.callbackManager);

const chatEngine = new SimpleChatEngine();
await chatEngine.chat({ message: "Explain quantum computing" });

console.log(`Session total: $${calcis.getSessionTotal().toFixed(4)}`);

Every LLM call now emits:

[calcis] claude-sonnet-4-6 · 243 in · 650 out · $0.0105 · session: $0.0105 (1 calls)

Scoped

If you only want cost reporting inside a specific block:

import { Settings, CallbackManager } from "llamaindex";
import { CalcisLlamaIndexHandler } from "@calcis/llamaindex";

const cm = new CallbackManager();
const calcis = new CalcisLlamaIndexHandler({
  apiKey: process.env.CALCIS_API_KEY!,
  model: "claude-sonnet-4-6",
});
calcis.attach(cm);

await Settings.withCallbackManager(cm, async () => {
  // ...LLM calls inside here are metered
});

calcis.detach(cm);

Config

new CalcisLlamaIndexHandler({
  apiKey: string,                   // required: calc_… key
  model?: string,                   // Calcis model ID override
  verbose?: boolean,                // default true: logs per-call summary
  onEstimate?: (e) => void,         // optional structured sink
});

model defaults to Settings.llm.metadata.model when you attach to the global Settings.callbackManager. Pass it explicitly when attaching to a scoped CallbackManager that doesn't live under Settings.withCallbackManager.

Session helpers

calcis.getSessionTotal(); // cumulative cost across calls
calcis.getCallCount();    // number of LLM calls so far
calcis.resetSession();    // zero the counters (e.g. per request)

Failure mode

This handler never throws. If the Calcis API is unreachable, returns an error, or the response is malformed, the handler silently skips the estimate for that call: the underlying LlamaIndex pipeline keeps running. Cost estimation is a nice-to-have; your product is not.

Compatibility

Tested against llamaindex 0.8.x. The event map (llm-start / llm-end) and payload shape ({ id, messages } / { id, response }) have been stable since 0.5, so earlier patch versions in that range should also work. If LlamaIndex ships a breaking callback change in a future release, open an issue: this package will be updated in lock step.

Links

• Web App
• API Docs
• CLI (calcis)
• Pricing dataset (@calcis/pricing)
• LangChain integration (@calcis/langchain)

License

MIT