LifeShield AI (MVP)

LifeShield AI provides:

• Risk analysis API (/analyze)
• Memory search (/memory/search)
• Tracker Agent (/api/tracker/run) – entity enrichment & evidence bundle builder
• Verifier Agent (/api/verifier/run) – claim-level RAG fact verification (Cofacts + 165 + local)
• Three input entrypoints (/line/webhook, /browser/analyze, /web/analyze)
• HF training and evaluation pipeline for 6-class risk classification

Labels (fixed)

• fake_news
• scam
• phishing
• job
• investment
• social

Python Version (Windows)

• Recommended: Python 3.12
• Supported/tested: Python 3.11, 3.12
• Not recommended for this pinned set: Python 3.13+ (for example 3.14 may trigger source builds and fail on Windows)

Rebuild venv (PowerShell, Windows):

cd lifeshield-ai
if (Test-Path .venv) { Remove-Item -Recurse -Force .venv }
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Runtime Setup (API)

cd lifeshield-ai
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Health check:

curl.exe http://127.0.0.1:8000/health

Dashboard (Streamlit)

The project includes a Level-2 demo dashboard with the same analysis pipeline as API/LINE.

Features:

• Input: text, URL, image upload (OCR)
• Output: risk level/label, confidence raw/calibrated, evidence/actions, signals breakdown
• Traceability: event_id, fact-check reference links, memory hit/similarity
• Observability: recent audit log and memory store tables (redacted view only)
• Scam radar: local trends dataset (data/scam_trends.json) with trusted-source links

Run:

python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
streamlit run dashboard/dashboard_app.py

Optional extras (install only when needed):

# Chroma memory backend (optional)
pip install -r requirements.memory-chroma.txt

# Paddle OCR engine (optional)
pip install -r requirements.ocr-paddle.txt

Dashboard mode options:

• DASHBOARD_MODE=direct (default): import and call analyze_payload directly
• DASHBOARD_MODE=api: call POST /analyze by HTTP (configure DASHBOARD_API_URL)

UI modes (new):

• 長輩小助理:
  • Simplified action-first view (安全/注意/可能是詐騙，請小心)
  • Shows only top reasons and next steps
  • Includes a template refusal sentence button
• 一般模式:
  • Standard analysis + audit + memory tabs
• 年輕雷達:
  • Shows TOP5 scam trends and top-3 similar套路 matches
  • Includes matched keywords and trusted source links
• 專業鑑識:
  • Standard tabs + redacted full result JSON for demo forensics view

API demo resilience:

• Sidebar includes API timeout seconds (default 60)
• If API timeout/request fails, dashboard shows clear guidance and one-click fallback to direct

Windows helper:

./scripts/run_dashboard.ps1 -Mode direct
./scripts/run_dashboard.ps1 -Mode api -ApiUrl http://127.0.0.1:8000/analyze

MVP demo note:

• Memory uses persistent local store (data/memory/memory.jsonl) and supports chroma|tfidf|keyword backends.
• FEATURE_MEMORY=false by default, so memory matching is skipped unless explicitly enabled.
• If optional deps (for example chromadb / sentence-transformers / sklearn) are unavailable, memory falls back without crashing.
• Fact-check uses local data (data/fact_check/cofacts_sample.json) with score threshold gating; below threshold means no fact-check evidence.

Environment Variables

.env uses:

APP_NAME=LifeShield AI
CHROMA_PATH=
CHROMA_COLLECTION=
CHROMA_PERSIST_DIR=
CHROMA_COLLECTION_CASES=lifeshield_cases
CHROMA_COLLECTION_USERS=lifeshield_users
CHROMA_COLLECTION_EVIDENCE=lifeshield_evidence
EMBEDDING_MODEL=
EMBEDDING_PROVIDER=sentence_transformers
RISK_MODEL_DIR=
LINE_CHANNEL_SECRET=
LINE_CHANNEL_ACCESS_TOKEN=
GOOGLE_SAFE_BROWSING_API_KEY=
FEATURE_URL_SCAN=true
FEATURE_URL_HEURISTIC=true
FEATURE_IMAGE_SIGNAL=true
FEATURE_FACT_CHECK=true
FACT_CHECK_THRESHOLD=0.40
FEATURE_NER=true
FEATURE_WIKI_LOOKUP=true
FEATURE_COMPANY_REGISTRY=true
FEATURE_DOMAIN_INTEL=true
FEATURE_MEMORY=false
FEATURE_MEMORY_AUTOSAVE=false
FEATURE_CALIBRATION=true
CALIBRATION_MODE=sigmoid
CALIBRATION_TEMPERATURE=1.5
FEATURE_AUDIT_LOG=true
AUDIT_LOG_PATH=data/audit/audit.jsonl
MEMORY_SIM_THRESHOLD=0.80
W_MEMORY=0.08
MEMORY_STORE_PATH=data/memory/memory.jsonl
MEMORY_BACKEND=chroma
MEMORY_TOP_K=5
MEMORY_TTL_DAYS=0
MEMORY_NEAR_DUP_THRESHOLD=0.93
MEMORY_DECAY_PER_DAY=0.0
TESSERACT_PATH=C:/Program Files/Tesseract-OCR/tesseract.exe
TESSERACT_CMD=
TESSDATA_PREFIX=
OCR_ENGINE=tesseract
OCR_LANG=chi_tra+eng
MAX_REPLY_TEXT_CHARS=900
# Tracker Agent
FEATURE_TRACKER=true
SERPAPI_KEY=
BING_KEY=
SPACY_MODEL=zh_core_web_sm
MOEA_MODE=stub
TRACKER_WEB_RESULTS=5
# Verifier Agent
COFACTS_APP_SECRET=
NPA165_CACHE_PATH=data/165_rumor.csv
RETRIEVER_MODE=keyword

spaCy models (optional, for better NER)

python -m spacy download zh_core_web_sm   # Chinese
python -m spacy download en_core_web_sm   # English fallback

If neither model is installed the tracker falls back to regex-based NER automatically.

Security:

• Keep .env.example secret-free (no real token values).
• Do not commit .env to version control.
• Dashboard does not expose webhook raw payload or token/secret values.
• Dashboard text display uses redacted previews ([PHONE], [ACCOUNT], [LINE_ID], [URL]).

Core Endpoints

POST /analyze

Request:

{
  "text": "string",
  "url": "https://optional.url",
  "source": "text|image (optional, default=text)"
}

Response fields:

• risk_label
• confidence
• risk_level
• evidence
• actions
• signals

POST /api/tracker/run

Entity enrichment and evidence gathering.

Request:

{
  "text": "請匯款至帳號 123-456，聯絡 LINE: abc123",
  "locale": "zh-TW"
}

Response fields:

• entities – NER results (type, text, confidence)
• wiki_matches – Wikipedia hits per entity
• wikidata_matches – Wikidata hits per entity
• web_results – web search evidence with credibility scores
• company_records – MOEA GCIS company registry matches
• overall_score – weighted credibility score (0–100)
• reasons – human-readable summary list
• decision_log – 6-step structured trace (NER → Wikipedia → Wikidata → WebSearch → CompanyRegistry → CredibilityScoring)

Quick test:

curl -s -X POST http://127.0.0.1:8000/api/tracker/run \
  -H "Content-Type: application/json" \
  -d '{"text":"台積電 股票投資保證獲利","locale":"zh-TW"}' | python -m json.tool

POST /api/verifier/run

Claim-level fact verification with evidence chain and decision log.

Request:

{
  "text": "老師帶單保證獲利，請先轉帳保證金",
  "locale": "zh-TW"
}

Response fields:

• claims
• evidence_chain (supporting / contradicting / unknown per claim)
• verdict (safe|suspicious|scam|unknown)
• reasons
• reasoning_steps
• decision_log
• raw_sources_summary

Quick test:

curl -s -X POST http://127.0.0.1:8000/api/verifier/run \
  -H "Content-Type: application/json" \
  -d '{"text":"請點連結驗證並匯款到指定帳號","locale":"zh-TW"}' | python -m json.tool

GET /memory/search?q=...

Returns top-5 similar memory cases:

• id
• similarity
• summary

POST /api/memory/add

Add/update one memory item:

{
  "text": "老師帶單保證獲利，請先匯款",
  "type": "scam_case",
  "user_id": "u123",
  "session_id": "s456",
  "metadata": {
    "source": "verifier",
    "domain": "example.com",
    "risk_label": "scam",
    "score": 92.5,
    "entities": {"tax_id": "12345678"},
    "tags": ["investment", "transfer"]
  }
}

POST /api/memory/search

Search similar memory by text + filters:

{
  "text": "保證獲利 匯款",
  "k": 5,
  "filters": {
    "type": ["scam_case", "evidence"],
    "domain": "example.com",
    "user_id": "u123",
    "entities": {"tax_id": "12345678"}
  }
}

Input Module (3 Entrypoints)

1) LINE Bot webhook: POST /line/webhook

Behavior:

• Verifies X-Line-Signature with LINE_CHANNEL_SECRET
• Processes message events for both message.type=text and message.type=image
• Runs analysis by internal function call (analyze_payload) without extra HTTP hop
• Replies via LINE Reply API (/v2/bot/message/reply)
• Does not store user IDs
• Image handling is in-memory only (no image file written to disk)

Image OCR flow:

• Download image bytes from https://api-data.line.me/v2/bot/message/{messageId}/content
• OCR via app/services/ocr_pipeline.py
• Default: improved Tesseract pipeline (chat-area crop + multi-pass OCR candidate selection)
• Engine switch: set OCR_ENGINE=tesseract or OCR_ENGINE=paddle (unset defaults to tesseract)
• Text and image both go through the same analyze_payload pipeline
• If OCR text is too short/empty or Chinese ratio is too low, reply: 我看不到足夠清晰的文字，請改傳原圖或先裁切對話區再上傳。

Week2 Multi-Signal Router

app/services/agent_router.py coordinates multiple signals:

• Always run HF classifier (RiskClassifier)
• URL heuristic (app/agents/url_heuristic.py) when FEATURE_URL_HEURISTIC=true
• URL scan (app/agents/url_scan.py) when URL exists and FEATURE_URL_SCAN=true
• Image signal (app/agents/image_signal.py) for OCR/image text when FEATURE_IMAGE_SIGNAL=true
• Fact-check (app/agents/fact_check.py) when FEATURE_FACT_CHECK=true
• Entity extraction (app/agents/ner.py) when FEATURE_NER=true
• Wikipedia lookup (app/agents/wiki_lookup.py) when FEATURE_WIKI_LOOKUP=true
• Company registry stub (app/agents/company_registry.py) when FEATURE_COMPANY_REGISTRY=true
• Domain intel (app/agents/domain_intel.py) when FEATURE_DOMAIN_INTEL=true
• Optional memory (FEATURE_MEMORY=true) with graceful degradation

Feature flags:

FEATURE_URL_SCAN=true
FEATURE_URL_HEURISTIC=true
FEATURE_IMAGE_SIGNAL=true
FEATURE_FACT_CHECK=true
FACT_CHECK_THRESHOLD=0.40
FEATURE_NER=true
FEATURE_WIKI_LOOKUP=true
FEATURE_COMPANY_REGISTRY=true
FEATURE_DOMAIN_INTEL=true
FEATURE_MEMORY=false
FEATURE_MEMORY_AUTOSAVE=false
FEATURE_CALIBRATION=true
CALIBRATION_MODE=sigmoid
CALIBRATION_TEMPERATURE=1.5
FEATURE_AUDIT_LOG=true
AUDIT_LOG_PATH=data/audit/audit.jsonl
MEMORY_SIM_THRESHOLD=0.80
W_MEMORY=0.08
MEMORY_STORE_PATH=data/memory/memory.jsonl
GOOGLE_SAFE_BROWSING_API_KEY=

Fact-check behavior (Week2 Agent3):

• Input text is matched against local fact-check records (data/fact_check/cofacts_sample.json) with lightweight TF-IDF retrieval.
• top_k=3; if best_score < FACT_CHECK_THRESHOLD then no related claim is emitted (has_related_claim=false, empty evidence, empty reference_links).
• Recommended FACT_CHECK_THRESHOLD range: 0.35-0.45 (default 0.40).
• Only trusted source domains are allowed in reference_links; unmatched/unsafe records are dropped from index.
• When matched, output includes score, best_match_title, clipped summary, and traceable reference_links (max 2).

Memory behavior (Agent5):

• Memory engine is in app/agents/memory_engine/ with persistent JSONL + optional Chroma index.
• Backend selection: MEMORY_BACKEND=chroma|tfidf|keyword.
• Embedding providers: EMBEDDING_PROVIDER=sentence_transformers|openai|none.
• If you need Chroma backend, install: pip install -r requirements.memory-chroma.txt
• Chroma collections are split by context:
  • lifeshield_cases
  • lifeshield_users
  • lifeshield_evidence
• If Chroma/embedding deps are unavailable, service falls back to tfidf, then keyword, without crashing.
• Memory schema includes id, case_id, version, type, text, metadata, user_id/session_id.
• Upsert policy includes dedup + near-duplicate version bump.
• Search supports filters by domain, user_id, session_id, type, entities, tags.
• Verifier/Profiler write incremental memory entries when risk/evidence policy is met.

Confidence calibration behavior (Week3-1):

• Router computes confidence_raw from multi-signal fusion, then calibrates to confidence_calibrated.
• FEATURE_CALIBRATION=true enables calibration (default on).
• CALIBRATION_MODE=sigmoid uses 1/(1+exp(-k*(raw-b))) with defaults k=5, b=0.5.
• CALIBRATION_MODE=temperature uses sigmoid(raw / T) with CALIBRATION_TEMPERATURE (default 1.5).
• Risk-level routing uses calibrated confidence; if calibration is disabled/failed, raw confidence is used.

Audit trail behavior (Week3-5):

• Each analysis generates event_id and writes an audit event to data/audit/audit.jsonl.
• Audit stores only redacted preview and hash (redacted_text_preview, text_hash), never raw user text/webhook body.
• key_signals_summary gives compact traceability for external reporting (for example url_suspect=1, sb_hit=0, fc_hit=0).
• FEATURE_AUDIT_LOG=true controls logging; disable it to skip audit writes safely.

Safe degradation behavior:

• If FEATURE_MEMORY=false, memory module is fully skipped and app startup is unaffected.
• If memory optional dependencies are missing, memory matching degrades to fallback algorithm without crashing.
• If Safe Browsing key is missing, URL scan is skipped and app still returns classifier result.
• If FEATURE_FACT_CHECK=false, fact-check is fully skipped (no lookup, no evidence, no dependency impact).
• If FEATURE_AUDIT_LOG=false, audit writes are skipped and analysis still works.
• URL heuristic / image signal / NER / wiki / company stub / domain intel failures are isolated per agent.
• Missing optional dependencies (for example external API timeout) do not crash router or webhook.
• LINE webhook always returns 200 and masks phone/account/LINE ID in logs.

LINE reply format (text/image):

• Risk level + category + confidence (0-100; higher means more likely this scam type)
• Maximum length <= 900 characters (MAX_REPLY_TEXT_CHARS, hard-capped at 900)
• Evidence 2-4 points
• Recommended actions 3 points

Week2 demo script:

python scripts/demo_week2.py

Memory rebuild (dev):

python scripts/rebuild_memory_db.py --clear
python scripts/rebuild_memory_db.py --seed-demo

Audit query examples:

python scripts/audit_query.py --limit 20
python scripts/audit_query.py --event-id <event_id>
python scripts/audit_query.py --date-from 2026-02-20T00:00:00+00:00 --date-to 2026-02-20T23:59:59+00:00

LINE channel setup (product):

1. Get long-lived Channel access token:

• LINE Developers Console -> Messaging API -> Channel access token -> issue long-lived token

2. Set webhook URL via ngrok:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
ngrok http 8000

• Set webhook URL to:
• https://<your-ngrok-domain>/line/webhook
• Enable Use webhook
• Disable Auto-reply messages in LINE Official Account Manager (avoid duplicate replies)

Local signature test (PowerShell):

cd lifeshield-ai
$body = '{"events":[{"type":"message","replyToken":"REPLY_TOKEN","message":{"type":"text","text":"老師帶單保證獲利，現在加入VIP群"}}]}'
$secret = "YOUR_LINE_CHANNEL_SECRET"
$sig = [Convert]::ToBase64String(
  [System.Security.Cryptography.HMACSHA256]::new([Text.Encoding]::UTF8.GetBytes($secret)).
    ComputeHash([Text.Encoding]::UTF8.GetBytes($body))
)

curl.exe -X POST "http://127.0.0.1:8000/line/webhook" `
  -H "Content-Type: application/json" `
  -H "X-Line-Signature: $sig" `
  -d $body

OCR Setup (Windows)

Windows 使用者需安裝 Tesseract 並設定路徑。

方案 1：改良 Tesseract pipeline（預設）

1. Install Tesseract OCR:

• Installer: https://github.com/UB-Mannheim/tesseract/wiki
• Ensure Traditional Chinese language data (chi_tra.traineddata) is installed under tessdata

2. Make sure tesseract.exe is available:

• Add install path to PATH, or set .env:

TESSERACT_PATH=C:/Program Files/Tesseract-OCR/tesseract.exe

3. Reinstall/update Python deps:

pip install -r requirements.txt

4. OCR env:

TESSERACT_PATH=C:/Program Files/Tesseract-OCR/tesseract.exe
TESSERACT_CMD=C:\\Program Files\\Tesseract-OCR\\tesseract.exe
TESSDATA_PREFIX=C:\\Program Files\\Tesseract-OCR\\tessdata
OCR_ENGINE=tesseract
OCR_LANG=chi_tra+eng
MAX_REPLY_TEXT_CHARS=900

方案 2：PaddleOCR（較高準確率，較重）

1. 安裝 PaddleOCR：

pip install -r requirements.ocr-paddle.txt

2. 啟用 .env：

OCR_ENGINE=paddle

3. 首次啟用 PaddleOCR 會下載模型，請確保網路可用並預留較長啟動時間。
4. 若 OCR_ENGINE 未設定或值不合法，系統會回到 tesseract。

OCR debug command

python scripts/ocr_debug.py path\\to\\chat_screenshot.png --engine tesseract
python scripts/ocr_debug.py path\\to\\chat_screenshot.png --engine paddle

Outputs:

• <name>_<engine>_text.txt
• <name>_<engine>_debug.json

Test flow:

• Text test: send a suspicious text message to your LINE bot.
• Screenshot test: send original chat screenshot (avoid screenshot-of-screenshot to keep OCR quality).
• Webhook verify: in LINE Developers Console click Verify after setting ngrok URL.

2) Chrome extension: POST /browser/analyze

curl.exe -X POST "http://127.0.0.1:8000/browser/analyze" `
  -H "Content-Type: application/json" `
  -d "{\"url\":\"https://example.com/promo\",\"page_text\":\"立即加入投資群，保證翻倍，私訊領取名額\"}"

3) Web form: POST /web/analyze

curl.exe -X POST "http://127.0.0.1:8000/web/analyze" `
  -H "Content-Type: application/json" `
  --data "@examples/job_high_salary.json"

Two /analyze cURL examples

Investment scam:

curl.exe -X POST "http://127.0.0.1:8000/analyze" `
  -H "Content-Type: application/json" `
  --data "@examples/investment_group.json"

Job scam:

curl.exe -X POST "http://127.0.0.1:8000/analyze" `
  -H "Content-Type: application/json" `
  --data "@examples/job_high_salary.json"

Public Data Collection Pipeline

Only public content is collected. Scripts are designed to avoid storing user IDs and to de-identify sensitive info.

python scripts/collect_public_cases.py --source cofacts --limit 50
python scripts/sanitize_cases.py
python scripts/auto_label_cases.py
python scripts/build_real_testset.py --per_class 20

Notes:

• collect_public_cases.py supports --source cofacts|gov_anti_fraud_pages|ptt_public_posts
• sanitize_cases.py masks phone/account/ID/email and converts full URLs to domain form
• auto_label_cases.py adds predicted_label, confidence, needs_review (confidence < 0.6)
• build_real_testset.py reports missing counts if class coverage is insufficient

Training Pipeline

Training data files:

• data/train.jsonl
• data/dev.jsonl
• data/test.jsonl

JSONL format per line:

{"text":"...", "label":"fake_news|scam|phishing|job|investment|social"}

Generate larger balanced dataset (auto backup old files to .bak):

python scripts/generate_dataset.py --per_class 120

Supported args:

• --per_class N
• --seed 42
• --train_ratio 0.8 --dev_ratio 0.1 --test_ratio 0.1

Install training dependencies:

pip install -r requirements-train.txt

Run fine-tuning:

python training/train_classifier.py

Optional env overrides:

• BASE_MODEL (default: bert-base-chinese)
• OUT_DIR (default: artifacts/risk_classifier)
• TRAIN_FILE, DEV_FILE, TEST_FILE

Training output:

• model + tokenizer in artifacts/risk_classifier
• console metrics: Accuracy, Macro-F1, classification_report

Evaluation Report

Run evaluation:

python training/eval_report.py

Generated files in artifacts/risk_classifier:

• metrics.json
• confusion_matrix.png
• latency_ms.txt
• baseline_metrics.json
• baseline_confusion_matrix.png
• baseline_latency_ms.txt

Baseline uses legacy rule-based classifier on the same data/test.jsonl.

How /analyze uses the model

• app/core/risk_classifier_hf.py loads model from artifacts/risk_classifier
• /analyze always runs HF prediction first to produce risk_label and confidence
• app/services/agent_router.py combines classifier + Agent1 + Agent2 signals by feature flags
• Final schema is unified as: risk_label, confidence, risk_level, evidence, actions, signals
• If model files are missing, classifier falls back to legacy rule-based logic