AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载导读pdf_reader是 atomic-agents 生态atomic-forge/tools工具集中一个标准化的 Atomic Tool用于从本地文件路径或 HTTP(S) URL 读取 PDF提取其文本内容与文档元数据并支持1-5、3、1,3,5-7这类 1-based 页面范围过滤。本文将完整讲解它的依赖安装、输入/输出 Schema、配置参数与调用方式并结合其源码实现tool/pdf_reader.py与测试用例tests/test_pdf_reader.py剖析底层运行原理读完即可在自己的 Agent 中接入论文、报告、数据表等 PDF 内容的读取能力。一、工具概览与设计定位pdf_reader的核心能力一句话概括从 PDF 中提取文本和元数据输入可以是本地路径或 HTTP(S) URL支持页面范围过滤输出逐页文本加拼接后的全文。它的底层由pypdf驱动属于纯 Python 实现、无需任何原生二进制依赖的解析方案因此在不同平台上都能直接运行接入成本很低。从代码结构看这个工具遵循了 Atomic Agents 的“原子工具”设计哲学——单一职责、自包含、可独立运行也可被 Agent 调度。整个实现放在一个文件夹内atomic-forge/tools/pdf_reader/ ├── tool/ │ └── pdf_reader.py # 工具实现schema 配置 逻辑 ├── tests/ │ └── test_pdf_reader.py ├── README.md ├── pyproject.toml └── requirements.txtpdf_reader.py内部按标准 Atomic Tool 结构组织Imports → Input Schema → Output Schema(s) → Configuration → Main Tool Logic → Example Usage各部分均以注释块分隔与 atomic-forge/guides/tool_structure.md 中规定的六段式结构完全一致。二、环境要求与依赖依据 pyproject.toml 与 requirements.txt该工具的运行条件如下依赖版本约束用途Python3.12运行环境requires-python强制要求atomic-agents2.0.0,3.0.0提供BaseIOSchema、BaseTool、BaseToolConfig等框架基类pydantic2.10.3,3.0.0输入/输出 Schema 的类型校验与字段约束pypdf5.1.0,7.0.0核心 PDF 文本解析引擎requests2.32.3,3.0.0URL 源 PDF 的下载开发/测试环境额外需要pytest、pytest-cov、coverage以及用于在测试中动态生成 PDF 样本的reportlab见pyproject.toml的[dependency-groups].dev。三、安装方式pdf_reader提供了两种安装途径1. 使用 Atomic Assembler CLI 选择安装运行atomic启动 Atomic Assembler 交互式 CLI在工具列表中选择pdf_reader即可。Assembler 会从atomic-forge/tools目录见 atomic-assembler/atomic_assembler/constants.py 中TOOLS_SUBFOLDER atomic-forge/tools读取工具列表并通过 atomic-assembler/atomic_assembler/utils.py 中的copy_atomic_tool把工具的tool/目录复制到你的项目同时自动忽略requirements.txt、pyproject.toml、.coveragerc、uv.lock这些打包元文件。2. 手动复制直接把tool/文件夹复制到你的项目中保持from tool.pdf_reader import ...的导入路径结构然后安装依赖pip install atomic-agents pydantic pypdf requests # 或直接使用仓库提供的依赖清单 pip install -r atomic-forge/tools/pdf_reader/requirements.txt四、输入与输出结构输入 SchemaPdfReaderToolInputSchema继承自BaseIOSchema由源码tool/pdf_reader.py定义三个字段字段类型默认值说明sourcestr必填min_length1—本地文件路径绝对或相对或 HTTP(S) URL指向目标 PDFpage_rangeOptional[str]None读取全部页1-based 页面范围表达式如1、1-5、1,3,5-7越界页会被静默跳过include_metadataboolTrue是否在输出中包含文档元数据其中page_range的语法支持单页、连续区间、逗号组合三种形式均以 1 为起始页码。输出 SchemaPdfReaderToolOutputSchema由源码tool/pdf_reader.py定义包含以下字段字段类型说明sourcestr输入 source 的原样回显textstr所有被提取页文本的拼接结果各页之间以\fform feed换页符分隔pageslist[PdfPage]逐页文本列表每项含 1-based 的page_number与textpage_countint实际提取到的页数经过page_range过滤后total_page_countint源文档的总页数metadataPdfMetadata可选文档信息字典仅在include_metadataTrue时填充errorstr可选操作失败时设置错误信息成功时为NonePdfMetadata结构源码 L50-L59对应 PDF 文档信息字典中的标准键title/Title、author/Author、subject/Subject、creator/Creator、producer/Producer、creation_date/CreationDate、modification_date/ModDate全部为可空字符串。五、基础使用示例原 README 给出了两个最小可运行示例完整代码如下from tool.pdf_reader import PdfReaderTool, PdfReaderToolInputSchema tool PdfReaderTool() # 读取远程 PDF只取前两页 out tool.run(PdfReaderToolInputSchema( sourcehttps://arxiv.org/pdf/1706.03762, page_range1-2, )) print(out.text[:1000]) # 读取本地 PDF提取全部页面 out tool.run(PdfReaderToolInputSchema(source./paper.pdf))解析重点PdfReaderTool()使用默认配置实例化零参数即可开始工作tool.run()接收PdfReaderToolInputSchema实例返回PdfReaderToolOutputSchema实例访问out.text获取全文可切片预览、out.pages逐页访问、out.metadata查看文档信息、out.total_page_count获知文档规模判断失败只需检查out.error is not None。此外pdf_reader.py文件末尾自带的__main__示例还演示了一个完整可运行的脚本它强制将stdout重新配置为 UTF-8 编码sys.stdout.reconfigure(encodingutf-8, errorsreplace)确保 Windows 默认 cp1252 代码页下含非 ASCII 字符的 PDF 文本也能正常打印随后读取 arXiv 上经典的Attention Is All You Need论文https://arxiv.org/pdf/1706.03762前两页用 rich 渲染元数据并打印文本摘要。直接执行python tool/pdf_reader.py即可看到效果。六、配置参数详解PdfReaderToolConfigPdfReaderTool的构造器接受一个PdfReaderToolConfig实例默认PdfReaderToolConfig()该配置类继承自BaseToolConfig定义于 atomic-agents/atomic_agents/base/base_tool.py并提供三个自定义字段字段默认值约束说明user_agentChrome 131 的完整 UA 字符串—URL 源下载时携带的 HTTPUser-Agent请求头timeout30.0ge1.0、le600.0秒URL 源下载的 HTTP 超时时间max_size_bytes50 * 1024 * 102450 MBge1从 URL 下载 PDF 的最大字节数上限自定义配置的写法from tool.pdf_reader import PdfReaderTool, PdfReaderToolConfig config PdfReaderToolConfig( user_agentMyAgent/1.0 (research bot), timeout60.0, max_size_bytes100 * 1024 * 1024, # 放宽到 100 MB ) tool PdfReaderTool(configconfig)在构造器中源码 L101-L105这些配置会被读取并保存为实例属性供后续下载逻辑使用。七、实现原理从源码看工具如何工作1. 输入源识别与加载_load_bytes_is_url通过正则^https?://忽略大小写判断 source 是 URL 还是本地路径然后分两条路径加载字节数据URL 源使用requests.get(source, headers..., timeout..., streamTrue)流式下载。下载前先检查响应头Content-Length若声明大小超过max_size_bytes直接抛错下载过程中以 64 KB 为 chunk 累计字节数一旦实际累计超过上限立即中断并抛错——这就是 README 中“URL 下载被max_size_bytes硬性封顶默认 50 MB”的实现细节。请求头还额外带上了Accept: application/pdf。本地文件Path(source).expanduser()支持~展开随后校验文件存在性否则FileNotFoundError与是否确为文件否则ValueError最后read_bytes()读入内存。2. 页面范围解析parse_page_range这是工具中最值得关注的一个静态方法源码 L134-L171它把page_range表达式解析为按升序排列、裁剪到total_pages的 1-based 页码集合按逗号切分后含-的段按起止页码展开区间单个数字段直接作为页码页码 1、区间end start、无法转成整数的段都会抛出ValueError超出文档总页数的页码被静默忽略对应 README 中“out-of-range pages are silently skipped”若解析后一个有效页都没有如表达式8-9而文档只有 4 页会抛错“No pages selected”让 Agent 明确知晓选择失败。这些行为被测试用例完整覆盖见下文其中test_parse_page_range_clips_to_total验证parse_page_range(1,3,5-7, 4) [1, 3]即越界部分被裁剪。3. 提取与组装run主流程run方法源码 L191-L227的流程加载字节 →PdfReader(io.BytesIO(data))在内存中构建 pypdf 解析器total_pages len(reader.pages)若有page_range则调用parse_page_range否则取全部页range(1, total_pages 1)逐页reader.pages[page_number - 1].extract_text()提取文本空页回退为组装pages列表以\n\f\n作为页间分隔符拼接text按需调用_format_metadata从reader.metadata中读取文档信息字典映射为PdfMetadata返回完整的PdfReaderToolOutputSchema。4. 优雅失败graceful degradation整个run主体被try/except Exception包裹任何异常文件不存在、页面范围非法、加密/损坏 PDF、下载失败、网络超时等都不会抛出而是返回一个errorstr(e)、其余字段置空的PdfReaderToolOutputSchema。这与 README 中“工具优雅失败在输出中返回error而非抛出异常”的说明完全对应方便 Agent 直接根据output.error分支处理而无需 try/except。八、测试验证行为即文档tests/test_pdf_reader.py 用reportlab在内存中动态构造多页 PDF 作为样本覆盖了工具几乎全部行为契约测试用例验证点test_parse_page_range_singletons / range / mixed三种页面表达式均解析正确test_parse_page_range_clips_to_total越界页码被静默裁剪test_parse_page_range_rejects_*空串、非法数字、倒序区间、0 页码均抛ValueErrortest_parse_page_range_no_pages_selected范围整体越界时明确报错test_run_local_file_reads_all_pages本地文件默认读取全部页text含\f分隔符test_run_local_file_with_page_range指定单页时仅返回该页内容test_run_metadata_present / disabled元数据默认返回、可关闭test_run_missing_local_file_returns_error缺失文件以error字段返回而非抛异常test_run_invalid_page_range_returns_error非法页面表达式进入error分支test_run_url_sourceURL 下载路径mockrequests.get可用test_run_url_too_large_by_header响应头声明的超大 PDF 被max_size_bytes拦截可见“本地文件、远程 URL、范围过滤、元数据开关、错误处理、大小上限”这六类能力均有对应的自动化断言可以作为你集成该工具时的行为参考。九、注意事项与限制失败不抛异常始终先检查output.error再读取text/pages/metadata等字段URL 大小封顶下载受max_size_bytes默认 50 MB限制超大 PDF 会被拒绝可在配置中调整加密 PDF 暂不支持pypdf对加密文档的处理不在本工具范围内加密 PDF 当前会进入error分支文本提取依赖 PDF 质量扫描版 PDF纯图片无文本层无法提取出文本需要配合 OCR 方案text的分页分隔符是\f代码中实际拼接为\n\f\n按此切分即可还原页面边界page_range的页码是 1-based且越界页静默跳过——若表达式完全越界则会报错这两种行为需要在使用时区分。十、在 Agent 中集成由于PdfReaderTool继承了BaseTool[PdfReaderToolInputSchema, PdfReaderToolOutputSchema]它会自动获得tool_name、tool_description、input_schema、output_schema等属性见 base_tool.py 中的泛型推导逻辑可以直接注册到 Atomic Agent 的工具列表中让 LLM 依据输入 Schema 的描述自行决定“何时需要读取 PDF、以什么page_range调用”。这正是 Atomic Agents “构建原子化 Agent”理念的典型落点把 PDF 读取这一原子能力封装好其余 Agent 只需注册即可复用。一句话总结pdf_reader是 atomic-agents 生态中开箱即用的 PDF 文本提取工具本地/远程双源、页面范围过滤、元数据返回、优雅失败四大特性加上纯 Python 依赖使其非常适合作为论文阅读、报告分析、批量文档处理等 Agent 场景的基础能力模块。赞分享AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载相关推荐xberg Python 实战用 extract 接口从 PDF 中提取文本与元数据xberg Python 实战用 extract 接口从 PDF 中提取文本与元数据 在 xberg 的 Python 绑定中所有提取入口 extract后端AI 应用NLPOpenSpace PDF 文本提取实战用 pdftotext 与 bash 工具绕过 read_file 的二进制读取限制OpenSpace PDF 文本提取实战用 pdftotext 与 bash 工具绕过 read_file 的二进制读取限制 OpenSpace 的 GDPV人工智能AI 技能MCP 服务AI 评测PinchTab 长文阅读模式实战指南默认文本提取与全量文本模式的原理与用法PinchTab 长文阅读模式实战指南默认文本提取与全量文本模式的原理与用法 导读 本文围绕 PinchTab 优化基准任务组 Group 35「长篇文章读取上一篇Ultralytics 深度估计预测器解析以 DepthPredictor 源码理解 YOLO 单目深度推理下一篇auditok音频活动检测与分割工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 的声明式请求校验：express-validator 模式化验证完全指南)
