fix: add force_refresh param + poisoned property cleanup endpoint

- enrich_property() accepts force_refresh=True to bypass dedup check
- SSE stream endpoint accepts ?force_refresh=true query param
- POST /api/analysis/admin/cleanup-poisoned deletes properties created
  during the RENTCAST_API_KEY outage (no beds, no sqft, no type)
  Protected by X-Internal-Key header.
- Standalone cleanup script in scripts/ for future use

Author: ivan-711

backend/core/property_data/service.py

@@ -150,6 +150,7 @@ def enrich_property(
     db: Session,
     providers: list[str] | None = None,
     default_strategy: str = "buy_and_hold",
+    force_refresh: bool = False,
 ) -> EnrichmentResult:
     """Enrich a property from address string using configured providers.
 
@@ -188,8 +189,8 @@ def enrich_property(
         result.status = "failed"
         return result
 
-    # 2. Check for existing property (dedup)
-    existing = _find_existing_property(db, user_id, parsed.address_line1, parsed.zip_code)
+    # 2. Check for existing property (dedup) — skip if force_refresh
+    existing = None if force_refresh else _find_existing_property(db, user_id, parsed.address_line1, parsed.zip_code)
     if existing:
         logger.info("enrich_property: found existing property %s, skipping provider calls", existing.id)
         result.property = existing

backend/routers/analysis.py

@@ -409,6 +409,7 @@ async def quick_analysis_stream(
     lat: float | None = None,
     lng: float | None = None,
     place_id: str | None = None,
+    force_refresh: bool = False,
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
     _quota: None = Depends(require_quota("analyses_per_month")),
@@ -452,6 +453,7 @@ def _enrich_sync():
                             address=address, user_id=current_user.id,
                             db=thread_db, default_strategy=strategy,
                             providers=["rentcast"],
+                            force_refresh=force_refresh,
                         )
                         thread_db.commit()
                         # Don't pass ORM objects across threads — just IDs.
@@ -466,6 +468,7 @@ def _enrich_sync():
                         address=address, user_id=current_user.id,
                         db=db, default_strategy=strategy,
                         providers=["rentcast"],
+                        force_refresh=force_refresh,
                     )
 
             enrichment = await asyncio.to_thread(_enrich_sync) if _use_thread else _enrich_sync()
@@ -952,3 +955,84 @@ async def compare_strategies(
         recommendation=recommendation,
         recommendation_reason=reason,
     )
+
+
+# ---------------------------------------------------------------------------
+# POST /api/analysis/admin/cleanup-poisoned — one-time DB cleanup
+# ---------------------------------------------------------------------------
+
+@router.post("/admin/cleanup-poisoned")
+async def cleanup_poisoned_properties(
+    request: Request,
+    db: Session = Depends(get_db),
+):
+    """Delete properties created during the RENTCAST_API_KEY outage.
+
+    Requires X-Internal-Key header. These properties have no enrichment data
+    and their dedup records prevent re-analysis of those addresses.
+    """
+    import hmac
+    import os
+    from sqlalchemy import text
+
+    internal_key = os.getenv("INTERNAL_API_KEY", "")
+    provided_key = request.headers.get("X-Internal-Key", "")
+    if not internal_key or not hmac.compare_digest(provided_key, internal_key):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    # Find poisoned properties
+    poisoned = db.execute(text("""
+        SELECT id, address_line1, city, state, zip_code
+        FROM properties
+        WHERE bedrooms IS NULL
+          AND sqft IS NULL
+          AND property_type IS NULL
+          AND is_sample = false
+          AND is_deleted = false
+    """)).fetchall()
+
+    if not poisoned:
+        return {"deleted": 0, "message": "No poisoned properties found"}
+
+    ids = [row.id for row in poisoned]
+
+    # Delete FK-dependent rows
+    deleted_counts = {}
+    for table in [
+        "data_source_events", "analysis_scenarios", "transactions",
+        "payments", "obligations", "financing_instruments", "rehab_projects",
+        "buyer_packets", "documents", "tasks", "communications",
+        "skip_traces", "mail_campaigns", "reports",
+    ]:
+        result = db.execute(
+            text(f"DELETE FROM {table} WHERE property_id = ANY(:ids)"),
+            {"ids": ids},
+        )
+        if result.rowcount > 0:
+            deleted_counts[table] = result.rowcount
+
+    # Unlink deals (nullable FK)
+    result = db.execute(
+        text("UPDATE deals SET property_id = NULL WHERE property_id = ANY(:ids)"),
+        {"ids": ids},
+    )
+    if result.rowcount > 0:
+        deleted_counts["deals_unlinked"] = result.rowcount
+
+    # Delete the properties
+    result = db.execute(
+        text("DELETE FROM properties WHERE id = ANY(:ids)"),
+        {"ids": ids},
+    )
+    deleted_counts["properties"] = result.rowcount
+
+    db.commit()
+
+    addresses = [f"{r.address_line1}, {r.city} {r.state} {r.zip_code}" for r in poisoned]
+    logger.info("Cleaned up %d poisoned properties: %s", len(ids), addresses)
+
+    return {
+        "deleted": len(ids),
+        "addresses": addresses,
+        "details": deleted_counts,
+    }

backend/scripts/cleanup_poisoned_properties.py

@@ -0,0 +1,118 @@
+"""One-time cleanup: delete properties created during the RENTCAST_API_KEY outage.
+
+These properties have no enrichment data (no bedrooms, no sqft, no data_sources)
+and their scenarios have no purchase_price. Their dedup records prevent re-analysis.
+
+Run via: python3 scripts/cleanup_poisoned_properties.py [DATABASE_URL]
+  - Inside Railway container: uses DATABASE_URL from env
+  - Locally: pass the public Postgres URL as an argument
+"""
+
+import os
+import sys
+
+# Add parent dir so imports work when run from backend/
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+# Allow DATABASE_URL override via CLI argument
+if len(sys.argv) > 1:
+    os.environ["DATABASE_URL"] = sys.argv[1]
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.orm import sessionmaker
+
+_url = os.environ.get("DATABASE_URL")
+if not _url:
+    print("ERROR: DATABASE_URL not set. Pass it as an argument or set the env var.")
+    sys.exit(1)
+
+engine = create_engine(_url)
+SessionLocal = sessionmaker(bind=engine)
+
+db = SessionLocal()
+
+try:
+    # 1. Find poisoned properties: no physical data AND not sample data
+    poisoned = db.execute(text("""
+        SELECT p.id, p.address_line1, p.city, p.state, p.zip_code, p.created_at
+        FROM properties p
+        WHERE p.bedrooms IS NULL
+          AND p.sqft IS NULL
+          AND p.property_type IS NULL
+          AND p.is_sample = false
+          AND p.is_deleted = false
+    """)).fetchall()
+
+    if not poisoned:
+        print("No poisoned properties found. Nothing to clean up.")
+        sys.exit(0)
+
+    print(f"Found {len(poisoned)} poisoned properties:")
+    for row in poisoned:
+        print(f"  {row.id} — {row.address_line1}, {row.city} {row.state} {row.zip_code} (created {row.created_at})")
+
+    ids = [row.id for row in poisoned]
+
+    # 2. Delete FK-dependent rows (order matters: children before parents)
+    fk_tables = [
+        "data_source_events",
+        "analysis_scenarios",
+        "transactions",
+        "payments",
+        "obligations",
+        "financing_instruments",
+        "rehab_projects",
+        "buyer_packets",
+        "documents",
+        "tasks",
+        "communications",
+        "skip_traces",
+        "mail_campaigns",
+        "reports",
+    ]
+
+    for table in fk_tables:
+        result = db.execute(
+            text(f"DELETE FROM {table} WHERE property_id = ANY(:ids)"),
+            {"ids": ids},
+        )
+        if result.rowcount > 0:
+            print(f"  Deleted {result.rowcount} rows from {table}")
+
+    # Deals have nullable property_id — null it out instead of deleting the deal
+    result = db.execute(
+        text("UPDATE deals SET property_id = NULL WHERE property_id = ANY(:ids)"),
+        {"ids": ids},
+    )
+    if result.rowcount > 0:
+        print(f"  Unlinked {result.rowcount} deals from poisoned properties")
+
+    # 3. Delete the poisoned properties
+    result = db.execute(
+        text("DELETE FROM properties WHERE id = ANY(:ids)"),
+        {"ids": ids},
+    )
+    print(f"  Deleted {result.rowcount} poisoned properties")
+
+    db.commit()
+
+    # 4. Verify
+    remaining = db.execute(text("""
+        SELECT count(*) FROM properties
+        WHERE bedrooms IS NULL AND sqft IS NULL AND property_type IS NULL
+          AND is_sample = false AND is_deleted = false
+    """)).scalar()
+    print(f"\nVerification: {remaining} poisoned properties remaining (should be 0)")
+
+except Exception as e:
+    db.rollback()
+    print(f"ERROR: {e}")
+    raise
+finally:
+    db.close()