@civiq/entity-resolution 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2025 Mark Sandford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @civiq/entity-resolution
+
+Entity resolution for civic data — committee/agency alias matching, industry taxonomy, ticker-to-sector resolution, FEC entity deduplication.
+
+## Install
+
+```bash
+npm install @civiq/entity-resolution
+```
+
+## Quick Start
+
+```typescript
+import {
+  configure,
+  categorizeContribution,
+  resolveGovernmentEntity,
+  resolveTickerIndustry,
+  deduplicateContributions,
+} from '@civiq/entity-resolution';
+
+// Optional: provide your own logger and cache
+configure({
+  logger: myLogger,
+  cache: myRedisAdapter,
+});
+
+// Categorize a campaign contribution by employer/occupation
+const result = categorizeContribution('Goldman Sachs', 'Investment Banker');
+// { sector: 'Finance/Insurance/Real Estate', category: 'Commercial Banks', confidence: 'high', ... }
+
+// Resolve LDA government_entities to committees/agencies
+const entity = resolveGovernmentEntity('Senate Committee on Finance');
+// { type: 'committee', committeeCode: 'SSFI', committeeName: 'Finance', confidence: 1.0, ... }
+
+// Resolve stock ticker to industry sector (async, uses SEC EDGAR)
+const ticker = await resolveTickerIndustry('AAPL');
+// { sector: 'Communications/Electronics', sicCode: '3571', confidence: 1.0 }
+
+// Deduplicate FEC contributions by entity
+const unique = deduplicateContributions(rawContributions);
+```
+
+## Subpath Exports
+
+```typescript
+// Just the industry taxonomy
+import { IndustrySector, categorizeContribution } from '@civiq/entity-resolution/industry-taxonomy';
+
+// Just the committee-agency mapping
+import {
+  ALL_COMMITTEE_MAPPINGS,
+  getAgenciesForCommittee,
+} from '@civiq/entity-resolution/committee-agency-map';
+```
+
+## Configuration
+
+By default, the package uses no-op logger and no-op cache. For production use, call `configure()` once at startup:
+
+```typescript
+import { configure } from '@civiq/entity-resolution';
+
+configure({
+  logger: {
+    debug: console.log,
+    info: console.log,
+    warn: console.warn,
+    error: console.error,
+  },
+  cache: {
+    get: async key => redis.get(key),
+    set: async (key, value, ttl) => redis.set(key, value, 'EX', ttl),
+  },
+});
+```
+
+## API Reference
+
+### Industry Taxonomy
+
+- `categorizeContribution(employer?, occupation?)` — Classify by employer/occupation keywords
+- `categorizePACByName(name?)` — Classify PAC/committee by name
+- `categorizeContributionSmart(employer?, occupation?, name?)` — Try all methods
+- `aggregateByIndustrySector(contributions)` — Aggregate contributions by sector
+- `getTopCategories(contributions, limit?)` — Top categories across sectors
+
+### Committee-Agency Map
+
+- `getAgenciesForCommittee(name)` — Agencies a committee oversees
+- `getCommitteesForAgency(slug)` — Committees that oversee an agency
+- `getTopicsForCommittee(name)` — Topics for a committee
+- `ALL_COMMITTEE_MAPPINGS` — All 29 committee mappings
+
+### Lobbying Resolution
+
+- `resolveGovernmentEntity(entity)` — 3-tier resolution (noise/exact/fuzzy)
+- `resolveFilingEntities(entities)` — Batch resolution
+- `getResolvedCommittees(resolutions)` — Extract committee codes
+
+### Ticker Resolution
+
+- `resolveTickerIndustry(ticker)` — Ticker to IndustrySector via SEC EDGAR
+
+### SIC Mapping
+
+- `sicToSector(sicCode)` — SIC code to IndustrySector
+
+### LDA Issue Mapping
+
+- `getLDAIssueLabel(code)` — Human-readable label
+- `getPolicyAreasForLDAIssue(code)` — Congress.gov policyArea strings
+
+### FEC Entity Resolution
+
+- `deduplicateContributions(contributions)` — Merge name variants
+- `deduplicateDisbursements(disbursements)` — Merge recipients
+- `entitiesMatch(entity1, entity2, threshold?)` — Levenshtein similarity
+
+### Bioguide-FEC Mapping
+
+- `getFECIdFromBioguide(id)` — Bioguide ID to FEC candidate ID
+- `getBioguideFromFEC(id)` — Reverse lookup
+
+## Data Sources
+
+- FEC.gov — Contributor employer/occupation, PAC names
+- Senate LDA API — Lobbying government entities, issue codes
+- SEC EDGAR — Company tickers, SIC codes
+- Congress.gov — Bill policy areas, committee assignments
+- OpenSecrets — 13-sector classification model (inspiration)
+
+## License
+
+MIT - Mark Sandford