promptspeak-mcp-server 0.1.0

package/dist/legal/courtlistener-adapter.js

@@ -0,0 +1,684 @@
+// =============================================================================
+// COURTLISTENER API ADAPTER
+// =============================================================================
+// Implements CaseDatabase interface using CourtListener's Citation Lookup API.
+// https://www.courtlistener.com/help/api/rest/v3/citation-lookup/
+//
+// CourtListener is provided by Free Law Project, a 501(c)(3) nonprofit.
+// API is rate-limited to 60 valid citations per minute.
+//
+// This adapter:
+//   1. Queries CourtListener to verify citations exist
+//   2. Caches results to reduce API calls
+//   3. Falls back gracefully on API errors
+// =============================================================================
+import { createLogger } from '../core/logging/index.js';
+const logger = createLogger('CourtListener');
+const DEFAULT_CONFIG = {
+    baseUrl: 'https://www.courtlistener.com/api/rest/v4',
+    timeoutMs: 30000,
+    enableCache: true,
+    cacheTtlMs: 24 * 60 * 60 * 1000, // 24 hours
+    maxCacheSize: 10000,
+    maxRequestsPerMinute: 55, // Stay under 60 limit
+};
+const NOMINATIVE_REPORTERS = [
+    { name: 'Dallas', abbreviation: 'Dall.', usVolumeStart: 1, usVolumeEnd: 4 },
+    { name: 'Cranch', abbreviation: 'Cranch', usVolumeStart: 5, usVolumeEnd: 13 },
+    { name: 'Wheaton', abbreviation: 'Wheat.', usVolumeStart: 14, usVolumeEnd: 25 },
+    { name: 'Peters', abbreviation: 'Pet.', usVolumeStart: 26, usVolumeEnd: 41 },
+    { name: 'Howard', abbreviation: 'How.', usVolumeStart: 42, usVolumeEnd: 65 },
+    { name: 'Black', abbreviation: 'Black', usVolumeStart: 66, usVolumeEnd: 67 },
+    { name: 'Wallace', abbreviation: 'Wall.', usVolumeStart: 68, usVolumeEnd: 90 },
+];
+/**
+ * Convert a U.S. Reports citation to its nominative reporter equivalent.
+ * Example: "5 U.S. 137" → "1 Cranch 137"
+ *
+ * @returns The nominative citation string, or null if not a pre-1875 case
+ */
+function convertToNominativeCitation(volume, reporter, page) {
+    // Only apply to U.S. Reports citations
+    const normalizedReporter = reporter.toUpperCase().replace(/\./g, '').replace(/\s/g, '');
+    if (normalizedReporter !== 'US') {
+        return null;
+    }
+    // Find the nominative reporter for this volume
+    const nominative = NOMINATIVE_REPORTERS.find(r => volume >= r.usVolumeStart && volume <= r.usVolumeEnd);
+    if (!nominative) {
+        return null; // Volume 91+ uses standard U.S. Reports
+    }
+    // Calculate the nominative volume number
+    // e.g., 5 U.S. → Cranch starts at 5, so 5 - 5 + 1 = 1 Cranch
+    const nominativeVolume = volume - nominative.usVolumeStart + 1;
+    return `${nominativeVolume} ${nominative.name} ${page}`;
+}
+class CitationCache {
+    cache = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Generate cache key from citation components.
+     */
+    makeKey(volume, reporter, page) {
+        const normReporter = (reporter ?? '').replace(/\s+/g, '').toLowerCase();
+        return `${volume ?? ''}-${normReporter}-${page ?? ''}`;
+    }
+    /**
+     * Get cached result if valid.
+     */
+    get(volume, reporter, page) {
+        if (!this.config.enableCache)
+            return null;
+        const key = this.makeKey(volume, reporter, page);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        // Check if expired
+        if (Date.now() - entry.timestamp > this.config.cacheTtlMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    /**
+     * Store result in cache.
+     */
+    set(volume, reporter, page, record, apiResponse) {
+        if (!this.config.enableCache)
+            return;
+        // Evict oldest entries if at capacity
+        if (this.cache.size >= this.config.maxCacheSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        const key = this.makeKey(volume, reporter, page);
+        this.cache.set(key, {
+            record,
+            timestamp: Date.now(),
+            apiResponse,
+        });
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            hitRate: 0, // Would need hit/miss tracking for accurate rate
+        };
+    }
+    /**
+     * Clear the cache.
+     */
+    clear() {
+        this.cache.clear();
+    }
+}
+// =============================================================================
+// RATE LIMITER
+// =============================================================================
+class RateLimiter {
+    requests = [];
+    maxRequests;
+    windowMs = 60000; // 1 minute
+    constructor(maxRequestsPerMinute) {
+        this.maxRequests = maxRequestsPerMinute;
+    }
+    /**
+     * Check if we can make a request.
+     */
+    canRequest() {
+        this.cleanup();
+        return this.requests.length < this.maxRequests;
+    }
+    /**
+     * Record a request.
+     */
+    recordRequest() {
+        this.requests.push(Date.now());
+    }
+    /**
+     * Get time until next request allowed (ms).
+     */
+    getWaitTime() {
+        this.cleanup();
+        if (this.requests.length < this.maxRequests)
+            return 0;
+        const oldestRequest = this.requests[0];
+        const waitUntil = oldestRequest + this.windowMs;
+        return Math.max(0, waitUntil - Date.now());
+    }
+    /**
+     * Remove expired requests from the window.
+     */
+    cleanup() {
+        const cutoff = Date.now() - this.windowMs;
+        this.requests = this.requests.filter(t => t > cutoff);
+    }
+}
+// =============================================================================
+// COURTLISTENER CASE DATABASE
+// =============================================================================
+/**
+ * CaseDatabase implementation backed by CourtListener API.
+ *
+ * Usage:
+ *   const db = new CourtListenerCaseDatabase();
+ *   const record = await db.lookupCaseAsync('Smith', 500, 'F.3d', 123);
+ *
+ * Note: The CaseDatabase interface uses synchronous methods, but CourtListener
+ * requires async HTTP calls. This adapter provides both sync (cached-only) and
+ * async (with API fallback) methods.
+ */
+export class CourtListenerCaseDatabase {
+    config;
+    cache;
+    rateLimiter;
+    localOverrides = new Map();
+    pendingLookups = new Map();
+    // Statistics
+    stats = {
+        totalLookups: 0,
+        cacheHits: 0,
+        apiCalls: 0,
+        apiErrors: 0,
+        casesFound: 0,
+        casesNotFound: 0,
+    };
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.cache = new CitationCache(this.config);
+        this.rateLimiter = new RateLimiter(this.config.maxRequestsPerMinute);
+    }
+    // ===========================================================================
+    // CaseDatabase INTERFACE METHODS (Synchronous - Cache Only)
+    // ===========================================================================
+    /**
+     * Synchronous lookup - returns cached results only.
+     * For API-backed lookup, use lookupCaseAsync().
+     *
+     * Returns null if not in cache (caller should use async method).
+     */
+    lookupCase(caseName, volume, reporter, page) {
+        this.stats.totalLookups++;
+        // Check local overrides first
+        const overrideKey = this.makeKey(volume, reporter, page);
+        const override = this.localOverrides.get(overrideKey);
+        if (override) {
+            this.stats.cacheHits++;
+            return override;
+        }
+        // Check cache
+        const cached = this.cache.get(volume, reporter, page);
+        if (cached) {
+            this.stats.cacheHits++;
+            return cached.record;
+        }
+        // Not in cache - return null (caller should use async method)
+        return null;
+    }
+    /**
+     * Add a verified case to local overrides.
+     */
+    addVerifiedCase(record) {
+        const key = this.makeKey(record.volume, record.reporter, record.page);
+        this.localOverrides.set(key, {
+            ...record,
+            addedAt: Date.now(),
+        });
+        // Also add to cache
+        this.cache.set(record.volume, record.reporter, record.page, { ...record, addedAt: Date.now() });
+    }
+    /**
+     * Mark a case as overruled.
+     */
+    markOverruled(volume, reporter, page, overruledBy) {
+        const key = this.makeKey(volume, reporter, page);
+        // Check if in local overrides
+        const existing = this.localOverrides.get(key);
+        if (existing) {
+            this.localOverrides.set(key, {
+                ...existing,
+                overruled: true,
+                overruledBy,
+            });
+            return true;
+        }
+        // Check cache
+        const cached = this.cache.get(volume, reporter, page);
+        if (cached?.record) {
+            const updated = { ...cached.record, overruled: true, overruledBy };
+            this.cache.set(volume, reporter, page, updated, cached.apiResponse);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get database statistics.
+     */
+    getStats() {
+        const overrides = Array.from(this.localOverrides.values());
+        return {
+            totalCases: overrides.length + this.cache.getStats().size,
+            overruledCases: overrides.filter(r => r.overruled).length,
+        };
+    }
+    // ===========================================================================
+    // ASYNC LOOKUP METHODS (API-Backed)
+    // ===========================================================================
+    /**
+     * Async lookup with CourtListener API fallback.
+     * This is the preferred method for actual citation verification.
+     */
+    async lookupCaseAsync(caseName, volume, reporter, page) {
+        // Check synchronous sources first
+        const syncResult = this.lookupCase(caseName, volume, reporter, page);
+        if (syncResult)
+            return syncResult;
+        // Need volume, reporter, and page for API lookup
+        if (volume === null || reporter === null || page === null) {
+            return null;
+        }
+        // Check for pending lookup (dedup concurrent requests)
+        const key = this.makeKey(volume, reporter, page);
+        const pending = this.pendingLookups.get(key);
+        if (pending) {
+            return pending;
+        }
+        // Create new lookup promise
+        const lookupPromise = this.performApiLookup(caseName, volume, reporter, page);
+        this.pendingLookups.set(key, lookupPromise);
+        try {
+            const result = await lookupPromise;
+            return result;
+        }
+        finally {
+            this.pendingLookups.delete(key);
+        }
+    }
+    /**
+     * Lookup a citation by text (uses CourtListener's search API).
+     * Updated to use /search/ endpoint which is more reliable than /citation-lookup/.
+     *
+     * IMPORTANT: This method verifies that returned results actually contain the
+     * exact citation we're looking for, not just any document matching search terms.
+     *
+     * For pre-1875 Supreme Court cases, it will automatically try the nominative
+     * reporter format (e.g., "1 Cranch 137" instead of "5 U.S. 137").
+     */
+    async lookupByText(citationText) {
+        // Parse the citation we're looking for
+        const citationMatch = citationText.match(/(\d+)\s+([A-Za-z.\s]+?)\s+(\d+)/);
+        if (!citationMatch) {
+            logger.warn(`Could not parse citation: ${citationText}`);
+            return null;
+        }
+        const searchVolume = parseInt(citationMatch[1]);
+        const searchReporter = this.normalizeReporter(citationMatch[2]);
+        const searchPage = parseInt(citationMatch[3]);
+        // First, try the original citation
+        const result = await this.performCitationSearch(citationText, searchVolume, searchReporter, searchPage);
+        if (result) {
+            return result;
+        }
+        // If not found and it's a pre-1875 U.S. Reports citation, try nominative format
+        const nominativeCitation = convertToNominativeCitation(searchVolume, citationMatch[2], // Use original reporter text for conversion check
+        searchPage);
+        if (nominativeCitation) {
+            logger.info(`Trying nominative citation: ${nominativeCitation}`);
+            // Parse the nominative citation
+            const nomMatch = nominativeCitation.match(/(\d+)\s+([A-Za-z.\s]+?)\s+(\d+)/);
+            if (nomMatch) {
+                const nomVolume = parseInt(nomMatch[1]);
+                const nomReporter = this.normalizeReporter(nomMatch[2]);
+                const nomPage = parseInt(nomMatch[3]);
+                const nomResult = await this.performCitationSearch(nominativeCitation, nomVolume, nomReporter, nomPage);
+                if (nomResult) {
+                    // Return with original U.S. Reports citation info
+                    return {
+                        ...nomResult,
+                        volume: searchVolume,
+                        reporter: searchReporter,
+                        page: searchPage,
+                    };
+                }
+            }
+        }
+        this.stats.casesNotFound++;
+        return null;
+    }
+    /**
+     * Perform a single citation search against CourtListener API.
+     * This is the core search logic used by lookupByText.
+     */
+    async performCitationSearch(citationText, targetVolume, targetReporter, targetPage) {
+        // Check rate limit
+        if (!this.rateLimiter.canRequest()) {
+            const waitTime = this.rateLimiter.getWaitTime();
+            logger.warn(`Rate limited. Wait ${waitTime}ms`);
+            return null;
+        }
+        try {
+            this.stats.apiCalls++;
+            this.rateLimiter.recordRequest();
+            // Use citation= parameter for exact citation matching instead of q= for full-text
+            // This returns only cases that have the citation in their citation list
+            const searchParams = new URLSearchParams({
+                citation: citationText,
+                type: 'o', // opinions
+                page_size: '20', // Get more results to find exact match
+            });
+            const url = `${this.config.baseUrl}/search/?${searchParams.toString()}`;
+            const headers = {
+                'Accept': 'application/json',
+            };
+            if (this.config.apiToken) {
+                headers['Authorization'] = `Token ${this.config.apiToken}`;
+            }
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!response.ok) {
+                this.stats.apiErrors++;
+                logger.error(`API error: ${response.status} ${response.statusText}`);
+                return null;
+            }
+            const data = await response.json();
+            // Search through results to find one with an EXACT citation match
+            if (data.results && data.results.length > 0) {
+                for (const result of data.results) {
+                    const citations = result.citation || [];
+                    // Check each citation in the result
+                    for (const citeStr of citations) {
+                        if (this.citationMatches(citeStr, targetVolume, targetReporter, targetPage)) {
+                            this.stats.casesFound++;
+                            // Extract year from result
+                            const dateStr = String(result.dateFiled || result.date_filed || '');
+                            const yearMatch = dateStr.match(/(\d{4})/);
+                            const year = yearMatch ? parseInt(yearMatch[1]) : new Date().getFullYear();
+                            // Extract case name and court
+                            const caseName = String(result.caseName || result.case_name || 'Unknown Case');
+                            const courtValue = String(result.court || result.court_id || 'unknown');
+                            return {
+                                caseName,
+                                normalizedName: caseName.toLowerCase().replace(/[^a-z]/g, ''),
+                                volume: targetVolume,
+                                reporter: targetReporter,
+                                page: targetPage,
+                                year,
+                                court: courtValue,
+                                jurisdiction: this.inferJurisdiction(courtValue),
+                                overruled: false,
+                                source: 'verified_addition',
+                                addedAt: Date.now(),
+                            };
+                        }
+                    }
+                }
+            }
+            // No exact match found in this search
+            return null;
+        }
+        catch (error) {
+            this.stats.apiErrors++;
+            if (error instanceof Error && error.name === 'AbortError') {
+                logger.error('Request timed out');
+            }
+            else {
+                logger.error('API error', error instanceof Error ? error : undefined);
+            }
+            return null;
+        }
+    }
+    /**
+     * Normalize a reporter name for comparison.
+     * Handles variations like "U.S." vs "US", "F.3d" vs "F. 3d", etc.
+     */
+    normalizeReporter(reporter) {
+        return reporter
+            .replace(/\s+/g, ' ') // Normalize whitespace
+            .replace(/\.\s*/g, '.') // Remove spaces after periods
+            .trim()
+            .toUpperCase();
+    }
+    /**
+     * Check if a citation string matches volume/reporter/page.
+     * Handles various citation formats like "347 U.S. 483", "500 F.3d 123", etc.
+     */
+    citationMatches(citationStr, targetVolume, targetReporter, targetPage) {
+        // Parse the citation string
+        const match = citationStr.match(/(\d+)\s+([A-Za-z.\s]+?)\s+(\d+)/);
+        if (!match)
+            return false;
+        const volume = parseInt(match[1]);
+        const reporter = this.normalizeReporter(match[2]);
+        const page = parseInt(match[3]);
+        // Check for exact match
+        if (volume !== targetVolume || page !== targetPage)
+            return false;
+        // Compare reporters (allowing some flexibility)
+        const normalizedTarget = targetReporter.replace(/\./g, '').replace(/\s/g, '');
+        const normalizedFound = reporter.replace(/\./g, '').replace(/\s/g, '');
+        return normalizedTarget === normalizedFound;
+    }
+    /**
+     * Batch lookup multiple citations.
+     * More efficient than individual lookups.
+     */
+    async lookupBatch(citations) {
+        const results = new Map();
+        // First, check cache for all
+        const uncached = [];
+        for (const c of citations) {
+            const cached = this.lookupCase(c.caseName, c.volume, c.reporter, c.page);
+            const key = this.makeKey(c.volume, c.reporter, c.page);
+            if (cached) {
+                results.set(key, cached);
+            }
+            else {
+                uncached.push(c);
+            }
+        }
+        // Build citation text for batch lookup
+        if (uncached.length > 0) {
+            const citationTexts = uncached
+                .map(c => `${c.volume} ${c.reporter} ${c.page}`)
+                .join('\n');
+            const batchResult = await this.lookupByText(citationTexts);
+            // For now, simple implementation - individual lookups for uncached
+            // TODO: Parse batch response properly
+            for (const c of uncached) {
+                const key = this.makeKey(c.volume, c.reporter, c.page);
+                if (!results.has(key)) {
+                    const result = await this.lookupCaseAsync(c.caseName, c.volume, c.reporter, c.page);
+                    results.set(key, result);
+                }
+            }
+        }
+        return results;
+    }
+    // ===========================================================================
+    // PRIVATE METHODS
+    // ===========================================================================
+    makeKey(volume, reporter, page) {
+        const normReporter = (reporter ?? '').replace(/\s+/g, '').toLowerCase();
+        return `${volume ?? ''}-${normReporter}-${page ?? ''}`;
+    }
+    /**
+     * Perform API lookup to CourtListener using the search endpoint.
+     * The search endpoint is more reliable than citation-lookup for verification.
+     *
+     * IMPORTANT: Verifies that returned results contain the EXACT citation,
+     * not just documents that happen to match search terms.
+     *
+     * For pre-1875 Supreme Court cases, automatically tries nominative reporter
+     * format (e.g., "1 Cranch 137" instead of "5 U.S. 137").
+     */
+    async performApiLookup(caseName, volume, reporter, page) {
+        const citationStr = `${volume} ${reporter} ${page}`;
+        const normalizedReporter = this.normalizeReporter(reporter);
+        // First, try the original citation
+        const result = await this.performCitationSearch(citationStr, volume, normalizedReporter, page);
+        if (result) {
+            // Cache and return
+            this.cache.set(volume, reporter, page, result);
+            return result;
+        }
+        // If not found and it's a pre-1875 U.S. Reports citation, try nominative format
+        const nominativeCitation = convertToNominativeCitation(volume, reporter, page);
+        if (nominativeCitation) {
+            logger.info(`Trying nominative citation: ${nominativeCitation}`);
+            // Parse the nominative citation
+            const nomMatch = nominativeCitation.match(/(\d+)\s+([A-Za-z.\s]+?)\s+(\d+)/);
+            if (nomMatch) {
+                const nomVolume = parseInt(nomMatch[1]);
+                const nomReporter = this.normalizeReporter(nomMatch[2]);
+                const nomPage = parseInt(nomMatch[3]);
+                const nomResult = await this.performCitationSearch(nominativeCitation, nomVolume, nomReporter, nomPage);
+                if (nomResult) {
+                    // Return with original U.S. Reports citation info
+                    const record = {
+                        ...nomResult,
+                        volume,
+                        reporter,
+                        page,
+                    };
+                    this.cache.set(volume, reporter, page, record);
+                    return record;
+                }
+            }
+        }
+        // No match found - cache negative result
+        this.stats.casesNotFound++;
+        this.cache.set(volume, reporter, page, null);
+        return null;
+    }
+    /**
+     * Infer jurisdiction from court ID.
+     */
+    inferJurisdiction(courtId) {
+        if (!courtId)
+            return 'unknown';
+        const id = courtId.toLowerCase();
+        if (id.includes('scotus') || id.includes('supreme'))
+            return 'federal';
+        if (id.startsWith('ca') || id.includes('circuit'))
+            return 'federal';
+        if (id.includes('dist') || id.includes('d.'))
+            return 'federal';
+        if (id.includes('bap') || id.includes('bankr'))
+            return 'federal';
+        return 'state';
+    }
+    /**
+     * Convert CourtListener API response to KnownCaseRecord.
+     */
+    convertToRecord(result) {
+        // Extract first citation details
+        const firstCitation = result.citations?.[0];
+        // Parse date to year
+        let year = 0;
+        if (result.date_filed) {
+            const parsed = new Date(result.date_filed);
+            if (!isNaN(parsed.getTime())) {
+                year = parsed.getFullYear();
+            }
+        }
+        // Determine jurisdiction
+        let jurisdiction = 'unknown';
+        if (result.court?.jurisdiction) {
+            jurisdiction = result.court.jurisdiction;
+        }
+        else if (result.court?.id) {
+            // Infer from court ID
+            if (result.court.id.startsWith('scotus')) {
+                jurisdiction = 'federal';
+            }
+            else if (result.court.id.includes('ca')) {
+                jurisdiction = 'federal';
+            }
+            else if (result.court.id.includes('d-')) {
+                jurisdiction = 'federal';
+            }
+        }
+        return {
+            caseName: result.case_name ?? 'Unknown Case',
+            normalizedName: (result.case_name ?? '').toLowerCase().replace(/[^\w\s]/g, ''),
+            volume: firstCitation?.volume ?? 0,
+            reporter: firstCitation?.reporter ?? '',
+            page: parseInt(firstCitation?.page ?? '0', 10),
+            court: result.court?.name_abbreviation ?? result.court?.id ?? '',
+            year,
+            jurisdiction,
+            overruled: false, // CourtListener doesn't provide this directly
+            source: 'verified_addition',
+            addedAt: Date.now(),
+        };
+    }
+    // ===========================================================================
+    // UTILITY METHODS
+    // ===========================================================================
+    /**
+     * Get detailed statistics.
+     */
+    getDetailedStats() {
+        const cacheHitRate = this.stats.totalLookups > 0
+            ? this.stats.cacheHits / this.stats.totalLookups
+            : 0;
+        const apiErrorRate = this.stats.apiCalls > 0
+            ? this.stats.apiErrors / this.stats.apiCalls
+            : 0;
+        return {
+            ...this.stats,
+            cacheHitRate,
+            apiErrorRate,
+            cacheSize: this.cache.getStats().size,
+            rateLimitRemaining: this.config.maxRequestsPerMinute - this.stats.apiCalls,
+        };
+    }
+    /**
+     * Clear all caches.
+     */
+    clearCache() {
+        this.cache.clear();
+        this.localOverrides.clear();
+    }
+    /**
+     * Get configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration.
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+        this.cache = new CitationCache(this.config);
+        this.rateLimiter = new RateLimiter(this.config.maxRequestsPerMinute);
+    }
+}
+// =============================================================================
+// FACTORY FUNCTION
+// =============================================================================
+/**
+ * Create a CourtListener-backed case database.
+ */
+export function createCourtListenerDatabase(config) {
+    return new CourtListenerCaseDatabase(config);
+}
+/**
+ * Default singleton instance.
+ */
+export const courtListenerDb = createCourtListenerDatabase();
+//# sourceMappingURL=courtlistener-adapter.js.map