Neutral Cost
Organizes all of your costs into one place. Seamlessly track your AI usage and Tool costs and charge accordingly.
git clone https://github.com/neutralbase/neutral-cost.git
cd neutral-costThis upstream package has not been adapted or qualified for Bijection. Read the original documentation before adopting it.
Description
Organizes all of your costs into one place. Seamlessly track your AI usage and Tool costs and charge accordingly.
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: neutralbase/neutral-cost. License: See repository. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
A cost tracking component for Convex.
Upstream overview
From the upstream package documentation.
Neutral Cost provides comprehensive cost tracking and billing management for AI applications built on Convex. It tracks token usage from AI providers like OpenAI, tool costs from services like web search APIs, and applies configurable markup multipliers for customer billing. The component includes rate limiting capabilities and credit-based billing to help developers understand profitability and build sustainable business models.
Use cases
From the upstream package documentation.
- Track AI model costs per customer to understand which users are profitable and identify high-usage accounts that need pricing adjustments
- Implement tiered usage models where customers get premium model access up to a limit, then fall back to cheaper models to maintain profitability
- Build prepaid credit systems with configurable markup multipliers across different AI providers and models for flexible billing
- Monitor tool usage costs from external APIs like search, image generation, or data enrichment services alongside AI model costs
- Export detailed cost analytics to frontend dashboards for customer usage insights and billing transparency
How it works
From the upstream package documentation.
The component integrates into your Convex app through the convex.config.ts file and provides a CostComponent class that wraps cost tracking functionality. You call addAICost() and addToolCost() from Convex actions to log usage with token counts, provider details, and user context.
Cost calculation uses a pricing database that maps model IDs and tool IDs to their actual costs, then applies optional markup multipliers configured per provider, model, or tool. These multipliers can be set in code or stored in the database for runtime updates.
The component exposes query functions like getAICostsByThread() and getTotalAICostsByUser() that you can export through your own Convex functions to power frontend cost displays. All cost data is organized by user, thread, and message for granular tracking and billing.
Upstream package FAQ
Which AI providers does Neutral Cost support for cost tracking?
Neutral Cost supports major AI providers including OpenAI, Anthropic, and other popular APIs. It can track both direct API costs and internal tool usage, providing comprehensive cost visibility for Convex applications.
How does Neutral Cost integrate with Convex databases?
Neutral Cost stores cost data directly in your Convex database, allowing you to query and analyze spending alongside your application data. It provides functions to track costs within your Convex mutations and queries.
Can I set up automatic billing based on tracked costs?
Yes, Neutral Cost provides detailed cost attribution data that you can use to implement usage-based billing. It tracks costs per user and operation, giving you the data needed to charge customers accurately for their AI usage.
Does Neutral Cost provide cost forecasting features?
Neutral Cost focuses on accurate cost tracking and reporting rather than forecasting. It provides historical usage patterns and real-time monitoring that you can use to analyze trends and plan budgets for your Convex applications.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Neutral Cost with Bijection.
Read: https://bijection.com/components/neutralcost/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from neutralbase/neutral-cost, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
Neutral Cost
Organizes all of your costs into one place. Seamlessly track your AI usage and tool costs and charge accordingly.
Why Neutral Cost?
This component makes it easy to define and track AI costs and tool costs, giving you visibility into:
- Your actual costs - Know exactly what each AI call and tool usage costs your business
- Customer profitability - Understand which customers are profitable and which need attention
- Flexible billing - Charge customers using prepaid credits with configurable markup multipliers
- Sophisticated rate limiting - For example, give users $10 of premium model usage, then unlimited access to lower-cost models to keep every customer profitable
Knowing your costs is the foundation for building your business AND your business model.
Found a bug? Feature request? File it here.
Pre-requisite: Convex
You'll need an existing Convex project to use the component. Convex is a hosted backend platform, including a database, serverless functions, and a ton more you can learn about here.
Run npm create convex or follow any of the quickstarts to set one up.
Installation
Install the component package:
npm install neutral-cost
Create a convex.config.ts file in your app's convex/ folder and install the component by calling use:
// convex/convex.config.ts
import { defineApp } from "convex/server";
import neutralCost from "neutral-cost/convex.config";
const app = defineApp();
app.use(neutralCost);
export default app;
Usage
import { components } from "./_generated/api";
import { CostComponent } from "neutral-cost";
const costs = new CostComponent(components.neutralCost, {
// Optional: Configure markup multipliers per provider, model, or tool
providerMarkupMultiplier: [
{ providerId: "openai", multiplier: 1.5 }, // 50% markup on OpenAI
],
modelMarkupMultiplier: [
{ modelId: "gpt-4", providerId: "openai", multiplier: 2.0 }, // 100% markup on GPT-4
],
toolMarkupMultiplier: [
{ toolId: "web-search", providerId: "tavily", multiplier: 1.25 }, // 25% markup on web search
],
});
Note: You can also configure markup multipliers in the Convex database. If a markup is defined in the database, it will take precedence and the configuration here will be ignored.
Track AI Costs
// In an action
const result = await costs.addAICost(ctx, {
messageId: "msg_123",
userId: "user_456",
threadId: "thread_789",
usage: { promptTokens: 100, completionTokens: 50, totalTokens: 150 },
modelId: "gpt-4",
providerId: "openai",
});
Track Tool Costs
// In an action
const result = await costs.addToolCost(ctx, {
messageId: "msg_123",
userId: "user_456",
threadId: "thread_789",
providerId: "tavily",
toolId: "web-search",
usage: { calls: 1 },
});
Query Costs
// Get costs by thread or user
const threadCosts = await costs.getAICostsByThread(ctx, "thread_789");
const userCosts = await costs.getTotalAICostsByUser(ctx, "user_456");
// Get tool costs
const toolCosts = await costs.getToolCostsByUser(ctx, "user_456");
Export Client API
Easily expose cost queries to your frontend:
// convex/costs.ts
import { components } from "./_generated/api";
import { CostComponent } from "neutral-cost";
const costs = new CostComponent(components.costComponent);
export const {
getAICostsByThread,
getAICostsByUser,
getTotalAICostsByUser,
getTotalAICostsByThread,
getToolCostsByThread,
getToolCostsByUser,
getTotalToolCostsByUser,
getTotalToolCostsByThread,
getAllPricing,
addAICost,
addToolCost,
updatePricingData,
getAllToolPricing,
getToolPricingByProvider,
getMarkupMultiplier,
getMarkupMultiplierById,
getPricingByProvider,
searchPricingByModelName,
getAICostByMessageId,
} = costs.clientApi();
See more example usage in example.ts.
Development
Run the example:
npm i
npm run dev
License
FSL-1.1-ALv2 - Functional Source License, Version 1.1, with Apache License 2.0 future license.
This means you can use the software for any purpose except competing uses. After two years from each release, that version becomes available under Apache 2.0.