Analytics

The @openinsure/analytics package provides portfolio KPI computation, Workers AI-powered predictive modeling, AI cost anomaly detection, and event tracking via Tinybird. It is consumed by the API worker’s analytics routes and by the Finance/Carrier portals.

Modules

Portfolio KPIs (`compute.ts`)

`computeMGAKPIs(policies, claims, submissions)`

Computes the full MGA portfolio metrics snapshot:

const kpis = computeMGAKPIs(policies, claims, submissions);
// Returns: MGAPortfolioKPIs

Output:

Field	Description
`grossWrittenPremium`	Sum of `grossPremium` across active/issued/renewed policies
`earnedPremium`	GWP × 0.85 (earned premium factor)
`totalIncurred`	Sum of `paidAmount + reserveAmount` across all claims
`lossRatio`	totalIncurred / earnedPremium
`expenseRatio`	12% of earned premium (MGA default)
`combinedRatio`	lossRatio + expenseRatio
`gwpByLob`	GWP breakdown by line of business
`gwpByState`	GWP breakdown by state
`submissionCount`	Total submissions in pipeline
`boundRate`	Submissions with `status = 'bound'` / total
`producerRankings`	Top producers by GWP contribution

`computeCaptiveKPIs(policies, claims, members)`

Captive-specific fund analysis:

Field	Description
`fundBalance`	Net fund position
`memberContributions`	Total premium contributions
`claimReserves`	Active claim reserve total
`ibnrEstimate`	Case reserves × 15%
`stopLossPenetrations`	Members approaching specific stop-loss attachment
`premiumToSurplusRatio`	Regulatory solvency indicator

`summarizeClaims(claims)`

Claims summary for dashboard widgets:

const summary = summarizeClaims(claims);
// { openCount, closedCount, totalPaid, totalReserved, totalIncurred, avgCycleTimeDays, ibnrEstimate }

`computeSubmissionPipelineKPIs(submissions)`

Submission funnel metrics:

const pipeline = computeSubmissionPipelineKPIs(submissions);
// { inQueue, autoAccepted, autoReferred, autoDeclined, avgAppetiteScore, premiumIndicated }

Predictive Modeling (`predict.ts`)

Workers AI-powered financial forecasting. Calls the CF Workers AI binding with a structured JSON schema for deterministic output.

`predictLossRatio(input: LossRatioPredictionInput)`

Forecasts loss ratio for a given LOB using historical performance and macro factors:

const forecast = await predictLossRatio(
  {
    lineOfBusiness: 'Commercial Auto',
    historicalLossRatios: [0.62, 0.58, 0.71, 0.65], // prior 4 years
    premiumTrend: 0.08, // 8% premium growth
    claimFrequencyTrend: 0.03, // 3% frequency increase
    macroFactors: {
      inflation: 0.04,
      socialInflation: 0.06,
      economicCycle: 'expansion',
    },
  },
  aiBinding
);

// Returns: LossRatioPrediction
// { forecastLossRatio, lowerBound90, upperBound90, trend, keyDrivers[] }

`scorePricingAdequacy(currentPremium, predictedLossRatio, expenses)`

Evaluates whether current pricing is adequate:

const adequacy = scorePricingAdequacy(1_200, 0.68, 0.15);
// { adequate: false, score: 42, deficiencyPercent: 0.17, recommendedAdjustment: 1.24 }

Retention & Portfolio Health (`predictive.ts`)

`scoreRetention(policy, claims, paymentHistory)`

Predicts renewal retention risk:

const score = scoreRetention(policy, claims, payments);
// { score: 78, riskLevel: 'medium', factors: ['3 claims this term', 'premium increase > 15%'] }

Risk levels: low (80+) · medium (60–79) · high (40–59) · critical (<40)

`findCrossSellopportunities(insured, policies)`

Identifies cross-sell opportunities based on current coverages and industry:

const opps = findCrossSellOpportunities(insured, activePolicies);
// [{ recommendedLob: 'Cyber', estimatedPremium: 4800, priority: 'high', reasoning: '...' }]

Premium factors by LOB: GL 1.0× · WC 1.2× · BOP 0.8× · Commercial Auto 1.1× · Cyber 2.2×

`computePortfolioHealth(policies)`

Portfolio concentration and at-risk premium analysis:

const health = computePortfolioHealth(policies);
// { concentrationIndex, topLobs, topStates, atRiskPremium, herfindahlIndex }

herfindahlIndex > 0.25 signals dangerous concentration in a single LOB or state.

AI Spend Monitoring (`ai-spend.ts`)

`detectSpendAnomaly(dailyCosts, multiplier?)`

Detects AI API cost spikes using a rolling 7-day average:

const result = detectSpendAnomaly(last30Days, 3.0);
// { isAnomaly: true, currentCost: 142.50, avgCost: 38.20, ratio: 3.73 }

Default multiplier is 3.0 — anything 3× the rolling average triggers an anomaly alert. Used by the cron job (apps/api/src/cron/portfolio-sweep.ts) to emit a queue event when AI costs spike.

Event Tracking

Tinybird Integration

import { trackEvent } from '@openinsure/analytics';

await trackEvent(
  'submission.quoted',
  {
    submissionId: 'sub_123',
    orgId: 'org_456',
    premium: 12500,
    lineOfBusiness: 'GL',
    state: 'NC',
  },
  env.ANALYTICS_ENGINE
);

Events flow to Tinybird via Cloudflare Analytics Engine. The ANALYTICS_ENGINE binding is configured in wrangler.toml under [analytics_engine_datasets].

Analytics Engine (CF Native)

For high-throughput events (policy bound, claim opened, payment processed), the API writes directly to the CF Analytics Engine binding — zero latency, no HTTP call:

env.ANALYTICS_ENGINE.writeDataPoint({
  blobs: [submissionId, orgId, lob, state],
  doubles: [premium, claimCount, reserveAmount],
  indexes: [orgId],
});

API Routes

The analytics package powers these API endpoints:

Route	Description
`GET /v1/analytics/mga`	MGA portfolio KPIs
`GET /v1/analytics/captive`	Captive fund KPIs
`GET /v1/analytics/pipeline`	Submission funnel metrics
`GET /v1/analytics/entities`	Entity-level analytics
`GET /v1/analytics/compliance`	Filing status breakdown
`GET /v1/analytics/claims`	Claims frequency and severity

All routes accept ?period=ytd|qtd|mtd and ?orgId= filters.

Adding Custom KPIs

Extend compute.ts by adding a new function:

export function computeMyKPI(data: MyData): MyKPIResult {
  // deterministic calculation — no side effects
  return { ... };
}

Add the corresponding API route in apps/api/src/routes/analytics.ts and update the Tinybird datasource schema if new event types are needed.

Finance Portal

AR aging, statutory reports, and TigerBeetle ledger.

AI Agents

Predictive underwriting and claims AI agents.

Getting Started

Platform

Portals

MGA

Captive

Compliance

Integrations

User Guides

Operations Manuals

Contributing

Modules

Portfolio KPIs (`compute.ts`)

`computeMGAKPIs(policies, claims, submissions)`

`computeCaptiveKPIs(policies, claims, members)`

`summarizeClaims(claims)`

`computeSubmissionPipelineKPIs(submissions)`

Predictive Modeling (`predict.ts`)

`predictLossRatio(input: LossRatioPredictionInput)`

`scorePricingAdequacy(currentPremium, predictedLossRatio, expenses)`

Retention & Portfolio Health (`predictive.ts`)

`scoreRetention(policy, claims, paymentHistory)`

`findCrossSellopportunities(insured, policies)`

`computePortfolioHealth(policies)`

AI Spend Monitoring (`ai-spend.ts`)

`detectSpendAnomaly(dailyCosts, multiplier?)`

Event Tracking

Tinybird Integration

Analytics Engine (CF Native)

API Routes

Adding Custom KPIs

Finance Portal

AI Agents

Getting Started

Platform

Portals

MGA

Captive

Compliance

Integrations

User Guides

Operations Manuals

Contributing

​Modules

​Portfolio KPIs (compute.ts)

​computeMGAKPIs(policies, claims, submissions)

​computeCaptiveKPIs(policies, claims, members)

​summarizeClaims(claims)

​computeSubmissionPipelineKPIs(submissions)

​Predictive Modeling (predict.ts)

​predictLossRatio(input: LossRatioPredictionInput)

​scorePricingAdequacy(currentPremium, predictedLossRatio, expenses)

​Retention & Portfolio Health (predictive.ts)

​scoreRetention(policy, claims, paymentHistory)

​findCrossSellopportunities(insured, policies)

​computePortfolioHealth(policies)

​AI Spend Monitoring (ai-spend.ts)

​detectSpendAnomaly(dailyCosts, multiplier?)

​Event Tracking

​Tinybird Integration

​Analytics Engine (CF Native)

​API Routes

​Adding Custom KPIs

​Finance Portal

​AI Agents

Modules

Portfolio KPIs (`compute.ts`)

`computeMGAKPIs(policies, claims, submissions)`

`computeCaptiveKPIs(policies, claims, members)`

`summarizeClaims(claims)`

`computeSubmissionPipelineKPIs(submissions)`

Predictive Modeling (`predict.ts`)

`predictLossRatio(input: LossRatioPredictionInput)`

`scorePricingAdequacy(currentPremium, predictedLossRatio, expenses)`

Retention & Portfolio Health (`predictive.ts`)

`scoreRetention(policy, claims, paymentHistory)`

`findCrossSellopportunities(insured, policies)`

`computePortfolioHealth(policies)`

AI Spend Monitoring (`ai-spend.ts`)

`detectSpendAnomaly(dailyCosts, multiplier?)`

Event Tracking

Tinybird Integration

Analytics Engine (CF Native)

API Routes

Adding Custom KPIs

Finance Portal

AI Agents