Cost Tiers

The Bridge SDK uses a two-layer model architecture — an orchestrator (PM mode: analysis, planning, validation) and an executor (Coder mode: implementation). Cost tiers control which models back each layer.

Tier Overview

Tier	Orchestrator	Executor	Cost Indicator	Use Case
`free`	Ollama	Ollama (local)	$0	Development, testing, CI
`hybrid`	Ollama	Claude Sonnet 4	Low	Balanced production workloads
`premium`	Claude Sonnet 4	Claude Sonnet 4	Medium	Maximum capability, complex tasks

Using Tiers

import { createNitySession } from '@mariozechner/pi-coding-agent/extensions/nity/bridge';
 
// Free — local models, zero cost
const session = await createNitySession({ costTier: 'free' });
 
// Hybrid — orchestrator stays local, executor is cloud
const session = await createNitySession({ costTier: 'hybrid' });
 
// Premium — both layers use Claude
const session = await createNitySession({ costTier: 'premium' });

The default tier is free when no costTier is specified.

Environment Variable Overrides

Override the default models for any tier without changing code:

Variable	Description	Example
`NITY_BRIDGE_ORCHESTRATOR_MODEL`	Override the orchestrator model across all tiers	`anthropic/claude-sonnet-4-20250514`
`NITY_BRIDGE_EXECUTOR_MODEL`	Override the executor model across all tiers	`ollama`

Environment variables take priority over tier defaults:

# Force hybrid tier to use a specific executor
NITY_BRIDGE_EXECUTOR_MODEL=anthropic/claude-sonnet-4-20250514 node app.js

import { getTierModels } from '@mariozechner/pi-coding-agent/extensions/nity/bridge';
 
// Respects env var overrides
const config = getTierModels('free');
console.log(config.orchestrator); // process.env.NITY_BRIDGE_ORCHESTRATOR_MODEL ?? 'ollama'
console.log(config.executor);     // process.env.NITY_BRIDGE_EXECUTOR_MODEL ?? 'ollama'

Model Capabilities

Each model has a capability profile used for intelligent routing:

Model	Code Gen	Analysis	Long Context	Context Window	Cost/Input 1K	Cost/Output 1K
`ollama`	Yes	Yes	No	4,096 tokens	$0	$0
`mimo`	No	Yes	No	8,192 tokens	$0	$0
`claude-sonnet-4`	Yes	Yes	Yes	200,000 tokens	$0.003	$0.015

Check capabilities programmatically:

import {
  getModelCapabilities,
  modelHasCapability,
  matchModel,
} from '@mariozechner/pi-coding-agent/extensions/nity/bridge';
 
// Full capability object
const caps = getModelCapabilities('ollama');
// { name: 'ollama', codeGen: true, analysis: true, longContext: false, ... }
 
// Check a single capability
const canCodeGen = modelHasCapability('mimo', 'codeGen'); // false
 
// Find best model for requirements
const model = matchModel(['longContext', 'codeGen'], 'free');
// Returns premium executor since free tier models lack longContext

Fallback Chains

Each tier has a fallback chain. If the primary model fails, the SDK falls back to the next model in the chain:

Tier	Chain
`free`	`["ollama"]`
`hybrid`	`["claude-sonnet-4", "ollama"]`
`premium`	`["claude-sonnet-4", "claude-sonnet-4"]`

import {
  getFallbackChain,
  getNextFallback,
} from '@mariozechner/pi-coding-agent/extensions/nity/bridge';
 
getFallbackChain('hybrid');
// ['anthropic/claude-sonnet-4-20250514', 'ollama']
 
getNextFallback('hybrid', 'anthropic/claude-sonnet-4-20250514');
// 'ollama'
 
getNextFallback('hybrid', 'ollama');
// null (end of chain)

Session-level fallback is enabled by default via enableFallback: true in the config. When Nity tools are unavailable, the session degrades to standalone mode and executes the prompt directly without tool routing.

Budget Tracking

Use CostTracker to monitor spend and enforce budgets:

import { CostTracker } from '@mariozechner/pi-coding-agent/extensions/nity/bridge';
 
const tracker = new CostTracker({
  budgetLimit: 1.00,           // Hard stop at $1.00
  budgetAlertThreshold: 0.50,  // Warn at $0.50
});
 
// Register alert callback
tracker.onBudgetAlert((spent, limit) => {
  console.warn(`Budget alert: $${spent.toFixed(4)} spent of $${limit.toFixed(2)} limit`);
});
 
// Record a task execution
const cost = tracker.recordTask('premium', 5000, 1200);
console.log(`Task cost: $${cost.toFixed(6)}`);
 
// Check budget
if (tracker.isBudgetExceeded()) {
  throw new Error('Session budget exceeded');
}
 
// Get full report
const report = tracker.getReport();
console.log(report);
// {
//   totalSessions: 1,
//   totalTasks: 12,
//   totalCost: 0.0342,
//   byTier: { free: { tasks: 8, cost: 0 }, hybrid: { tasks: 3, cost: 0.012 }, premium: { tasks: 1, cost: 0.0222 } },
//   avgCostPerTask: 0.00285
// }
 
// Get optimization suggestions
const suggestions = tracker.getOptimizationSuggestions();
// ['Consider using hybrid or free tier for simple tasks to reduce costs']

Pre-Execution Cost Estimation

Estimate cost before running a task:

const estimate = tracker.estimateCost('premium', 10000, 3000);
console.log(estimate);
// {
//   estimatedCost: 0.075,
//   orchestratorModel: 'anthropic/claude-sonnet-4-20250514',
//   executorModel: 'anthropic/claude-sonnet-4-20250514',
//   tier: 'premium'
// }

Tier Selection Guide

Use free for local development and CI. Requires a running Ollama instance.

const session = await createNitySession({ costTier: 'free' });

⚠️

The free tier depends on a local Ollama instance. If Ollama is unavailable and enableFallback is true, the session degrades to standalone mode (direct prompting without Nity tools).

API Reference Context Injection