Pyhroff/lucid-housing-ai
GitHub: Pyhroff/lucid-housing-ai
Lucid 是一个多语言神经符号化住房支持助手，通过 LLM 提取事实与确定性规则引擎分离的架构，帮助用户安全、可引用地查询住房援助资格。
Stars: 0 | Forks: 0
# 🧭 Lucid
**一个多语言、神经符号化的助手，帮助处于压力下的人们安全地获取住房支持——它基于引用的官方规则进行推理，识别诈骗，抵御操纵，在不确定时选择弃权，并报告自身评估的准确度。**
   
## 为什么与众不同
大多数“利用 AI 进行资格判定”的工具仅仅是询问 LLM——但这会在规则上产生**幻觉**，且无法令人信任。Lucid 的核心理念是：
这种神经符号化的分离是制胜的关键：LLM 负责处理自然语言；符号引擎负责做出判定。其结果是**可解释、可审计、即时且不可能产生幻觉的。**
## 架构
```
flowchart LR
U["User's story
(any language) + a link to check"] --> I["Agent 1 · Intake
LLM → structured facts
(schema-validated)"] I --> C{"Confirm the
facts with user"} C --> R["Rules Engine
DETERMINISTIC
cannot hallucinate"] KB[("Knowledge Base
9 official programs
+ source URLs")] --> R R --> F["Faithfulness Guard
blocks fabricated
links / numbers / claims"] F --> CF["Derived confidence
+ counterfactuals"] CF --> G["Agent 3 · Guardian
scam · injection · bias
· escalate to human"] G --> T["Translate to
the user's language"] T --> O["Cited, plain-language
answer + next steps"] ``` ## 突出特性 - 🧠 **神经符号化核心** — LLM 负责自然语言，确定性引擎负责判定（*无法对资格产生幻觉*）。 - 📎 **引用真实来源** — 9 个美国官方项目（HUD, CFPB, 211, LIHEAP, LSC…），均经过网络验证。 - 🔬 **实时资格探索器** — 拖动收入/家庭成员人数，观看规则引擎*实时*重新计算资格；当您跨越官方阈值时，项目会变为绿色。这是任何 LLM 都无法稳定做到的。 - 🌟 **反事实解释** — “如果您的收入为*极低*或更低，Section 8 将向您开放。”极其精确，因为引擎是确定性的。 - 🛡️ **防诈骗与 prompt injection 防御** — 将*所有*用户输入视为不受信任；实时的红队测试面板证明了这一点。*即使注入成功，也无法更改资格判定。* - 🧮 **忠实度防护** — 拒绝任何包含伪造链接、无根据数字或“保证”承诺的回答。 - 🌐 **多语言 + 🔊 语音** — 使用用户的语言进行回答并大声朗读（提升无障碍体验）。 - 📊 **自我评估** — 双层测试框架报告其自身的准确度*及其表现不佳之处*（`eval/EVAL_RESULTS.md`）。 - 🌐 **多语言 + 🔊 语音** — 使用用户的语言进行回答并大声朗读（提升无障碍体验）。 - ⚖️ **校准弃权** — 知道自己在何时不知道；低置信度时会升级转交给人工（在评估中达到 100%）。 - 🙋 **人工介入** — 在做出决定*之前*与您确认提取的事实，并且绝不代您做出最终决定。 ## 底层机制 **Pipeline：** `故事（任何语言）→ 信息收集（LLM → 事实）→ 用户确认 → 规则引擎（确定性）→ 检索（引用来源）→ 忠实度防护 → 置信度 + 反事实 → 守卫（诈骗 · 注入 · 偏见 · 升级）→ 翻译 → 引用来源的回答。` | 模块 | 职责 | |---|---| | `agents/intake.py` | LLM 将故事转化为结构化事实（+ 离线关键词回退） | | `core/rules_engine.py` | **确定性**资格判定 — 无需 LLM，无法产生幻觉 | | `core/retrieval.py` | 匹配官方项目及其来源 URL | | `agents/eligibility.py` | 通俗语言渲染 + **忠实度防护** + 推导置信度 | | `core/confidence.py` | 基于具体信号的置信度（完整度、匹配清晰度、检索） | | `core/counterfactual.py` | “什么会改变您的结果”——跨收入区间重新运行引擎 | | `agents/guardian.py` | 诈骗检测 · prompt injection 防御 · 偏见检查 · 升级 | | `core/translate.py` | 翻译最终答案（推理过程使用英语，最后进行翻译） | | `eval/run_eval.py` | 双层评估框架（确定性回归测试 + 实时测试，按角色划分） | | `app.py` | Streamlit UI — 温馨主题、交互流程、资格探索器、红队测试、语音 | **负责任 AI 准则登记（以下 7 项均实际运行）：** 资格幻觉 → 确定性引擎 · 错误信息 → 接地 + 忠实度防护 + 引用来源 · 过度依赖 → “可能符合资格”的表述 + 推导置信度 + 升级处理 · 偏见/排斥 → 多语言 + 偏见检查 + 公平性审计 · 隐私 → 无需登录，无 PII，不存储任何内容 · 诈骗 → Guardian 诈骗检测 · prompt injection → 将所有用户输入视为不受信任。 **技术栈（全部免费）：** Python 3.12 · Streamlit · Groq Llama-3.3-70B / Google Gemini（可通过 `.env` 切换） · Pydantic · textstat · 使用 **Claude Code**（AI 编程助手，已公开说明）构建。 ## 评估要点 `python eval/run_eval.py --live` — 完整表格见 [`eval/EVAL_RESULTS.md`](eval/EVAL_RESULTS.md)： | | | |---|---| | 规则引擎判定（给定正确事实时） | **100%** | | 实时 LLM 事实提取 | **91%** | | 忠实度 — 触达用户的幻觉 | **0**（防护机制捕获了 1 次实时漂移） | | 对抗鲁棒性（捕获植入攻击） | **71%** | | 诈骗召回率 · 注入召回率 | 75% · 67% *(客观的局限性，已明确指出)* | | 公平性审计 | 标记**服务不足的用户（50% 提取率）**— 需要改进之处 | *合成、自创场景；回归测试线用于测试我们的规则编码，实时测试线则是可能出错的地方。* ## 快速开始 ``` cd lucid python -m venv .venv && .venv\Scripts\activate # Windows pip install -r requirements.txt copy .env.example .env # add ONE provider's key (Groq or Gemini) streamlit run app.py ``` 在未设置 key 的情况下，可**离线**运行（关键词回退）并提供英语支持；当设置了 key 时，LLM 信息收集、多语言回答和语音功能将被激活。尝试侧边栏的示例——包括 🌎 西班牙语和 🚨 诈骗链接。 ``` python dev_smoke_m1.py ... dev_smoke_m6.py # offline regression tests (deterministic, free) python eval/run_eval.py --live # the evaluation harness ``` ## Lucid 不做的事情 它从不做出**最终**的资格决定，从不自动申请，从不证明某个网站是安全的，并且**不提供法律建议**。它只会说*“您**可能**符合资格，”*并在不确定时向人工弃权，对于英语类美国项目最为可靠（当可能无法充分服务您时，它会主动标记）。它不收集任何 PII，也不存储任何内容。 ## 仓库结构 ``` lucid/ ├── app.py # Streamlit UI (warm theme, journey, Explorer, red-team, voice) ├── pipeline.py # run_pipeline(): Intake → Engine → Guardian → translate ├── agents/ # intake (LLM), eligibility (faithfulness + confidence), guardian ├── core/ # llm, schemas, rules_engine, retrieval, confidence, │ # counterfactual, translate, config, ui_copy ├── data/ # knowledge_base.json (9 verified) + eval_scenarios.json (23) ├── eval/ # run_eval.py + EVAL_RESULTS.md └── dev_smoke_m*.py # offline regression tests ```
(any language) + a link to check"] --> I["Agent 1 · Intake
LLM → structured facts
(schema-validated)"] I --> C{"Confirm the
facts with user"} C --> R["Rules Engine
DETERMINISTIC
cannot hallucinate"] KB[("Knowledge Base
9 official programs
+ source URLs")] --> R R --> F["Faithfulness Guard
blocks fabricated
links / numbers / claims"] F --> CF["Derived confidence
+ counterfactuals"] CF --> G["Agent 3 · Guardian
scam · injection · bias
· escalate to human"] G --> T["Translate to
the user's language"] T --> O["Cited, plain-language
answer + next steps"] ``` ## 突出特性 - 🧠 **神经符号化核心** — LLM 负责自然语言，确定性引擎负责判定（*无法对资格产生幻觉*）。 - 📎 **引用真实来源** — 9 个美国官方项目（HUD, CFPB, 211, LIHEAP, LSC…），均经过网络验证。 - 🔬 **实时资格探索器** — 拖动收入/家庭成员人数，观看规则引擎*实时*重新计算资格；当您跨越官方阈值时，项目会变为绿色。这是任何 LLM 都无法稳定做到的。 - 🌟 **反事实解释** — “如果您的收入为*极低*或更低，Section 8 将向您开放。”极其精确，因为引擎是确定性的。 - 🛡️ **防诈骗与 prompt injection 防御** — 将*所有*用户输入视为不受信任；实时的红队测试面板证明了这一点。*即使注入成功，也无法更改资格判定。* - 🧮 **忠实度防护** — 拒绝任何包含伪造链接、无根据数字或“保证”承诺的回答。 - 🌐 **多语言 + 🔊 语音** — 使用用户的语言进行回答并大声朗读（提升无障碍体验）。 - 📊 **自我评估** — 双层测试框架报告其自身的准确度*及其表现不佳之处*（`eval/EVAL_RESULTS.md`）。 - 🌐 **多语言 + 🔊 语音** — 使用用户的语言进行回答并大声朗读（提升无障碍体验）。 - ⚖️ **校准弃权** — 知道自己在何时不知道；低置信度时会升级转交给人工（在评估中达到 100%）。 - 🙋 **人工介入** — 在做出决定*之前*与您确认提取的事实，并且绝不代您做出最终决定。 ## 底层机制 **Pipeline：** `故事（任何语言）→ 信息收集（LLM → 事实）→ 用户确认 → 规则引擎（确定性）→ 检索（引用来源）→ 忠实度防护 → 置信度 + 反事实 → 守卫（诈骗 · 注入 · 偏见 · 升级）→ 翻译 → 引用来源的回答。` | 模块 | 职责 | |---|---| | `agents/intake.py` | LLM 将故事转化为结构化事实（+ 离线关键词回退） | | `core/rules_engine.py` | **确定性**资格判定 — 无需 LLM，无法产生幻觉 | | `core/retrieval.py` | 匹配官方项目及其来源 URL | | `agents/eligibility.py` | 通俗语言渲染 + **忠实度防护** + 推导置信度 | | `core/confidence.py` | 基于具体信号的置信度（完整度、匹配清晰度、检索） | | `core/counterfactual.py` | “什么会改变您的结果”——跨收入区间重新运行引擎 | | `agents/guardian.py` | 诈骗检测 · prompt injection 防御 · 偏见检查 · 升级 | | `core/translate.py` | 翻译最终答案（推理过程使用英语，最后进行翻译） | | `eval/run_eval.py` | 双层评估框架（确定性回归测试 + 实时测试，按角色划分） | | `app.py` | Streamlit UI — 温馨主题、交互流程、资格探索器、红队测试、语音 | **负责任 AI 准则登记（以下 7 项均实际运行）：** 资格幻觉 → 确定性引擎 · 错误信息 → 接地 + 忠实度防护 + 引用来源 · 过度依赖 → “可能符合资格”的表述 + 推导置信度 + 升级处理 · 偏见/排斥 → 多语言 + 偏见检查 + 公平性审计 · 隐私 → 无需登录，无 PII，不存储任何内容 · 诈骗 → Guardian 诈骗检测 · prompt injection → 将所有用户输入视为不受信任。 **技术栈（全部免费）：** Python 3.12 · Streamlit · Groq Llama-3.3-70B / Google Gemini（可通过 `.env` 切换） · Pydantic · textstat · 使用 **Claude Code**（AI 编程助手，已公开说明）构建。 ## 评估要点 `python eval/run_eval.py --live` — 完整表格见 [`eval/EVAL_RESULTS.md`](eval/EVAL_RESULTS.md)： | | | |---|---| | 规则引擎判定（给定正确事实时） | **100%** | | 实时 LLM 事实提取 | **91%** | | 忠实度 — 触达用户的幻觉 | **0**（防护机制捕获了 1 次实时漂移） | | 对抗鲁棒性（捕获植入攻击） | **71%** | | 诈骗召回率 · 注入召回率 | 75% · 67% *(客观的局限性，已明确指出)* | | 公平性审计 | 标记**服务不足的用户（50% 提取率）**— 需要改进之处 | *合成、自创场景；回归测试线用于测试我们的规则编码，实时测试线则是可能出错的地方。* ## 快速开始 ``` cd lucid python -m venv .venv && .venv\Scripts\activate # Windows pip install -r requirements.txt copy .env.example .env # add ONE provider's key (Groq or Gemini) streamlit run app.py ``` 在未设置 key 的情况下，可**离线**运行（关键词回退）并提供英语支持；当设置了 key 时，LLM 信息收集、多语言回答和语音功能将被激活。尝试侧边栏的示例——包括 🌎 西班牙语和 🚨 诈骗链接。 ``` python dev_smoke_m1.py ... dev_smoke_m6.py # offline regression tests (deterministic, free) python eval/run_eval.py --live # the evaluation harness ``` ## Lucid 不做的事情 它从不做出**最终**的资格决定，从不自动申请，从不证明某个网站是安全的，并且**不提供法律建议**。它只会说*“您**可能**符合资格，”*并在不确定时向人工弃权，对于英语类美国项目最为可靠（当可能无法充分服务您时，它会主动标记）。它不收集任何 PII，也不存储任何内容。 ## 仓库结构 ``` lucid/ ├── app.py # Streamlit UI (warm theme, journey, Explorer, red-team, voice) ├── pipeline.py # run_pipeline(): Intake → Engine → Guardian → translate ├── agents/ # intake (LLM), eligibility (faithfulness + confidence), guardian ├── core/ # llm, schemas, rules_engine, retrieval, confidence, │ # counterfactual, translate, config, ui_copy ├── data/ # knowledge_base.json (9 verified) + eval_scenarios.json (23) ├── eval/ # run_eval.py + EVAL_RESULTS.md └── dev_smoke_m*.py # offline regression tests ```
标签：AI助手, Kubernetes, Streamlit, 云计算, 住房保障, 神经符号AI, 规则引擎, 访问控制, 逆向工具, 防诈骗