roshnithakor07/multimodal-damage-claim-verification

# 多模态证据审查系统 一个基于终端的 AI agent，用于使用图像、对话历史、用户风险画像和证据要求来验证**汽车**、**笔记本电脑**和**包裹**的损坏索赔。 为 **HackerRank Orchestrate 24 小时黑客松**构建。 ## 功能说明 对于 `dataset/claims.csv` 中的每一条索赔，该 agent 会： 1. 读取用户对话，提取所申报的损坏情况 2. 加载并编码所有提交的图像 (base64 → Claude vision API) 3. 检查用户的索赔历史以获取风险信号 4. 查找该对象类型的最低证据要求 5. 通过一次多模态 API 调用将所有内容发送给 Claude 6. 解析并验证结构化的 JSON 响应 7. 写入包含所有必填字段的一行输出 ## 仓库结构 ``` . ├── README.md ├── AGENTS.md # AI tool transcript logging instructions ├── problem_statement.md # Full problem description ├── code/ │ ├── main.py # ← Main entry point (run this) │ └── evaluation/ │ ├── main.py # Evaluation script (sample_claims.csv) │ ├── evaluation_report.md # Operational analysis │ └── metrics.json # Generated after running evaluation ├── dataset/ │ ├── claims.csv # Test inputs (run main.py on this) │ ├── sample_claims.csv # Labeled examples (for evaluation) │ ├── user_history.csv # User risk history │ ├── evidence_requirements.csv # Minimum image evidence rules │ └── images/ │ ├── sample/ # Images for sample_claims.csv │ │ └── case_001/img_1.jpg # (and so on) │ └── test/ # Images for claims.csv │ └── case_001/img_1.jpg # (and so on) └── output.csv # Generated predictions for claims.csv ``` ## 环境要求 - Python 3.10+ - 拥有可访问 `claude-haiku-4-5-20251001` 的 Anthropic API key ### 安装依赖 ``` pip install anthropic pandas ``` ## 设置 ### 1. 克隆 / 解压此解决方案 ``` unzip code.zip -d claim-verifier cd claim-verifier ``` ### 2. 添加您的图像 将 HackerRank 仓库中的 `dataset/images/` 文件夹复制到 `dataset/` 中： ``` dataset/images/sample/case_001/img_1.jpg dataset/images/test/case_001/img_1.jpg ... ``` ### 3. 设置您的 API key **macOS / Linux:** ``` export ANTHROPIC_API_KEY=sk-ant-... ``` **Windows (PowerShell):** ``` $env:ANTHROPIC_API_KEY = "sk-ant-..." ``` ## 运行 ### 处理测试索赔 → output.csv ``` python code/main.py ``` 或使用显式路径： ``` python code/main.py \ --input dataset/claims.csv \ --output output.csv \ --dataset-root . ``` 您将看到实时进度日志： ``` 12:01:03 [INFO] Loaded 44 claims from dataset/claims.csv 12:01:03 [INFO] ── Row 1/44 ────────────────────────── 12:01:03 [INFO] Processing user_002 | object=car | images=images/test/case_001/... 12:01:08 [INFO] ── Row 2/44 ────────────────────────── ... 12:07:41 [INFO] ✅ Saved 44 results to output.csv ``` ### 对样本数据运行评估 ``` python code/evaluation/main.py --dataset-root . ``` 这将生成： - `evaluation/sample_predictions.csv` — 针对 20 行样本数据的预测 - `evaluation/metrics.json` — 字段级别准确率与真值的对比 ## 输出格式 `output.csv` 包含以下列（按顺序排列）： | 列名 | 描述 | |--------|-------------| | `user_id` | 输入中的用户 ID | | `image_paths` | 原始图像路径 | | `user_claim` | 原始对话 | | `claim_object` | car / laptop / package | | `evidence_standard_met` | true/false — 图像是否足以进行评估？ | | `evidence_standard_met_reason` | 简要说明 | | `risk_flags` | 分号分隔的标签 (或 `none`) | | `issue_type` | dent, scratch, crack 等 | | `object_part` | 例如 rear_bumper, screen, box | | `claim_status` | supported / contradicted / not_enough_information | | `claim_status_justification` | 基于图像的解释 | | `supporting_image_ids` | 例如 img_1;img_2 或 none | | `valid_image` | true/false — 是否可用于自动审查？ | | `severity` | none / low / medium / high / unknown | ## 设计决策 ### 每次索赔进行单次多模态调用 索赔的所有图像会与完整的 prompt 一起在单次 API 调用中发送。这使得 Claude 能够同时对多张图像进行推理（例如，“img_1 显示了保险杠，而 img_2 显示了底部——两者都支持该索赔”）。 ### 带验证的结构化 JSON 输出 通过 prompt 指示模型仅返回 JSON。`validate_and_fix()` 函数会在写入 CSV 之前，根据所有允许的值集合对输出进行净化处理，从而确保不会将无效值写入输出文件。 ### 用户历史仅作为风险上下文 用户历史标签（例如 `user_history_risk`）会作为上下文注入，但不能覆盖清晰的视觉证据。如果历史 CSV 显示存在高风险，验证步骤会自动将 `user_history_risk` 添加到 `risk_flags` 中。 ### 优雅降级 如果图像缺失，该 agent 会返回 `not_enough_information` 并附带明确的原因，而不是直接崩溃。如果 API 在重试 3 次后仍然失败，则会写入安全的兜底结果。 ### 速率限制处理 - 调用之间休眠 1 秒（可通过 `RATE_LIMIT_SLEEP` 调整） - 遇到 `RateLimitError` 时进行指数退避（重试 3 次，每次 5秒 × 尝试次数） - 如果您拥有 Tier 3+ API 访问权限，可降低 `RATE_LIMIT_SLEEP` 的值 ## 故障排除 **“Image not found” 警告**：确保 `dataset/images/` 已正确放置在您运行脚本时所在的相对路径 `./dataset/images/` 下。 **速率限制错误**：将 `code/main.py` 中的 `RATE_LIMIT_SLEEP`（文件顶部的常量）从 `1.0` 增加到 `2.0` 或 `3.0`。 **JSON 解析错误**：很少见，但可能会在复杂的响应中发生。该 agent 会自动重试，最多 3 次。 **无 API key**：在运行前设置 `ANTHROPIC_API_KEY` 环境变量。 ## 成本与运行时间（预估） | 数据集 | 行数 | 预计运行时间 | 预计成本 | |---------|------|-------------|-----------| | Sample | 20 | ~3 分钟 | ~$3 | | Test | 44 | ~6 分钟 | ~$5 | 有关完整的运行分析，请参阅 `code/evaluation/evaluation_report.md`。

标签：Python, 云计算, 人工智能, 多模态模型, 无后门, 理赔验证, 用户模式Hook绕过, 自动化审核, 规则引擎, 逆向工具