feat: implement signal overrides for phone number reputation checks

Author: SagarBiswas-MultiHAT

.gitignore

@@ -16,4 +16,3 @@ venv/
 ENV/
 .env
 .cache/
-

README.md

@@ -1,16 +1,35 @@
-# file: README.md
 # phoneint (Phone Number OSINT)
 
-`phoneint` parses and enriches phone numbers offline (via `phonenumbers`) and runs optional, pluggable async reputation checks to produce an auditable risk score and report. It is designed to be transparent, explainable, and safe-by-default.
+`phoneint` parses and enriches phone numbers offline (via `phonenumbers`) and runs optional, pluggable async reputation checks to produce an auditable risk score and report. The goal is transparent, explainable OSINT with clear inputs, visible signals, and reproducible output.
 
 ## Disclaimer (Read First)
 
 **This tool is for lawful, ethical OSINT research only.**
 Do not use it to harass, stalk, dox, or violate privacy. Always comply with applicable laws and third-party Terms of Service.
 
-## What This Tool Does (At a Glance)
-
-- Normalizes numbers to E.164 and common formats
+## Table of Contents
+
+- What This Tool Does
+- How It Works
+- Features
+- Install
+- Quick Start (CLI)
+- GUI Usage
+- Signals and Scoring
+- Signal Overrides (Testing)
+- Configuration
+- Adapters
+- Owner Intelligence
+- Reports
+- Example Numbers
+- Troubleshooting
+- Development and CI
+- Docker
+- License
+
+## What This Tool Does
+
+- Normalizes numbers to E.164 and common display formats
 - Enriches with deterministic metadata (carrier when available, region, time zones, number type)
 - Optionally queries public OSINT sources via adapters
 - Produces explainable risk scoring and owner intelligence
@@ -22,17 +41,17 @@ Do not use it to harass, stalk, dox, or violate privacy. Always comply with appl
 1. **Parse + Normalize**: `phonenumbers` parses the input to E.164 and standard formats.
 2. **Deterministic Enrichment**: carrier, time zone, number type, and region are derived offline.
 3. **Adapter Checks (Optional)**: adapters query public sources and return evidence items.
-4. **Scoring**: risk score is calculated from explicit signals with a breakdown.
+4. **Signals + Scoring**: boolean signals are derived and a risk score is computed with a breakdown.
 5. **Owner Intelligence (Optional)**: evidence is converted into associations and confidence scores.
 6. **Reporting**: a full JSON report is built and can be exported to CSV/PDF.
 
 ## Features
 
-- E.164 parsing + normalization (`phonenumbers`)
-- Deterministic enrichment: carrier (when available), region/country name, time zones, number type, ISO code
+- E.164 parsing and normalization (`phonenumbers`)
+- Deterministic enrichment: carrier, region, time zones, number type, ISO code
 - Async adapters (`httpx`): DuckDuckGo Instant Answer, Google Custom Search, public dataset checks
 - Explainable risk scoring with configurable weights (YAML/JSON)
-- Owner Intelligence with audit trail for PII-capable adapters
+- Owner intelligence with audit trail for PII-capable adapters
 - Reports: JSON + CSV; optional PDF (extra dependency)
 - Optional SQLite TTL caching
 - CLI and GUI (PySide6 + qasync)
@@ -43,28 +62,28 @@ Python 3.11+ recommended.
 
 ```bash
 python -m venv .venv
-.\.venv\Scripts\Activate.ps1
+\.\.venv\Scripts\Activate.ps1
 
-pip install -U pip
-pip install .
+python -m pip install -U pip
+python -m pip install -e .
 ```
 
 Dev tools:
 
 ```bash
-pip install ".[dev]"
+python -m pip install ".[dev]"
 ```
 
 GUI:
 
 ```bash
-pip install ".[gui]"
+python -m pip install ".[gui]"
 ```
 
 PDF export:
 
 ```bash
-pip install ".[pdf]"
+python -m pip install ".[pdf]"
 ```
 
 ## Quick Start (CLI)
@@ -94,143 +113,57 @@ phoneint report report.json --format csv --output evidence.csv
 phoneint report report.json --format pdf --output report.pdf
 ```
 
-Launch GUI:
+If you have a national-format number without `+CC`, provide a default region:
 
 ```bash
-phoneint serve-gui
-```
-
-## GUI Highlights
-
-- **Download report**: choose `json`, `csv`, or `pdf` and click Save.
-- **Owner Intelligence**: consent checkbox gates PII-capable lookups.
-- **Evidence list**: populated as adapters complete.
-- **Non-blocking**: UI remains responsive during async checks.
-
-## Example Numbers
-These example numbers are reserved test ranges, fictional examples, or public-format demonstrations intended for documentation and testing only. Do not use them to query private services or to target real individuals.
-
-### 1. Reserved Test Numbers (RFC / NANP)
-
-These numbers are explicitly reserved for testing and documentation and are never assigned to real users.
-
-```text
-+1 202-555-0100
-+1 202-555-0101
-+1 202-555-0147
-+1 202-555-0199
-```
-
-Expected behavior (when running in example/test mode or when marked in harnesses):
-
-- `number_classification`: `reserved_test_number`
-- `example_mode`: `true`
-- `risk_score`: `0`
-- No live OSINT checks performed; adapters should be mocked or skipped.
-
-### 2. Toll-Free Number Examples
-
-Useful for testing toll-free detection, multi-timezone handling, and business vs scam ambiguity.
-
-```text
-+1 800-356-9377
-+1 888-555-0000
-+1 877-555-1212
-```
-
-Expected behavior:
-
-- `line_type`: `toll_free`
-- Timezone coverage may be broad or absent depending on enrichment metadata
-- Neutral or low risk in example mode unless synthetic signals are injected
-
-### 3. Fictional Bangladesh Numbers (Example Mode)
-
-These demonstrate country-specific parsing and carrier detection. Treat as fictional/demo data.
-
-```text
-+8801700000000
-+8801800000000
-+8801900000000
+phoneint lookup 6502530000 --region US
 ```
 
-Expected behavior:
+## GUI Usage
 
-- `number_classification`: `fictional_example`
-- `example_mode`: `true`
-- `risk_score`: `0`
-- Carrier may be mocked for demo purposes
+Launch:
 
-### 4. International Fictional Examples
-
-Useful for international formatting, country & timezone extraction, and multi-region validation.
-
-```text
-+44 7000 000000   # UK-style fictional number
-+61 400 000 000   # Australia-style fictional mobile
-+49 151 00000000  # Germany-style fictional mobile
+```bash
+phoneint serve-gui
 ```
 
-Expected behavior:
+Highlights:
 
-- Correct country detection
-- Valid international formatting (E.164 and international display)
-- No real OSINT signals in example mode
+- Download report: choose `json`, `csv`, or `pdf` and click Save.
+- Owner Intelligence: consent checkbox gates PII-capable lookups.
+- Evidence list: populated as adapters complete.
+- Non-blocking: UI remains responsive during async checks.
 
-### 5. Spam / Risk Logic Demonstration (Mocked)
+## Signals and Scoring
 
-These are NOT real scam numbers; use them to exercise scoring and signal detection in example/test harnesses.
+`phoneint` calculates a small set of transparent, boolean signals and then computes a risk score with a breakdown. Default signals include:
 
-```text
-+1 202-555-0147   # used to simulate scam_db match in tests
-+1 800-555-9999   # used to simulate classifieds exposure
-```
-
-Expected behavior (example mode only):
+- `found_in_scam_db`: true when the number is matched in the public scam dataset
+- `voip`: true when libphonenumber classifies the number as VoIP
+- `found_in_classifieds`: true when evidence URLs match classifieds domains
+- `business_listing`: true when evidence URLs match business directory domains
 
-- Deterministic mocked signals (e.g., `found_in_scam_db: true` for the first item)
-- Scoring logic exercised without querying live data
+Scoring weights are configurable; see Configuration below.
 
-How to use in tests or demos:
+## Signal Overrides (Testing)
 
-- CLI: run with adapters mocked or with `--no-cache` and a local test adapter.
-- GUI: use a test harness that injects `example_mode` or pre-populates adapter results.
-- Always mark runs that use these numbers as `example_mode=true` in logs/reports so audits can distinguish synthetic data from live OSINT.
+When you need deterministic tests (or you do not have access to provider-specific VoIP numbers), use signal overrides. The override file lets you force signals for specific E.164 numbers.
 
----
+Default override file:
 
+- `phoneint/data/signal_overrides.json`
 
+Example:
 
-If you have a national-format number without `+CC`, provide a default region:
-
-```bash
-phoneint lookup 6502530000 --region US
+```json
+{
+  "voip": ["+14155552671"],
+  "found_in_classifieds": ["+12025550199"],
+  "business_listing": ["+18005550100"]
+}
 ```
 
-## Sample Output (Human Summary)
-
-```text
-E.164: +88027111234
-International: +880 2-7111234
-National: 02-7111234
-Region (ISO): BD
-Country code: 880
-
-Carrier:
-Region: Dhaka
-Time zones: Asia/Dhaka
-Type: fixed_line
-ISO country code: BD
-Dialing prefix: 880
-
-Risk score: 0/100
-
-Breakdown:
-- found_in_scam_db: 0.0 (Matched a public scam dataset)
-- voip: 0.0 (libphonenumber classified the number as VOIP)
-- found_in_classifieds: 0.0 (Evidence URL matched a classifieds domain heuristic)
-- business_listing: -0.0 (Evidence URL matched a business listing domain heuristic)
-```
+You can also set a custom path via `PHONEINT_SIGNAL_OVERRIDES_PATH`.
 
 ## Configuration
 
@@ -241,6 +174,7 @@ Environment variables:
 - `GCS_API_KEY` / `GCS_CX`: required only for the Google Custom Search adapter
 - `PHONEINT_*`: HTTP, cache, logging, default region, scoring weights (JSON)
 - `ENABLE_TRUECALLER` / `TRUECALLER_API_KEY`: required only for PII-capable Truecaller adapter
+- `PHONEINT_SIGNAL_OVERRIDES_PATH`: path to the signal override JSON file
 
 YAML config (recommended for score weights and non-secret defaults):
 
@@ -266,7 +200,7 @@ Or set `PHONEINT_CONFIG=config.yaml` in `.env`.
 
 ## Adapters
 
-- `public`: checks a JSON dataset (ships with `phoneint/data/scam_list.json` as a demo)
+- `public`: checks a JSON dataset (ships with a demo list in `phoneint/data/scam_list.json`)
 - `duckduckgo`: DuckDuckGo Instant Answer API (not full web search)
 - `google`: Google Custom Search (requires your API key + CX)
 
@@ -301,7 +235,7 @@ What it does not do:
 PII-capable adapters (e.g., Truecaller) are disabled by default and will only run when:
 
 1. You provide official credentials via `.env` (never commit secrets)
-2. You explicitly enable the adapter in config/environment
+2. You explicitly enable the adapter in config or environment
 3. You explicitly confirm lawful purpose plus explicit consent (`--enable-pii` in CLI, checkbox in GUI)
 4. An audit trail is recorded in the report (`owner_audit_trail`)
 
@@ -348,24 +282,75 @@ If you do not have official credentials or consent, leave PII disabled. Public e
 ## Reports
 
 - JSON: full report, includes owner intelligence and audit trail
-- CSV: evidence + owner associations + audit trail in a single long table
+- CSV: evidence and owner associations in a single long table
 - PDF: summary pages plus legal disclaimer (requires `reportlab`)
 
-## Docker
+## Example Numbers
+
+These example numbers are reserved test ranges or fictional examples intended for documentation and testing only. Do not use them to query private services or target real individuals.
+
+Reserved test range (NANP):
+
+```text
++1 202-555-0100
++1 202-555-0101
++1 202-555-0147
++1 202-555-0199
+```
+
+Toll-free examples:
+
+```text
++1 800-356-9377
++1 888-555-0000
++1 877-555-1212
+```
+
+International format examples:
+
+```text
++44 7000 000000
++61 400 000 000
++49 151 00000000
+```
+
+If you want deterministic testing for scoring signals, use the signal overrides file described above.
+
+## Troubleshooting
+
+**Error: GUI dependencies not installed**
+
+- Ensure you installed GUI extras into the active venv:
 
 ```bash
-docker build -t phoneint .
-docker run --rm phoneint lookup +16502530000
+python -m pip install ".[gui]"
+```
+
+- If you still see the error, run the GUI directly to surface the real traceback:
+
+```bash
+python run_gui_direct.py
 ```
 
-## Development
+## Development and CI
+
+Local checks (the same checks you would typically run in CI):
 
 ```bash
 black phoneint tests
 mypy phoneint
 pytest
 ```
 
+If you add GitHub Actions, use these commands in your workflow to keep the build green.
+
+## Docker
+
+```bash
+docker build -t phoneint .
+docker run --rm phoneint lookup +16502530000
+```
+
 ## License
 
 MIT. See `LICENSE`.