> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homelogs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals & Methodology

> Public overview of how HomeLogs signals are generated and versioned

## What a signal is

A signal is a permit-backed decision for a location scope.

Each signal row returns:

* `decision`: `positive`, `negative`, or `insufficient_data`
* `score`: normalized 0.0 to 1.0
* `confidence`: confidence level for that decision
* `reasons`: deterministic reason codes explaining the decision
* `computed_at`: timestamp of the scoring run

## Signal families

### Geo-scoped signals

Geo-scoped signals use a location anchor and are exposed through:

* `GET /v1/signals/geo/location/{geo_id}`
* `GET /v1/signals/geo/search`
* `GET /v1/signals/catalog`

Quick examples:

```bash theme={null}
# One location
GET /v1/signals/geo/location/{geo_id}?signal_keys=roofing_activity_hotspot,hvac_activity_hotspot

# Ranked search across WA
GET /v1/signals/geo/search?state=WA&geo_type=county&signal_keys=roofing_activity_hotspot&decision=positive&min_score=0.60
```

These reads are keyed by location scope such as `city`, `zip`, `county`, `jurisdiction`, or `state`.
For the current customer-facing signal catalog, see [Signals Catalog](/signals).

### Permit-scoped signals

Permit-scoped signals use a non-property `geo_id` and are exposed through:

* `GET /v1/signals/permit/leads`
* `GET /v1/signals/permit/stats`

These reads require:

* `geo_id`
* a non-property anchor
* customer-facing permit signal keys such as `site_prep_issued_nowcast`, `new_construction_issued_nowcast`, `framing_nowcast_early`, `framing_window_late`, `rough_in_nowcast_early`, and `rough_in_window_late`

Freshness defaults to the last 60 days. Pass `include_stale=true` to disable the freshness window, or set `max_freshness_days` between `1` and `3650`.

Lead rows include the trust fields used for ranking and review:

* `event_date_used`
* `signal_basis`
* `confidence`
* `reason_codes`
* `freshness_lag_days`

Public basis labels are `observed_event` and `inferred_timing`.

The signal catalog includes both geo-scoped and permit-signal entries, so discovery stays in one place.

## Current production signals (WA)

Current public geo signals:

* `roofing_activity_hotspot`
* `hvac_activity_hotspot`

Current public permit-pack signals:

* `site_prep_issued_nowcast`
* `new_construction_issued_nowcast`
* `framing_nowcast_early`
* `framing_window_late`
* `rough_in_nowcast_early`
* `rough_in_window_late`

## How signals are computed (conceptual)

Geo-scoped signals compare recent permit activity to prior activity for the same location scope.\
At a high level, we evaluate:

* current activity level
* change vs previous periods
* minimum support needed to make a reliable call

## Decision logic (high level)

Signals are deterministic and profile-driven.

1. Eligibility check\
   If data support is too low for a reliable decision, output is `insufficient_data`.

2. Positive check\
   If activity and momentum meet the profile requirements, output is `positive`.

3. Otherwise\
   Output is `negative`.

Reason codes explain why the decision was assigned (for example activity threshold met, trend up, or low support).

## Confidence interpretation

Confidence reflects how much supporting evidence exists for that location decision.

* lower support typically yields lower confidence
* stronger support yields higher confidence

This is designed to avoid over-confidence in sparse geographies.

## Timing guidance

Observed nowcasts are best when you want the most literal read on the permit record.

Early inferred windows are best when you want more lead time and can accept more uncertainty.

Late inferred windows are best when you want tighter timing and fewer premature leads.

Freshness still matters: if your source data lands monthly, the support behind a valid signal can still be several days old.

## Versioning and release control

Signal reads are controlled by active pointers.\
`signal_release_pointers` selects active versions by `state` + `signal_key`.

This allows:

* predictable production behavior
* pointer-based rollback
* safe promotion of new runs without breaking clients

## Product boundaries

* Signals are ranking inputs, not guarantees.
* Signals do not replace underwriting, legal, or compliance review.
* Confidence can vary across geographies based on data availability.

Use signals as ranking and prioritization inputs, then combine with your own workflow logic.