formbridge (Nilsyai)

模板桥

面向LLM和人类的指令感知PDF表单填写。

](https://pypi.org/project/formbridge/)   

FormBridge是一个开源的CLI工具，通过结合OCR、官方指令摄取和AI驱动的字段映射，可以准确地填写任何PDF表单。它是唯一一个读取实际表单指令以确定每个字段中内容的工具。

为什么选择FormBridge？

问题： 以编程方式填充PDF表单容易出错。你需要确切地知道哪个字段获取了哪些数据，IRS 5472等表格上的一个错误可能意味着25000美元的罚款。

现有解决方案：

• TurboTax、H&R区块：专有、昂贵、仅含税
• Adobe Acrobat：手动输入，无情报
• pdf库，pikepdf：你弄清楚什么会去哪里
• ChatGPT/Claude：看不见表格，产生幻觉

FormBridge的方法： 阅读实际的表格说明，使用LLM了解每个字段中的数据，并给你信心分数，这样你就知道要验证什么。

主要特点

• 注意填写说明 -阅读官方说明以确定字段映射
• 信心评分 -每个映射都有一个0-1的推理置信度得分
• 形式不可知论 -适用于IRS表格、移民表格、保险索赔、任何PDF
• 模板系统 -扫描一次，填写多次
• MCP服务器 -适用于Claude Desktop、OpenClaw、任何MCP客户端
• 验证工作流程 -写作前的互动式复习
• PDF差异 -逐个字段比较两个已填写的表单，看看发生了什么变化

快速安装

pip install formbridge

# With OCR support for non-fillable PDFs
pip install formbridge[ocr]

# With MCP server support
pip install formbridge[mcp]

# Everything
pip install formbridge[all]

快速开始

1.用模板填写表格

# Install a template from the registry
formbridge template install irs-1065-2025

# Generate a data template
formbridge data-template irs-1065-2025 --output my-data.json

# Edit my-data.json with your information, then fill
formbridge fill irs-1065-2025 --data my-data.json --output filled-1065.pdf --verify

2.填写没有模板的表格

# One-shot fill with instructions
formbridge fill form.pdf \
  --data my-data.json \
  --instructions instructions.pdf \
  --output filled.pdf \
  --verify

3.扫描并理解表格

# Extract field structure
formbridge scan form.pdf --output fields.json

# Parse instructions
formbridge parse instructions.pdf --fields fields.json --output instructions.json

CLI 参考

formbridge scan

扫描PDF表单并提取字段结构。

formbridge scan  [--output fields.json]

输出a FormSchema 所有检测到的字段、类型、位置和标签。

formbridge parse

解析指令文档并映射到字段。

formbridge parse  --fields fields.json [--output instructions.json]

需要扫描的表单架构。从指导文件中提取每个现场的指导。

formbridge fill

用数据填写PDF表格。

formbridge fill  --data data.json --output filled.pdf [--verify] [--dry-run]

选项：

• --verify -写入前的交互式验证
• --dry-run -无需编写PDF即可显示映射
• `--instructions

` -附加说明文件

formbridge verify

核实已填写的表格。

formbridge verify  --template 

显示已填充内容的逐字段细分。

formbridge diff

逐字段比较两个已填写的PDF。

formbridge diff 
             # Show changes
formbridge diff old.pdf new.pdf --all          # Include unchanged fields
formbridge diff old.pdf new.pdf --json         # JSON output
formbridge diff old.pdf new.pdf -r report.json # Save diff report

使用颜色编码输出显示添加、删除和更改的字段。 可用于查看税务表格、移民申请或任何PDF工作流程的迭代编辑。

formbridge template

管理模板。

formbridge template list                    # List installed templates
formbridge template create  [inst]    # Create new template
formbridge template install           # Install from registry
formbridge template get               # Show template details
formbridge template delete            # Delete template

formbridge serve

启动MCP服务器。

formbridge serve --stdio     # For Claude Desktop, OpenClaw
formbridge serve --port 3000 # HTTP/SSE mode

formbridge data-template

为表单生成空白数据模板。

formbridge data-template  --output data.json

MCP服务器设置

FormBridge作为MCP服务器发布，因此任何AI代理都可以将其用作工具。

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "formbridge": {
      "command": "formbridge",
      "args": ["serve", "--stdio"],
      "env": {
        "FORMBRIDGE_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

开爪

添加到您的 openclaw.json:

{
  "mcpServers": {
    "formbridge": {
      "command": "formbridge",
      "args": ["serve", "--stdio"],
      "env": {
        "FORMBRIDGE_PROVIDER": "openai",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

可用工具

模板系统

模板将扫描的表单+解析的指令捆绑到一个可重用的包中。

结构

~/.formbridge/templates/irs-1065-2025/
├── manifest.json          # Metadata
├── form.pdf               # Original blank form
├── schema.json            # Scanner output
├── instructions.json      # Parser output (optional)
└── instructions-source.pdf # Original instructions (optional)

创建模板

formbridge template create \
  f1065.pdf \
  i1065-instructions.pdf \
  --name irs-1065-2025 \
  --display-name "IRS Form 1065 (2025)" \
  --category tax/us/irs \
  --tag irs --tag partnership --tag 2025

模板注册表

社区模板可在以下网址获得 .

formbridge template install irs-1065-2025
formbridge template install uscis-i130-2025

LLM提供程序配置

FormBridge通过环境变量或 formbridge.toml.

环境变量

export FORMBRIDGE_PROVIDER=openai
export FORMBRIDGE_MODEL=gpt-4o-mini
export OPENAI_API_KEY=sk-...

# Or for Anthropic
export FORMBRIDGE_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Or for local models (Ollama)
export FORMBRIDGE_PROVIDER=local
export FORMBRIDGE_API_BASE=http://localhost:11434/v1
export FORMBRIDGE_MODEL=llama3.1:8b

配置文件

复制 formbridge.toml.example 到 formbridge.toml:

[llm]
provider = "openai"
model = "gpt-4o-mini"
api_key_env = "OPENAI_API_KEY"

[llm.local]
base_url = "http://localhost:11434/v1"
model = "llama3.1:8b"

建筑

┌─────────────────────────────────────────────────────┐
│                    FormBridge CLI                    │
├──────────┬──────────┬───────────┬───────────────────┤
│  Scanner │  Parser  │  Mapper   │  Writer           │
│  (OCR)   │  (Inst.) │  (LLM)    │  (PDF Fill)       │
├──────────┴──────────┴───────────┴───────────────────┤
│              Form Template System                    │
│         (.formbridge/ packages - reusable)           │
├─────────────────────────────────────────────────────┤
│              LLM Provider Abstraction                │
│     (OpenAI / Anthropic / Local / Any compatible)    │
├─────────────────────────────────────────────────────┤
│              MCP Server (optional)                   │
└─────────────────────────────────────────────────────┘

数据流

USER DATA (JSON)      BLANK FORM (PDF)      INSTRUCTIONS (PDF)
       │                     │                      │
       └──────────┬──────────┴──────────────────────┘
                  │
           ┌──────▼──────┐
           │   Scanner   │ → FormSchema
           └──────┬──────┘
                  │
           ┌──────▼──────┐
           │   Parser    │ → InstructionMap
           └──────┬──────┘
                  │
           ┌──────▼──────┐
           │   Mapper    │ → FieldMapping (with confidence)
           └──────┬──────┘
                  │
           ┌──────▼──────┐
           │   Writer    │ → Filled PDF
           └─────────────┘

验证工作流程

每次填写都会生成一份验证报告：

FormBridge Fill Verification
Form: IRS Form 1065 (2025)
Fields: 45 mapped, 44 blank, 1 flagged

Page 1:
  ✅ Line A: Name ...................... "Acme Partners LLC" (conf: 0.99)
  ✅ Line B: EIN ....................... "82-1234567" (conf: 0.99)
  ⚠️  Line D: Date started .............. "03/15/2023" (conf: 0.78)
     └─ NOTE: Verify this is formation date, not filing date

Overall confidence: 0.96

置信阈值：

• ≥ 0.95：自动填充，无需审核
• 0.80 - 0.94：填写但标记以供审核
• \< 0.80：留空，需要手动输入

Python API

from formbridge import Scanner, Mapper, PDFWriter, load_llm_config

# Scan a form
scanner = Scanner("form.pdf")
schema = scanner.scan()

# Load LLM config
llm_config = load_llm_config()

# Map data to fields
mapper = Mapper(
    user_data={"name": "Acme Corp", "ein": "12-3456789"},
    form_schema=schema,
    llm_config=llm_config,
)
mapping = mapper.map()

# Write filled PDF
writer = PDFWriter("form.pdf", schema)
writer.write(mapping, "filled.pdf")

需求

• Python 3.11+
• 对于OCR:Tesseract（通过系统包管理器安装）

# Ubuntu/Debian
sudo apt-get install tesseract-ocr poppler-utils

# macOS
brew install tesseract poppler

贡献

欢迎投稿！感兴趣的领域：

• 常见表单的新模板
• 针对不可填写PDF的OCR改进
• 额外的LLM提供商支持
• 视觉验证（渲染预览）
• 批量填充工作流

1. 分叉回购
2. 创建要素分支
3. 运行测试： pytest tests/ -v
4. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

内置：

• PDF 解析器 -PDF文本提取
• pikepdf -PDF操作
• 派丹蒂克 -数据验证
• 主控程序 -模型上下文协议

______________________________________________________________________

由以下材料制成❤️ 通过 Nilsy