labre-mcp 0.1.0

package/dist/lib/patent/bigquery-query-builders.d.mts

@@ -0,0 +1,205 @@
+/**
+ * Shared context for all query builder functions.
+ *
+ * @typedef {Object} QueryContext
+ * @property {string}   dataset     - Fully-qualified BigQuery dataset (e.g. 'patents-public-data')
+ * @property {string[]} cpcCodes    - 4-char CPC subclass codes (e.g. ['G06F', 'H04L'])
+ * @property {number}   minYear     - Minimum filing year filter (default: 2000)
+ * @property {number}   maxPatents  - Maximum patents to scan per query (default: 100,000)
+ */
+/**
+ * Built query ready for BigQuery execution via client.query().
+ *
+ * @typedef {Object} BuiltQuery
+ * @property {string} sql    - Parameterized SQL string (uses @named_params)
+ * @property {Object} params - Named parameter values (e.g. { cpc_codes: ['G06F'] })
+ * @property {Object} types  - BigQuery parameter type declarations
+ * @property {string} name   - Human-readable query name (for logging/tracing)
+ */
+export interface QueryContext {
+    dataset: string;
+    cpcCodes: string[];
+    minYear: number;
+    maxPatents: number;
+}
+export interface BuiltQuery {
+    sql: string;
+    params: Record<string, unknown>;
+    types: Record<string, unknown>;
+    name: string;
+}
+/**
+ * Create a QueryContext from CPC codes and optional overrides.
+ *
+ * @param {string[]} cpcCodes - Array of CPC codes (4-char subclass or more specific prefixes)
+ * @param {Object}   [options]
+ * @param {string}   [options.dataset]    - BigQuery dataset override
+ * @param {number}   [options.minYear]    - Minimum filing year
+ * @param {number}   [options.maxPatents] - Maximum patents per query
+ * @returns {QueryContext}
+ */
+export declare function createQueryContext(cpcCodes: string[], options?: {
+    dataset?: string;
+    minYear?: number;
+    maxPatents?: number;
+}): QueryContext;
+/**
+ * Build query for CPC subclass patent count distribution.
+ *
+ * Returns one row per CPC subclass code found across patents matching the
+ * input CPC codes, with the count of distinct publications in each subclass.
+ * This feeds the HHI concentration metric in convergenceHHI().
+ *
+ * Result columns: cpc (STRING), count (INT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildCpcDistributionQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for year-over-year CPC classification snapshots.
+ *
+ * Returns one row per filing year, each containing an array of distinct CPC
+ * subclass codes used in patents filed that year. This feeds the Jaccard
+ * stability metric in stabiliteTaxonomique().
+ *
+ * Result columns: year (INT64), cpc_codes (ARRAY<STRING>)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildYearlyClassificationsQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for forward citation density.
+ *
+ * Counts how many times patents in the target CPC class are cited by other
+ * patents (forward citations). Uses a self-join via the citation array.
+ * Includes cost controls via LIMIT on the target patent set.
+ *
+ * Result columns: patent_count (INT64), total_forward_citations (INT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildCitationDataQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for independent claims narrowing analysis.
+ *
+ * Estimates the average number of independent claims per patent per filing year.
+ * Independent claims are identified by regex: numbered claims (N.) in English
+ * claims text that do NOT contain dependent-claim phrases like "of claim N".
+ *
+ * Approximation: total claim count minus dependent claim references.
+ * Patent offices vary in formatting, so this is a best-effort estimate.
+ *
+ * Result columns: year (INT64), avg_independent_claims (FLOAT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildClaimsTimelineQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for assignee (patent holder) diversity.
+ *
+ * Counts distinct assignee names and total patent publications in the target
+ * CPC class. Uses the assignee_harmonized field for cleaned company names.
+ *
+ * Result columns: unique_assignees (INT64), total_patents (INT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildAssigneeDataQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for geographic filing coverage.
+ *
+ * Counts distinct jurisdiction (country) codes where patents in the target
+ * CPC class have been filed. Also returns the list of jurisdictions for
+ * optional analysis.
+ *
+ * Result columns: jurisdiction_count (INT64), jurisdictions (ARRAY<STRING>)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildGeoDataQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for cross-sector CPC diffusion analysis.
+ *
+ * Counts distinct CPC sections (A-H, Y — first character) and CPC main
+ * classes (first 3 characters, e.g. G06, H04) across all patents that share
+ * at least one CPC code with the target subclass. This measures how broadly
+ * the technology diffuses across different industrial sectors.
+ *
+ * Result columns: unique_sections (INT64), unique_classes (INT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildSectorDataQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for patent expiration ratio analysis.
+ *
+ * Classifies patents as expired or active based on the standard 20-year
+ * patent term from filing date. High expiration ratio indicates mature,
+ * commoditized technology.
+ *
+ * Note: This is a simplified model — actual patent expiration depends on
+ * maintenance fee payments, jurisdiction rules, and patent type. The 20-year
+ * term from filing is the standard US/EP/PCT baseline.
+ *
+ * Result columns: expired_count (INT64), total_patents (INT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildExpirationDataQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Build query for total patent count in the target CPC class.
+ * Used for data quality assessment in the confidence model.
+ *
+ * Result columns: total_patents (INT64)
+ *
+ * @param {QueryContext} ctx
+ * @returns {BuiltQuery}
+ */
+export declare function buildTotalPatentsQuery(ctx: QueryContext): BuiltQuery;
+/**
+ * Map of indicator keys to their query builder functions.
+ * Used by buildAllQueries() to construct the full query set.
+ * Keys match the PatentData field names in patent-data-source.mjs.
+ *
+ * @type {Record<string, (ctx: QueryContext) => BuiltQuery>}
+ */
+export declare const QUERY_BUILDERS: {
+    cpcDistribution: typeof buildCpcDistributionQuery;
+    yearlyClassifications: typeof buildYearlyClassificationsQuery;
+    citationData: typeof buildCitationDataQuery;
+    claimsTimeline: typeof buildClaimsTimelineQuery;
+    assigneeData: typeof buildAssigneeDataQuery;
+    geoData: typeof buildGeoDataQuery;
+    sectorData: typeof buildSectorDataQuery;
+    expirationData: typeof buildExpirationDataQuery;
+};
+/**
+ * Build all 8 indicator queries plus the total patents baseline query.
+ *
+ * Returns a map of query name -> BuiltQuery, ready for parallel execution.
+ * Individual queries can be omitted by passing an `exclude` set (useful
+ * when indicators are disabled via toggles).
+ *
+ * @param {string[]} cpcCodes  - 4-char CPC subclass codes (e.g. ['G06F', 'H04L'])
+ * @param {Object}   [options]
+ * @param {string}   [options.dataset]    - BigQuery dataset override
+ * @param {number}   [options.minYear]    - Minimum filing year (default: 2000)
+ * @param {number}   [options.maxPatents] - Max patents per query (default: 100,000)
+ * @param {Set<string>} [options.exclude] - Set of indicator keys to skip
+ * @returns {Record<string, BuiltQuery>} Map of query name -> built query
+ */
+export declare function buildAllQueries(cpcCodes: string[], options?: {
+    dataset?: string;
+    minYear?: number;
+    maxPatents?: number;
+    exclude?: Set<string>;
+}): Record<string, BuiltQuery>;
+//# sourceMappingURL=bigquery-query-builders.d.mts.map

package/dist/lib/patent/bigquery-query-builders.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigquery-query-builders.d.mts","sourceRoot":"","sources":["../../../src/lib/patent/bigquery-query-builders.mts"],"names":[],"mappings":"AAuBA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAqB9I;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CAyBvE;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CA+B7E;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CAgDpE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CA0CtE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CA+BpE;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CA6B/D;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CAgDlE;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CAoCtE;AAID;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,GAAG,UAAU,CAoBpE;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;;;CAS1B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAO,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAiBhL"}