bedrock

Honest, evidence-backed apartment due diligence for the NJ Gold Coast, built for someone who knows the area but not the buildings.

Tell it what you need, not where to look. It finds real, current listings, researches each one down to flood zone, commute, rent fairness, crime, and landlord reputation, and ranks them honestly, labeling every fact and never inventing confidence it doesn't have.

What it does

1. Interview: captures your needs (budget, bedrooms, move-in, commute target, dealbreakers, "also consider" towns) as a saved, versioned profile.
2. Discover: finds real for-rent listings from your profile alone, no building names supplied, via the official RentCast rental-listings API (lawful, no scraping). Pages through the full inventory for your area.
3. Research: for each candidate, NJ geocoding and parcel/permits records, FEMA flood zone, noise exposure, commute to your destination, listing details and photos, rent-comp context, building/landlord reputation, municipality crime context, and nearby resident-reported civic issues.
4. Rank: sorts candidates into honest tiers (strong / has risks / needs confirmation / reject / out of area), weighing your stated priorities and trade-offs, with the blocking reasons stated plainly.
5. Report: a per-listing due-diligence report plus a daily dashboard and digest of what changed, with an action queue (who to contact, what to ask).

Honesty, by construction

• Evidence labels on every load-bearing fact: verified > corroborated

  single-source > inferred > unknown-to-confirm. An unknown is shown as "not known yet, here's how to find out," never dressed up as a fact.

• No invented confidence: it never emits a calibrated percentage it can't back; it says calibration pending instead.
• No silent degradation: every external service reports per run whether it ran, was reused from cache (♻), degraded, was skipped, or failed, with the reason. A thin or fallen-back result never looks like a full one.
• Lawful sourcing only: official APIs and public data; no portal scraping, and attended browsing never bypasses a verification wall.

Research-freshness cache

A building's research is reused across runs instead of re-fetched every time: static facts (geocode, parcel records, flood, noise, commute) for ~180 days, dynamic facts (crime, civic, reputation, rent estimate) for ~30. Re-seeing a known building therefore makes near-zero live calls. Every reuse is surfaced with its age; --force-refresh re-fetches live.

Target area

Jersey City, Hoboken, Edgewater, Fort Lee, Cliffside Park, Palisades Park, and the secondary overflow towns Weehawken, West New York, North Bergen, and Guttenberg: the Hudson and Bergen waterfront, oriented around the NYC commute.

Quick start

Requires uv and Python 3.13.

uv sync
uv run playwright install chromium        # for attended page capture
cp .env.example .env                       # then paste any API keys you have
uv run nj-housing nj-doctor                # shows which keys are set
uv run nj-housing nj-daily                 # the one-command search loop

Every API key is optional: a missing key never breaks a run; it leaves the sections it powers as honest "unknown" instead of filled in. See .env.example for what each key unlocks and where to get it (all have free tiers).

Common commands

Run via uv run nj-housing <command>:

Command	What it does
nj-doctor	Show which keys are set (booleans only) plus environment checks.
nj-profile --set-text "<needs>"	Parse free-form needs into a saved profile.
nj-daily	The full loop: profile → discover → research → rank → dashboard + digest.
nj-due-diligence-report --address "<addr>" --requirements "<needs>"	Deep dive on one place.
nj-qualification --set-json '<json>'	Save your lease-qualification profile (visa, credit, guarantor options); local-only, never sent anywhere.
nj-qualification-match --report "<report.json>"	Your realistic paths to qualify for that building (guarantor services, foreign credit, deposit options).
nj-shopping-dashboard-server	Serve the local dashboard (loopback only).

Data sources

NJ geocoder and statewide parcels/MOD-IV, NJ DCA construction permits, FEMA National Flood Hazard Layer, Google Routes / Places / Street View, RentCast listings and rent comps, FBI Crime Data Explorer, and SeeClickFix civic reports. LLM-assisted extraction and synthesis run on Google Gemini or, with --llm-backend claude-code, a local Claude subscription — never on a paid API key unless you set one.

Privacy

Local-first: your profile, candidates, and notes live in a local SQLite database; API keys live only in your gitignored .env. Nothing is uploaded anywhere except the direct calls to the data-source APIs above. See docs/privacy.md.

License

Personal project; no license granted for reuse at this time.