dearnana 0.1.0__tar.gz

dearnana-0.1.0/.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=sk-ant-...

dearnana-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+**What happened?**
+
+A clear description of the bug.
+
+**Command you ran**
+
+```bash
+# Paste your dearnana command — feel free to replace your address with a generic
+# city/zip (e.g. "Bellevue, WA 98008") if you don't want to share it.
+dearnana --address "..." --budget ... --condition "..."
+```
+
+- Were you using `--no-ai`? (yes/no)
+- Was `ANTHROPIC_API_KEY` set? (yes/no — never paste the key itself)
+
+**Expected behavior**
+
+**Actual behavior / error output**
+
+```
+paste the traceback or wrong output here
+```
+
+**Environment**
+
+- OS:
+- Python version (`python --version`):
+- dearnana version (`pip show dearnana`):

dearnana-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an improvement
+labels: enhancement
+---
+
+**What problem would this solve?**
+
+Describe the situation — e.g. "When searching near a state border, facilities across the line don't show up."
+
+**Proposed solution**
+
+**Alternatives considered**
+
+**Note for scoring-related requests:** changes to the ranking methodology need a rationale and a before/after comparison — see [CONTRIBUTING.md](../../CONTRIBUTING.md#changing-the-scoring-methodology).

dearnana-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

dearnana-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## What does this PR do?
+
+## Checklist
+
+- [ ] `pytest` passes locally (no API key needed — LLM calls are mocked)
+- [ ] New behavior has tests
+- [ ] README/docs updated if user-facing behavior changed
+- [ ] **If this touches scoring** (`WEIGHTS`, `ranker.py` scorers, `condition.py` measure map): rationale + before/after comparison included per [CONTRIBUTING.md](../CONTRIBUTING.md#changing-the-scoring-methodology)

dearnana-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -v

dearnana-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dearnana-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.env
+.env.*
+!.env.example
+
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+
+.dearnana/
+reports/
+dearnana-reports/
+
+.venv/
+venv/

dearnana-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to DearNana
+
+Thanks for helping make nursing home data more transparent. Issues and PRs are welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/miaomiaocui/dearnana
+cd dearnana
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Requires Python 3.11+.
+
+## Running tests
+
+```bash
+pytest
+```
+
+**No API key is needed for the test suite** — all Anthropic API calls are mocked. The tests also make no network calls to CMS or Nominatim.
+
+To smoke-test against live data without any API cost:
+
+```bash
+dearnana --address "Bellevue, WA 98008" --budget 8000 \
+  --condition "moderate dementia, has fallen twice" --no-ai
+```
+
+CMS responses are cached for 24h under `~/.dearnana/cache`, so repeat runs are fast and gentle on the API.
+
+## Bringing your own API key
+
+The AI features (condition parsing + recommendation report) require an Anthropic API key. Get one at [console.anthropic.com](https://console.anthropic.com) and either export `ANTHROPIC_API_KEY` or copy `.env.example` to `.env`. Everything else works without one.
+
+## Changing the scoring methodology
+
+Scoring changes affect real families making high-stakes decisions, so they get extra scrutiny. A PR that touches `WEIGHTS`, the per-component scorers in `ranker.py`, the condition→measure map in `condition.py`, or any benchmark constant must include:
+
+1. **A rationale** — why is the new weighting/formula a better reflection of care quality? Cite evidence where possible (CMS technical docs, published research).
+2. **A before/after comparison** on a representative set of facilities (one full state is a good unit — Washington is the convention used so far). Report: how many facilities changed score, the mean/min/max delta, and the facilities with the largest moves. A small script against the cached state file is fine.
+3. **Updated documentation** — the README's "How Scores Are Calculated" section must stay in sync with the code.
+
+Please also read [DISCLAIMER.md](DISCLAIMER.md) for known data-accuracy limitations before proposing changes.
+
+## Code conventions
+
+- Pure scoring logic lives in `ranker.py` and must stay LLM-free and network-free.
+- All CMS API access goes through `cms_client.py` (retry helper + file cache).
+- All LLM access goes through the provider layer in `llm.py` (Anthropic API or local Ollama); providers return `None` on failure so callers can fall back.
+- New CLI behavior needs a test; LLM interactions are tested with mocks (`pytest-mock`).
+- Anything user-facing should degrade gracefully without an API key.
+
+## Releases (maintainers)
+
+Publishing to PyPI uses GitHub Actions [trusted publishing](https://docs.pypi.org/trusted-publishers/) — no tokens are stored in the repo.
+
+One-time setup: on pypi.org → your project (or "pending publisher" for the first release) → add a trusted publisher with repository `miaomiaocui/dearnana`, workflow `release.yml`, environment `pypi`.
+
+To release:
+
+1. Bump `version` in `pyproject.toml` and `__version__` in `src/dearnana/__init__.py`
+2. Create a GitHub release with tag `vX.Y.Z`
+3. The `release.yml` workflow builds the sdist/wheel and publishes automatically

dearnana-0.1.0/DISCLAIMER.md

@@ -0,0 +1,65 @@
+# DearNana — Disclaimers and Limitations
+
+---
+
+## 1. Not Medical or Legal Advice
+
+DearNana is an informational tool that surfaces publicly available government data. It is **NOT** a substitute for professional medical advice, legal counsel, or in-person facility evaluation.
+
+The composite score is a starting point for research — it is not a recommendation to place a family member in any specific facility. Nursing home selection is a complex, deeply personal decision that depends on factors well beyond what any dataset can capture.
+
+Always consult qualified healthcare professionals (physicians, social workers, geriatric care managers) before making placement decisions. Always visit facilities in person and speak with staff and current residents' families before signing any agreement.
+
+---
+
+## 2. Data Source and Accuracy
+
+- All facility data is sourced from the **CMS Provider Data Catalog** (https://data.cms.gov/provider-data/topics/nursing-homes), which CMS refreshes monthly.
+- DearNana caches data locally for up to 24 hours to reduce API load — cached data may be up to 24 hours old at the time of your search.
+- CMS data itself may lag real-world conditions by weeks to months, particularly for recent inspection findings, staffing changes, or newly levied penalties.
+- DearNana does **not** independently verify CMS data. Errors, omissions, or outdated information in the CMS source will appear in DearNana output.
+- **Facility costs** shown are state-level monthly medians for semi-private rooms from the CareScout (Genworth Financial) Cost of Care Survey 2024 (surveyed July–December 2024; https://www.carescout.com/cost-of-care). These are **not** facility-specific prices — actual costs vary significantly by facility, room type, and care level. Contact facilities directly for current rates. Many facilities accept Medicaid; eligibility is determined separately.
+
+---
+
+## 3. Scoring Methodology Limitations
+
+- The composite score is based on **quantitative CMS metrics only**. It cannot capture subjective quality factors such as facility culture, staff warmth, food quality, activity programming, family communication practices, or the general environment.
+- Scoring weights (e.g., 25% for overall rating, 20% for health inspections) are set by the DearNana project and represent one reasonable interpretation of available evidence. Reasonable people — including healthcare professionals — may weight these factors differently based on individual circumstances.
+- Facilities with **missing data fields** receive a neutral score (50 out of 100) for those components. This may artificially inflate or deflate their overall ranking compared to fully-reported facilities.
+- **Distance scoring** assumes that closer is generally preferable for family visits and continuity of care. This may not reflect your actual situation (e.g., if you prefer a specific facility farther away for clinical reasons).
+- The **abuse flag deduction** (−50 points) is based on CMS's own abuse icon designation. DearNana applies this as a near-disqualifying penalty, which reflects the severity of the finding. However, the underlying CMS record should always be reviewed directly at https://www.medicare.gov/care-compare before drawing conclusions.
+
+---
+
+## 4. AI-Generated Recommendations
+
+- When AI is enabled with the default provider (an `ANTHROPIC_API_KEY` is set and `--no-ai` is not used), DearNana sends your care condition description to the **Anthropic Claude API** twice: once to parse it into a structured needs profile that personalizes the ranking, and once to generate the personalized recommendation report.
+- The condition description you provide is transmitted to Anthropic's servers and is subject to their privacy policy: https://www.anthropic.com/privacy
+- You bring your own API key — DearNana never proxies your data through any server operated by the project. The only third parties contacted are CMS (facility data), OpenStreetMap Nominatim (geocoding your search address), and Anthropic (when AI is enabled with the default provider).
+- **Local alternative:** with `DEARNANA_LLM_PROVIDER=ollama`, all AI processing runs on your own machine via a local model and your condition description is never transmitted to any AI provider. AI quality depends on the local model you choose.
+- AI output is generated from the CMS data described above — it does not incorporate real-time information, facility-specific knowledge, or clinical assessment.
+- AI-generated recommendations should be treated as a **structured summary of public data**, not a clinical assessment or professional referral.
+- Use the `--no-ai` flag to skip all Anthropic API calls entirely. The ranked list — including condition-based personalization via built-in keyword matching — is still produced using CMS data only, and your condition description never leaves your machine.
+
+---
+
+## 5. No Financial Relationships
+
+DearNana has no financial relationship with any nursing home, senior care network, placement service, referral agency, or healthcare organization. Facilities **cannot pay** to improve their scores or appear in results. Rankings are determined solely by the algorithm described in [README.md](README.md).
+
+This tool was built to counter the opacity of for-profit referral networks that often steer families toward facilities that pay the highest referral fees rather than those that best fit their needs.
+
+---
+
+## 6. Liability
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+THE AUTHORS AND CONTRIBUTORS OF DEARNANA DISCLAIM ALL LIABILITY FOR ANY DECISIONS, ACTIONS, OR OUTCOMES THAT RESULT FROM USE OF THIS TOOL OR RELIANCE ON ITS OUTPUT. THIS INCLUDES, WITHOUT LIMITATION, ANY HARM ARISING FROM NURSING HOME PLACEMENT DECISIONS INFORMED IN WHOLE OR IN PART BY DEARNANA'S SCORES, RANKINGS, OR AI-GENERATED REPORTS.
+
+USE THIS TOOL AT YOUR OWN RISK. IT IS A STARTING POINT FOR RESEARCH — NOT A SUBSTITUTE FOR PROFESSIONAL ADVICE OR IN-PERSON EVALUATION.
+
+---
+
+*Last updated: June 2026*

dearnana-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 DearNana Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dearnana-0.1.0/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: dearnana
+Version: 0.1.0
+Summary: Find and rank nursing homes using CMS public data
+Project-URL: Homepage, https://github.com/miaomiaocui/dearnana
+Project-URL: Source, https://github.com/miaomiaocui/dearnana
+Project-URL: Bug Tracker, https://github.com/miaomiaocui/dearnana/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: CMS,healthcare,nursing home,senior care
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.78
+Requires-Dist: click>=8.1
+Requires-Dist: geopy>=2.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DearNana
+
+**Find trustworthy nursing homes using CMS public data — not ads, not referrals.**
+
+[![PyPI](https://img.shields.io/pypi/v/dearnana)](https://pypi.org/project/dearnana/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## What It Does
+
+DearNana searches the CMS (Centers for Medicare & Medicaid Services) public database of all Medicare/Medicaid certified nursing homes in the US and scores each facility on objective criteria derived entirely from government data. Your description of your loved one's care needs personalizes the ranking: it is matched against CMS's per-facility clinical quality measures (antipsychotic medication rates for dementia, falls with major injury for fall risk, pressure ulcers for wound care, and more). Each facility's ownership chain — and the chain's average track record — is surfaced alongside the score. No facility pays to be included, and no referral fees are ever involved. CMS refreshes the underlying datasets monthly.
+
+**DearNana runs fully for free — no API key, no tokens.** AI is an optional final layer that rewrites the results into a plain-language report; everything else works the same with or without it.
+
+### Features
+
+Works with **no API key, no tokens**:
+
+- 🏥 **Quality ranking** of every certified nursing home near you, from objective CMS data
+- 🎯 **Condition-aware personalization** — describe care needs in plain text, or build the profile with `--interactive` guided questions (no AI)
+- 📋 **Detailed rule-based report** — per-facility strengths/weaknesses, automatically surfaced red flags (abuse flags, CMS Special Focus status, actual-harm citations, penalties, ownership changes), and concrete questions to ask on a tour
+- 📊 **Side-by-side comparison table** of the top results in every run
+- 🔎 **Filters** — `--min-stars`, `--exclude-abuse`, `--exclude-special-focus`, `--sprinkler-only`, `--independent-only`
+- 💾 **Export & watchlist** — save results as CSV/HTML to share with family, and track picks across runs with a local watchlist
+
+Optional, when you want it:
+
+- 🤖 **AI-written recommendation** via the Anthropic API, or a **fully local** model through [Ollama](#run-fully-local-with-ollama) (nothing leaves your machine)
+
+See [Using DearNana Without AI Tokens](#using-dearnana-without-ai-tokens) for a complete token-free workflow.
+
+---
+
+## Installation
+
+```bash
+pip install dearnana
+```
+
+Until the first PyPI release lands, install straight from GitHub:
+
+```bash
+pip install git+https://github.com/miaomiaocui/dearnana
+```
+
+**Requirements:**
+
+- Python 3.11 or higher
+- No API key required — DearNana works fully for free; see [Using DearNana Without AI Tokens](#using-dearnana-without-ai-tokens)
+- For an AI-written recommendation (optional): set the `ANTHROPIC_API_KEY` environment variable (get a key at [console.anthropic.com](https://console.anthropic.com))
+- Use `--no-ai` (or just leave the key unset) to get a detailed rule-based report instead — ranking and condition personalization still work using CMS data only
+
+**Optional environment variables:**
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DEARNANA_REPORTS_DIR` | `./dearnana-reports` | Where markdown reports are written |
+| `DEARNANA_LLM_PROVIDER` | `anthropic` | `anthropic` (API key required) or `ollama` (local models) |
+| `DEARNANA_LLM_MODEL` | `claude-sonnet-4-6` / `llama3.1:8b` | Model for the recommendation report (default depends on provider) |
+| `DEARNANA_PARSER_MODEL` | `claude-haiku-4-5` / same as LLM model | Model for condition parsing |
+| `DEARNANA_OLLAMA_HOST` | `http://localhost:11434` | Ollama server address |
+
+---
+
+## Run Fully Local with Ollama
+
+Prefer not to send anything to a cloud API? DearNana can use a local model
+via [Ollama](https://ollama.com) — **the care-needs description never leaves
+your machine** (the only network calls are to CMS for facility data and
+OpenStreetMap for geocoding your search address):
+
+```bash
+ollama pull llama3.1:8b
+
+export DEARNANA_LLM_PROVIDER=ollama
+dearnana --address "Bellevue, WA 98008" --budget 8000 \
+  --condition "Mom has moderate dementia and has fallen twice"
+```
+
+No API key needed. Pick any model you have pulled with `DEARNANA_LLM_MODEL`
+(e.g. `llama3.1:70b`, `qwen2.5:14b`).
+
+**Quality note:** local model output quality varies widely by model and
+size — expect smaller models (e.g. 8B) to produce more generic
+recommendation reports than the cloud default. Try a couple of models you
+can run and compare. The condition-parsing step works well even on small
+models, and if the model fails or Ollama isn't running, DearNana degrades
+gracefully to keyword-based personalization and the data-only ranking.
+
+---
+
+## Quick Start (CLI)
+
+```bash
+dearnana \
+  --address "Bellevue, WA 98008" \
+  --budget 8000 \
+  --condition "Mom has moderate dementia, needs memory care and mobility assistance" \
+  --radius 25 \
+  --top 5
+```
+
+**Flag reference:**
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--address` | Yes | US address or city/zip to search near |
+| `--budget` | Yes | Monthly budget in dollars |
+| `--condition` | Yes* | Description of care needs — personalizes the ranking and the report (*optional with `--interactive`) |
+| `--interactive` | No | Answer guided questions to build the needs profile — no AI, nothing leaves your computer |
+| `--radius` | No | Search radius in miles (default: 50) |
+| `--top` | No | Number of results to show (default: 5) |
+| `--no-ai` | No | Skip the AI call; produce a detailed **rule-based** report instead |
+| `--min-stars` | No | Only include facilities with at least this CMS overall rating (1–5) |
+| `--exclude-abuse` | No | Exclude facilities flagged for abuse/neglect |
+| `--exclude-special-focus` | No | Exclude CMS Special Focus facilities |
+| `--sprinkler-only` | No | Only include facilities with full sprinkler coverage |
+| `--independent-only` | No | Exclude chain-affiliated facilities |
+| `--export csv\|html` | No | Also write results as a CSV or HTML file next to the report |
+| `--save-watchlist` | No | Save the top picks to a local watchlist (`~/.dearnana/watchlist.json`) |
+| `--show-watchlist` | No | Print your saved watchlist and exit |
+
+**Example output (real run, June 2026, abbreviated):**
+
+```
+Geocoding: Bellevue, WA 98008
+  -> (47.5851, -122.1470) in WA
+Personalizing for: dementia / memory care (long-stay antipsychotic use, ...);
+  fall risk (falls with major injury, ...) — parsed via keyword matching
+Fetching nursing homes in WA...
+  -> 194 facilities found (2 not yet rated by CMS)
+Fetching care quality measures for WA...
+Ranking within 25.0 miles...
+
+--- DearNana Top 5 ---
+
+#1. COVENANT SHORES HEALTH CENTER
+    9107 FORTUNA DRIVE, MERCER ISLAND, WA 98040
+    3.0 mi | Score: 86.1/100 | CMS: 5/5 | Phone: 2063168042
+    Chain: COVENANT LIVING (15 facilities, avg 4.3/5)
+    long-stay antipsychotic use: 10.3% vs state median 14.0% (better than 75% of WA facilities)
+    falls with major injury: 0.0% vs state median 2.3% (better than 100% of WA facilities)
+
+At a glance:
+
+| # | Facility                      | Dist    | Score | CMS | Staffing | Turnover | Penalties | Abuse | Chain           |
+| - | ----------------------------- | ------- | ----- | --- | -------- | -------- | --------- | ----- | --------------- |
+| 1 | COVENANT SHORES HEALTH CENTER | 3.0 mi  | 86.1  | 5/5 | 5/5      | 49%      | 0         | —     | COVENANT LIVING |
+| 2 | RAINIER REHABILITATION        | 28.6 mi | 85.0  | 5/5 | 3/5      | 20%      | 0         | —     | THE ENSIGN GROUP|
+```
+
+And the **rule-based recommendation** (no API key needed) — abbreviated:
+
+```
+### #1. COVENANT SHORES HEALTH CENTER
+3.0 mi away  |  DearNana score: 86.1/100  |  CMS: 5/5 stars
+
+**Strong on:** CMS overall rating (100/100), staffing levels (100/100), proximity (94/100).
+
+Care measures relevant to the described needs (lower is better):
+  - long-stay antipsychotic use: 10.3% (state median 14.0%) — better than 75% of facilities in the state
+
+**Ask on your tour:**
+  - What does a typical day look like for a resident with my loved one's needs, and who would I call with concerns?
+
+**Best overall match: #1. COVENANT SHORES HEALTH CENTER** (86.1/100 — strongest on CMS overall rating, staffing levels)...
+```
+
+(Facility data shown is from the CMS dataset at the time of the run and will change as CMS refreshes it.)
+
+---
+
+## Using DearNana Without AI Tokens
+
+DearNana is fully useful with **no API key and no tokens**. Every step except the
+final write-up — geocoding, fetching CMS data, scoring, ranking, and condition
+matching — is plain Python that runs for free. When no `ANTHROPIC_API_KEY` is set
+(or you pass `--no-ai`), DearNana produces a detailed **rule-based report**
+instead of the AI one: per-facility strengths and weaknesses, automatically
+surfaced red flags (abuse flags, CMS Special Focus status, actual-harm
+inspection citations, penalties, ownership changes), condition-fit measures, and
+concrete questions to ask on a tour — all derived from the same CMS data.
+
+A fully token-free workflow:
+
+```bash
+# Build the needs profile by answering guided questions (no AI), filter,
+# export a CSV to share with family, and save the picks to a watchlist:
+dearnana \
+  --address "Bellevue, WA 98008" --budget 8000 \
+  --interactive \
+  --min-stars 3 --exclude-abuse \
+  --export csv --save-watchlist
+
+# Review your saved picks anytime:
+dearnana --show-watchlist
+```
+
+You also get a **side-by-side comparison table** of the top results in every
+run, and the filter flags above narrow the pool before ranking. For a private
+local AI write-up with no cloud tokens, see *Run Fully Local with Ollama* above.
+
+---
+
+## Library Usage
+
+DearNana is also importable as a Python library. The FastAPI backend uses this pattern:
+
+```python
+from dearnana import (
+    build_measure_weights,
+    compute_measure_benchmarks,
+    geocode_address,
+    parse_condition,
+    rank_facilities,
+    score_condition_match,
+)
+from dearnana.cms_client import fetch_facilities_by_state, fetch_mds_measures_by_state
+
+lat, lng, state = geocode_address("Bellevue, WA 98008")
+facilities = fetch_facilities_by_state(state)
+
+# Optional: personalize the ranking with a needs profile
+profile = parse_condition("moderate dementia, has fallen twice")
+weights = build_measure_weights(profile)
+mds = fetch_mds_measures_by_state(state)
+benchmarks = compute_measure_benchmarks(mds)
+condition_scores = {
+    ccn: score_condition_match(m, weights, benchmarks) for ccn, m in mds.items()
+}
+
+ranked = rank_facilities(
+    facilities, lat, lng, radius_miles=25, top_n=5,
+    condition_scores=condition_scores,
+)
+
+for r in ranked:
+    print(f"{r.facility.name}: {r.composite_score}/100")
+```
+
+All public-facing functions are importable directly from the `dearnana` package. No subprocess calls are required.
+
+---
+
+## How Scores Are Calculated
+
+DearNana uses a weighted composite score (0–100) based entirely on public CMS data. Here's what goes into it:
+
+| Component | Weight | What it measures |
+|-----------|--------|-----------------|
+| Overall CMS Rating | 25% | CMS's own 1–5 star summary rating based on inspections, staffing, and quality measures |
+| Health Inspection | 20% | Results of state health inspections — citations for care problems, medication errors, and safety issues |
+| Staffing Quality | 20% | Blend of the CMS staffing star rating and actual nurse hours per resident per day vs. the 4.1 hrs/day minimum recommended by the 2001 CMS-commissioned staffing study |
+| Staff Stability | 10% | Annual nursing staff turnover rate — high turnover often signals poor management and care continuity |
+| Penalty History | 10% | Number of enforcement actions and total fines levied by CMS |
+| Distance | 10% | Proximity to the address you searched — closer facilities score higher |
+| Fire Safety | 5% | Whether the facility has full sprinkler coverage |
+
+**Condition match (15%, when care needs are recognized):** Your `--condition` text is parsed into a needs profile (via a small AI call, or a built-in keyword matcher when no API key is set or `--no-ai` is used). Each need maps to CMS MDS clinical quality measures — e.g. dementia → long-stay antipsychotic medication rate and physical restraint use; fall risk → falls with major injury. Each facility's measures are scored against the **state percentile distribution** (lower is better for all tracked measures). When the condition component is active, the base weights above are scaled by 0.85 so all weights still sum to 100%. If no needs are recognized in the text, the ranking is identical to the base weights.
+
+**Abuse flag:** If a facility has an active CMS abuse flag, 50 points are deducted from its score — this is treated as a near-disqualifying finding. When the needs profile includes a vulnerable population (dementia or mental health), the deduction increases to 60 points.
+
+**Missing data:** Facilities with missing data for a component receive a neutral score (50) for that component. Facilities not yet rated by CMS (typically newer facilities) are included with neutral component scores and labeled "not yet rated".
+
+**Ownership transparency (not scored):** Each facility's chain affiliation and the chain's average CMS ratings are shown alongside results. Warnings are flagged — not folded into the score, since chain averages aggregate the same star ratings already weighted above — when a facility belongs to a chain averaging ≤ 2.5 stars, changed ownership in the last 12 months, or carries CMS Special Focus status. For top picks, individual owners (name, role, percentage) from the CMS Ownership dataset are included in the report.
+
+### Scoring details
+
+- **Overall CMS Rating** maps the 1–5 star summary directly to 0–100 (5 stars = 100, 1 star = 20).
+- **Staffing Quality** is a weighted blend: 60% from the CMS staffing star rating, 40% from actual nurse hours compared to 4.1 hrs/resident/day — the minimum recommended by the 2001 CMS-commissioned staffing study (the actual national average is lower, ~3.6 hrs). If only one part is reported, it is used alone.
+- **Staff Stability** inverts the turnover rate against national reference points (~52% total nursing, ~50% RN — CMS staffing-data analyses report national means of roughly 53% and 52%). A facility at the reference point scores 50; a facility with 0% turnover scores 100.
+- **Penalty History** starts at 100 and deducts 15 points per enforcement action, plus 5 points per $10,000 in total fines.
+- **Distance** uses linear decay: 100 at 0 miles, 0 at the search radius boundary.
+- **Fire Safety** gives 100 for full sprinkler coverage, 50 for partial, 0 for none, 50 if unreported.
+- **Condition Match** scores each relevant MDS measure as `100 × (1 − state percentile)` and averages them by need weight. Measures with missing data, or with fewer than 20 reporting facilities in the state, score a neutral 50.
+
+---
+
+## Data Source
+
+| Attribute | Detail |
+|-----------|--------|
+| Source | [CMS Provider Data Catalog](https://data.cms.gov/provider-data/topics/nursing-homes) |
+| Datasets | Provider information (ratings, staffing, chain), MDS Quality Measures (clinical measures), Health Deficiencies, Penalties, Ownership |
+| Updated | Monthly by CMS (per dataset metadata) |
+| Coverage | All Medicare/Medicaid certified nursing homes in the US (~14,700 facilities as of mid-2026) |
+| Cost data | State-level monthly medians for semi-private rooms from the [CareScout (Genworth) Cost of Care Survey 2024](https://www.carescout.com/cost-of-care) — **not** facility-specific pricing |
+| Caching | API responses are cached for 24h under `~/.dearnana/cache` |
+
+CMS does not publish per-facility pricing. Budget comparisons use state-level median costs as a rough proxy. Contact facilities directly for current rates. Many facilities accept Medicaid — contact them directly if your budget is below the state median.
+
+---
+
+## Disclaimer
+
+DearNana is a decision-support tool, not a substitute for professional medical or legal advice. Always visit facilities in person, speak with staff, and consult with a healthcare professional before making placement decisions. See [DISCLAIMER.md](DISCLAIMER.md) for full details.
+
+---
+
+## Contributing
+
+Issues and PRs are welcome. Before contributing changes to scoring weights or methodology, please read [DISCLAIMER.md](DISCLAIMER.md) for notes on data accuracy and known limitations. Scoring changes should include a rationale and a before/after comparison on a representative set of facilities.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)