Local testing guide

This guide walks you through running the RCI Platform locally, seeding it with CMS sample data, and verifying every API endpoint works. Follow the section for your operating system.

Prerequisites

Requirement	Version	Notes
Python	3.11+	3.12 recommended
Docker	20.10+	Docker Desktop (macOS/Windows) or Docker Engine (Linux)
Docker Compose	v2+	Included with Docker Desktop
Git	2.30+
curl	any	Included on macOS/Linux; available on Windows 10+

1. Clone and install

macOS
Linux (Ubuntu/Debian)
Windows (PowerShell)

# Install prerequisites (if needed)
brew install python@3.12 git

# Clone and enter the repo
git clone https://github.com/RCI-Healthcare-knowledbase/rc-platfom.git
cd rc-platfom

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the platform with dev dependencies
pip install -e ".[dev]"

# Copy environment config
cp .env.example .env

# Install prerequisites
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3-pip git curl

# Install Docker Engine (if not already installed)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for the group change to take effect

# Clone and enter the repo
git clone https://github.com/RCI-Healthcare-knowledbase/rc-platfom.git
cd rc-platfom

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install the platform with dev dependencies
pip install -e ".[dev]"

# Copy environment config
cp .env.example .env

# Install prerequisites:
#   Python 3.12+ — https://python.org (check "Add to PATH" during install)
#   Docker Desktop — https://docker.com/products/docker-desktop
#   Git — https://git-scm.com

# Clone and enter the repo
git clone https://github.com/RCI-Healthcare-knowledbase/rc-platfom.git
cd rc-platfom

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate

# Install the platform with dev dependencies
pip install -e ".[dev]"

# Copy environment config
copy .env.example .env

If pip install fails with “Microsoft Visual C++ required”, install the Build Tools for Visual Studio (select “Desktop development with C++“).

2. Start infrastructure

Start PostgreSQL and Redis with Docker Compose. This is the same on all platforms.

macOS / Linux
Windows (PowerShell)

# Start the full stack (PostgreSQL + Redis + API + Prometheus + Grafana)
docker compose up -d

# Or start only the database and cache (run API locally with hot-reload)
docker compose up -d postgres redis

# Make sure Docker Desktop is running first

# Start the full stack
docker compose up -d

# Or start only the database and cache
docker compose up -d postgres redis

Wait for containers to be healthy:

docker compose ps

You should see both postgres and redis with status healthy.

3. Apply database migrations

alembic upgrade head

Expected output:

INFO  Running upgrade  -> 001, Initial schema
INFO  Running upgrade 001 -> 002, Structured payer, service code, and prior auth tables
...
INFO  Running upgrade 009 -> 010, Add NCCI summary agent types to agenttype enum

All 10 migrations should apply cleanly. If you hit enum errors on a re-run, see the Troubleshooting section.

4. Start the API server

macOS / Linux
Windows (PowerShell)

If you started the full Docker stack in step 2, the API is already running at http://localhost:8000. Skip to step 5.To run with hot-reload for development:

uvicorn kustode_platform.main:app --reload --port 8000

If you started the full Docker stack in step 2, the API is already running at http://localhost:8000. Skip to step 5.To run with hot-reload for development:

python -m uvicorn kustode_platform.main:app --reload --port 8000

Use python -m uvicorn on Windows if uvicorn alone is not found in your PATH.

5. Verify the server

macOS / Linux
Windows (PowerShell)

curl http://localhost:8000/health

Invoke-RestMethod http://localhost:8000/health

Or with curl (available on Windows 10+):

curl.exe http://localhost:8000/health

PowerShell aliases curl to Invoke-WebRequest. Use curl.exe to call the real curl, or use Invoke-RestMethod for cleaner output.

Expected: {"status":"ok"}

6. Bootstrap a tenant and API key

macOS / Linux
Windows (PowerShell)

curl -X POST http://localhost:8000/v1/admin/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Hospital", "slug": "test-hospital"}'

$body = '{"name": "Test Hospital", "slug": "test-hospital"}'
Invoke-RestMethod -Method Post -Uri http://localhost:8000/v1/admin/bootstrap `
  -ContentType "application/json" -Body $body

Or with curl.exe:

curl.exe -X POST http://localhost:8000/v1/admin/bootstrap `
  -H "Content-Type: application/json" `
  -d "{\"name\": \"Test Hospital\", \"slug\": \"test-hospital\"}"

Expected response:

{
  "tenant": {
    "id": "...",
    "name": "Test Hospital",
    "slug": "test-hospital",
    "plan_tier": "free"
  },
  "api_key": "l049vdD58OQge...",
  "key_prefix": "l049vdD5",
  "note": "Save this API key — it will not be shown again."
}

Copy the api_key value now — it cannot be retrieved later. Store it in an environment variable for the rest of this guide.

macOS / Linux
Windows (PowerShell)

export API_KEY="paste-your-key-here"

$env:API_KEY = "paste-your-key-here"

7. Seed all reference data

This single call loads RVU fee schedules, GPCI geographic indices, NCCI coding edits (MUE + PTP + AOC), MAC contractors, CBSA mappings, Medicaid programs, and sample facilities.

macOS / Linux
Windows (PowerShell)

curl -X POST http://localhost:8000/v1/admin/data/refresh \
  -H "X-API-Key: $API_KEY"

Invoke-RestMethod -Method Post -Uri http://localhost:8000/v1/admin/data/refresh `
  -Headers @{"X-API-Key" = $env:API_KEY}

Expected response:

{
  "status": "completed",
  "facilities_loaded": 1,
  "rvu_rows": 72,
  "gpci_rows": 111,
  "ncci_ptp_rows": 42,
  "ncci_mue_rows": 56,
  "ncci_aoc_rows": 29,
  "medicaid_programs": 50,
  "mac_contractors_loaded": 12,
  "cbsa_mappings_loaded": 12
}

If all counts are 0, see Troubleshooting.

8. Test every endpoint

The commands below use macOS/Linux curl syntax. On Windows, replace curl with curl.exe, replace \ line continuations with `, and use $env:API_KEY instead of $API_KEY.

Knowledge resolution

# Full L1-L6 resolution
curl http://localhost:8000/v1/knowledge/layers/170001 \
  -H "X-API-Key: $API_KEY"

# Billing guide
curl -X POST http://localhost:8000/v1/knowledge/billing-guide \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ccn": "170001", "cpt": "99213"}'

# Payment calculation
curl -X POST http://localhost:8000/v1/knowledge/payment-calc \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ccn": "170001", "cpt": "99213"}'

Expected payment result: $86.02 for CPT 99213 at CCN 170001.

NCCI MUE limits

# Practitioner setting
curl "http://localhost:8000/v1/ncci/mue/practitioner/99213" \
  -H "X-API-Key: $API_KEY"

# Hospital Outpatient setting
curl "http://localhost:8000/v1/ncci/mue/hosp-op/99213" \
  -H "X-API-Key: $API_KEY"

# DME setting
curl "http://localhost:8000/v1/ncci/mue/dme/E0601" \
  -H "X-API-Key: $API_KEY"

Setting	Code	Expected `mue_value`	MAI
Practitioner	99213	3	3 (Clinical)
Hospital OP	99213	3	3 (Clinical)
DME	E0601	1	2 (Policy)

NCCI PTP edits

# Practitioner table
curl "http://localhost:8000/v1/ncci/ptp/prac?col1_proc_cd=27447&col2_proc_cd=29881" \
  -H "X-API-Key: $API_KEY"

# Hospital table
curl "http://localhost:8000/v1/ncci/ptp/hosp?col1_proc_cd=27447&col2_proc_cd=29881" \
  -H "X-API-Key: $API_KEY"

# Validate a code pair
curl "http://localhost:8000/v1/ncci/validate?code1=27447&code2=29881" \
  -H "X-API-Key: $API_KEY"

Expected: modifier: "1" (modifier allowed), is_bundled: true.

NCCI Add-On Code edits

# By add-on code
curl "http://localhost:8000/v1/ncci/aoc?add_on_code=99417" \
  -H "X-API-Key: $API_KEY"

# By primary procedure
curl "http://localhost:8000/v1/ncci/aoc?primary_proc_cd=27447" \
  -H "X-API-Key: $API_KEY"

Expected: 99417 returns 3 primary codes (99213, 99214, 99215).

NPI search

NPI search calls the live CMS NPPES registry. No seeded data needed.

# Search by last name and state
curl "http://localhost:8000/v1/npi/search?last_name=Smith&state=KS&limit=3" \
  -H "X-API-Key: $API_KEY"

# Search by organization name
curl "http://localhost:8000/v1/npi/search?organization_name=Stormont+Vail&state=KS" \
  -H "X-API-Key: $API_KEY"

Facilities

# List all facilities (enriched with MAC, GPCI)
curl "http://localhost:8000/v1/facilities/" \
  -H "X-API-Key: $API_KEY"

# Get a single facility by CCN
curl "http://localhost:8000/v1/facilities/170001" \
  -H "X-API-Key: $API_KEY"

Expected: response includes mac, gpci, and cbsa_detail fields.

AI agents

# Submit a code research job
curl -X POST http://localhost:8000/v1/agents/code-research \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is CPT 99213?"}'

# Poll for result (replace JOB_ID)
curl "http://localhost:8000/v1/agents/jobs/JOB_ID" \
  -H "X-API-Key: $API_KEY"

Agent jobs require the rcm-agents service running at RCM_AGENTS_URL. Without it, jobs stay in pending status — the rest of the platform works independently.

Audit

curl "http://localhost:8000/v1/audit/stats" \
  -H "X-API-Key: $API_KEY"

curl "http://localhost:8000/v1/audit/events?limit=10" \
  -H "X-API-Key: $API_KEY"

Admin

# Usage metrics
curl "http://localhost:8000/v1/admin/usage" \
  -H "X-API-Key: $API_KEY"

# List API keys
curl "http://localhost:8000/v1/admin/api-keys" \
  -H "X-API-Key: $API_KEY"

# Data freshness
curl "http://localhost:8000/v1/admin/data/status" \
  -H "X-API-Key: $API_KEY"

# Tracked data sources
curl "http://localhost:8000/v1/admin/data/sources" \
  -H "X-API-Key: $API_KEY"

9. Run the test suite

macOS / Linux
Windows (PowerShell)

# Platform tests
pytest tests/ -v

# SDK tests (if using the Python SDK)
cd rci_python && pytest tests/ -v && cd ..

# Platform tests
python -m pytest tests/ -v

# SDK tests (if using the Python SDK)
cd rci_python
python -m pytest tests/ -v
cd ..

10. Open interactive docs

Open your browser to http://localhost:8000/docs for the Swagger UI. Every endpoint is documented with request/response schemas and you can execute requests directly from the browser.

Sample data reference

The seed data loaded in step 7 includes:

NCCI MUE (56 entries)

Setting	Codes available
Practitioner	99203, 99204, 99213, 99214, 99215, 27440, 27441, 27442, 27447, 29880, 29881, 36415, 71046, 73610, 80053, 85025, 10060, 12001, 99291, 96374
Hospital OP	99213, 99214, 99215, 27440, 27441, 27442, 27447, 29880, 29881, 36415, 71046, 73610, 80053, 10060, 12001, 99291, 96374, 80061, 85027
DME	E0601, E0470, E1390, K0823, K0001, K0462, A4253, L3000, A7035, B4035, A6550, E0260, E0277, E0305, A4606, L0650

NCCI PTP (42 pairs)

Available in both professional (/ptp/prac) and institutional (/ptp/hosp) tables.

Column 1	Column 2	Modifier	Rationale
27447	27440	0	More extensive procedure
27447	29881	1	HCPCS/CPT procedure code definition
99213	99214	0	Mutually exclusive procedures
80053	85025	0	Laboratory panel
10060	12001	1	Standards of medical/surgical practice

NCCI AOC (29 relationships)

Primary	Add-On	Type	Notes
99213	99417	2	Contractor Defined Primary Codes
27447	22614	1	Limited list
99291	99292	1	Limited list
96374	96376	3	96376 may be reported by facilities only

Other reference data

Dataset	Rows	Source
RVU fee schedule	72	`pprrvu26_sample.csv`
GPCI localities	111	`gpci2026.csv`
Medicaid programs	50	`medicaid_programs.yaml`
MAC contractors	12	`mac_contractors.yaml`
CBSA mappings	12	`cbsa_mappings.yaml`

Troubleshooting

Data refresh returns all zeros

If POST /v1/admin/data/refresh returns 0 for all row counts:

Docker stack: Make sure you started the full stack with docker compose up -d (not just postgres redis). The API container needs access to the data/ directory via volume mount.
Local dev server: If running with uvicorn directly, the data files are resolved from the project root. Make sure you’re running from the repository root directory.
Verify files exist: Check that the data/cms/ directory contains the CSV files:

ls data/cms/
# Should show: gpci2026.csv  ncci_aoc_sample.csv  ncci_mue_sample.csv
#              ncci_ptp_sample.csv  pprrvu26_sample.csv  medicaid_programs.yaml

Migration errors: duplicate_object

If alembic upgrade head fails with type "..." already exists:

# Option 1: Clean up and retry
docker compose down -v     # Removes volumes (deletes all data)
docker compose up -d
alembic upgrade head

# Option 2: Drop orphaned types from a partial run
docker exec platform-postgres-1 psql -U hkl -d hkl -c "
  DROP TABLE IF EXISTS data_sources, cbsa_mappings, gpci_localities, mac_contractors;
  DROP TYPE IF EXISTS datasourcetype, syncstatus;
"
alembic upgrade head

Windows: curl syntax

PowerShell requires different quoting rules than bash:

# Use curl.exe (not the PowerShell alias)
curl.exe -X POST http://localhost:8000/v1/admin/bootstrap `
  -H "Content-Type: application/json" `
  -d "{\"name\": \"Test Hospital\", \"slug\": \"test-hospital\"}"

# Or use Invoke-RestMethod for cleaner output
$headers = @{"X-API-Key" = $env:API_KEY}
Invoke-RestMethod -Uri "http://localhost:8000/v1/ncci/mue/practitioner/99213" `
  -Headers $headers

Windows: uvicorn not found

If uvicorn is not recognized:

python -m uvicorn kustode_platform.main:app --reload --port 8000

Agent jobs stuck in pending

Agent jobs require the rcm-agents service. If it’s not running:

Jobs will be created with status: "pending" but never complete
All other endpoints (knowledge, NCCI, NPI, facilities, audit) work independently
Set RCM_AGENTS_URL in .env to point to a running rcm-agents instance

Redis connection refused

If NPI search or rate limiting fails:

# Check Redis is running
docker compose ps redis

# Restart if needed
docker compose restart redis

Cleanup

# Stop all containers and remove volumes
docker compose down -v

# Deactivate virtual environment
deactivate

# Remove virtual environment (optional)
rm -rf .venv          # macOS/Linux
rmdir /s /q .venv     # Windows

​Prerequisites

​1. Clone and install

​2. Start infrastructure

​3. Apply database migrations

​4. Start the API server

​5. Verify the server

​6. Bootstrap a tenant and API key

​7. Seed all reference data

​8. Test every endpoint

​Knowledge resolution

​NCCI MUE limits

​NCCI PTP edits

​NCCI Add-On Code edits

​NPI search

​Facilities

​AI agents

​Audit

​Admin

​9. Run the test suite

​10. Open interactive docs

​Sample data reference

​NCCI MUE (56 entries)

​NCCI PTP (42 pairs)

​NCCI AOC (29 relationships)

​Other reference data

​Troubleshooting

​Data refresh returns all zeros

​Migration errors: duplicate_object

​Windows: curl syntax

​Windows: uvicorn not found

​Agent jobs stuck in pending

​Redis connection refused

​Cleanup

Prerequisites

1. Clone and install

2. Start infrastructure

3. Apply database migrations

4. Start the API server

5. Verify the server

6. Bootstrap a tenant and API key

7. Seed all reference data

8. Test every endpoint

Knowledge resolution

NCCI MUE limits

NCCI PTP edits

NCCI Add-On Code edits

NPI search

Facilities

AI agents

Audit

Admin

9. Run the test suite

10. Open interactive docs

Sample data reference

NCCI MUE (56 entries)

NCCI PTP (42 pairs)

NCCI AOC (29 relationships)

Other reference data

Troubleshooting

Data refresh returns all zeros

Migration errors: duplicate_object

Windows: curl syntax

Windows: uvicorn not found

Agent jobs stuck in pending

Redis connection refused

Cleanup