@pgsage/loaders 0.1.0

package/dist/census/loader.js.map

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

package/dist/census/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared types for the Census ACS loader.
+ */
+export interface CensusConfig {
+    /** Census Bureau API key. Required for all data requests. */
+    apiKey: string;
+    /** ACS 5-Year vintage (data year). Default: 2024. */
+    vintage: number;
+    /** Census API base URL. Default: 'https://api.census.gov/data'. */
+    baseUrl: string;
+    /** pg connection string for the app/admin role. */
+    databaseUrl: string;
+    /** Voyage AI API key for embedding the schema. */
+    voyageApiKey: string;
+    /**
+     * Smoke-test mode: restrict the load to a single state (Rhode Island,
+     * FIPS 44) and a small subset of variables to validate the pipeline
+     * quickly without a full Census API run.
+     * Default: false.
+     */
+    smoke?: boolean;
+    /**
+     * Milliseconds to wait between Census API batch requests.
+     * Default: 200 ms — polite to the Census API.
+     */
+    batchDelayMs?: number;
+    /** Maximum fetch retries on 429/5xx. Default: 3. */
+    maxRetries?: number;
+    /** Fetch timeout in milliseconds. Default: 30_000. */
+    requestTimeoutMs?: number;
+}
+export type GeoLevel = "state" | "county";
+export interface GeoRecord {
+    geoId: string;
+    stateFips: string;
+    countyFips: string | null;
+    stateName: string;
+    countyName: string | null;
+    level: GeoLevel;
+}
+export interface VariableDefinition {
+    /** ACS estimate variable code, e.g. 'B19013_001E'. */
+    code: string;
+    /** Human-readable label, cleaned of the 'Estimate!!' prefix. */
+    label: string;
+    /** The ACS table concept, e.g. 'Median Household Income'. */
+    concept: string;
+    /** Broad category for retrieval grouping. */
+    category: VariableCategory;
+    /** ACS group/table this variable belongs to, e.g. 'B19013'. */
+    group: string;
+}
+export type VariableCategory = "income" | "poverty" | "housing" | "employment" | "demographics" | "education" | "transportation" | "health_insurance";
+export interface EstimateRecord {
+    geoId: string;
+    variableCode: string;
+    estimate: number | null;
+    marginError: number | null;
+}
+/**
+ * The Census API returns a 2D array of strings. Row 0 is the header
+ * (column names). Subsequent rows are data. All values are strings;
+ * null/missing data is represented as the string "null" or an empty string.
+ */
+export type CensusApiResponse = string[][];
+export interface LoadSummary {
+    geographiesUpserted: number;
+    variablesUpserted: number;
+    estimatesUpserted: number;
+    embeddingTokens: number;
+    elapsedMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/census/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/census/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,SAAS,GACT,SAAS,GACT,YAAY,GACZ,cAAc,GACd,WAAW,GACX,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAMD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,EAAE,EAAE,CAAC;AAM3C,MAAM,WAAW,WAAW;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/census/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for the Census ACS loader.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/census/types.js.map

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

package/dist/census/variables.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Curated ACS 5-Year variable list for pgsage v1.
+ *
+ * Source: 2024 ACS 5-Year Detailed Tables (https://api.census.gov/data/2024/acs/acs5)
+ * Vintage: 2024
+ *
+ * Selection strategy:
+ * - Include all variables from compact groups (single-value summaries, income
+ *   brackets, housing, transportation, education).
+ * - Cherry-pick totals and key breakdowns from large crosscut groups (poverty
+ *   by sex×age, employment by sex×age, health insurance by sex×age, sex×age
+ *   distribution) to avoid loading hundreds of rarely-queried sub-cells.
+ * - All variables are estimate codes (_E suffix). Their paired margin-of-error
+ *   codes (_M suffix) are fetched automatically by the API client.
+ */
+import type { VariableDefinition } from "./types.js";
+export declare const CENSUS_VARIABLES: VariableDefinition[];
+/**
+ * All valid VariableCategory values.
+ */
+export declare const VARIABLE_CATEGORIES: VariableDefinition["category"][];
+/**
+ * A small subset of variables used for smoke-test runs (--smoke flag).
+ * Covers all 8 categories with 1-2 representative variables each.
+ */
+export declare const SMOKE_TEST_VARIABLES: VariableDefinition[];
+//# sourceMappingURL=variables.d.ts.map

package/dist/census/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../src/census/variables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,eAAO,MAAM,gBAAgB,EAAE,kBAAkB,EAwxDhD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,kBAAkB,CAAC,UAAU,CAAC,EAS/D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAWpD,CAAC"}