orangeslice 2.1.0 → 2.1.2

package/docs/services/healthcare/npi.md

@@ -1,190 +0,0 @@
-# Healthcare NPI Database Service
-
-Execute SQL queries against the NPI (National Provider Identifier) healthcare database containing 1.8M+ healthcare organizations.
-
-## Usage
-
-```typescript
-const result = await services.healthcare.npi({ query: "SELECT * FROM healthcare_orgs WHERE state = 'CA' LIMIT 10" });
-// result.rows: Array of matching records
-// result.rowCount: Number of rows returned
-```
-
-## Schema
-
-```
-taxonomy_codes (884 rows) - Specialty lookup table
-├── code (PK, e.g., "207RC0000X")
-├── title ("Cardiovascular Disease Physician")
-├── definition (full description)
-├── provider_type ("Allopathic & Osteopathic Physicians")
-├── classification ("Internal Medicine")
-├── specialization ("Cardiovascular Disease")
-└── hierarchy[] (full path array)
-
-healthcare_orgs (1.8M rows) - Organizations
-├── npi (PK, 10-digit identifier)
-├── name, other_name
-├── address_line1, address_line2, city, state, zip, phone
-├── is_subpart, parent_org_name
-└── enumeration_date, last_update_date
-
-org_taxonomies (2.6M rows) - Junction table
-├── npi → healthcare_orgs
-├── taxonomy_code → taxonomy_codes
-├── is_primary (boolean)
-└── position (1-15)
-```
-
-## Query Patterns
-
-### 1. Find taxonomy codes first (fast, 35ms)
-
-```typescript
-const result = await services.healthcare.npi({
-   query: `
-    SELECT code, title, classification, specialization
-    FROM taxonomy_codes
-    WHERE to_tsvector('english', title || ' ' || COALESCE(definition,''))
-          @@ to_tsquery('cardiology | heart')
-  `
-});
-```
-
-### 2. Query orgs by taxonomy
-
-```typescript
-const result = await services.healthcare.npi({
-   query: `
-    SELECT o.name, o.city, o.state, t.title
-    FROM healthcare_orgs o
-    JOIN org_taxonomies ot ON o.npi = ot.npi
-    JOIN taxonomy_codes t ON ot.taxonomy_code = t.code
-    WHERE o.state = 'CA'
-      AND t.classification = 'Internal Medicine'
-    LIMIT 100
-  `
-});
-```
-
-### 3. Search orgs by name
-
-```typescript
-const result = await services.healthcare.npi({
-   query: `
-    SELECT npi, name, city, state
-    FROM healthcare_orgs
-    WHERE to_tsvector('english', name) @@ to_tsquery('kaiser & permanente')
-    LIMIT 50
-  `
-});
-```
-
-### 4. Filter by provider_type
-
-```typescript
-// provider_type values: Hospitals, Ambulatory Health Care Facilities,
-// Agencies, Suppliers, Allopathic & Osteopathic Physicians, etc.
-const result = await services.healthcare.npi({
-   query: `
-    SELECT o.name, o.city FROM healthcare_orgs o
-    JOIN org_taxonomies ot ON o.npi = ot.npi
-    JOIN taxonomy_codes t ON ot.taxonomy_code = t.code
-    WHERE t.provider_type = 'Hospitals' AND o.state = 'TX'
-    LIMIT 100
-  `
-});
-```
-
-### 5. Get all services for an org
-
-```typescript
-const result = await services.healthcare.npi({
-   query: `
-    SELECT t.title, t.specialization
-    FROM org_taxonomies ot
-    JOIN taxonomy_codes t ON ot.taxonomy_code = t.code
-    WHERE ot.npi = 1234567890
-    ORDER BY ot.position
-  `
-});
-```
-
-### 6. Find multi-specialty orgs
-
-```typescript
-const result = await services.healthcare.npi({
-   query: `
-    SELECT o.name, o.city, COUNT(*) as specialties
-    FROM healthcare_orgs o
-    JOIN org_taxonomies ot ON o.npi = ot.npi
-    GROUP BY o.npi, o.name, o.city
-    HAVING COUNT(*) >= 3
-    LIMIT 10
-  `
-});
-```
-
-### 7. Find subparts of a parent
-
-```typescript
-const result = await services.healthcare.npi({
-   query: `
-    SELECT name, city, state
-    FROM healthcare_orgs
-    WHERE parent_org_name ILIKE '%kaiser%'
-    LIMIT 50
-  `
-});
-```
-
-## Key provider_type Values
-
-- `Hospitals`
-- `Ambulatory Health Care Facilities` (clinics)
-- `Agencies` (home health, hospice)
-- `Suppliers` (DME, pharmacy)
-- `Allopathic & Osteopathic Physicians`
-- `Nursing & Custodial Care Facilities`
-- `Behavioral Health & Social Service Providers`
-- `Dental Providers`
-- `Transportation Services`
-
-## Key classification Values
-
-- `Clinic/Center`, `Internal Medicine`, `Pediatrics`
-- `Family Medicine`, `General Acute Care Hospital`
-- `Skilled Nursing Facility`, `Pharmacy`
-- `Dentist`, `Physical Therapist`, `Radiology`
-
-**Credits: 1/result (per-result). Reserves based on query `LIMIT`.**
-
-## LIMIT Guidelines
-
-### Exploration (use small limits)
-
-```sql
--- Test with small limit first - 5 credits
-SELECT * FROM healthcare_orgs WHERE state = 'TX' LIMIT 5
-```
-
-### Data Extraction
-
-```sql
--- 100 rows = 100 credits
-SELECT npi, name, city, state
-FROM healthcare_orgs
-WHERE state = 'CA'
-LIMIT 100
-```
-
-## Tips
-
-- **Always include LIMIT** - The database has 1.8M+ rows
-- Always search `taxonomy_codes` first to find relevant codes
-- Use `ILIKE '%term%'` for partial matches on text fields
-- Use `to_tsquery()` for full-text search (faster)
-- State codes are uppercase 2-letter (CA, TX, NY)
-- Cities are uppercase (LOS ANGELES, NEW YORK)
-- Join through `org_taxonomies` for specialty filtering
-- Only SELECT queries are allowed (no INSERT, UPDATE, DELETE)