Metadata-Version: 2.4
Name: expense-agent
Version: 0.1.1
Summary: Local reimbursement invoice and payment proof matching agent
License: MIT
Keywords: expense,feishu,invoice,ocr,reimbursement
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: paddleocr>=3.5.0
Requires-Dist: paddlepaddle>=3.3.1
Requires-Dist: pypdf>=4.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Expense Agent

本地运行的报销凭证匹配与自动命名 Agent。当前版本使用规则引擎，不依赖大模型。

支持 macOS、Linux 和 Windows。Python 要求 3.10+。

## 安装

```bash
pip install expense-agent
# 或
uv add expense-agent
```

首次运行时 PaddleOCR 会自动下载模型文件（约 100 MB），请保持网络畅通。

## 本地批处理

```bash
expense-agent --input ./input --output ./output
```

## 输入

支持 `pdf`、`jpg`、`jpeg`、`png`。

- PDF：使用 `pypdf` 提取文本。
- 图片：默认使用 `PaddleOCREngine` 调用 PaddleOCR。若 PaddleOCR 未安装或初始化失败，会在结果中输出明确错误信息。
- 开发和测试时可使用同名 `.txt` 旁路作为 mock OCR 文本。例如 `payment.png` 对应 `payment.txt`。

## 输出

输出目录包含：

- `renamed/`：按建议文件名生成的副本，不覆盖原始文件。
- `result.json`：结构化识别和匹配结果。
- `summary.txt`：人工可读摘要和异常说明。

异常、风险和审核提示只写入 `result.json` 与 `summary.txt`，不会塞进文件名。

## 飞书多维表格 Job

手动处理一批"待处理"记录：

```bash
expense-agent-feishu --once
```

定时串行处理：

```bash
expense-agent-feishu --schedule
```

### 配置

在运行目录下创建 `.env` 文件，只需填写 4 个飞书凭证：

```bash
FEISHU_APP_ID=
FEISHU_APP_SECRET=
FEISHU_APP_TOKEN=
FEISHU_TABLE_ID=
```

Job 启动时自动读取当前目录下的 `.env`，无需手动 `source`。

字段映射（表头名称）已内置默认值，如需覆盖，在 `.env` 中追加对应的环境变量即可：

```bash
# 以下均有默认值，仅在表头与默认不同时才需要覆盖
FIELD_STATUS=处理状态
FIELD_INVOICE=发票原件
FIELD_PAYMENT=支付凭证
FIELD_CONSUMPTION_DETAIL=消费清单
FIELD_OUTPUT_INVOICE=重命名后的发票附件
FIELD_OUTPUT_PAYMENT=重命名后的支付凭证
FIELD_OUTPUT_CONSUMPTION_DETAIL=重命名后的消费清单
FIELD_INVOICE_AMOUNT=发票识别金额
FIELD_PAYMENT_AMOUNT=支付凭证识别金额
FIELD_INVOICE_DATE=开票日期
FIELD_SELLER=销售方
FIELD_BUYER=购买方
FIELD_PAYMENT_TIME=支付时间
FIELD_EXPENSE_TYPE=费用类型
FIELD_MATCH_RESULT=匹配结果
FIELD_RISK=风险等级
FIELD_SUMMARY=处理说明
FIELD_PROCESSED_AT=处理时间
FIELD_ERROR_MESSAGE=错误信息
```

可选的运行参数：

```bash
WORKSPACE_DIR=/tmp/expense-agent-workspace  # 默认走系统临时目录
JOB_BATCH_SIZE=20                           # 1..500，默认 20
JOB_INTERVAL_MINUTES=60                     # --schedule 模式的轮询间隔
```

### 工作目录

`WORKSPACE_DIR` 未设置时默认为系统临时目录下的 `expense-agent-workspace`（macOS/Linux：`/tmp/...`，Windows：`%TEMP%\...`）。按 record 隔离：

- `downloads/{record_id}/`：原始附件
- `outputs/{record_id}/summary.txt` 与 `result.json`：处理结果

### 返回码

`--once` 返回码：

- `0`：本批次全部记录处理成功，或没有待处理记录。
- `1`：至少一条记录处理失败，或本机已有 Job 在运行。
- `2`：缺少必填环境变量等配置错误。

## 开发

依赖通过 `uv` 管理：

```bash
uv run --extra test pytest -q           # 运行全部测试
uv run python -m expense_agent.app.main --input ./input --output ./output
uv run python -m expense_agent.app.feishu_job --once
```
