property-shared 0.1.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1 @@
+"""Shared property service package."""

app/api/__init__.py

@@ -0,0 +1 @@
+"""API routers for the shared service."""

app/api/routes.py

@@ -0,0 +1,12 @@
+from fastapi import APIRouter
+
+from .v1 import epc, health, meta, planning, ppd, report, rightmove
+
+api_router = APIRouter(prefix="/v1")
+api_router.include_router(health.router)
+api_router.include_router(ppd.router)
+api_router.include_router(epc.router)
+api_router.include_router(rightmove.router)
+api_router.include_router(planning.router)
+api_router.include_router(report.router)
+api_router.include_router(meta.router)

app/api/v1/__init__.py

@@ -0,0 +1 @@
+"""v1 API routers."""

app/api/v1/epc.py

@@ -0,0 +1,90 @@
+"""EPC API endpoint."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.schemas.epc import EPCRecordResponse
+from app.services.epc_service import EPCService
+
+router = APIRouter(prefix="/epc", tags=["epc"])
+service = EPCService()
+
+# UK postcode regex for parsing combined address strings
+UK_POSTCODE_RE = re.compile(
+    r"([A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2})\s*$",
+    re.IGNORECASE,
+)
+
+
+def _parse_address_query(q: str) -> tuple[Optional[str], Optional[str]]:
+    """Parse a combined address string into (postcode, address).
+
+    Examples:
+        "10 Downing Street, SW1A 2AA" -> ("SW1A 2AA", "10 Downing Street")
+        "SW1A 2AA" -> ("SW1A 2AA", None)
+    """
+    q = q.strip()
+    match = UK_POSTCODE_RE.search(q)
+    if match:
+        postcode = match.group(1).upper()
+        # Everything before the postcode is the address
+        address_part = q[: match.start()].strip().rstrip(",").strip()
+        return (postcode, address_part if address_part else None)
+    return (None, None)
+
+
+@router.get("/certificate/{certificate_hash}", response_model=EPCRecordResponse)
+async def get_certificate(
+    certificate_hash: str,
+    include_raw: bool = Query(False, description="Include raw EPC API JSON"),
+) -> EPCRecordResponse:
+    """Get EPC certificate by lmk-key (certificate hash)."""
+    if not service.is_configured():
+        raise HTTPException(status_code=501, detail="EPC client not configured")
+
+    result = await service.get_certificate(
+        certificate_hash=certificate_hash, include_raw=include_raw
+    )
+    if result is None:
+        raise HTTPException(status_code=404, detail="No EPC certificate found")
+    return result
+
+
+@router.get("/search", response_model=EPCRecordResponse)
+async def search(
+    postcode: Optional[str] = Query(None, min_length=2),
+    address: Optional[str] = None,
+    q: Optional[str] = Query(None, description="Combined address query, e.g. '10 Downing Street, SW1A 2AA'"),
+    include_raw: bool = Query(False, description="Include raw EPC API JSON"),
+) -> EPCRecordResponse:
+    """Search for an EPC certificate by postcode (optional address match).
+
+    Supports two modes:
+    1. Explicit: postcode=SW1A+2AA&address=10+Downing+Street
+    2. Combined: q=10+Downing+Street,+SW1A+2AA (postcode parsed from end)
+    """
+    if not service.is_configured():
+        raise HTTPException(status_code=501, detail="EPC client not configured")
+
+    # Parse combined query if provided
+    if q:
+        parsed_postcode, parsed_address = _parse_address_query(q)
+        if not parsed_postcode:
+            raise HTTPException(
+                status_code=422,
+                detail="Could not parse postcode from query. Use format: '10 Downing Street, SW1A 2AA'",
+            )
+        postcode = parsed_postcode
+        address = parsed_address or address
+
+    if not postcode:
+        raise HTTPException(status_code=422, detail="postcode or q parameter required")
+
+    result = await service.search(postcode=postcode, address=address, include_raw=include_raw)
+    if result is None:
+        raise HTTPException(status_code=404, detail="No EPC certificate found")
+    return result

app/api/v1/health.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health", summary="Health check")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}

app/api/v1/meta.py

@@ -0,0 +1,29 @@
+"""Meta endpoints for service introspection."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from app.core.config import get_settings
+from app.services.epc_service import EPCService
+
+router = APIRouter(prefix="/meta", tags=["meta"])
+
+
+@router.get("/integrations", summary="Integration configuration status")
+async def integrations() -> dict[str, object]:
+    """Return which integrations are configured/enabled.
+
+    Intended for AI agents / clients to self-check capabilities before calling.
+    """
+    settings = get_settings()
+    epc = EPCService()
+
+    return {
+        "environment": settings.environment,
+        "integrations": {
+            "ppd": {"available": True, "configured": True},
+            "rightmove": {"available": True, "configured": True},
+            "epc": {"available": True, "configured": epc.is_configured()},
+        },
+    }

app/api/v1/planning.py

@@ -0,0 +1,249 @@
+"""Planning API endpoints: scrape UK council planning portals."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, HttpUrl
+
+from property_core.planning_service import PlanningService
+
+router = APIRouter(prefix="/planning", tags=["planning"])
+service = PlanningService()
+
+
+class PlanningScraperRequest(BaseModel):
+    """Request to scrape a planning application."""
+    url: str
+    save_screenshots: bool = False
+
+
+class PlanningScraperResponse(BaseModel):
+    """Response from planning scraper."""
+    url: str
+    council_system: str
+    screenshots_captured: int
+    data: dict[str, Any]
+
+
+class PlanningScrapeError(BaseModel):
+    """Error response."""
+    url: str
+    error: str
+
+
+@router.post("/scrape", response_model=PlanningScraperResponse)
+def scrape_application(
+    request: PlanningScraperRequest,
+) -> PlanningScraperResponse:
+    """
+    Scrape a single planning application from any UK council portal.
+
+    Uses vision AI to extract structured data from screenshots.
+    Supports Idox, Northgate, Ocella, Arcus, and generic systems.
+
+    Note: This is a sync endpoint that may take 20-40 seconds.
+    """
+    try:
+        from property_core.planning_scraper import scrape_planning_application
+    except ImportError as e:
+        raise HTTPException(
+            status_code=501,
+            detail=f"Planning scraper not available: {e}. Install playwright and openai.",
+        ) from e
+
+    try:
+        result = scrape_planning_application(
+            url=request.url,
+            save_screenshots=request.save_screenshots,
+        )
+        return PlanningScraperResponse(**result)
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Scrape failed: {e}") from e
+
+
+class ProbeRequest(BaseModel):
+    """Request for connectivity probe."""
+    url: str
+    timeout_ms: int = 30000
+
+
+class ProbeResponse(BaseModel):
+    """Diagnostic probe response."""
+    url: str
+    success: bool
+    page_title: Optional[str]
+    status_code: Optional[int]
+    load_time_ms: Optional[int]
+    screenshot_base64: Optional[str]
+    html_snippet: Optional[str]
+    blocking_indicators: list[str]
+    error: Optional[str]
+    proxy_used: Optional[str] = None
+
+
+@router.post("/probe", response_model=ProbeResponse)
+def probe_url(request: ProbeRequest) -> ProbeResponse:
+    """
+    Quick connectivity probe to diagnose access issues.
+
+    Returns screenshot, HTML snippet, and blocking indicators.
+    Use this to diagnose why scraping might be failing (IP blocks, captchas, etc).
+    """
+    try:
+        from property_core.planning_scraper import probe_connectivity
+    except ImportError as e:
+        raise HTTPException(
+            status_code=501,
+            detail=f"Probe not available: {e}",
+        ) from e
+
+    try:
+        result = probe_connectivity(url=request.url, timeout_ms=request.timeout_ms)
+        return ProbeResponse(**result)
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Probe failed: {e}") from e
+
+
+@router.get("/search")
+def search_by_postcode(
+    postcode: str = Query(..., min_length=2, description="UK postcode"),
+) -> dict[str, Any]:
+    """Search for planning applications by postcode.
+
+    Looks up the council for this postcode and returns search URLs.
+    For Idox councils (most common), provides a direct search URL.
+    For other systems, provides the search page and instructions.
+
+    Note: Actual scraping of search results requires UK residential IP.
+    """
+    try:
+        return service.search(postcode)
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Planning search failed: {e}") from e
+
+
+@router.get("/council-for-postcode")
+def council_for_postcode(
+    postcode: str = Query(..., min_length=2, description="UK postcode"),
+    include_raw: bool = Query(False, description="Include full postcodes.io response"),
+) -> dict[str, Any]:
+    """Look up the planning council for a UK postcode.
+
+    Uses postcodes.io to identify the local authority, then matches to our
+    councils database. Returns council info if found, otherwise returns
+    local authority info for reference.
+    """
+    try:
+        return service.council_for_postcode(postcode, include_raw=include_raw)
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Postcode lookup failed: {e}") from e
+
+
+@router.get("/councils")
+def list_councils() -> dict[str, Any]:
+    """List verified UK council planning portals."""
+    return service.list_councils()
+
+
+@router.get("/council/{code}")
+def get_council(code: str) -> dict[str, Any]:
+    """Get details for a specific council by code."""
+    council = service.get_council(code)
+    if not council:
+        raise HTTPException(status_code=404, detail=f"Council '{code}' not found")
+    return council
+
+
+class SearchResultsRequest(BaseModel):
+    """Request to search for planning applications."""
+    postcode: str
+    portal_url: Optional[str] = None
+    system: Optional[str] = None
+    max_results: int = 10
+
+
+class PlanningApplication(BaseModel):
+    """Single planning application result."""
+    reference: Optional[str] = None
+    address: Optional[str] = None
+    description: Optional[str] = None
+    status: Optional[str] = None
+    link: Optional[str] = None
+
+
+class SearchResultsResponse(BaseModel):
+    """Response with planning search results."""
+    postcode: str
+    council_name: Optional[str] = None
+    system: Optional[str] = None
+    portal_url: str
+    results: list[PlanningApplication]
+    count: int
+
+
+@router.post("/search-results", response_model=SearchResultsResponse)
+def search_results(request: SearchResultsRequest) -> SearchResultsResponse:
+    """
+    Search for planning applications by postcode.
+
+    Uses vision-guided browser automation to fill council search forms
+    and extract results. Takes 30-60 seconds.
+
+    Requires: Playwright, OpenAI API key, UK residential IP (or proxy).
+    """
+    try:
+        from property_core.planning_scraper import search_planning_by_postcode
+    except ImportError as e:
+        raise HTTPException(
+            status_code=501,
+            detail=f"Planning search not available: {e}. Install playwright and openai.",
+        ) from e
+
+    # Resolve portal_url from postcode if not provided
+    portal_url = request.portal_url
+    system = request.system
+    council_name = None
+
+    if not portal_url:
+        search_data = service.search(request.postcode)
+        if not search_data.get("council_found"):
+            raise HTTPException(
+                status_code=404,
+                detail=f"No council found for postcode '{request.postcode}'",
+            )
+        council = search_data["council"]
+        council_name = council.get("name")
+        system = system or council.get("system")
+        urls = search_data.get("search_urls", {})
+        portal_url = urls.get("direct_search") or urls.get("search_page")
+        # For Idox, use simple search form (not weeklyList)
+        if system == "idox" and portal_url:
+            if "weeklyList" in portal_url or "action=simple" not in portal_url:
+                base = portal_url.split("/search.do")[0] if "/search.do" in portal_url else portal_url.rstrip("/")
+                portal_url = f"{base}/search.do?action=simple"
+        if not portal_url:
+            raise HTTPException(
+                status_code=404,
+                detail="No search URL available for this council",
+            )
+
+    try:
+        results = search_planning_by_postcode(
+            portal_url=portal_url,
+            postcode=request.postcode,
+            max_results=request.max_results,
+            system=system,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Search failed: {e}") from e
+
+    return SearchResultsResponse(
+        postcode=request.postcode,
+        council_name=council_name,
+        system=system,
+        portal_url=portal_url,
+        results=[PlanningApplication(**app) for app in results],
+        count=len(results),
+    )

app/api/v1/ppd.py

@@ -0,0 +1,178 @@
+"""PPD API endpoints: search, comps, and transaction record lookup."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.schemas.ppd import (
+    PPDCompsResponse,
+    PPDDownloadURLResponse,
+    PPDSearchResponse,
+    PPDTransaction,
+    PPDTransactionRecordResponse,
+)
+from property_core.enrichment import compute_enriched_stats, enrich_comps_with_epc
+from property_core.ppd_service import PPDService
+
+router = APIRouter(prefix="/ppd", tags=["ppd"])
+service = PPDService()
+
+
+@router.get("/download-url", response_model=PPDDownloadURLResponse)
+def download_url(
+    kind: Literal["complete", "year", "monthly"] = "monthly",
+    year: Optional[int] = Query(None, ge=1995),
+    part: Optional[int] = Query(None, ge=1, le=2),
+    fmt: Literal["csv", "txt"] = "csv",
+) -> PPDDownloadURLResponse:
+    """Return a direct Land Registry download URL for bulk datasets."""
+    try:
+        url = service.download_url(kind=kind, year=year, part=part, fmt=fmt)
+        return PPDDownloadURLResponse(url=url)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.get("/transactions", response_model=PPDSearchResponse)
+def transactions(
+    postcode: Optional[str] = Query(None, min_length=2),
+    postcode_prefix: Optional[str] = Query(None, min_length=2),
+    from_date: Optional[str] = Query(None, description="YYYY-MM-DD"),
+    to_date: Optional[str] = Query(None, description="YYYY-MM-DD"),
+    min_price: Optional[int] = Query(None, ge=0),
+    max_price: Optional[int] = Query(None, ge=0),
+    property_type: Optional[str] = Query(None, description="D/S/T/F/O"),
+    estate_type: Optional[str] = Query(None, description="F/L"),
+    transaction_category: Optional[str] = Query(None, description="A/B"),
+    record_status: Optional[str] = Query(None, description="A/C/D"),
+    new_build: Optional[bool] = None,
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+    order_desc: bool = True,
+    include_raw: bool = Query(False, description="Include raw SPARQL bindings"),
+) -> PPDSearchResponse:
+    """Search PPD transactions using postcode or postcode prefix (district/sector)."""
+    if bool(postcode) == bool(postcode_prefix):
+        raise HTTPException(
+            status_code=422,
+            detail="Provide exactly one of postcode or postcode_prefix.",
+        )
+
+    try:
+        result = service.search_transactions(
+            postcode=postcode,
+            postcode_prefix=postcode_prefix,
+            from_date=from_date,
+            to_date=to_date,
+            min_price=min_price,
+            max_price=max_price,
+            property_type=property_type,
+            estate_type=estate_type,
+            transaction_category=transaction_category,
+            record_status=record_status,
+            new_build=new_build,
+            limit=limit,
+            offset=offset,
+            order_desc=order_desc,
+            include_raw=include_raw,
+        )
+        return PPDSearchResponse(**result)
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=502, detail=f"PPD search failed: {exc}") from exc
+
+
+@router.get("/address-search", response_model=PPDSearchResponse)
+def address_search(
+    paon: Optional[str] = Query(None, min_length=1, description="Primary addressable object name"),
+    saon: Optional[str] = Query(None, min_length=1, description="Secondary addressable object name"),
+    street: Optional[str] = Query(None, min_length=2),
+    town: Optional[str] = Query(None, min_length=2),
+    county: Optional[str] = Query(None, min_length=2),
+    postcode: Optional[str] = Query(None, min_length=2),
+    postcode_prefix: Optional[str] = Query(None, min_length=2),
+    limit: int = Query(25, ge=1, le=50),
+    include_raw: bool = Query(False, description="Include raw SPARQL bindings"),
+) -> PPDSearchResponse:
+    """Web-form style address search (requires at least two fields)."""
+    provided = [v for v in (paon, saon, street, town, county, postcode, postcode_prefix) if v]
+    if len(provided) < 2:
+        raise HTTPException(
+            status_code=422, detail="Provide at least two address fields (e.g., postcode + street)."
+        )
+
+    try:
+        result = service.address_search(
+            paon=paon,
+            saon=saon,
+            street=street,
+            town=town,
+            county=county,
+            postcode=postcode,
+            postcode_prefix=postcode_prefix,
+            limit=limit,
+            include_raw=include_raw,
+        )
+        return PPDSearchResponse(**result)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=502, detail=f"PPD address search failed: {exc}") from exc
+
+
+@router.get("/comps", response_model=PPDCompsResponse)
+async def comps(
+    postcode: str = Query(..., min_length=2),
+    property_type: Optional[str] = Query(None, description="D/S/T/F/O"),
+    months: int = Query(24, ge=1, le=120),
+    limit: int = Query(50, ge=1, le=200),
+    search_level: Literal["postcode", "sector", "district"] = "sector",
+    address: Optional[str] = Query(None, description="Subject property address for context"),
+    enrich_epc: bool = Query(False, description="Enrich comps with EPC floor area and price/sqft"),
+) -> PPDCompsResponse:
+    """Get comparable sales summary for a postcode (sector/district supported).
+
+    If address is provided, returns subject_property with its transaction history.
+    If enrich_epc is True, attaches EPC floor area and price-per-sqft to each comp.
+    """
+    try:
+        result = service.comps(
+            postcode=postcode,
+            property_type=property_type,
+            months=months,
+            limit=limit,
+            search_level=search_level,
+            address=address,
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=502, detail=f"PPD comps failed: {exc}") from exc
+
+    if enrich_epc:
+        comp_dicts = [t.model_dump() for t in result.transactions]
+        enriched = await enrich_comps_with_epc(comp_dicts)
+        result.transactions = [PPDTransaction(**d) for d in enriched]
+        compute_enriched_stats(result)
+
+    return result
+
+
+@router.get("/transaction/{transaction_id}", response_model=PPDTransactionRecordResponse)
+def transaction_record(
+    transaction_id: str,
+    view: str = Query("all", description="Linked Data view (e.g., all, basic)"),
+    include_raw: bool = Query(False, description="Include raw linked-data JSON"),
+) -> PPDTransactionRecordResponse:
+    """Fetch and normalize a single transaction record from the Linked Data API."""
+    try:
+        result = service.transaction_record(
+            transaction_id=transaction_id,
+            view=view,
+            include_raw=include_raw,
+        )
+        return PPDTransactionRecordResponse(**result)
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(
+            status_code=502,
+            detail=f"PPD transaction lookup failed: {exc}",
+        ) from exc

app/api/v1/report.py

@@ -0,0 +1,66 @@
+"""Property report endpoint: aggregated property assessment."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel
+
+from property_core.models.report import PropertyReport
+from property_core.report_service import PropertyReportService
+
+router = APIRouter(prefix="/property", tags=["property"])
+
+
+class ReportRequest(BaseModel):
+    """Request to generate a property report."""
+    address: str
+    include_rentals: bool = True
+    include_sales_market: bool = True
+    ppd_months: int = 24
+    search_radius: float = 0.5
+
+
+@router.post("/report", response_model=PropertyReport)
+async def generate_report(
+    request: ReportRequest,
+    format: Optional[str] = Query(None, description="Response format: 'html' or default JSON"),
+):
+    """
+    Generate a comprehensive property report.
+
+    Aggregates data from Land Registry (PPD), EPC register, and Rightmove
+    (rentals + sales) into a single assessment with estimated value range,
+    yield analysis, and market context.
+
+    Address format: "10 Downing Street, SW1A 2AA" (postcode at end).
+    """
+    service = PropertyReportService()
+
+    try:
+        report = await service.generate_report(
+            address_query=request.address,
+            include_rentals=request.include_rentals,
+            include_sales_market=request.include_sales_market,
+            ppd_months=request.ppd_months,
+            search_radius=request.search_radius,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Report generation failed: {e}") from e
+
+    if format == "html":
+        from pathlib import Path
+
+        from jinja2 import Environment, FileSystemLoader
+
+        template_dir = Path(__file__).parent.parent.parent / "templates"
+        env = Environment(loader=FileSystemLoader(str(template_dir)))
+        template = env.get_template("report.html")
+        html = template.render(report=report)
+        return HTMLResponse(content=html)
+
+    return report