Gwinnett Index

Gwinnett 索引

Gwinnett County（佐治亚州）及其 17 个市镇的分区、土地使用和开发记录机器可读索引。优先面向 AI Agent，其次面向人类。

为什么要建立这个项目

邮寄地址为 “Duluth, GA” 的地点通常不在 Duluth 市内，而是在 Gwinnett 的非建制地区——适用不同的法规，由不同的委员会管理，也使用不同的许可门户。互联网上没有任何工具会在回答分区问题前，先将地址解析为其实际管辖的辖区，因此如今每个回答“佐治亚州 Duluth 的退界距离是多少？”的 AI 助手都只能猜测。

Gwinnett 的非建制地区占全县土地面积的 67.3%。弄错辖区是常态，而非边缘情况。

内容一览

数据集	记录数	来源
辖区边界	19（县 + 非建制地区 + 17 个市）	US Census TIGER — 公共领域
县级分区案例	11,739（1970–2026）	Gwinnett GC_Planning ArcGIS
已解析的申请人	7,369（来自 8,246 种原始拼写）	派生数据
Duluth UDC	860 个章节，18 个表格	市政府 PDF，共 426 页
Duluth 会议文件	356（共 7,878 页，2023–2026）	duluthga.net
Duluth 土地使用案例	109 个不同案例，其中 64 个有投票记录	议程挖掘

设置 — 仅需一次

仓库已有初始 README，因此请先克隆再复制文件，以避免推送冲突：

git clone https://github.com/willmobhill-arch/gwinnett-index.git
tar -xzf gwinnett-index-repo.tar.gz -C gwinnett-index      # overwrites the stub README
cd gwinnett-index
git add -A && git commit -m "Gwinnett Index: pipeline, schema, and extracted corpora"
git push

然后，在仓库设为公开后加载数据集。Postgres 会自行获取数据——无需在本地运行任何程序，也不涉及凭据：

-- set to your repo's raw base
-- https://raw.githubusercontent.com/willmobhill-arch/gwinnett-index/main/data/

SELECT load_udc_sections_from_url(
  'https://raw.githubusercontent.com/willmobhill-arch/gwinnett-index/main/data/udc_sections.jsonl');

SELECT * FROM load_duluth_cases_from_url(
  'https://raw.githubusercontent.com/willmobhill-arch/gwinnett-index/main/data/duluth_cases.jsonl');

SELECT load_meeting_docs_from_url(
  'https://raw.githubusercontent.com/willmobhill-arch/gwinnett-index/main/data/duluth_meeting_docs.jsonl');

预期结果：860 个章节、228 条案例记录（109 个不同案例）、356 份会议文件。

架构

数据摄取通过 http 扩展在 Postgres 内部运行——它会直接获取县政府的 ArcGIS REST 服务、Census TIGERweb，以及此仓库自身的原始 URL。无需外部工作进程，传输过程中不涉及凭据，加载全县 11,739 条案例记录时也不会有任何字节经过客户端。

ingest/
  duluth/          UDC PDF -> 860 sections + 18 tables (extract_udc, extract_tables)
  duluth_agendas/  crawl -> OCR -> parse case items from agendas/minutes/packets
db/migrations/     the schema, md5-verified against the live Supabase project
scripts/           export_snapshot.py (the only thing that talks to Postgres) + loaders
data/              extracted corpora, fetched by the SQL loaders above
site/              Astro static site + full agent surface (.md twins, llms.txt, DCAT)
worker/            Cloudflare Worker: REST API + MCP server, five tools, no auth
docs/plans/        design doc, build plan, status

构建网站

DATABASE_URL=postgresql://... python3 scripts/export_snapshot.py   # writes data/snapshot/
cd site && npm ci && SITE_URL=https://your-domain npm run ci        # build + 15 gates

没有快照时，网站会使用 site/fixtures/ 构建——这是一个已提交的小型样本，数据结构完全相同——并在每个页面上说明这一点。若任何路由缺少对应的 .md 文件、任何页面在指出其管辖辖区之前就展示记录，或批量导出中包含几何数据，npm run ci 都会导致构建失败。

API 和 MCP 服务

cd worker && npm ci && npm test        # 10 protocol tests, no network
wrangler secret put SUPABASE_ANON_KEY && wrangler deploy

提供五种公开、只读、无需身份验证的工具：resolve_jurisdiction（务必首先调用）、search_cases、get_case、get_code_section、list_jurisdictions。REST API 通过同一套实现提供相同的五项操作，并发布 /openapi.json。

适配器模式

17 个辖区不可能靠 17 个手写抓取器来处理。供应商生态高度集中——Municode、ArcGIS REST、CivicPlus、CivicClerk、BS&A、Accela——因此大约六种适配器就能覆盖其中约 90%，新增城市只需添加一个配置文件。健康指标：如果新增城市需要编写新代码，而不是添加新配置，说明适配器层存在泄漏。

如实说明数据质量

• 辖区解析器：使用该县自身的分区图层，对 1,915 个探测点进行评分。当 confidence='high' 时，结果正确率为 1,546/1,546 — 100%。所有错误都落在低置信度范围内。22 处不一致均位于边界 141 m 范围内（吞并地区数据滞后；人口普查每年更新）。
• Duluth UDC：原始文本覆盖率为 97.3%；缺失部分是被剥除的标题行，在 426 页中共留下 591 个无法解释的字符。
• UDC Table 2-B（尺寸标准）已逐单元格与渲染后的源页面核对。其他 17 张表已提取，但未经抽查；Table 2-B 中合并的 PUD/CBD 行仍不可靠。数据中已标记相关问题。
• Duluth 会议纪要：其中 57–69% 为扫描件，没有文本层（打印、签署后再次扫描）。OCR 文本单独存储，标记为 text_source='ocr'；它是重建文本，绝非记录原文引述。
• **Duluth 的 109 个案例是查找辅助资料，不是数据集。**逐字段检查结果：67 条的“location”字段不含门牌号，57 条的“request”字段只有 ORDINANCE 一词，23 条的申请人字段延伸到了邮寄地址，只有 13 条注明了分区。每一行都链接到其来源 PDF；**原始记录是文件，字段只是指向文件。**发布为 stats.duluth_extraction。
• 申请人解析：按严格的编辑距离合并了 271 个变体；**262 对置信度较低的匹配项已排队等待人工审核，不会凭猜测合并。**拆分后的实体一眼就能看出有误；错误合并的实体看似权威，却难以察觉。

法律立场

内容	处理方式	依据
法规 / 规划文本	完整镜像	Georgia v. Public.Resource.Org (2020) — 政府法令
案件记录	完整镜像	事实；Georgia Open Records Act
县级地块 / 分区几何数据	仅提供代理数据，绝不重新托管	Gwinnett GIS 许可禁止再分发
辖区边界	托管	US Census TIGER — 公共领域
IBC/IRC 基础文本	绝不提供	ICC 版权；仅索引 Georgia 修订内容

此索引是镜像和衍生分析，并非权威记录系统。每条记录都包含 source_url 和 last_verified。

以 CC0 发布。