@civiq/entity-resolution 0.1.0

package/dist/sic-sector-map.js

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2019-2025 Mark Sandford
+ * Licensed under the MIT License. See LICENSE and NOTICE files.
+ */
+/**
+ * SIC Code to IndustrySector Mapping
+ *
+ * Maps Standard Industrial Classification (SIC) code ranges to the
+ * IndustrySector enum from src/lib/fec/industry-taxonomy.ts.
+ *
+ * SIC codes are 4-digit numbers organized into divisions:
+ *   0100-0999: Agriculture, Forestry, Fishing
+ *   1000-1499: Mining
+ *   1500-1799: Construction
+ *   2000-3999: Manufacturing
+ *   4000-4999: Transportation, Communications, Utilities
+ *   5000-5199: Wholesale Trade
+ *   5200-5999: Retail Trade
+ *   6000-6799: Finance, Insurance, Real Estate
+ *   7000-8999: Services
+ *   9100-9999: Public Administration
+ *
+ * Some ranges are further subdivided to match the OpenSecrets-style
+ * 13-sector model used across CIV.IQ.
+ */
+import { IndustrySector } from './industry-taxonomy';
+/**
+ * Ordered list of SIC code ranges mapped to IndustrySector.
+ * More specific ranges precede broader ones.
+ */
+const SIC_RANGES = [
+    // Agriculture, Forestry, Fishing (0100-0999)
+    { start: 100, end: 999, sector: IndustrySector.AGRIBUSINESS },
+    // Mining (1000-1499) — Energy/Natural Resources
+    { start: 1000, end: 1499, sector: IndustrySector.ENERGY_NATURAL_RESOURCES },
+    // Construction (1500-1799)
+    { start: 1500, end: 1799, sector: IndustrySector.CONSTRUCTION },
+    // Manufacturing — Food products (2000-2099) → Agribusiness
+    { start: 2000, end: 2099, sector: IndustrySector.AGRIBUSINESS },
+    // Manufacturing — Tobacco, Textiles, Wood, Paper, Printing (2100-2799) → Misc Business
+    { start: 2100, end: 2799, sector: IndustrySector.MISC_BUSINESS },
+    // Manufacturing — Chemicals, Pharmaceuticals (2800-2899) → Health
+    { start: 2800, end: 2899, sector: IndustrySector.HEALTH },
+    // Manufacturing — Petroleum refining, Rubber, Plastics (2900-3099) → Energy
+    { start: 2900, end: 3099, sector: IndustrySector.ENERGY_NATURAL_RESOURCES },
+    // Manufacturing — Stone, Clay, Glass, Primary Metals, Fabricated Metals (3100-3499) → Misc Business
+    { start: 3100, end: 3499, sector: IndustrySector.MISC_BUSINESS },
+    // Manufacturing — Industrial machinery, Computers (3500-3599) → Communications/Electronics
+    { start: 3500, end: 3599, sector: IndustrySector.COMMUNICATIONS_ELECTRONICS },
+    // Manufacturing — Electronic components, Semiconductors (3600-3699) → Communications/Electronics
+    { start: 3600, end: 3699, sector: IndustrySector.COMMUNICATIONS_ELECTRONICS },
+    // Manufacturing — Transportation equipment (3700-3799) → Transportation
+    { start: 3700, end: 3719, sector: IndustrySector.TRANSPORTATION },
+    // Manufacturing — Aircraft, Guided missiles, Space vehicles (3720-3799) → Defense
+    { start: 3720, end: 3799, sector: IndustrySector.DEFENSE },
+    // Manufacturing — Instruments, Medical devices (3800-3899) → Health
+    { start: 3800, end: 3899, sector: IndustrySector.HEALTH },
+    // Manufacturing — Misc manufacturing (3900-3999) → Misc Business
+    { start: 3900, end: 3999, sector: IndustrySector.MISC_BUSINESS },
+    // Transportation — Railroad, Trucking, Water, Air (4000-4599) → Transportation
+    { start: 4000, end: 4599, sector: IndustrySector.TRANSPORTATION },
+    // Transportation — Pipelines (4600-4699) → Energy
+    { start: 4600, end: 4699, sector: IndustrySector.ENERGY_NATURAL_RESOURCES },
+    // Communications — Telephone, Radio, TV, Cable (4700-4899) → Communications/Electronics
+    { start: 4700, end: 4899, sector: IndustrySector.COMMUNICATIONS_ELECTRONICS },
+    // Utilities — Electric, Gas, Water, Sanitary (4900-4999) → Energy
+    { start: 4900, end: 4999, sector: IndustrySector.ENERGY_NATURAL_RESOURCES },
+    // Wholesale Trade (5000-5199) → Misc Business
+    { start: 5000, end: 5199, sector: IndustrySector.MISC_BUSINESS },
+    // Retail Trade (5200-5999) → Misc Business
+    { start: 5200, end: 5999, sector: IndustrySector.MISC_BUSINESS },
+    // Finance, Insurance, Real Estate (6000-6797)
+    { start: 6000, end: 6797, sector: IndustrySector.FINANCE_INSURANCE_REAL_ESTATE },
+    // Services — Hotels, Personal services (7000-7299) → Misc Business
+    { start: 7000, end: 7299, sector: IndustrySector.MISC_BUSINESS },
+    // Services — Business services, Computer programming (7300-7399) → Communications/Electronics
+    { start: 7300, end: 7399, sector: IndustrySector.COMMUNICATIONS_ELECTRONICS },
+    // Services — Auto repair, Misc repair, Entertainment (7400-7999) → Misc Business
+    { start: 7400, end: 7999, sector: IndustrySector.MISC_BUSINESS },
+    // Services — Health services (8000-8099) → Health
+    { start: 8000, end: 8099, sector: IndustrySector.HEALTH },
+    // Services — Legal services (8100-8199) → Lawyers & Lobbyists
+    { start: 8100, end: 8199, sector: IndustrySector.LAWYERS_LOBBYISTS },
+    // Services — Education (8200-8299) → Ideology/Single-Issue
+    { start: 8200, end: 8299, sector: IndustrySector.IDEOLOGY_SINGLE_ISSUE },
+    // Services — Social services, Museums, Membership orgs (8300-8699) → Ideology/Single-Issue
+    { start: 8300, end: 8699, sector: IndustrySector.IDEOLOGY_SINGLE_ISSUE },
+    // Services — Engineering, Accounting, Research, Management (8700-8999) → Misc Business
+    { start: 8700, end: 8999, sector: IndustrySector.MISC_BUSINESS },
+    // Public Administration (9100-9999) → Other
+    { start: 9100, end: 9999, sector: IndustrySector.OTHER },
+];
+/**
+ * Resolve a 4-digit SIC code string to an IndustrySector.
+ * Returns null if the code is invalid or falls outside all known ranges.
+ */
+export function sicToSector(sicCode) {
+    const code = parseInt(sicCode, 10);
+    if (isNaN(code) || code < 100 || code > 9999) {
+        return null;
+    }
+    for (const range of SIC_RANGES) {
+        if (code >= range.start && code <= range.end) {
+            return range.sector;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=sic-sector-map.js.map

package/dist/sic-sector-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sic-sector-map.js","sourceRoot":"","sources":["../src/sic-sector-map.ts"],"names":[],"mappings":"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"}

package/dist/ticker-industry-resolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2019-2025 Mark Sandford
+ * Licensed under the MIT License. See LICENSE and NOTICE files.
+ */
+import type { TickerResolution } from './types';
+/**
+ * Resolve a stock ticker to an IndustrySector.
+ *
+ * Returns null for ETFs, mutual funds, and tickers that can't be resolved.
+ * Uses Redis caching for SEC API responses (30-day TTL).
+ */
+export declare function resolveTickerIndustry(ticker: string): Promise<TickerResolution | null>;
+/**
+ * Resolve multiple stock tickers to IndustrySectors in parallel.
+ *
+ * Deduplicates tickers, checks cache in batch, then resolves remaining
+ * tickers concurrently (max 5 parallel SEC API requests).
+ *
+ * Returns a Map from normalized ticker to resolution (null for unresolvable).
+ */
+export declare function resolveTickerIndustries(tickers: string[]): Promise<Map<string, TickerResolution | null>>;
+//# sourceMappingURL=ticker-industry-resolver.d.ts.map

package/dist/ticker-industry-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticker-industry-resolver.d.ts","sourceRoot":"","sources":["../src/ticker-industry-resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAsDhD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAiE5F;AAqCD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC,CAAC,CAqD/C"}

package/dist/ticker-industry-resolver.js

@@ -0,0 +1,254 @@
+/**
+ * Copyright (c) 2019-2025 Mark Sandford
+ * Licensed under the MIT License. See LICENSE and NOTICE files.
+ */
+/**
+ * Ticker-to-Industry Resolver
+ *
+ * Resolves stock tickers from House Clerk disclosure filings to
+ * IndustrySector using SEC EDGAR data + SIC code mapping.
+ *
+ * Flow: ticker → CIK (static lookup) → SIC code (SEC API, cached) → IndustrySector
+ *
+ * ETFs, mutual funds, and unresolvable tickers return null.
+ */
+import { getLogger } from './logger';
+import { getCache } from './cache';
+import { sicToSector } from './sic-sector-map';
+// Static ticker → CIK mapping from SEC EDGAR company_tickers.json
+// ~10K entries, ~155KB
+import tickerCikMap from '../data/sec-sic-data.json';
+/** SIC code cache TTL: 30 days (SIC codes rarely change) */
+const SIC_CACHE_TTL = 30 * 24 * 60 * 60;
+/** SEC EDGAR submissions API base URL */
+const SEC_SUBMISSIONS_URL = 'https://data.sec.gov/submissions';
+/** SEC requires a User-Agent header identifying the requester */
+const SEC_USER_AGENT = 'CIV.IQ civic-intel-hub/1.0 (civdotiq.org)';
+/**
+ * Known ETF/fund tickers that should return null (no single sector).
+ * This is not exhaustive — the resolver also returns null for tickers
+ * not found in the SEC company data.
+ */
+const KNOWN_FUNDS = new Set([
+    'SPY',
+    'QQQ',
+    'IWM',
+    'DIA',
+    'VTI',
+    'VOO',
+    'VEA',
+    'VWO',
+    'EFA',
+    'AGG',
+    'BND',
+    'TLT',
+    'GLD',
+    'SLV',
+    'USO',
+    'XLF',
+    'XLE',
+    'XLK',
+    'XLV',
+    'XLI',
+    'XLP',
+    'XLY',
+    'XLB',
+    'XLU',
+    'XLRE',
+    'XLC',
+    'ARKK',
+    'ARKW',
+    'ARKG',
+    'ARKF',
+    'ARKQ',
+]);
+/**
+ * Resolve a stock ticker to an IndustrySector.
+ *
+ * Returns null for ETFs, mutual funds, and tickers that can't be resolved.
+ * Uses Redis caching for SEC API responses (30-day TTL).
+ */
+export async function resolveTickerIndustry(ticker) {
+    const normalizedTicker = ticker.toUpperCase().trim();
+    if (!normalizedTicker) {
+        return null;
+    }
+    // Skip known funds/ETFs
+    if (KNOWN_FUNDS.has(normalizedTicker)) {
+        return null;
+    }
+    // Check Redis cache first
+    const cacheKey = `ticker-sic:${normalizedTicker}`;
+    try {
+        const cached = await getCache().get(cacheKey);
+        if (cached === 'null') {
+            return null;
+        }
+        if (cached) {
+            return cached;
+        }
+    }
+    catch {
+        // Cache miss or error — continue to resolution
+    }
+    // Look up CIK from static data
+    const cik = tickerCikMap[normalizedTicker];
+    if (!cik) {
+        getLogger().debug(`[TickerResolver] No CIK found for ticker: ${normalizedTicker}`);
+        await cacheMiss(cacheKey);
+        return null;
+    }
+    // Fetch SIC code from SEC EDGAR API
+    const sicCode = await fetchSicCode(cik);
+    if (!sicCode) {
+        await cacheMiss(cacheKey);
+        return null;
+    }
+    // Map SIC code to IndustrySector
+    const sector = sicToSector(sicCode);
+    if (!sector) {
+        getLogger().debug(`[TickerResolver] SIC ${sicCode} has no sector mapping for ${normalizedTicker}`);
+        await cacheMiss(cacheKey);
+        return null;
+    }
+    const result = {
+        sector,
+        sicCode,
+        confidence: 1.0,
+    };
+    // Cache successful resolution
+    try {
+        await getCache().set(cacheKey, result, SIC_CACHE_TTL);
+    }
+    catch {
+        // Cache write failure is non-fatal
+    }
+    return result;
+}
+/**
+ * Fetch SIC code from SEC EDGAR submissions API.
+ * The CIK is zero-padded to 10 digits per SEC convention.
+ */
+async function fetchSicCode(cik) {
+    const paddedCik = String(cik).padStart(10, '0');
+    const url = `${SEC_SUBMISSIONS_URL}/CIK${paddedCik}.json`;
+    try {
+        const response = await fetch(url, {
+            headers: { 'User-Agent': SEC_USER_AGENT },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!response.ok) {
+            getLogger().warn(`[TickerResolver] SEC API returned ${response.status} for CIK ${cik}`);
+            return null;
+        }
+        const data = await response.json();
+        const sic = data?.sic;
+        if (!sic) {
+            return null;
+        }
+        return String(sic);
+    }
+    catch (error) {
+        getLogger().error('[TickerResolver] SEC API fetch failed', error, {
+            cik: String(cik),
+        });
+        return null;
+    }
+}
+/**
+ * Resolve multiple stock tickers to IndustrySectors in parallel.
+ *
+ * Deduplicates tickers, checks cache in batch, then resolves remaining
+ * tickers concurrently (max 5 parallel SEC API requests).
+ *
+ * Returns a Map from normalized ticker to resolution (null for unresolvable).
+ */
+export async function resolveTickerIndustries(tickers) {
+    const results = new Map();
+    // Deduplicate and normalize
+    const uniqueTickers = [...new Set(tickers.map(t => t.toUpperCase().trim()).filter(Boolean))];
+    if (uniqueTickers.length === 0) {
+        return results;
+    }
+    // Separate known funds (instant null)
+    const resolvable = [];
+    for (const ticker of uniqueTickers) {
+        if (KNOWN_FUNDS.has(ticker)) {
+            results.set(ticker, null);
+        }
+        else {
+            resolvable.push(ticker);
+        }
+    }
+    // Batch cache lookup
+    const cacheKeys = resolvable.map(t => `ticker-sic:${t}`);
+    const cached = await Promise.all(cacheKeys.map(key => getCache()
+        .get(key)
+        .catch(() => null)));
+    const uncached = [];
+    for (let i = 0; i < resolvable.length; i++) {
+        const hit = cached[i];
+        if (hit === 'null') {
+            results.set(resolvable[i], null);
+        }
+        else if (hit) {
+            results.set(resolvable[i], hit);
+        }
+        else {
+            uncached.push(resolvable[i]);
+        }
+    }
+    // Resolve uncached tickers with concurrency limit
+    const CONCURRENCY = 5;
+    for (let i = 0; i < uncached.length; i += CONCURRENCY) {
+        const batch = uncached.slice(i, i + CONCURRENCY);
+        const resolved = await Promise.all(batch.map(t => resolveSingle(t)));
+        for (let j = 0; j < batch.length; j++) {
+            results.set(batch[j], resolved[j]);
+        }
+    }
+    return results;
+}
+/**
+ * Resolve a single ticker (no cache check — used by batch after cache miss).
+ */
+async function resolveSingle(normalizedTicker) {
+    const cacheKey = `ticker-sic:${normalizedTicker}`;
+    const cik = tickerCikMap[normalizedTicker];
+    if (!cik) {
+        getLogger().debug(`[TickerResolver] No CIK found for ticker: ${normalizedTicker}`);
+        await cacheMiss(cacheKey);
+        return null;
+    }
+    const sicCode = await fetchSicCode(cik);
+    if (!sicCode) {
+        await cacheMiss(cacheKey);
+        return null;
+    }
+    const sector = sicToSector(sicCode);
+    if (!sector) {
+        getLogger().debug(`[TickerResolver] SIC ${sicCode} has no sector mapping for ${normalizedTicker}`);
+        await cacheMiss(cacheKey);
+        return null;
+    }
+    const result = { sector, sicCode, confidence: 1.0 };
+    try {
+        await getCache().set(cacheKey, result, SIC_CACHE_TTL);
+    }
+    catch {
+        // Non-fatal
+    }
+    return result;
+}
+/**
+ * Cache a null result to avoid repeated lookups for unresolvable tickers.
+ */
+async function cacheMiss(cacheKey) {
+    try {
+        await getCache().set(cacheKey, 'null', SIC_CACHE_TTL);
+    }
+    catch {
+        // Non-fatal
+    }
+}
+//# sourceMappingURL=ticker-industry-resolver.js.map

package/dist/ticker-industry-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticker-industry-resolver.js","sourceRoot":"","sources":["../src/ticker-industry-resolver.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2019-2025 Mark Sandford
+ * Licensed under the MIT License. See LICENSE and NOTICE files.
+ */
+import type { IndustrySector } from './industry-taxonomy';
+/** Result of resolving a single LDA government_entities string. */
+export interface GovernmentEntityResolution {
+    /** Original text from the LDA filing. */
+    rawText: string;
+    /** Resolution outcome. */
+    type: 'committee' | 'agency' | 'noise' | 'unresolved';
+    /** Committee code (e.g., "SSFI") if resolved to a committee. */
+    committeeCode?: string;
+    /** Committee name if resolved. */
+    committeeName?: string;
+    /** Agency slug if resolved to an agency. */
+    agencySlug?: string;
+    /** Resolution confidence: 1.0 for exact, 0.85+ for fuzzy, 0 for noise. */
+    confidence: number;
+}
+/**
+ * Result of resolving a stock ticker to an industry sector.
+ * Returns null for ETFs, mutual funds, and unresolvable tickers.
+ */
+export interface TickerResolution {
+    sector: IndustrySector;
+    sicCode: string;
+    confidence: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,mEAAmE;AACnE,MAAM,WAAW,0BAA0B;IACzC,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;IACtD,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2019-2025 Mark Sandford
+ * Licensed under the MIT License. See LICENSE and NOTICE files.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@civiq/entity-resolution",
+  "version": "0.1.0",
+  "description": "Entity resolution for civic data — committee/agency alias matching, industry taxonomy, ticker-to-sector resolution, FEC entity deduplication",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./industry-taxonomy": {
+      "types": "./dist/industry-taxonomy.d.ts",
+      "import": "./dist/industry-taxonomy.js"
+    },
+    "./committee-agency-map": {
+      "types": "./dist/committee-agency-map.d.ts",
+      "import": "./dist/committee-agency-map.js"
+    }
+  },
+  "files": [
+    "dist",
+    "data"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "fuse.js": "^7.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT",
+  "author": "Mark Sandford",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/civiq/entity-resolution"
+  },
+  "keywords": [
+    "entity-resolution",
+    "civic",
+    "government",
+    "committee",
+    "fec",
+    "civic-tech"
+  ]
+}