[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-sentient-agi--ROMA":3,"tool-sentient-agi--ROMA":62},[4,18,28,37,45,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":24,"last_commit_at":25,"category_tags":26,"status":17},9989,"n8n","n8n-io\u002Fn8n","n8n 是一款面向技术团队的公平代码（fair-code）工作流自动化平台，旨在让用户在享受低代码快速构建便利的同时，保留编写自定义代码的灵活性。它主要解决了传统自动化工具要么过于封闭难以扩展、要么完全依赖手写代码效率低下的痛点，帮助用户轻松连接 400 多种应用与服务，实现复杂业务流程的自动化。\n\nn8n 特别适合开发者、工程师以及具备一定技术背景的业务人员使用。其核心亮点在于“按需编码”：既可以通过直观的可视化界面拖拽节点搭建流程，也能随时插入 JavaScript 或 Python 代码、调用 npm 包来处理复杂逻辑。此外，n8n 原生集成了基于 LangChain 的 AI 能力，支持用户利用自有数据和模型构建智能体工作流。在部署方面，n8n 提供极高的自由度，支持完全自托管以保障数据隐私和控制权，也提供云端服务选项。凭借活跃的社区生态和数百个现成模板，n8n 让构建强大且可控的自动化系统变得简单高效。",184740,2,"2026-04-19T23:22:26",[16,14,13,15,27],"插件",{"id":29,"name":30,"github_repo":31,"description_zh":32,"stars":33,"difficulty_score":10,"last_commit_at":34,"category_tags":35,"status":17},10095,"AutoGPT","Significant-Gravitas\u002FAutoGPT","AutoGPT 是一个旨在让每个人都能轻松使用和构建 AI 的强大平台，核心功能是帮助用户创建、部署和管理能够自动执行复杂任务的连续型 AI 智能体。它解决了传统 AI 应用中需要频繁人工干预、难以自动化长流程工作的痛点，让用户只需设定目标，AI 即可自主规划步骤、调用工具并持续运行直至完成任务。\n\n无论是开发者、研究人员，还是希望提升工作效率的普通用户，都能从 AutoGPT 中受益。开发者可利用其低代码界面快速定制专属智能体；研究人员能基于开源架构探索多智能体协作机制；而非技术背景用户也可直接选用预置的智能体模板，立即投入实际工作场景。\n\nAutoGPT 的技术亮点在于其模块化“积木式”工作流设计——用户通过连接功能块即可构建复杂逻辑，每个块负责单一动作，灵活且易于调试。同时，平台支持本地自托管与云端部署两种模式，兼顾数据隐私与使用便捷性。配合完善的文档和一键安装脚本，即使是初次接触的用户也能在几分钟内启动自己的第一个 AI 智能体。AutoGPT 正致力于降低 AI 应用门槛，让人人都能成为 AI 的创造者与受益者。",183572,"2026-04-20T04:47:55",[13,36,27,14,15],"语言模型",{"id":38,"name":39,"github_repo":40,"description_zh":41,"stars":42,"difficulty_score":10,"last_commit_at":43,"category_tags":44,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":46,"name":47,"github_repo":48,"description_zh":49,"stars":50,"difficulty_score":24,"last_commit_at":51,"category_tags":52,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",161147,"2026-04-19T23:31:47",[14,13,36],{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":59,"last_commit_at":60,"category_tags":61,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,27],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":76,"owner_website":76,"owner_url":77,"languages":78,"stars":105,"forks":106,"last_commit_at":107,"license":76,"difficulty_score":10,"env_os":108,"env_gpu":108,"env_ram":108,"env_deps":109,"category_tags":114,"github_topics":76,"view_count":24,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":115,"updated_at":116,"faqs":117,"releases":147},10156,"sentient-agi\u002FROMA","ROMA","Recursive-Open-Meta-Agent v0.1 (Beta). A meta-agent framework to build high-performance multi-agent systems.","ROMA（Recursive-Open-Meta-Agent）是一个旨在简化高性能多智能体系统构建的元智能体框架。面对复杂任务时，单一智能体往往能力有限，而传统多智能体协作又面临架构设计难、协调效率低等挑战。ROMA 通过引入“递归”与“分层”机制，让智能体能够像组织一样自我编排：高层智能体负责拆解目标与调度，底层智能体专注执行，甚至能动态生成新的子智能体来应对突发需求，从而显著提升系统解决复杂问题的整体性能。\n\n这款工具特别适合 AI 开发者、研究人员以及需要构建自动化工作流的技术团队使用。如果你正在探索如何让多个 AI 模型高效协作，或者希望搭建具备自我进化能力的代理系统，ROMA 提供了灵活的底层支持。其核心亮点在于“元智能体”设计理念，即框架本身不仅能运行智能体，还能管理智能体的创建与交互逻辑，实现了从静态编排到动态递归协作的跨越。作为开源项目，ROMA 目前处于测试阶段，为社区提供了一个探索下一代多智能体架构的实用起点，帮助创作者更轻松地实现从概念到高性能系统的落地。","\u003Cdiv align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_898e6a2a280a.png\" alt=\"alt text\" width=\"60%\"\u002F>\n    \u003Ch1>ROMA: Recursive Open Meta-Agents\u003C\u002Fh1>\n\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Building hierarchical high-performance multi-agent systems made easy! (Beta) \u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F14848\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_4a68feb902da.png\" alt=\"sentient-agi%2FROMA | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fsentient.xyz\u002F\" target=\"_blank\" style=\"margin: 2px;\">\n    \u003Cimg alt=\"Homepage\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSentient-Homepage-%23EAEAEA?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNDEuMzMzIiBoZWlnaHQ9IjM0MS4zMzMiIHZlcnNpb249IjEuMCIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0xMzIuNSAyOC40Yy0xLjUgMi4yLTEuMiAzLjkgNC45IDI3LjIgMy41IDEzLjcgOC41IDMzIDExLjEgNDIuOSAyLjYgOS45IDUuMyAxOC42IDYgMTkuNCAzLjIgMy4zIDExLjctLjggMTMuMS02LjQuNS0xLjktMTcuMS03Mi0xOS43LTc4LjYtMS4yLTMtNy41LTYuOS0xMS4zLTYuOS0xLjYgMC0zLjEuOS00LjEgMi40ek0xMTAgMzBjLTEuMSAxLjEtMiAzLjEtMiA0LjVzLjkgMy40IDIgNC41IDMuMSAyIDQuNSAyIDMuNC0uOSA0LjUtMiAyLTMuMSAyLTQuNS0uOS0zLjQtMi00LjUtMy4xLTItNC41LTItMy40LjktNC41IDJ6TTgxLjUgNDYuMWMtMi4yIDEuMi00LjYgMi44LTUuMiAzLjctMS44IDIuMy0xLjYgNS42LjUgNy40IDEuMyAxLjIgMzIuMSAxMC4yIDQ1LjQgMTMuMyAzIC44IDYuOC0yLjIgNi44LTUuMyAwLTMuNi0yLjItOS4yLTMuOS0xMC4xQzEyMy41IDU0LjIgODcuMiA0NCA4NiA0NGMtLjMuMS0yLjMgMS00LjUgMi4xek0xNjUgNDZjLTEuMSAxLjEtMiAyLjUtMiAzLjIgMCAyLjggMTEuMyA0NC41IDEyLjYgNDYuNS45IDEuNSAyLjQgMi4zIDQuMiAyLjMgMy44IDAgOS4yLTUuNiA5LjItOS40IDAtMS41LTIuMS0xMC45LTQuNy0yMC44bC00LjctMTguMS00LjUtMi44Yy01LjMtMy40LTcuNC0zLjYtMTAuMS0uOXpNNDguNyA2NS4xYy03LjcgNC4xLTYuOSAxMC43IDEuNSAxMyAyLjQuNiAyMS40IDUuOCA0Mi4yIDExLjYgMjIuOCA2LjIgMzguOSAxMC4yIDQwLjMgOS44IDMuNS0uOCA0LjYtMy44IDMuMi04LjgtMS41LTUuNy0yLjMtNi41LTguMy04LjJDOTQuMiA3My4xIDU2LjYgNjMgNTQuOCA2M2MtMS4zLjEtNCAxLTYuMSAyLjF6TTE5OC4yIDY0LjdjLTMuMSAyLjgtMy41IDUuNi0xLjEgOC42IDQgNS4xIDEwLjkgMi41IDEwLjktNC4xIDAtNS4zLTUuOC03LjktOS44LTQuNXpNMTgxLjggMTEzLjFjLTI3IDI2LjQtMzEuOCAzMS41LTMxLjggMzMuOSAwIDEuNi43IDMuNSAxLjUgNC40IDEuNyAxLjcgNy4xIDMgMTAuMiAyLjQgMi4xLS4zIDU2LjktNTMuNCA1OS01Ny4xIDEuNy0zLjEgMS42LTkuOC0uMy0xMi41LTMuNi01LjEtNC45LTQuMi0zOC42IDI4Ljl6TTM2LjYgODguMWMtNSA0LTIuNCAxMC45IDQuMiAxMC45IDMuMyAwIDYuMi0yLjkgNi4yLTYuMyAwLTIuMS00LjMtNi43LTYuMy02LjctLjggMC0yLjYuOS00LjEgMi4xek02My40IDk0LjVjLTEuNi43LTguOSA3LjMtMTYuMSAxNC43TDM0IDEyMi43djUuNmMwIDYuMyAxLjYgOC43IDUuOSA4LjcgMi4xIDAgNi0zLjQgMTkuOS0xNy4zIDkuNS05LjUgMTcuMi0xOCAxNy4yLTE4LjkgMC00LjctOC40LTguNi0xMy42LTYuM3pNNjIuOSAxMzAuNiAzNCAxNTkuNXY1LjZjMCA2LjIgMS44IDguOSA2IDguOSAzLjIgMCA2Ni02Mi40IDY2LTY1LjYgMC0zLjMtMy41LTUuNi05LjEtNi4ybC01LS41LTI5IDI4Ljl6TTE5Ni4zIDEzNS4yYy05IDktMTYuNiAxNy4zLTE2LjkgMTguNS0xLjMgNS4xIDIuNiA4LjMgMTAgOC4zIDIuOCAwIDUuMi0yIDE3LjktMTQuOCAxNC41LTE0LjcgMTQuNy0xNC45IDE0LjctMTkuMyAwLTUuOC0yLjItOC45LTYuMi04LjktMi42IDAtNS40IDIuMy0xOS41IDE2LjJ6TTk2IDEzNi44Yy0yLjkuOS04IDYuNi04IDkgMCAxLjMgMi45IDEzLjQgNi40IDI3IDMuNiAxMy42IDcuOSAzMC4zIDkuNyAzNy4yIDEuNyA2LjkgMy42IDEzLjMgNC4xIDE0LjIuNSAxIDIuNiAyLjcgNC44IDMuOCA2LjggMy41IDExIDIuMyAxMS0zLjIgMC0zLTIwLjYtODMuMS0yMi4xLTg1LjktLjktMS45LTMuNi0yLjgtNS45LTIuMXpNMTIwLjUgMTU4LjRjLTEuOSAyLjktMS4yIDguNSAxLjQgMTEuNiAxLjEgMS40IDEyLjEgNC45IDM5LjYgMTIuNSAyMC45IDUuOCAzOC44IDEwLjUgMzkuOCAxMC41czMuNi0xIDUuNy0yLjJjOC4xLTQuNyA3LjEtMTAuNi0yLjMtMTMuMi0yOC4yLTguMS03OC41LTIxLjYtODAuMy0yMS42LTEuNCAwLTMgMS0zLjkgMi40ek0yMTAuNyAxNTguOGMtMS44IDEuOS0yLjIgNS45LS45IDcuOCAxLjUgMi4zIDUgMy40IDcuNiAyLjQgNi40LTIuNCA1LjMtMTEuMi0xLjUtMTEuOC0yLjQtLjItNCAuMy01LjIgMS42ek02OS42IDE2MmMtMiAyLjItMy42IDQuMy0zLjYgNC44LjEgMi42IDEwLjEgMzguNiAxMS4xIDM5LjkgMi4yIDIuNiA5IDUuNSAxMS41IDQuOSA1LTEuMyA0LjktMy0xLjUtMjcuNy0zLjMtMTIuNy02LjUtMjMuNy03LjItMjQuNS0yLjItMi43LTYuNC0xLjctMTAuMyAyLjZ6TTQ5LjYgMTgxLjVjLTIuNCAyLjUtMi45IDUuNC0xLjIgOEM1MiAxOTUgNjAgMTkzIDYwIDE4Ni42YzAtMS45LS44LTQtMS44LTQuOS0yLjMtMi4xLTYuNi0yLjItOC42LS4yek0xMjguNSAxODdjLTIuMyAyLjUtMS4zIDEwLjMgMS42IDEyLjggMi4yIDEuOSAzNC44IDExLjIgMzkuNCAxMS4yIDMuNiAwIDEwLjEtNC4xIDExLTcgLjYtMS45LTEuNy03LTMuMS03LS4yIDAtMTAuMy0yLjctMjIuMy02cy0yMi41LTYtMjMuMy02Yy0uOCAwLTIuMy45LTMuMyAyek0xMzYuNyAyMTYuOGMtMy40IDMuOC0xLjUgOS41IDMuNSAxMC43IDMuOSAxIDguMy0zLjQgNy4zLTcuMy0xLjItNS4xLTcuNS03LjEtMTAuOC0zLjR6Ii8%2BPC9zdmc%2B&link=https%3A%2F%2Fhuggingface.co%2FSentientagi\" style=\"display: inline-block; vertical-align: middle;\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsentient-agi\" target=\"_blank\" style=\"margin: 2px;\">\n    \u003Cimg alt=\"GitHub\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGithub-sentient_agi-181717?logo=github\" style=\"display: inline-block; vertical-align: middle;\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002FSentientagi\" target=\"_blank\" style=\"margin: 2px;\">\n    \u003Cimg alt=\"Hugging Face\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F%F0%9F%A4%97%20Hugging%20Face-SentientAGI-ffc107?color=ffc107&logoColor=white\" style=\"display: inline-block; vertical-align: middle;\"\u002F>\n  \u003C\u002Fa>\n\u003C\u002Fdiv>\n\n\u003Cdiv align=\"center\" style=\"line-height: 1;\">\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002Fsentientfoundation\" target=\"_blank\" style=\"margin: 2px;\">\n    \u003Cimg alt=\"Discord\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-SentientAGI-7289da?logo=discord&logoColor=white&color=7289da\" style=\"display: inline-block; vertical-align: middle;\"\u002F>\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fx.com\u002FSentientAGI\" target=\"_blank\" style=\"margin: 2px;\">\n    \u003Cimg alt=\"Twitter Follow\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F-SentientAGI-grey?logo=x&link=https%3A%2F%2Fx.com%2FSentientAGI%2F\" style=\"display: inline-block; vertical-align: middle;\"\u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.sentient.xyz\u002Fblog\u002Frecursive-open-meta-agent\">Technical Blog\u003C\u002Fa> •\n  \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2602.01848\">Paper\u003C\u002Fa> •\n  \u003Ca href=\"https:\u002F\u002Fwww.sentient.xyz\u002F\">Build Agents for $$$\u003C\u002Fa>\n\u003C\u002Fp>\n\n\n\n\u003C\u002Fdiv>\n\n## 📑 Table of Contents\n- [🧠 Conceptual Overview](#-conceptual-overview)\n- [📦 Installation & Setup](#-installation--setup)\n- [⚡ Quickstart: End-to-End Workflow](#-quickstart-end-to-end-workflow)\n- [⚙️ Configuration & Storage](#-configuration--storage)\n- [🧰 Toolkits](#-toolkits)\n- [🌐 REST API & CLI](#-rest-api--cli)\n- [🏗️ Core Building Block: `BaseModule`](#-core-building-block-basemodule)\n- [📚 Module Reference](#-module-reference)\n  - [⚛️ Atomizer](#-atomizer)\n  - [📋 Planner](#-planner)\n  - [⚙️ Executor](#-executor)\n  - [🔀 Aggregator](#-aggregator)\n  - [✅ Verifier](#-verifier)\n- [🎯 Advanced Patterns](#-advanced-patterns)\n- [🧪 Testing](#-testing)\n- [💡 Troubleshooting & Tips](#-troubleshooting--tips)\n- [📖 Glossary](#-glossary)\n\n---\n\n## 🎯 What is ROMA?\n\n\u003Cdiv align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_43359c776072.gif\" alt=\"alt text\" width=\"80%\"\u002F>\n\u003C\u002Fdiv>\n\u003Cbr>\n\n**ROMA** is a **meta-agent framework** that uses recursive hierarchical structures to solve complex problems. By breaking down tasks into parallelizable components, ROMA enables agents to tackle sophisticated reasoning challenges while maintaining transparency that makes context-engineering and iteration straightforward. The framework offers **parallel problem solving** where agents work simultaneously on different parts of complex tasks, **transparent development** with a clear structure for easy debugging, and **proven performance** demonstrated through our search agent's strong benchmark results. We've shown the framework's effectiveness, but this is just the beginning. As an **open-source and extensible** platform, ROMA is designed for community-driven development, allowing you to build and customize agents for your specific needs while benefiting from the collective improvements of the community.\n\n## 🏗️ How It Works\n\n\n**ROMA** framework processes tasks through a recursive **plan–execute loop**:\n\n```python\ndef solve(task):\n    if is_atomic(task):                 # Step 1: Atomizer\n        return execute(task)            # Step 2: Executor\n    else:\n        subtasks = plan(task)           # Step 2: Planner\n        results = []\n        for subtask in subtasks:\n            results.append(solve(subtask))  # Recursive call\n        return aggregate(results)       # Step 3: Aggregator\n\n# Entry point:\nanswer = solve(initial_request)\n```\n1. **Atomizer** – Decides whether a request is **atomic** (directly executable) or requires **planning**.  \n2. **Planner** – If planning is needed, the task is broken into smaller **subtasks**. Each subtask is fed back into the **Atomizer**, making the process recursive.  \n3. **Executors** – Handle atomic tasks. Executors can be **LLMs, APIs, or even other agents** — as long as they implement an `agent.execute()` interface.  \n4. **Aggregator** – Collects and integrates results from subtasks. Importantly, the Aggregator produces the **answer to the original parent task**, not just raw child outputs.  \n\n\n\n#### 📐 Information Flow  \n- **Top-down:** Tasks are decomposed into subtasks recursively.  \n- **Bottom-up:** Subtask results are aggregated upwards into solutions for parent tasks.  \n- **Left-to-right:** If a subtask depends on the output of a previous one, it waits until that subtask completes before execution.  \n\nThis structure makes the system flexible, recursive, and dependency-aware — capable of decomposing complex problems into smaller steps while ensuring results are integrated coherently. \n\n\u003Cdetails>\n\u003Csummary>Click to view the system flow diagram\u003C\u002Fsummary>\n\n```mermaid\nflowchart TB\n    A[Your Request] --> B{Atomizer}\n    B -->|Plan Needed| C[Planner]\n    B -->|Atomic Task| D[Executor]\n\n    %% Planner spawns subtasks\n    C --> E[Subtasks]\n    E --> G[Aggregator]\n\n    %% Recursion\n    E -.-> B  \n\n    %% Execution + Aggregation\n    D --> F[Final Result]\n    G --> F\n\n    style A fill:#e1f5fe\n    style F fill:#c8e6c9\n    style B fill:#fff3e0\n    style C fill:#ffe0b2\n    style D fill:#d1c4e9\n    style G fill:#c5cae9\n\n```\n\n\u003C\u002Fdetails>\u003Cbr>\n\n## 🚀 Quick Start\n\n### Fastest Way: Minimal Installation (Recommended for Evaluation)\n\nGet started in **under 30 seconds** with no infrastructure required:\n\n```bash\n# Install with uv (10-100x faster)\nuv pip install roma-dspy\n\n# Or with pip\npip install roma-dspy\n\n# Set your OpenRouter API key (default uses Claude Sonnet 4.5 + Gemini 2.5 Flash)\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"\n\n# Start solving tasks immediately\npython -c \"from roma_dspy.core.engine.solve import solve; print(solve('What is 2+2?'))\"\n```\n\n> **Note**: The default configuration uses OpenRouter with Claude Sonnet 4.5 (executor) and Gemini 2.5 Flash (other agents). You can also use OpenAI directly by setting `OPENAI_API_KEY` and customizing the config.\n\n**What you get:**\n- ✅ Core agent framework (Atomizer, Planner, Executor, Aggregator, Verifier)\n- ✅ All DSPy prediction strategies (CoT, ReAct, CodeAct, etc.)\n- ✅ File storage (no database required)\n- ✅ Built-in toolkits (Calculator, File operations)\n- ✅ Works with any LLM provider (OpenRouter, OpenAI, Anthropic, etc.)\n\n**No Docker, no database, no setup - just install and go!**\n\n### Production Setup: Full Features with Docker\n\nFor production use with persistence, observability, and API server:\n\n```bash\n# One-command setup (builds Docker, starts services)\njust setup\n\n# Or with specific profile\njust setup crypto_agent\n\n# Verify services running\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealth\n\n# Solve tasks via API\njust solve \"What is the capital of France?\"\n```\n\n**Additional features with Docker:**\n- 📊 PostgreSQL persistence (execution history, checkpoints)\n- 📈 MLflow observability (experiment tracking, visualization)\n- 🌐 REST API server (FastAPI with interactive docs)\n- 📦 S3-compatible storage (MinIO)\n- 🔧 E2B code execution sandboxes\n- 🎨 Interactive TUI visualization\n\n**Services Available:**\n- 🚀 **REST API**: http:\u002F\u002Flocalhost:8000\u002Fdocs\n- 🗄️ **PostgreSQL**: Automatic persistence\n- 📦 **MinIO**: S3-compatible storage (http:\u002F\u002Flocalhost:9001)\n- 📊 **MLflow**: http:\u002F\u002Flocalhost:5000 (with `docker-up-full`)\n\nSee [Quick Start Guide](docs\u002FQUICKSTART.md) and [Deployment Guide](docs\u002FDEPLOYMENT.md) for details.\n\n---\n\n## 🧠 Conceptual Overview\nROMA's module layer wraps canonical DSPy patterns into purpose-built components that reflect the lifecycle of complex task execution:\n\n1. **Atomizer** decides whether a request can be handled directly or needs decomposition.\n2. **Planner** breaks non-atomic goals into an ordered graph of subtasks.\n3. **Executor** resolves individual subtasks, optionally routing through function\u002Ftool calls.\n4. **Aggregator** synthesizes subtask outputs back into a coherent answer.\n5. **Verifier** (optional) inspects the aggregate output against the original goal before delivering.\n\nEvery module shares the same ergonomics: instantiate it with a language model (LM) or provider string, choose a prediction strategy, then call `.forward()` (or `.aforward()` for async) with the task-specific fields.\n\nAll modules ultimately delegate to DSPy signatures defined in `roma_dspy.core.signatures`. This keeps interfaces stable even as the internals evolve.\n\n## 📦 Installation & Setup\n\n### Option 1: Minimal Installation (Fastest - Recommended for Evaluation)\n\n**Perfect for:** Evaluating ROMA, development, testing, quick prototyping\n\n**Install in under 30 seconds:**\n\n```bash\n# With uv (recommended - 10-100x faster)\nuv pip install roma-dspy\n\n# Or with pip\npip install roma-dspy\n```\n\n**Set your API key:**\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"  # Recommended\n# OR\nexport OPENAI_API_KEY=\"sk-...\"\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n**Start using immediately:**\n```python\nfrom roma_dspy.core.engine.solve import solve\n\n# Solve any task\nresult = solve(\"What is the capital of France?\")\nprint(result)\n```\n\n**What's included:**\n- ✅ All core modules (Atomizer, Planner, Executor, Aggregator, Verifier)\n- ✅ All DSPy prediction strategies\n- ✅ File-based storage (no database needed)\n- ✅ Core toolkits (Calculator, File operations)\n- ✅ Works with any LLM provider\n\n**What's NOT included (install separately if needed):**\n- PostgreSQL persistence → `uv pip install roma-dspy[persistence]`\n- MLflow observability → `uv pip install roma-dspy[observability]`\n- E2B code execution → `uv pip install roma-dspy[e2b]`\n- REST API server → `uv pip install roma-dspy[api]`\n- S3 storage → `uv pip install roma-dspy[s3]`\n- All features → `uv pip install roma-dspy[all]`\n\n---\n\n### Option 2: Full Installation with Docker (Production)\n\n**Perfect for:** Production deployment, teams, full observability\n\n**Prerequisites:**\n- Docker & Docker Compose\n- Python 3.12+ (for local development)\n- [Just](https:\u002F\u002Fgithub.com\u002Fcasey\u002Fjust) command runner (optional, recommended)\n\n**One-command setup:**\n```bash\n# Interactive setup (prompts for E2B, S3, etc.)\njust setup\n\n# Or with specific profile\njust setup crypto_agent\n```\n\n**Manual Docker start:**\n```bash\njust docker-up       # Basic (PostgreSQL + MinIO + API)\njust docker-up-full  # With MLflow observability\n```\n\n**Environment variables** (auto-configured by `just setup`):\n```bash\n# LLM Provider (required)\nOPENROUTER_API_KEY=...     # Recommended\n# OR\nOPENAI_API_KEY=...\nANTHROPIC_API_KEY=...\n\n# Optional: Advanced features\nE2B_API_KEY=...           # Code execution\nCOINGECKO_API_KEY=...     # Crypto toolkit\n```\n\n**Additional Docker features:**\n- 📊 PostgreSQL (execution history, checkpoints)\n- 📈 MLflow (experiment tracking, metrics)\n- 🌐 REST API (FastAPI with docs)\n- 📦 MinIO (S3-compatible storage)\n- 🎨 TUI visualization\n\n---\n\n### Option 3: Development Installation\n\n**For contributing or extending ROMA:**\n\n```bash\n# Clone repository\ngit clone https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002Froma.git\ncd roma\n\n# Install with dev tools (includes pytest, ruff, mypy)\nuv pip install -e \".[dev]\"\n\n# Run tests\njust test\n\n# Format code\njust format\n\n# Type check\njust typecheck\n```\n\n---\n\n### Comparison: Which Installation is Right for You?\n\n| Feature | Minimal (`pip install roma-dspy`) | Docker (`just setup`) |\n|---------|----------------------------------|----------------------|\n| Installation time | **\u003C 30 seconds** | ~5-10 minutes |\n| Infrastructure required | **None** | Docker |\n| Core agent framework | ✅ | ✅ |\n| File storage | ✅ | ✅ |\n| PostgreSQL persistence | ❌ (install `[persistence]`) | ✅ |\n| MLflow observability | ❌ (install `[observability]`) | ✅ |\n| REST API | ❌ (install `[api]`) | ✅ |\n| Best for | Evaluation, development | Production, teams |\n\n## ⚡ Quickstart: End-to-End Workflow\nThe following example mirrors a typical orchestration loop. It uses three different providers to showcase how easily each module can work with distinct models and strategies.\n\n```python\nimport dspy\nfrom roma_dspy import Aggregator, Atomizer, Executor, Planner, Verifier, SubTask\nfrom roma_dspy.types import TaskType\n\n# Optional tool that the Executor may call\ndef get_weather(city: str) -> str:\n    \"\"\"Return a canned weather report for the city.\"\"\"\n    return f\"The weather in {city} is sunny.\"\n\n# Executor geared toward ReAct with a Fireworks model\nexecutor_lm = dspy.LM(\n    \"fireworks_ai\u002Faccounts\u002Ffireworks\u002Fmodels\u002Fkimi-k2-instruct-0905\",\n    temperature=0.7,\n    cache=True,\n)\nexecutor = Executor(\n    lm=executor_lm,\n    prediction_strategy=\"react\",\n    tools=[get_weather],\n    context_defaults={\"track_usage\": True},\n)\n\n# Atomizer decides when to branch into planning\natomizer = Atomizer(\n    lm=dspy.LM(\"openrouter\u002Fgoogle\u002Fgemini-2.5-flash\", temperature=0.6, cache=False),\n    prediction_strategy=\"cot\",\n    context_defaults={\"track_usage\": True},\n)\n\n# Planner produces executable subtasks for non-atomic goals\nplanner = Planner(\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.85, cache=True),\n    prediction_strategy=\"cot\",\n    context_defaults={\"track_usage\": True},\n)\n\naggregator = Aggregator(\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.65),\n    prediction_strategy=\"cot\",\n)\n\nverifier = Verifier(\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.0),\n)\n\ndef run_pipeline(goal: str) -> str:\n    atomized = atomizer.forward(goal)\n    if atomized.is_atomic or atomized.node_type.is_execute:\n        execution = executor.forward(goal)\n        candidate = execution.output\n    else:\n        plan = planner.forward(goal)\n        results = []\n        for idx, subtask in enumerate(plan.subtasks, start=1):\n            execution = executor.forward(subtask.goal)\n            results.append(\n                SubTask(\n                    goal=subtask.goal,\n                    task_type=subtask.task_type,\n                    dependencies=subtask.dependencies,\n                )\n            )\n        aggregated = aggregator.forward(goal, results)\n        candidate = aggregated.synthesized_result\n\n    verdict = verifier.forward(goal, candidate)\n    if verdict.verdict:\n        return candidate\n    return f\"Verifier flagged the output: {verdict.feedback or 'no feedback returned'}\"\n\nprint(run_pipeline(\"Plan a weekend in Barcelona and include a packing list.\"))\n```\n\nHighlights:\n- Different modules can run on different LMs and temperatures.\n- Tools are provided either at construction or per-call.\n- `context_defaults` ensures each `.forward()` call enters a proper `dspy.context()` with the module's LM.\n\n---\n\n## ⚙️ Configuration & Storage\n\nROMA-DSPy uses **OmegaConf** for layered configuration with **Pydantic** validation, and provides **execution-scoped storage** for complete task isolation.\n\n### Quick Configuration Example\n\n```python\nfrom roma_dspy.config import load_config\n\n# Load with profile and overrides\nconfig = load_config(\n    profile=\"crypto_agent\",\n    overrides=[\"agents.executor.llm.temperature=0.3\"]\n)\n```\n\n**Available Profiles**: `general`, `crypto_agent` (list with `just list-profiles`)\n\n**See**: [Configuration Guide](docs\u002FCONFIGURATION.md) for complete documentation on profiles, agent configuration, LLM settings, toolkit configuration, and task-aware agent mapping.\n\n### Storage\n\nStorage is automatic and execution-scoped - each task gets an isolated directory. Large toolkit responses (>100KB) are automatically stored as Parquet files.\n\n```python\nfrom roma_dspy.core.engine.solve import solve\n\n# Storage created automatically at: {base_path}\u002Fexecutions\u002F{execution_id}\u002F\nresult = solve(\"Analyze blockchain transactions\")\n```\n\n**Features**: Execution isolation, S3-compatible, automatic Parquet storage, Docker-managed\n\n**See**: [Deployment Guide](docs\u002FDEPLOYMENT.md) for production storage configuration including S3 integration.\n\n---\n\n## 🧰 Toolkits\n\nROMA-DSPy includes 9 built-in toolkits that extend agent capabilities:\n\n**Core**: FileToolkit, CalculatorToolkit, E2BToolkit (code execution)\n**Crypto**: CoinGeckoToolkit, BinanceToolkit, DefiLlamaToolkit, ArkhamToolkit\n**Search**: SerperToolkit (web search)\n**Universal**: MCPToolkit (connect to any [MCP server](https:\u002F\u002Fgithub.com\u002Fwong2\u002Fawesome-mcp-servers))\n\n### Quick Configuration\n\n```yaml\nagents:\n  executor:\n    toolkits:\n      - class_name: \"FileToolkit\"\n        enabled: true\n      - class_name: \"E2BToolkit\"\n        enabled: true\n        toolkit_config:\n          timeout: 600\n```\n\n**See**: [Toolkits Reference](docs\u002FTOOLKITS.md) for complete toolkit documentation including all tools, configuration options, MCP integration, and custom toolkit development.\n\n---\n\n## 🌐 REST API & CLI\n\nROMA-DSPy provides both a REST API and CLI for production use.\n\n### REST API\n\nFastAPI server with interactive documentation:\n\n```bash\n# Starts automatically with Docker\njust docker-up\n\n# API Documentation: http:\u002F\u002Flocalhost:8000\u002Fdocs\n# Health check: http:\u002F\u002Flocalhost:8000\u002Fhealth\n```\n\n**Endpoints**: Execution management, checkpoints, visualization, metrics\n\n### CLI\n\n```bash\n# Local task execution\nroma-dspy solve \"Your task\" --profile general\n\n# Server management\nroma-dspy server start\nroma-dspy server health\n\n# Execution management\nroma-dspy exec create \"Task\"\nroma-dspy exec status \u003Cid> --watch\n\n# Interactive TUI visualization (requires MLflow for best results)\njust viz \u003Cexecution_id>\n\n# Full help\nroma-dspy --help\n```\n\n**See**: API documentation at `\u002Fdocs` endpoint for complete OpenAPI specification and interactive testing.\n\n---\n\n## 🏗️ Core Building Block: `BaseModule`\nAll modules inherit from `BaseModule`, located at `roma_dspy\u002Fcore\u002Fmodules\u002Fbase_module.py`. It standardizes:\n- signature binding via DSPy prediction strategies,\n- LM instantiation and context management,\n- tool normalization and merging,\n- sync\u002Fasync entrypoints with safe keyword filtering.\n\n### Context & LM Management\nWhen you instantiate a module, you can either provide an existing `dspy.LM` or let the module build one from a provider string (`model`) and optional keyword arguments (`model_config`).\n\n```python\nfrom roma_dspy import Executor\n\nexecutor = Executor(\n    model=\"openrouter\u002Fopenai\u002Fgpt-4o-mini\",\n    model_config={\"temperature\": 0.5, \"cache\": True},\n)\n```\n\nInternally, `BaseModule` ensures that every `.forward()` call wraps the predictor invocation in:\n\n```python\nwith dspy.context(lm=self._lm, **context_defaults):\n    ...\n```\n\nYou can inspect the effective LM configuration via `get_model_config()` to confirm provider, cache settings, or sanitized kwargs.\n\n### Working with Tools\nTools can be supplied as a list, tuple, or mapping of callables accepted by DSPy’s ReAct\u002FCodeAct strategies.\n\n```python\nexecutor = Executor(tools=[get_weather])\nexecutor.forward(\"What is the weather in Amman?\", tools=[another_function])\n```\n\n`BaseModule` automatically deduplicates tools based on object identity and merges constructor defaults with per-call overrides.\n\n### Prediction Strategies\nROMA exposes DSPy's strategies through the `PredictionStrategy` enum (`roma_dspy\u002Ftypes\u002Fprediction_strategy.py`). Use either the enum or a case-insensitive string alias:\n\n```python\nfrom roma_dspy.types import PredictionStrategy\n\nplanner = Planner(prediction_strategy=PredictionStrategy.CHAIN_OF_THOUGHT)\nexecutor = Executor(prediction_strategy=\"react\")\n```\n\nAvailable options include `Predict`, `ChainOfThought`, `ReAct`, `CodeAct`, `BestOfN`, `Refine`, `Parallel`, `majority`, and more. Strategies that require tools (`ReAct`, `CodeAct`) automatically receive any tools you pass to the module.\n\n### Async Execution\nEvery module offers an `aforward()` method. When the underlying DSPy predictor supports async (`acall`\u002F`aforward`), ROMA dispatches asynchronously; otherwise, it gracefully falls back to the sync implementation while preserving awaitability.\n\n```python\nresult = await executor.aforward(\"Download the latest sales report\")\n```\n\n## 📚 Module Reference\n\n### ⚛️ Atomizer\n**Location**: `roma_dspy\u002Fcore\u002Fmodules\u002Fatomizer.py`\n\n**Purpose**: Decide whether a goal is atomic or needs planning.\n\n**Constructor**:\n```python\nAtomizer(\n    prediction_strategy: Union[PredictionStrategy, str] = \"ChainOfThought\",\n    *,\n    lm: Optional[dspy.LM] = None,\n    model: Optional[str] = None,\n    model_config: Optional[Mapping[str, Any]] = None,\n    tools: Optional[Sequence|Mapping] = None,\n    **strategy_kwargs,\n)\n```\n\n**Inputs** (`AtomizerSignature`):\n- `goal: str`\n\n**Outputs** (`AtomizerResponse`):\n- `is_atomic: bool` — whether the task can run directly.\n- `node_type: NodeType` — `PLAN` or `EXECUTE` hint for downstream routing.\n\n**Usage**:\n```python\natomized = atomizer.forward(\"Curate a 5-day Tokyo itinerary with restaurant reservations\")\nif atomized.is_atomic:\n    ...  # send directly to Executor\nelse:\n    ...  # hand off to Planner\n```\n\nThe Atomizer is strategy-agnostic but typically uses `ChainOfThought` or `Predict`. You can pass hints (e.g., `max_tokens`) via `call_params`:\n\n```python\natomizer.forward(\n    \"Summarize this PDF\",\n    call_params={\"max_tokens\": 200},\n)\n```\n\n### 📋 Planner\n**Location**: `roma_dspy\u002Fcore\u002Fmodules\u002Fplanner.py`\n\n**Purpose**: Break a goal into ordered subtasks with optional dependency graph.\n\n**Constructor**: identical pattern as the Atomizer.\n\n**Inputs** (`PlannerSignature`):\n- `goal: str`\n\n**Outputs** (`PlannerResult`):\n- `subtasks: List[SubTask]` — each has `goal`, `task_type`, and `dependencies`.\n- `dependencies_graph: Optional[Dict[str, List[str]]]` — explicit adjacency mapping when returned by the LM.\n\n**Usage**:\n```python\nplan = planner.forward(\"Launch a B2B webinar in 6 weeks\")\nfor subtask in plan.subtasks:\n    print(subtask.goal, subtask.task_type)\n```\n\n`SubTask.task_type` is a `TaskType` enum that follows the ROMA MECE framework (Retrieve, Write, Think, Code Interpret, Image Generation).\n\n### ⚙️ Executor\n**Location**: `roma_dspy\u002Fcore\u002Fmodules\u002Fexecutor.py`\n\n**Purpose**: Resolve atomic goals, optionally calling tools\u002Ffunctions through DSPy's ReAct, CodeAct, or similar strategies.\n\n**Constructor**: same pattern; the most common strategies are `ReAct`, `CodeAct`, or `ChainOfThought`.\n\n**Inputs** (`ExecutorSignature`):\n- `goal: str`\n\n**Outputs** (`ExecutorResult`):\n- `output: str | Any`\n- `sources: Optional[List[str]]` — provenance or citations.\n\n**Usage**:\n```python\nexecution = executor.forward(\n    \"Compile a packing list for a 3-day ski trip\",\n    config={\"temperature\": 0.4},  # per-call LM override\n)\nprint(execution.output)\n```\n\nTo expose tools only for certain calls:\n\n```python\nexecution = executor.forward(\n    \"What is the weather in Paris?\",\n    tools=[get_weather],\n)\n```\n\n### 🔀 Aggregator\n**Location**: `roma_dspy\u002Fcore\u002Fmodules\u002Faggregator.py`\n\n**Purpose**: Combine multiple subtask results into a final narrative or decision.\n\n**Constructor**: identical pattern.\n\n**Inputs** (`AggregatorResult` signature):\n- `original_goal: str`\n- `subtasks_results: List[SubTask]` — usually the planner’s proposals augmented with execution outputs.\n\n**Outputs** (`AggregatorResult` base model):\n- `synthesized_result: str`\n\n**Usage**:\n```python\naggregated = aggregator.forward(\n    original_goal=\"Plan a data migration\",\n    subtasks_results=[\n        SubTask(goal=\"Inventory current databases\", task_type=TaskType.RETRIEVE),\n        SubTask(goal=\"Draft migration timeline\", task_type=TaskType.WRITE),\n    ],\n)\nprint(aggregated.synthesized_result)\n```\n\nBecause it inherits `BaseModule`, you can still attach tools (e.g., a knowledge-base retrieval function) if your aggregation strategy requires external calls.\n\n### ✅ Verifier\n**Location**: `roma_dspy\u002Fcore\u002Fmodules\u002Fverifier.py`\n\n**Purpose**: Validate that the synthesized output satisfies the original goal.\n\n**Inputs** (`VerifierSignature`):\n- `goal: str`\n- `candidate_output: str`\n\n**Outputs**:\n- `verdict: bool`\n- `feedback: Optional[str]`\n\n**Usage**:\n```python\nverdict = verifier.forward(\n    goal=\"Draft a GDPR-compliant privacy policy\",\n    candidate_output=aggregated.synthesized_result,\n)\nif not verdict.verdict:\n    print(\"Needs revision:\", verdict.feedback)\n```\n\n## 🎯 Advanced Patterns\n\n### Swapping Models at Runtime\nUse `replace_lm()` to reuse the same module with a different LM (useful for A\u002FB testing or fallbacks).\n\n```python\nfast_executor = executor.replace_lm(dspy.LM(\"openrouter\u002Fanthropic\u002Fclaude-3-haiku\"))\n```\n\n### Per-Call Overrides\nYou can alter LM behavior or provide extra parameters without rebuilding the module.\n\n```python\nexecutor.forward(\n    \"Summarize the meeting notes\",\n    config={\"temperature\": 0.1, \"max_tokens\": 300},\n    context={\"stop\": [\"Observation:\"]},\n)\n```\n\n`call_params` (or keyword arguments) are filtered to match the DSPy predictor’s accepted kwargs, preventing accidental errors.\n\n### Tool-Only Execution\nIf you want deterministic tool routing, you can set a dummy LM (or a very low-temperature model) and pass pure Python callables.\n\n```python\nfrom roma_dspy import Executor\n\nexecutor = Executor(\n    prediction_strategy=\"code_act\",\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.0),\n    tools={\"get_weather\": get_weather, \"lookup_user\": lookup_user},\n)\n```\n\nROMA will ensure both constructor and per-call tools are available to the strategy.\n\n## 🧪 Testing\n\n```bash\n# Run all tests\njust test\n\n# Run specific tests\npytest tests\u002Funit\u002F -v\npytest tests\u002Fintegration\u002F -v\n```\n\n**See**: `justfile` for all available test commands.\n\n## 💡 Troubleshooting & Tips\n- **`ValueError: Either provide an existing lm`** — supply `lm=` or `model=` when constructing the module.\n- **`Invalid prediction strategy`** — check spelling; strings are case-insensitive but must match a known alias.\n- **Caching** — pass `cache=True` on your LM or set it in `model_config` to reutilize previous completions.\n- **Async contexts** — when mixing sync and async calls, ensure your event loop is running (e.g., use `asyncio.run`).\n- **Tool duplicates** — tools are deduplicated by identity; create distinct functions if you need variations.\n\n## 📖 Glossary\n\n### Core Concepts\n- **DSPy**: Stanford's declarative framework for prompting, planning, and tool integration.\n- **Prediction Strategy**: The DSPy class\u002Ffunction that powers reasoning (CoT, ReAct, etc.).\n- **SubTask**: Pydantic model describing a decomposed unit of work (`goal`, `task_type`, `dependencies`).\n- **NodeType**: Whether the Atomizer chose to `PLAN` or `EXECUTE`.\n- **TaskType**: MECE classification for subtasks (`RETRIEVE`, `WRITE`, `THINK`, `CODE_INTERPRET`, `IMAGE_GENERATION`).\n- **Context Defaults**: Keyword arguments provided to `dspy.context(...)` on every call.\n\n### Configuration & Storage\n- **FileStorage**: Execution-scoped storage manager providing isolated directories per task execution.\n- **DataStorage**: Automatic Parquet storage system for large toolkit responses (threshold-based).\n- **Execution ID**: Unique identifier for each task execution, used for storage isolation.\n- **Base Path**: Root directory for all storage operations (local path or S3 bucket).\n- **Profile**: Named configuration preset (e.g., `general`, `crypto_agent`).\n- **Configuration Override**: Runtime value that supersedes profile\u002Fdefault settings.\n\n### Toolkits\n- **BaseToolkit**: Abstract base class for all toolkits providing storage integration and tool registration.\n- **REQUIRES_FILE_STORAGE**: Metadata flag indicating a toolkit requires FileStorage (e.g., FileToolkit).\n- **Toolkit Config**: Toolkit-specific settings like API keys, timeouts, and thresholds.\n- **Tool Selection**: Include\u002Fexclude lists to filter which tools from a toolkit are available.\n- **Storage Threshold**: Size limit (KB) above which responses are stored in Parquet format.\n\n### Architecture\n- **Execution-Scoped Isolation**: Pattern where each execution gets unique storage directory.\n- **Parquet Integration**: Automatic columnar storage for large structured data.\n- **S3 Compatibility**: Ability to use S3-compatible storage via Docker volume mounts.\n- **Tool Registration**: Automatic discovery and registration of toolkit methods as callable tools.\n\n---\n\nHappy building! If you extend or customize a module, keep the signatures aligned so your higher-level orchestration remains stable.\n\n**Additional Resources:**\n- [Quick Start Guide](docs\u002FQUICKSTART.md) - Get started in under 10 minutes\n- [Configuration Guide](docs\u002FCONFIGURATION.md) - Complete configuration reference\n- [Toolkits Reference](docs\u002FTOOLKITS.md) - All built-in and custom toolkits\n- [Deployment Guide](docs\u002FDEPLOYMENT.md) - Production deployment with Docker\n- [E2B Setup](docs\u002FE2B_SETUP.md) - Code execution toolkit setup\n- [Observability](docs\u002FOBSERVABILITY.md) - MLflow tracking and monitoring\n- [Configuration System](config\u002FREADME.md) - Configuration profiles and examples\n\n\n## 📊 Benchmarks\n\nWe evaluate our simple implementation of a search system using ROMA, called ROMA-Search across three benchmarks: **SEAL-0**, **FRAMES**, and **SimpleQA**.  \nBelow are the performance graphs for each benchmark.\n\n### [SEAL-0](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fvtllms\u002Fsealqa)\nSealQA is a new challenging benchmark for evaluating Search-Augmented Language models on fact-seeking questions where web search yields conflicting, noisy, or unhelpful results.  \n\n![SEAL-0 Results](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_c6afd19b351b.jpeg)\n\n---\n\n### [FRAMES](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fgoogle\u002Fframes-benchmark)\n\u003Cdetails>\n\u003Csummary>View full results\u003C\u002Fsummary>\n\nA comprehensive evaluation dataset designed to test the capabilities of Retrieval-Augmented Generation (RAG) systems across factuality, retrieval accuracy, and reasoning.  \n\n![FRAMES Results](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_315e34f6d15e.jpeg)\n\n\u003C\u002Fdetails>\n\n---\n\n### [SimpleQA](https:\u002F\u002Fopenai.com\u002Findex\u002Fintroducing-simpleqa\u002F)\n\u003Cdetails>\n\u003Csummary>View full results\u003C\u002Fsummary>\n\nFactuality benchmark that measures the ability for language models to answer short, fact-seeking questions.  \n\n![SimpleQA Results](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_906b35f01ccb.jpeg)\n\n\u003C\u002Fdetails>\n\n## 🧩 Foundations & Lineage\n\nWhile ROMA introduces a practical, open-source framework for hierarchical task execution, it is directly built upon two foundational research contributions introduced in [WriteHERE](https:\u002F\u002Farxiv.org\u002Fabs\u002F2503.08275):\n\n- **Heterogeneous Recursive Planning** — The overall architecture of ROMA follows the framework first introduced in prior work on *heterogeneous recursive planning*, where complex tasks are recursively decomposed into a graph of subtasks, each assigned a distinct cognitive type.  \n\n- **Type Specification in Decomposition** — ROMA’s “Three Universal Operations” (THINK 🤔, WRITE ✍️, SEARCH 🔍) generalize the *type specification in decomposition* hypothesis, which identified reasoning, composition, and retrieval as the three fundamental cognitive types.  \n\nThese contributions are described in detail in the WriteHERE repository and paper. By explicitly adopting and extending this foundation, ROMA provides a **generalizable scaffold, agent system, versatility, and extensibility** that builds upon these insights and makes them usable for builders across domains. \n\n## 🙏 Acknowledgments\n\nThis framework would not have been possible if it wasn't for these amazing open-source contributions!\n- Inspired by the hierarchical planning approach described in [\"Beyond Outlining: Heterogeneous Recursive Planning\"](https:\u002F\u002Farxiv.org\u002Fabs\u002F2503.08275) by Xiong et al.\n- [Pydantic](https:\u002F\u002Fgithub.com\u002Fpydantic\u002Fpydantic) - Data validation using Python type annotations\n- [DSPy]([https:\u002F\u002Fdspy.ai\u002F)) - Framework for programming AI agents\n- [E2B](https:\u002F\u002Fgithub.com\u002Fe2b-dev\u002Fe2b) - Cloud runtime for AI agents\n\n## 📚 Citation\n\nIf you use the ROMA repo in your research, please cite:\n\n```bibtex\n@misc{alzubi2026romarecursiveopenmetaagent,\n      title={ROMA: Recursive Open Meta-Agent Framework for Long-Horizon Multi-Agent Systems}, \n      author={Salaheddin Alzu'bi and Baran Nama and Arda Kaz and Anushri Eswaran and Weiyuan Chen and Sarvesh Khetan and Rishab Bala and Tu Vu and Sewoong Oh},\n      year={2026},\n      eprint={2602.01848},\n      archivePrefix={arXiv},\n      primaryClass={cs.AI},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2602.01848}, \n}\n```\n\n## 🌟 Star History\n\n\u003Cdiv align=\"center\">\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_01ba43d47d6d.png)](https:\u002F\u002Fwww.star-history.com\u002F#sentient-agi\u002Froma&Date)\n\n\u003C\u002Fdiv>\n\n## 📄 License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n","\u003Cdiv align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_898e6a2a280a.png\" alt=\"alt text\" width=\"60%\"\u002F>\n    \u003Ch1>ROMA：递归开放元智能体\u003C\u002Fh1>\n\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>轻松构建分层高性能多智能体系统！（测试版）\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F14848\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_4a68feb902da.png\" alt=\"sentient-agi%2FROMA | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fsentient.xyz\u002F\" target=\"_blank\" style=\"margin: 2px;\">\n    \u003Cimg alt=\"主页\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSentient-Homepage-%23EAEAEA?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzNDEuMzMzIiBoZWlnaHQ9IjM0MS4zMzMiIHZlcnNpb249IjEuMCIgdmlld0JveD0iMCAwIDI1NiAyNTYiPjxwYXRoIGQ9Ik0xMzIuNSAyOC40Yy0xLjUgMi4yLTEuMiAzLjkgNC45IDI3LjIgMy41IDEzLjcgOC41IDMzIDExLjEgNDIuOSAyLjYgOS45IDUuMyAxOC42IDYgMTkuNCAzLjIgMy4zIDExLjctLjggMTMuLTYuQuNS0xLjktMTcuIS03Mi0xOS43LTc4LjYtMS4yLTMtNy41LTYuOS0xMS4zLTYuOS0xLjYgMC0zLjEuOS00LjEgMi40ek0xMTAgMzBjLTEuMSAxLjEtMiAzLjEtMiA0LjVzLjkgMy40IDIgNC41IDMuMSAyIDQuNSAyIDMuNC0uOSA0LjUtMiAyLTMuMSAyLTQuNS0uOS0zLjQtMi00LjUtMy4xLTItNC41LTItMy40LjktNC41IDJ6TTgxLjUgNDYuMWMtMi4yIDEuMi00LjYgMi44LTUuMiAzLjctMS44IDIuMy0xLjYgNS42LjUgNy40IDEuMyAxLjIgMzIuMSAxMC4yIDQ1LjQgMTMuMyAzIC44IDYuOC0yLjIgNi44LTUuMyAwLTMuNi0yLjItOS4yLTMuOS0xMC4xQzEyMy41IDU0LjIgODcuMiA0NCA4NiA0NGMtLjMuMS0yLjMgMS00LjUgMi4xek0xNjUgNDZjLTEuMSAxLjEtMiAyLjUtMiAzLjIgMCAyLjggMTEuMyA0NC41IDEyLjYgNDYuNS.9IDEuNSAyLjQgMi4zIDQuMiAyLjMgMy44IDAgOS4yLTUuNiA9LjItOS40IDAtMS41LTIuMS0xMC45LTQuNy0yMC44bC00LjctMTguMS00LjUtMi44Yy01LjMtMy40LTcuNC0zLjYtMTAuMS0uOXpNNDguNyA2NS4xYy03LjcgNC4xLTYuOSAxMC43IDEuNSAxMyAyLjQuNiAyMS40IDUuOCA0Mi4yIDExLjYgMjIuOCA6LjIgMzguOSAxMC4yIDQwLjMgOS44IDMuNS0uOCA0LjYtMy44IDMuMi04LjgtMS41LTUuNy0yLjMtNi41LTguMy04LjJDOTQuMiA3My4xIDU6LjYgNjMgNTQuOCA6M2MtMS4zLjEtNCAxLTYuIS0yLjF6TTE5OC4yIDY0LjdjLTMuMSAyLjgtMy41IDUuNi0xLjEgOC42IDQgNS4xIDEwLjkgMi41IDEwLjktNC4xIDAtNS4zLTUuOC07LjktOS44LTQuNXpNMTgxLjggMTEzLjFjLTI3IDI2LjQtMzEuOCAzMS41LTMxLjggMzMuOSAwIDEuNi.7IDMuNSAxLjUgNC40IDEuNyAxLjcgNy4xIDMgMTAuMiAyLjQgMi4xLS.3IDU6LjktNTMuNCA5OS05Ny4xIDEuNy0zLjEgMS46LTkuOC0uMy0xMi41LTMuNi05LjEtNC45LTQuMi0zOC42IDI4L.jl6TTM6LjYgODguMWMtNSA0L-TuCAxMC45IDQuMiAxMC45IDMuMyAwIDYuMi0yLjIgNi4yLTYuMyAwL-TuCAxMC45LTQuMi0zOC42IDI4L.jl6TTM36LjYgODguMWMtNSA0L-TuCAxMC45IDQuMiAxMC45IDMuMyAwIDYuMi0yLjIgNi4yLTYuMyAwL-TuCAxMC45LTQuMi0zOC42IDI4L.jl6TTM63.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM196.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM62.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM130.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM135.2cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM96IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM136.8cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM120.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM210.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM29.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM49.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM181.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM128.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM136.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM216.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM43.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM29.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM25.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM24.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM23.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM21.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM10.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM10.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM9.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM8.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM7.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM6.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM5.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM3.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM2.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM1.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM0.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM0.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-0.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.0IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-1.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.0IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-2.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.0IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-3.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.0IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-4.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.0IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.7IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.8IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-5.9IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.0IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.1IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.2IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.3IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.4IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.5IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.6IDk4.5cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.7IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.8IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-6.9IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.0IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.1IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.2IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.3IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.4IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.5IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.6IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.7IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.8IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.9IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.10IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.11IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.12IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.13IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.14IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.15IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.16IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.17IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.18IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.19IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.20IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.21IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.22IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.23IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.24IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.25IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.26IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.27IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.28IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.29IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.30IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.31IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.32IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.33IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.34IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.35IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.36IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.37IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.38IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.39IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.40IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.41IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.42IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.43IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.44IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.45IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.46IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.47IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.48IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.49IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.50IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.51IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.52IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.53IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.54IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.55IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.56IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.57IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.58IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.59IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.60IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.61IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.62IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.63IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.64IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.65IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.66IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.67IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.68IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.69IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.70IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.71IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.72IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.73IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.74IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.75IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.76IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.77IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.78IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.79IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.80IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.81IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.82IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.83IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.84IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.85IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.86IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.87IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.88IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.89IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.90IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.91IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.92IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.93IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.94IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.95IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.96IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.97IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.98IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.99IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.100IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.101IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.102IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.103IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.104IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.105IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.106IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.107IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.108IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.109IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.110IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.111IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.112IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.113IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.114IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.115IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.116IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.117IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.118IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.119IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.120IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.121IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.122IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.123IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.124IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.125IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.126IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.127IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.128IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.129IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.130IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.131IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.132IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.133IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.134IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.135IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.136IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.137IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.138IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.139IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.140IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.141IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.142IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.143IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.144IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.145IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.146IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.147IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.148IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.149IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.150IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.151IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.152IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.153IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.154IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.155IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.156IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.157IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.158IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.159IDk4.5 cj-LTuCAxMC45IDQuMi0zOC42IDI4L.jl6TTM-7.15...\n\n## 🎯 什么是 ROMA？\n\n\u003Cdiv align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_43359c776072.gif\" alt=\"alt text\" width=\"80%\"\u002F>\n\u003C\u002Fdiv>\n\u003Cbr>\n\n**ROMA** 是一个 **元智能体框架**，它利用递归的层次化结构来解决复杂问题。通过将任务分解为可并行化的组件，ROMA 使智能体能够应对复杂的推理挑战，同时保持透明性，从而让上下文工程和迭代变得简单直接。该框架提供 **并行问题求解**，即智能体可以同时处理复杂任务的不同部分；**透明开发**，拥有清晰的结构以便于调试；以及 **经过验证的性能**，这从我们的搜索智能体在基准测试中取得的优异成绩中可见一斑。我们已经证明了该框架的有效性，但这仅仅是个开始。作为一款 **开源且可扩展** 的平台，ROMA 专为社区驱动的开发而设计，允许您根据自身需求构建和定制智能体，同时受益于社区的集体改进。\n\n## 🏗️ 工作原理\n\n\n**ROMA** 框架通过递归的 **计划–执行循环** 来处理任务：\n\n```python\ndef solve(task):\n    if is_atomic(task):                 # 第一步：原子化器\n        return execute(task)            # 第二步：执行器\n    else:\n        subtasks = plan(task)           # 第二步：规划器\n        results = []\n        for subtask in subtasks:\n            results.append(solve(subtask))  # 递归调用\n        return aggregate(results)       # 第三步：聚合器\n\n# 入口：\nanswer = solve(initial_request)\n```\n1. **原子化器** – 决定请求是否为 **原子级**（可以直接执行）或需要 **规划**。\n2. **规划器** – 如果需要规划，任务会被分解成更小的 **子任务**。每个子任务会再次送回 **原子化器**，从而使整个过程具有递归性。\n3. **执行器** – 负责处理原子级任务。执行器可以是 **大语言模型、API，甚至是其他智能体**——只要它们实现了 `agent.execute()` 接口即可。\n4. **聚合器** – 收集并整合子任务的结果。重要的是，聚合器生成的是 **原始父任务的答案**，而不仅仅是子任务的原始输出。  \n\n\n\n#### 📐 信息流  \n- **自上而下：** 任务被递归地分解为子任务。\n- **自下而上：** 子任务的结果被向上聚合，形成父任务的解决方案。\n- **从左到右：** 如果某个子任务依赖于前一个子任务的输出，它会等待前一个子任务完成后再执行。  \n\n这种结构使系统灵活、递归且具备依赖感知能力——能够将复杂问题分解为更小的步骤，同时确保结果被连贯地整合在一起。 \n\n\u003Cdetails>\n\u003Csummary>点击查看系统流程图\u003C\u002Fsummary>\n\n```mermaid\nflowchart TB\n    A[您的请求] --> B{原子化器}\n    B -->|需要规划| C[规划器]\n    B -->|原子任务| D[执行器]\n\n    %% 规划器产生子任务\n    C --> E[子任务]\n    E --> G[聚合器]\n\n    %% 递归\n    E -.-> B  \n\n    %% 执行与聚合\n    D --> F[最终结果]\n    G --> F\n\n    style A fill:#e1f5fe\n    style F fill:#c8e6c9\n    style B fill:#fff3e0\n    style C fill:#ffe0b2\n    style D fill:#d1c4e9\n    style G fill:#c5cae9\n\n```\n\n\u003C\u002Fdetails>\u003Cbr>\n\n## 🚀 快速入门\n\n### 最快方式：最小化安装（推荐用于评估）\n\n无需任何基础设施，即可在 **30秒内** 开始使用：\n\n```bash\n# 使用 uv 安装（速度提升 10-100 倍）\nuv pip install roma-dspy\n\n# 或者使用 pip\npip install roma-dspy\n\n# 设置您的 OpenRouter API 密钥（默认使用 Claude Sonnet 4.5 + Gemini 2.5 Flash）\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"\n\n# 立即开始解决问题\npython -c \"from roma_dspy.core.engine.solve import solve; print(solve('2+2 是多少？'))\"\n```\n\n> **注意**：默认配置使用 OpenRouter 的 Claude Sonnet 4.5（执行器）和 Gemini 2.5 Flash（其他智能体）。您也可以通过设置 `OPENAI_API_KEY` 并自定义配置，直接使用 OpenAI。\n\n**您将获得：**\n- ✅ 核心智能体框架（原子化器、规划器、执行器、聚合器、验证器）\n- ✅ 所有 DSPy 预测策略（CoT、ReAct、CodeAct 等）\n- ✅ 文件存储（无需数据库）\n- ✅ 内置工具包（计算器、文件操作）\n- ✅ 可与任何 LLM 提供商兼容（OpenRouter、OpenAI、Anthropic 等）\n\n**无需 Docker、无需数据库、无需任何设置——只需安装即可使用！**\n\n### 生产环境部署：完整功能与 Docker\n\n适用于需要持久化、可观ability 和 API 服务器的生产环境：\n\n```bash\n# 一键部署（构建 Docker，启动服务）\njust setup\n\n# 或者使用特定配置\njust setup crypto_agent\n\n# 验证服务是否运行\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealth\n\n# 通过 API 解决任务\njust solve \"法国的首都是哪里？\"\n```\n\n**Docker 版本的附加功能：**\n- 📊 PostgreSQL 持久化（执行历史、检查点）\n- 📈 MLflow 可观测性（实验跟踪、可视化）\n- 🌐 REST API 服务器（FastAPI，附带交互式文档）\n- 📦 S3 兼容存储（MinIO）\n- 🔧 E2B 代码执行沙箱\n- 🎨 交互式 TUI 可视化\n\n**可用服务：**\n- 🚀 **REST API**：http:\u002F\u002Flocalhost:8000\u002Fdocs\n- 🗄️ **PostgreSQL**：自动持久化\n- 📦 **MinIO**：S3 兼容存储（http:\u002F\u002Flocalhost:9001）\n- 📊 **MLflow**：http:\u002F\u002Flocalhost:5000（使用 `docker-up-full`）\n\n详细信息请参阅 [快速入门指南](docs\u002FQUICKSTART.md) 和 [部署指南](docs\u002FDEPLOYMENT.md)。\n\n---\n\n## 🧠 概念概述\nROMA 的模块层将经典的 DSPy 模式封装为专门构建的组件，这些组件反映了复杂任务执行的生命周期：\n\n1. **原子化器** 决定请求是否可以直接处理，或者需要进一步分解。\n2. **规划器** 将非原子目标分解为有序的子任务图。\n3. **执行器** 解决各个子任务，必要时通过函数或工具调用来完成。\n4. **聚合器** 将子任务的输出综合成一个连贯的答案。\n5. **验证器**（可选）在交付最终结果之前，检查汇总输出是否符合原始目标。\n\n每个模块都采用相同的使用方式：只需传入语言模型（LM）或提供商字符串进行实例化，选择一种预测策略，然后使用任务特定的参数调用 `.forward()`（或异步的 `.aforward()`）方法。\n\n所有模块最终都会委托给 `roma_dspy.core.signatures` 中定义的 DSPy 签名。这样即使内部实现不断演进，接口也能保持稳定。\n\n## 📦 安装与设置\n\n### 选项 1：最小化安装（最快——推荐用于评估）\n\n**适用场景：** 评估 ROMA、开发、测试、快速原型制作\n\n**30 秒内即可完成安装：**\n\n```bash\n# 使用 uv（推荐——速度提升 10-100 倍）\nuv pip install roma-dspy\n\n# 或者使用 pip\npip install roma-dspy\n```\n\n**设置您的 API 密钥：**\n```bash\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"  # 推荐\n# 或者\nexport OPENAI_API_KEY=\"sk-...\"\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n**立即开始使用：**\n```python\nfrom roma_dspy.core.engine.solve import solve\n\n# 解决任何任务\nresult = solve(\"法国的首都是什么？\")\nprint(result)\n```\n\n**包含内容：**\n- ✅ 所有核心模块（原子化器、规划器、执行器、聚合器、验证器）\n- ✅ 所有 DSPy 预测策略\n- ✅ 基于文件的存储（无需数据库）\n- ✅ 核心工具包（计算器、文件操作）\n- ✅ 兼容任何 LLM 提供商\n\n**不包含的内容（如需请单独安装）：**\n- PostgreSQL 持久化 → `uv pip install roma-dspy[persistence]`\n- MLflow 可观测性 → `uv pip install roma-dspy[observability]`\n- E2B 代码执行 → `uv pip install roma-dspy[e2b]`\n- REST API 服务器 → `uv pip install roma-dspy[api]`\n- S3 存储 → `uv pip install roma-dspy[s3]`\n- 所有功能 → `uv pip install roma-dspy[all]`\n\n---\n\n### 方案 2：使用 Docker 的完整安装（生产环境）\n\n**适合场景：** 生产部署、团队协作、全面可观测性\n\n**先决条件：**\n- Docker 和 Docker Compose\n- Python 3.12+（用于本地开发）\n- [Just](https:\u002F\u002Fgithub.com\u002Fcasey\u002Fjust) 命令运行工具（可选，推荐使用）\n\n**一键式设置：**\n```bash\n# 交互式设置（会提示配置 E2B、S3 等）\njust setup\n\n# 或者指定特定配置文件\njust setup crypto_agent\n```\n\n**手动启动 Docker：**\n```bash\njust docker-up       # 基础版（PostgreSQL + MinIO + API）\njust docker-up-full  # 包含 MLflow 可观测性的完整版\n```\n\n**环境变量**（由 `just setup` 自动配置）：\n```bash\n# LLM 提供商（必填）\nOPENROUTER_API_KEY=...     # 推荐\n# 或者\nOPENAI_API_KEY=...\nANTHROPIC_API_KEY=...\n\n# 可选：高级功能\nE2B_API_KEY=...           # 代码执行\nCOINGECKO_API_KEY=...     # 加密货币工具包\n```\n\n**Docker 的其他功能：**\n- 📊 PostgreSQL（执行历史、检查点）\n- 📈 MLflow（实验跟踪、指标）\n- 🌐 REST API（FastAPI，附带文档）\n- 📦 MinIO（兼容 S3 的存储）\n- 🎨 TUI 可视化界面\n\n---\n\n### 方案 3：开发环境安装\n\n**适用于贡献或扩展 ROMA：**\n\n```bash\n# 克隆仓库\ngit clone https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002Froma.git\ncd roma\n\n# 安装开发工具（包括 pytest、ruff、mypy）\nuv pip install -e \".[dev]\"\n\n# 运行测试\njust test\n\n# 格式化代码\njust format\n\n# 类型检查\njust typecheck\n```\n\n---\n\n### 对比：哪种安装方式适合您？\n\n| 特性                 | 极简版（`pip install roma-dspy`） | Docker 版（`just setup`） |\n|----------------------|----------------------------------|--------------------------|\n| 安装时间             | **\u003C 30 秒**                     | ~5–10 分钟               |\n| 所需基础设施         | **无**                           | Docker                   |\n| 核心代理框架         | ✅                               | ✅                       |\n| 文件存储             | ✅                               | ✅                       |\n| PostgreSQL 持久化    | ❌（需安装 `[persistence]`）      | ✅                       |\n| MLflow 可观测性        | ❌（需安装 `[observability]`）    | ✅                       |\n| REST API             | ❌（需安装 `[api]`）              | ✅                       |\n| 最佳适用场景         | 评估、开发                       | 生产、团队协作           |\n\n## ⚡ 快速入门：端到端工作流\n以下示例模拟了一个典型的编排流程。它使用了三个不同的提供商，展示了各个模块如何轻松地与不同模型和策略协同工作。\n\n```python\nimport dspy\nfrom roma_dspy import Aggregator, Atomizer, Executor, Planner, Verifier, SubTask\nfrom roma_dspy.types import TaskType\n\n# 执行器可能调用的可选工具\ndef get_weather(city: str) -> str:\n    \"\"\"返回该城市的固定天气预报\"\"\"\n    return f\"{city} 的天气是晴朗的。\"\n\n# 面向 ReAct 的执行器，使用 Fireworks 模型\nexecutor_lm = dspy.LM(\n    \"fireworks_ai\u002Faccounts\u002Ffireworks\u002Fmodels\u002Fkimi-k2-instruct-0905\",\n    temperature=0.7,\n    cache=True,\n)\nexecutor = Executor(\n    lm=executor_lm,\n    prediction_strategy=\"react\",\n    tools=[get_weather],\n    context_defaults={\"track_usage\": True},\n)\n\n# 原子化器决定何时分支进入规划阶段\natomizer = Atomizer(\n    lm=dspy.LM(\"openrouter\u002Fgoogle\u002Fgemini-2.5-flash\", temperature=0.6, cache=False),\n    prediction_strategy=\"cot\",\n    context_defaults={\"track_usage\": True},\n)\n\n# 规划器为非原子目标生成可执行的子任务\nplanner = Planner(\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.85, cache=True),\n    prediction_strategy=\"cot\",\n    context_defaults={\"track_usage\": True},\n)\n\naggregator = Aggregator(\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.65),\n    prediction_strategy=\"cot\",\n)\n\nverifier = Verifier(\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.0),\n)\n\ndef run_pipeline(goal: str) -> str:\n    atomized = atomizer.forward(goal)\n    if atomized.is_atomic 或 atomized.node_type.is_execute:\n        execution = executor.forward(goal)\n        candidate = execution.output\n    else:\n        plan = planner.forward(goal)\n        results = []\n        for idx, subtask in enumerate(plan.subtasks, start=1):\n            execution = executor.forward(subtask.goal)\n            results.append(\n                SubTask(\n                    goal=subtask.goal,\n                    task_type=subtask.task_type,\n                    dependencies=subtask.dependencies,\n                )\n            )\n        aggregated = aggregator.forward(goal, results)\n        candidate = aggregated.synthesized_result\n\n    verdict = verifier.forward(goal, candidate)\n    if verdict.verdict:\n        return candidate\n    return f\"验证器标记了输出：{verdict.feedback 或 '未返回反馈'}\"\n\nprint(run_pipeline(\"计划一个巴塞罗那周末之旅，并附上打包清单。\"))\n```\n\n亮点：\n- 不同模块可以运行在不同的 LM 和温度下。\n- 工具可以在构建时提供，也可以在每次调用时动态传入。\n- `context_defaults` 确保每个 `.forward()` 调用都会进入带有模块 LM 的正确 `dspy.context()`。\n\n---\n\n## ⚙️ 配置与存储\n\nROMA-DSPy 使用 **OmegaConf** 进行分层配置，并结合 **Pydantic** 进行验证；同时提供 **执行范围内的存储**，以实现完全的任务隔离。\n\n### 快速配置示例\n\n```python\nfrom roma_dspy.config import load_config\n\n# 加载特定配置文件并覆盖默认值\nconfig = load_config(\n    profile=\"crypto_agent\",\n    overrides=[\"agents.executor.llm.temperature=0.3\"]\n)\n```\n\n**可用配置文件：** `general`、`crypto_agent`（可通过 `just list-profiles` 查看列表）\n\n**更多信息：** [配置指南](docs\u002FCONFIGURATION.md) 提供关于配置文件、代理配置、LLM 设置、工具包配置以及任务感知代理映射的完整说明。\n\n### 存储\n\n存储是自动且按执行范围管理的——每个任务都会获得一个独立的目录。较大的工具包响应（超过 100KB）会自动保存为 Parquet 文件。\n\n```python\nfrom roma_dspy.core.engine.solve import solve\n\n# 存储路径自动生成：{base_path}\u002Fexecutions\u002F{execution_id}\u002F\nresult = solve(\"分析区块链交易\")\n```\n\n**特点：** 执行隔离、兼容 S3、自动 Parquet 存储、Docker 管理\n\n**更多信息：** [部署指南](docs\u002FDEPLOYMENT.md) 提供生产环境存储配置，包括 S3 集成。\n\n## 🧰 工具包\n\nROMA-DSPy 包含 9 个内置工具包，用于扩展智能体的能力：\n\n**核心工具包**: FileToolkit、CalculatorToolkit、E2BToolkit（代码执行）\n**加密货币工具包**: CoinGeckoToolkit、BinanceToolkit、DefiLlamaToolkit、ArkhamToolkit\n**搜索工具包**: SerperToolkit（网页搜索）\n**通用工具包**: MCPToolkit（连接任意 [MCP 服务器](https:\u002F\u002Fgithub.com\u002Fwong2\u002Fawesome-mcp-servers)）\n\n### 快速配置\n\n```yaml\nagents:\n  executor:\n    toolkits:\n      - class_name: \"FileToolkit\"\n        enabled: true\n      - class_name: \"E2BToolkit\"\n        enabled: true\n        toolkit_config:\n          timeout: 600\n```\n\n**参阅**: [工具包参考文档](docs\u002FTOOLKITS.md)，其中包含所有工具的完整说明、配置选项、MCP 集成以及自定义工具包开发指南。\n\n---\n\n## 🌐 REST API 和 CLI\n\nROMA-DSPy 同时提供了 REST API 和命令行界面，适用于生产环境使用。\n\n### REST API\n\n基于 FastAPI 的服务器，附带交互式文档：\n\n```bash\n# 使用 Docker 自动启动\njust docker-up\n\n# API 文档：http:\u002F\u002Flocalhost:8000\u002Fdocs\n# 健康检查：http:\u002F\u002Flocalhost:8000\u002Fhealth\n```\n\n**端点**: 执行管理、检查点、可视化、指标\n\n### CLI\n\n```bash\n# 本地任务执行\nroma-dspy solve \"您的任务\" --profile general\n\n# 服务器管理\nroma-dspy server start\nroma-dspy server health\n\n# 执行管理\nroma-dspy exec create \"任务\"\nroma-dspy exec status \u003Cid> --watch\n\n# 交互式 TUI 可视化（建议配合 MLflow 使用以获得最佳效果）\njust viz \u003Cexecution_id>\n\n# 完整帮助信息\nroma-dspy --help\n```\n\n**参阅**: `\u002Fdocs` 端点中的 API 文档，获取完整的 OpenAPI 规范和交互式测试功能。\n\n---\n\n## 🏗️ 核心构建模块：`BaseModule`\n所有模块均继承自位于 `roma_dspy\u002Fcore\u002Fmodules\u002Fbase_module.py` 的 `BaseModule`。它实现了以下标准化：\n- 通过 DSPy 预测策略进行签名绑定；\n- 大模型实例化与上下文管理；\n- 工具规范化与合并；\n- 支持同步\u002F异步调用，并具备安全的关键字过滤机制。\n\n### 上下文与大模型管理\n实例化模块时，您可以提供一个已有的 `dspy.LM`，也可以让模块根据提供商字符串（`model`）及可选关键字参数（`model_config`）自动构建一个。\n\n```python\nfrom roma_dspy import Executor\n\nexecutor = Executor(\n    model=\"openrouter\u002Fopenai\u002Fgpt-4o-mini\",\n    model_config={\"temperature\": 0.5, \"cache\": True},\n)\n```\n\n在内部，`BaseModule` 确保每次调用 `.forward()` 时，都会将预测器的调用包裹在以下上下文中：\n\n```python\nwith dspy.context(lm=self._lm, **context_defaults):\n    ...\n```\n\n您可以通过 `get_model_config()` 检查实际的大模型配置，确认提供商、缓存设置或经过清理的关键字参数。\n\n### 工具的使用\n工具可以以列表、元组或映射的形式提供，这些工具应为 DSPy 的 ReAct\u002FCodeAct 策略所接受的可调用对象。\n\n```python\nexecutor = Executor(tools=[get_weather])\nexecutor.forward(\"安曼的天气如何？\", tools=[another_function])\n```\n\n`BaseModule` 会自动根据对象身份去重工具，并将构造函数默认值与每次调用的覆盖值合并。\n\n### 预测策略\nROMA 通过 `PredictionStrategy` 枚举（位于 `roma_dspy\u002Ftypes\u002Fprediction_strategy.py`）暴露了 DSPy 的策略。您可以直接使用枚举，也可以使用不区分大小写的字符串别名：\n\n```python\nfrom roma_dspy.types import PredictionStrategy\n\nplanner = Planner(prediction_strategy=PredictionStrategy.CHAIN_OF_THOUGHT)\nexecutor = Executor(prediction_strategy=\"react\")\n```\n\n可用的策略包括 `Predict`、`ChainOfThought`、`ReAct`、`CodeAct`、`BestOfN`、`Refine`、`Parallel`、`majority` 等。对于需要工具的策略（如 `ReAct` 或 `CodeAct`），模块会自动应用您传递的工具。\n\n### 异步执行\n每个模块都提供 `aforward()` 方法。当底层 DSPy 预测器支持异步操作（`acall`\u002F`aforward`）时，ROMA 会以异步方式调度；否则，它会优雅地回退到同步实现，同时保持可等待性。\n\n```python\nresult = await executor.aforward(\"下载最新的销售报告\")\n```\n\n## 📚 模块参考\n\n### ⚛️ 分解器\n**位置**: `roma_dspy\u002Fcore\u002Fmodules\u002Fatomizer.py`\n\n**用途**: 判断目标是否为原子级，还是需要规划。\n\n**构造函数**:\n```python\nAtomizer(\n    prediction_strategy: Union[PredictionStrategy, str] = \"ChainOfThought\",\n    *,\n    lm: Optional[dspy.LM] = None,\n    model: Optional[str] = None,\n    model_config: Optional[Mapping[str, Any]] = None,\n    tools: Optional[Sequence|Mapping] = None,\n    **strategy_kwargs,\n)\n```\n\n**输入** (`AtomizerSignature`):\n- `goal: str`\n\n**输出** (`AtomizerResponse`):\n- `is_atomic: bool` — 任务是否可以直接执行。\n- `node_type: NodeType` — 用于下游路由的提示，取值为 `PLAN` 或 `EXECUTE`。\n\n**使用示例**:\n```python\natomized = atomizer.forward(\"策划一份包含餐厅预订的东京五日行程\")\nif atomized.is_atomic:\n    ...  # 直接发送给执行器\nelse:\n    ...  # 转交给规划器\n```\n\n分解器与具体策略无关，但通常会使用 `ChainOfThought` 或 `Predict` 策略。您可以通过 `call_params` 传递提示信息（例如 `max_tokens`）：\n\n```python\natomizer.forward(\n    \"总结这份 PDF 文件\",\n    call_params={\"max_tokens\": 200},\n)\n```\n\n### 📋 规划器\n**位置**: `roma_dspy\u002Fcore\u002Fmodules\u002Fplanner.py`\n\n**用途**: 将目标分解为有序的子任务，并可选生成依赖关系图。\n\n**构造函数**: 与分解器相同。\n\n**输入** (`PlannerSignature`):\n- `goal: str`\n\n**输出** (`PlannerResult`):\n- `subtasks: List[SubTask]` — 每个子任务包含目标、任务类型和依赖关系。\n- `dependencies_graph: Optional[Dict[str, List[str]]]` — 当大模型返回时提供的显式邻接矩阵。\n\n**使用示例**:\n```python\nplan = planner.forward(\"在六周内举办一场 B2B 网络研讨会\")\nfor subtask in plan.subtasks:\n    print(subtask.goal, subtask.task_type)\n```\n\n`SubTask.task_type` 是一个遵循 ROMA MECE 框架的枚举类型（检索、写作、思考、代码解释、图像生成）。\n\n### ⚙️ 执行器\n**位置**: `roma_dspy\u002Fcore\u002Fmodules\u002Fexecutor.py`\n\n**用途**: 解决原子级目标，可选地通过 DSPy 的 ReAct、CodeAct 策略调用工具或函数。\n\n**构造函数**: 与前面一致；常用的策略是 `ReAct`、`CodeAct` 或 `ChainOfThought`。\n\n**输入** (`ExecutorSignature`):\n- `goal: str`\n\n**输出** (`ExecutorResult`):\n- `output: str | Any`\n- `sources: Optional[List[str]]` — 来源或引用。\n\n**使用示例**:\n```python\nexecution = executor.forward(\n    \"整理一份为期三天的滑雪旅行行李清单\",\n    config={\"temperature\": 0.4},  # 每次调用时对大模型的覆盖\n)\nprint(execution.output)\n```\n\n若仅希望在特定调用中启用工具：\n\n```python\nexecution = executor.forward(\n    \"巴黎的天气如何？\",\n    tools=[get_weather],\n)\n```\n\n### 🔀 聚合器\n**位置**: `roma_dspy\u002Fcore\u002Fmodules\u002Faggregator.py`\n\n**目的**: 将多个子任务的结果合并为最终的叙述或决策。\n\n**构造函数**: 模式相同。\n\n**输入**（`AggregatorResult` 签名）：\n- `original_goal: str`\n- `subtasks_results: List[SubTask]` — 通常是规划器的提案，并附加了执行结果。\n\n**输出**（`AggregatorResult` 基类模型）：\n- `synthesized_result: str`\n\n**使用方法**：\n```python\naggregated = aggregator.forward(\n    original_goal=\"计划数据迁移\",\n    subtasks_results=[\n        SubTask(goal=\"盘点当前数据库\", task_type=TaskType.RETRIEVE),\n        SubTask(goal=\"起草迁移时间表\", task_type=TaskType.WRITE),\n    ],\n)\nprint(aggregated.synthesized_result)\n```\n\n由于它继承自 `BaseModule`，如果您的聚合策略需要外部调用，仍然可以附加工具（例如知识库检索函数）。\n\n### ✅ 验证器\n**位置**: `roma_dspy\u002Fcore\u002Fmodules\u002Fverifier.py`\n\n**目的**: 验证合成输出是否满足原始目标。\n\n**输入**（`VerifierSignature`）：\n- `goal: str`\n- `candidate_output: str`\n\n**输出**：\n- `verdict: bool`\n- `feedback: Optional[str]`\n\n**使用方法**：\n```python\nverdict = verifier.forward(\n    goal=\"起草符合 GDPR 的隐私政策\",\n    candidate_output=aggregated.synthesized_result,\n)\nif not verdict.verdict:\n    print(\"需要修订:\", verdict.feedback)\n```\n\n## 🎯 高级模式\n\n### 运行时替换模型\n使用 `replace_lm()` 可以在同一个模块中使用不同的语言模型（适用于 A\u002FB 测试或备用方案）。\n\n```python\nfast_executor = executor.replace_lm(dspy.LM(\"openrouter\u002Fanthropic\u002Fclaude-3-haiku\"))\n```\n\n### 每次调用的覆盖\n您可以在不重新构建模块的情况下，改变语言模型的行为或提供额外参数。\n\n```python\nexecutor.forward(\n    \"总结会议记录\",\n    config={\"temperature\": 0.1, \"max_tokens\": 300},\n    context={\"stop\": [\"Observation:\"]},\n)\n```\n\n`call_params`（或关键字参数）会被过滤，以匹配 DSPy 预测器接受的参数，从而防止意外错误。\n\n### 仅工具执行\n如果您希望实现确定性的工具路由，可以设置一个虚拟语言模型（或极低温模型），并传入纯 Python 可调用对象。\n\n```python\nfrom roma_dspy import Executor\n\nexecutor = Executor(\n    prediction_strategy=\"code_act\",\n    lm=dspy.LM(\"openrouter\u002Fopenai\u002Fgpt-4o-mini\", temperature=0.0),\n    tools={\"get_weather\": get_weather, \"lookup_user\": lookup_user},\n)\n```\n\nROMA 将确保构造函数和每次调用中提供的工具都可供策略使用。\n\n## 🧪 测试\n\n```bash\n# 运行所有测试\njust test\n\n# 运行特定测试\npytest tests\u002Funit\u002F -v\npytest tests\u002Fintegration\u002F -v\n```\n\n**参阅**: `justfile` 中包含所有可用的测试命令。\n\n## 💡 故障排除与提示\n- **`ValueError: Either provide an existing lm`** — 在构造模块时，请提供 `lm=` 或 `model=`。\n- **`Invalid prediction strategy`** — 检查拼写；字符串不区分大小写，但必须匹配已知别名。\n- **缓存** — 在您的语言模型上启用 `cache=True`，或在 `model_config` 中设置，以重用之前的完成内容。\n- **异步上下文** — 在混合同步和异步调用时，确保事件循环正在运行（例如使用 `asyncio.run`）。\n- **工具重复** — 工具会按身份去重；如果您需要变体，请创建不同的函数。\n\n## 📖 术语表\n\n### 核心概念\n- **DSPy**: 斯坦福大学的声明式框架，用于提示、规划和工具集成。\n- **预测策略**: 驱动推理的 DSPy 类或函数（CoT、ReAct 等）。\n- **子任务**: 描述分解后工作单元的 Pydantic 模型（`goal`、`task_type`、`dependencies`）。\n- **节点类型**: Atomizer 选择的是 `PLAN` 还是 `EXECUTE`。\n- **任务类型**: 子任务的 MECE 分类（`RETRIEVE`、`WRITE`、`THINK`、`CODE_INTERPRET`、`IMAGE_GENERATION`）。\n- **上下文默认值**: 每次调用时传递给 `dspy.context(...)` 的关键字参数。\n\n### 配置与存储\n- **FileStorage**: 执行范围内的存储管理器，为每次任务执行提供隔离的目录。\n- **DataStorage**: 自动 Parquet 存储系统，用于大型工具包响应（基于阈值）。\n- **执行 ID**: 每次任务执行的唯一标识符，用于存储隔离。\n- **基础路径**: 所有存储操作的根目录（本地路径或 S3 存储桶）。\n- **配置文件**: 命名的配置预设（例如 `general`、`crypto_agent`）。\n- **配置覆盖**: 运行时值，会覆盖配置文件或默认设置。\n\n### 工具包\n- **BaseToolkit**: 提供存储集成和工具注册的所有工具包的抽象基类。\n- **REQUIRES_FILE_STORAGE**: 元数据标志，表示工具包需要 FileStorage（例如 FileToolkit）。\n- **工具包配置**: 工具包特有的设置，如 API 密钥、超时时间和阈值。\n- **工具选择**: 包含\u002F排除列表，用于筛选工具包中可用的工具。\n- **存储阈值**: 大小限制（KB），超过该限制的响应将以 Parquet 格式存储。\n\n### 架构\n- **执行范围隔离**: 每次执行都会获得唯一的存储目录的模式。\n- **Parquet 集成**: 自动列式存储，用于大型结构化数据。\n- **S3 兼容性**: 可通过 Docker 卷挂载使用兼容 S3 的存储。\n- **工具注册**: 自动发现并注册工具包方法为可调用工具。\n\n---\n\n祝您构建愉快！如果您扩展或自定义模块，请保持签名一致，以便您的高层编排保持稳定。\n\n**附加资源：**\n- [快速入门指南](docs\u002FQUICKSTART.md) - 10 分钟内上手\n- [配置指南](docs\u002FCONFIGURATION.md) - 完整配置参考\n- [工具包参考](docs\u002FTOOLKITS.md) - 所有内置和自定义工具包\n- [部署指南](docs\u002FDEPLOYMENT.md) - 使用 Docker 进行生产部署\n- [E2B 设置](docs\u002FE2B_SETUP.md) - 代码执行工具包设置\n- [可观测性](docs\u002FOBSERVABILITY.md) - MLflow 跟踪与监控\n- [配置系统](config\u002FREADME.md) - 配置文件及示例\n\n\n## 📊 基准测试\n\n我们使用 ROMA 实现的一个简单搜索系统——ROMA-Search，在三个基准测试中进行了评估：**SEAL-0**、**FRAMES** 和 **SimpleQA**。以下是每个基准测试的性能图表。\n\n### [SEAL-0](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fvtllms\u002Fsealqa)\nSealQA 是一个新的具有挑战性的基准测试，用于评估搜索增强型语言模型在事实查询方面的能力，尤其是在网络搜索产生冲突、噪声或无帮助结果的情况下。\n\n![SEAL-0 结果](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_c6afd19b351b.jpeg)\n\n---\n\n### [FRAMES](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002Fgoogle\u002Fframes-benchmark)\n\u003Cdetails>\n\u003Csummary>查看完整结果\u003C\u002Fsummary>\n\n这是一个全面的评估数据集，旨在测试检索增强生成（RAG）系统在事实准确性、检索精度和推理能力方面的表现。\n\n![FRAMES 结果](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_315e34f6d15e.jpeg)\n\n\u003C\u002Fdetails>\n\n---\n\n### [SimpleQA](https:\u002F\u002Fopenai.com\u002Findex\u002Fintroducing-simpleqa\u002F)\n\u003Cdetails>\n\u003Csummary>查看完整结果\u003C\u002Fsummary>\n\n一个事实性基准测试，用于衡量语言模型回答简短、以获取事实为目的的问题的能力。  \n\n![SimpleQA 结果](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_906b35f01ccb.jpeg)\n\n\u003C\u002Fdetails>\n\n## 🧩 基础与渊源\n\n尽管 ROMA 引入了一个实用的开源分层任务执行框架，但它直接建立在两项基础性研究贡献之上，这些贡献首次发表于 [WriteHERE](https:\u002F\u002Farxiv.org\u002Fabs\u002F2503.08275)：\n\n- **异构递归规划** — ROMA 的整体架构遵循先前关于 *异构递归规划* 的工作所提出的框架，在该框架中，复杂任务会被递归地分解为子任务图，每个子任务都被赋予一种独特的认知类型。\n\n- **分解中的类型指定** — ROMA 的“三大通用操作”（THINK 🤔、WRITE ✍️、SEARCH 🔍）推广了 *分解中的类型指定* 假说，该假说指出推理、创作和检索是三种基本的认知类型。\n\n这些贡献在 WriteHERE 仓库和论文中得到了详细描述。通过明确采纳并扩展这一基础，ROMA 提供了一个 **可泛化的框架、智能体系统、多功能性和可扩展性**，它基于这些洞见，并使其能够被跨领域的开发者所使用。\n\n## 🙏 致谢\n\n如果没有这些出色的开源贡献，这个框架将无法实现！\n- 受 Xiong 等人发表的《超越提纲：异构递归规划》([https:\u002F\u002Farxiv.org\u002Fabs\u002F2503.08275](https:\u002F\u002Farxiv.org\u002Fabs\u002F2503.08275)) 中描述的分层规划方法启发。\n- [Pydantic](https:\u002F\u002Fgithub.com\u002Fpydantic\u002Fpydantic) - 使用 Python 类型注解进行数据验证\n- [DSPy]([https:\u002F\u002Fdspy.ai\u002F)) - 用于编程 AI 智能体的框架\n- [E2B](https:\u002F\u002Fgithub.com\u002Fe2b-dev\u002Fe2b) - 用于 AI 智能体的云端运行时\n\n## 📚 引用\n\n如果您在研究中使用了 ROMA 仓库，请引用以下内容：\n\n```bibtex\n@misc{alzubi2026romarecursiveopenmetaagent,\n      title={ROMA: 面向长周期多智能体系统的递归式开放元智能体框架}, \n      author={Salaheddin Alzu'bi、Baran Nama、Arda Kaz、Anushri Eswaran、Weiyuan Chen、Sarvesh Khetan、Rishab Bala、Tu Vu、Sewoong Oh},\n      year={2026},\n      eprint={2602.01848},\n      archivePrefix={arXiv},\n      primaryClass={cs.AI},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2602.01848}, \n}\n```\n\n## 🌟 星标历史\n\n\u003Cdiv align=\"center\">\n\n[![星标历史图表](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_readme_01ba43d47d6d.png)](https:\u002F\u002Fwww.star-history.com\u002F#sentient-agi\u002Froma&Date)\n\n\u003C\u002Fdiv>\n\n## 📄 许可证\n\n本项目采用 Apache 2.0 许可证授权 — 详情请参阅 [LICENSE](LICENSE) 文件。","# ROMA 快速上手指南\n\nROMA (Recursive Open Meta-Agents) 是一个用于构建分层高性能多智能体系统的元智能体框架。它通过递归的“规划 - 执行”循环，将复杂任务分解为可并行处理的子任务，适合解决复杂的推理挑战。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**: Linux, macOS 或 Windows (推荐 WSL2)\n*   **Python 版本**: Python 3.10 或更高版本\n*   **包管理工具**: 推荐使用 `uv` (安装速度比 pip 快 10-100 倍)，也可使用标准 `pip`\n*   **API Key**: 需要大模型服务商的 API Key。\n    *   默认配置使用 **OpenRouter** (支持 Claude, Gemini 等模型)。\n    *   也可直接配置 **OpenAI**, **Anthropic** 等其他提供商。\n\n## 安装步骤\n\n### 方式一：最小化安装（推荐用于快速评估）\n\n无需 Docker 或数据库，仅需几十秒即可完成安装并运行。\n\n1.  **安装 ROMA 核心库**\n\n    使用 `uv` (推荐):\n    ```bash\n    uv pip install roma-dspy\n    ```\n\n    或使用 `pip`:\n    ```bash\n    pip install roma-dspy\n    ```\n\n2.  **配置 API Key**\n\n    设置环境变量以启用模型调用。以下以 OpenRouter 为例：\n    ```bash\n    export OPENROUTER_API_KEY=\"sk-or-v1-...\"\n    ```\n    > **提示**: 如果您使用 OpenAI，可设置 `OPENAI_API_KEY` 并在后续配置中指定模型。\n\n### 方式二：生产环境安装（完整功能）\n\n如果您需要数据持久化、可观测性监控及 REST API 服务，请使用 Docker 部署。\n\n1.  **一键启动服务**\n    ```bash\n    just setup\n    ```\n    *或者指定特定配置文件:*\n    ```bash\n    just setup crypto_agent\n    ```\n\n2.  **验证服务状态**\n    ```bash\n    curl http:\u002F\u002Flocalhost:8000\u002Fhealth\n    ```\n\n    *此模式将自动启动 PostgreSQL (持久化), MLflow (监控), MinIO (存储) 及 FastAPI 服务。*\n\n## 基本使用\n\n安装完成后，您可以立即开始解决任务。\n\n### 1. 代码方式调用 (最简示例)\n\n直接在命令行运行一行代码即可测试框架能力：\n\n```bash\npython -c \"from roma_dspy.core.engine.solve import solve; print(solve('What is 2+2?'))\"\n```\n\n或在 Python 脚本中使用：\n\n```python\nfrom roma_dspy.core.engine.solve import solve\n\n# 定义任务\ntask = \"Calculate the total cost of 3 apples at $1.5 each and 2 bananas at $0.8 each.\"\n\n# 执行求解\nresult = solve(task)\nprint(result)\n```\n\n### 2. CLI 方式调用 (仅限 Docker 部署模式)\n\n如果您使用了 Docker 完整部署，可以通过 CLI 工具提交任务：\n\n```bash\njust solve \"What is the capital of France?\"\n```\n\n### 3. 访问 REST API (仅限 Docker 部署模式)\n\n启动后，可访问交互式 API 文档进行调试和调用：\n*   **地址**: http:\u002F\u002Flocalhost:8000\u002Fdocs\n\n---\n\n**核心工作流程说明：**\nROMA 会自动判断任务是否需要拆解：\n1.  **Atomizer**: 判断任务是原子的（直接执行）还是需要规划。\n2.  **Planner**: 若需规划，将任务拆分为子任务并递归处理。\n3.  **Executor**: 执行原子任务（调用 LLM、API 或代码）。\n4.  **Aggregator**: 汇总子任务结果，生成最终答案。","某金融科技团队需要构建一个能实时监测全球新闻、分析市场情绪并自动生成交易策略报告的复杂系统。\n\n### 没有 ROMA 时\n- **架构搭建困难**：开发人员需手动编写大量样板代码来协调多个单一功能 Agent，层级关系混乱，难以维护。\n- **任务执行断裂**：当遇到需要多步推理的复杂任务（如“关联地缘政治事件与特定板块波动”）时，单个 Agent 容易迷失上下文，导致分析中断或逻辑跳跃。\n- **扩展性差**：每增加一个新的分析维度（如新增加密货币监控），都需要重构整个通信协议，迭代周期长达数周。\n- **资源调度低效**：无法动态分配计算资源，简单查询与深度研报消耗相同的算力，造成成本浪费。\n\n### 使用 ROMA 后\n- **层级化自动构建**：利用 ROMA 的元代理框架，团队只需定义高层目标，系统即可自动递归生成 hierarchical（分层）的多 Agent 架构，将开发时间从数周缩短至几天。\n- **递归推理增强**：面对复杂分析，ROMA 协调下的子 Agent 能自主进行多轮递归思考与自我修正，确保从新闻抓取到策略生成的全链路逻辑严密。\n- **灵活动态扩展**：新增监控维度仅需插入新的子节点 Agent，ROMA 会自动处理路由与协作，无需改动核心架构，实现热插拔式升级。\n- **高性能资源编排**：框架根据任务难度动态调度不同层级的 Agent，简单任务由轻量级节点处理，复杂研判才调用高级模型，显著降低运行成本。\n\nROMA 通过递归元代理机制，将原本碎片化的单点智能整合为具备自我演进能力的高性能协同网络，让构建复杂多智能体系统变得像搭积木一样简单高效。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsentient-agi_ROMA_c6afd19b.jpg","sentient-agi","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fsentient-agi_5e672b47.png","",null,"https:\u002F\u002Fgithub.com\u002Fsentient-agi",[79,83,87,91,95,98,101],{"name":80,"color":81,"percentage":82},"Python","#3572A5",91.8,{"name":84,"color":85,"percentage":86},"Jupyter Notebook","#DA5B0B",5.3,{"name":88,"color":89,"percentage":90},"Shell","#89e051",2.3,{"name":92,"color":93,"percentage":94},"Just","#384d54",0.3,{"name":96,"color":97,"percentage":94},"Jinja","#a52a22",{"name":99,"color":93,"percentage":100},"Dockerfile",0.1,{"name":102,"color":103,"percentage":104},"Mako","#7e858d",0,5025,768,"2026-04-20T00:23:30","未说明",{"notes":110,"python":108,"dependencies":111},"该工具是一个基于 DSPy 的多智能体框架。提供两种安装模式：1. 最小化安装（推荐评估）：仅需通过 pip 或 uv 安装 'roma-dspy' 包，无需 Docker 或数据库，默认使用 OpenRouter API 调用云端模型（如 Claude Sonnet 4.5, Gemini 2.5 Flash）。2. 生产环境安装：需使用 Docker 部署完整功能栈，包含 PostgreSQL（持久化）、MLflow（可观测性）、MinIO（存储）及 E2B（代码执行沙箱）。本地运行主要依赖网络连接和 API Key，对本地 GPU 无强制要求（除非自行配置本地模型）。",[112,113],"roma-dspy","DSPy",[13],"2026-03-27T02:49:30.150509","2026-04-20T19:32:32.717316",[118,123,128,133,138,143],{"id":119,"question_zh":120,"answer_zh":121,"source_url":122},45605,"如何配置兼容 OpenAI 接口的自定义模型（如 SiliconFlow、ModelScope 或本地 vLLM）？","需要修改代码中的参数支持列表并调整配置文件。具体步骤如下：\n1. 修改 `AgentFactory.create_model_instance`，在支持的 LLM 参数列表中添加 \"base_url\"：\n   supported_llm_params = [\"api_key\", \"api_base\", \"base_url\", ...]\n2. 修改 `agents.yaml` 配置文件，将 provider 设置为 \"litellm\"（注意：Litellm 使用 base_url 参数，而 OpenAI provider 使用 api_base）：\n   model:\n     provider: \"litellm\"\n     model_id: \"openai\u002Fdeepseek-ai\u002FDeepSeek-V3\" (格式通常为 openai\u002F组织\u002F模型名)\n     temperature: 0.3\n     base_url: \"https:\u002F\u002Fapi-inference.modelscope.cn\u002Fv1\u002F\"\n     api_key: \"ms-xxxx\"\n注意：如果使用 vLLM 本地部署，model_id 可能需要写成 `openai\u002Fopenai\u002Fqwen3` 这种格式，第一层前缀会被 litellm 移除。","https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002FROMA\u002Fissues\u002F27",{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},45606,"运行项目时遇到缺少 EXA_API_KEY 或其他外部依赖报错怎么办？","许多外部 API 密钥实际上是可选的。你可以检查 `.env` 文件，确认哪些是必须项，哪些是可选项。例如，Exa API 密钥用于网络搜索功能，是可选的（OPTIONAL）。如果不需要特定功能，可以注释掉相关配置或使用占位符。一个典型的 `.env` 配置示例如下：\n# OpenAI API settings (指向你的 Ollama 服务器)\nOPENAI_API_KEY=dummy-key\nOPENAI_API_BASE=http:\u002F\u002F192.168.3.122:11434\u002Fv1\nOPENAI_DEFAULT_MODEL=hf.co\u002Funsloth\u002Fgranite-4.0-h-micro-GGUF:granite-4.0-h-micro-Q6_K.gguf\n# Exa API key (可选)\n# EXA_API_KEY=your_exa_key_here\n确保只填写你实际使用的服务密钥，未使用的服务保持注释状态即可。","https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002FROMA\u002Fissues\u002F66",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},45607,"使用 Qwen 等模型时出现“无限循环（INFINITE LOOP）”或任务卡在 'think' 节点如何处理？","这个问题在某些模型上偶发，通常表现为日志中重复出现 \"AGGREGATION BLOCKED\" 和 \"No nodes in READY\"。解决方案包括：\n1. 更新代码：维护者已在 master 分支更新了 roma dspy 实现，请拉取最新代码重新运行。\n2. 配置超时：可以通过允许用户配置“无限循环”执行的持续时间来部分解决此问题（参考相关 PR #61）。\n如果问题依然存在，尝试更换模型或检查后端日志中是否有特定的子图（sub_graph）卡死情况。","https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002FROMA\u002Fissues\u002F39",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},45608,"启动时提示 \"No planner available for node root\" 错误如何解决？","该错误通常发生在克隆仓库后直接运行时。维护者已修复了此问题。如果你遇到此错误，请确保拉取了最新的代码提交。有用户反馈在特定 commit (ba7b8b0e233064500b6954480ba13484a3e816ec) 上出现过此问题，但在修复后的版本中已正常。请尝试执行 `git pull` 更新到 master 分支最新版本后再通过 Docker 或本地开发环境重试。","https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002FROMA\u002Fissues\u002F19",{"id":139,"question_zh":140,"answer_zh":141,"source_url":142},45609,"发布说明（Release Notes）中存在拼写错误吗？","是的，用户已报告并在社区中得到确认。在 ROMA (v0.1-beta) 的发布说明中存在以下拼写错误：\n1. \"Recusrive Open Meta Agent\" 应修正为 \"Recursive Open Meta Agent\"。\n2. \"Node timouts\" 应修正为 \"Node timeouts\"。\n这些错误已在后续沟通中被记录，管理员会进行修正。","https:\u002F\u002Fgithub.com\u002Fsentient-agi\u002FROMA\u002Fissues\u002F47",{"id":144,"question_zh":145,"answer_zh":146,"source_url":122},45610,"如何正确设置前端和后端以启动 ROMA 项目？","启动项目分为后端和前端两部分：\n1. 启动后端：激活虚拟环境并运行主模块。\n   source .venv\u002Fbin\u002Factivate\n   python -m sentientresearchagent\n2. 启动前端：进入 frontend 目录并运行开发服务器。\n   cd frontend && npm run dev\n3. 访问应用：在浏览器中打开 http:\u002F\u002Flocalhost:3001\u002F (或配置的 IP 地址)。\n确保在启动前已在 `.env` 文件中正确配置了必要的 API 密钥（如 OPENAI_API_KEY 等）。",[148,153],{"id":149,"version":150,"summary_zh":151,"released_at":152},360481,"v0.2.0-beta","# ROMA v0.2.0 发行说明\n\n## 🎉 重大发布：框架全面重写\n\n我们很高兴地宣布 **ROMA v0.2.0**，这是一个基于 [DSPy](https:\u002F\u002Fgithub.com\u002Fstanfordnlp\u002Fdspy) 的全新框架重写版本。此次发布将 ROMA 转变为一个生产就绪的分层多智能体框架，并带来了强大的新功能。\n\n---\n\n## ⚠️ 破坏性变更\n\n**这是一次重大的架构重构。** 为 v1.0.0 编写的代码与 v0.2.0 **不兼容**。\n\n### 变更内容：\n- 完全迁移到基于 DSPy 的模块系统\n- 使用 OmegaConf 的新配置系统\n- 重构了 API 和模块接口\n- 更新了存储和执行模型\n\n### 迁移指南：\n如果您正在从 v1.0.0 升级：\n\n1. **查看新的模块系统**：所有智能体现在都继承自 `BaseModule`\n2. **更新配置**：切换到基于 YAML 的配置文件（参见 `config\u002Fprofiles\u002F`）\n3. **更新导入路径**：核心模块已移动至 `roma_dspy.core.modules`\n4. **检查工具包使用**：新的工具包系统包含 9 个内置工具包\n5. **API 变更**：如果以编程方式使用，请查看新的函数签名\n\n请参阅更新后的 [README](README.md) 和 [快速入门指南](docs\u002FQUICKSTART.md)，以获取示例。\n\n---\n\n## 🚀 新特性\n\n### 🏗️ 基于 DSPy 的架构\n\n使用斯坦福大学的 DSPy 框架进行完全重写：\n- **BaseModule**：所有智能体模块的统一基类\n- **灵活的预测策略**：CoT、ReAct、CodeAct、BestOfN 等\n- **语言模型抽象层**：轻松实现模型切换和运行时配置\n- **异步优先**：原生支持异步执行，并提供优雅的回退机制\n\n### 🐳 生产就绪的部署\n\n只需一条命令即可完成 Docker 部署，涵盖完整的生产环境栈：\n\n```bash\njust setup  # 交互式设置，启动所有服务\n```\n\n**包含的服务：**\n- 🚀 **FastAPI REST API**，附带 OpenAPI 文档\n- 🗄️ **PostgreSQL** 数据库，用于持久化存储\n- 📦 **MinIO** 兼容 S3 的对象存储\n- 📊 **MLflow**，用于实验跟踪和可观测性\n\n### 🧰 9 个内置工具包\n\n强大的工具包系统扩展了智能体的能力：\n\n**核心工具包：**\n- **FileToolkit**：文件系统操作\n- **CalculatorToolkit**：数学计算\n- **E2BToolkit**：在沙箱环境中安全执行代码\n\n**加密工具包：**\n- **CoinGeckoToolkit**：加密货币数据与价格信息\n- **BinanceToolkit**：交易所数据与交易信息\n- **DefiLlamaToolkit**：DeFi 协议分析\n- **ArkhamToolkit**：区块链情报\n\n**搜索工具包：**\n- **SerperToolkit**：网页搜索能力\n\n**通用工具包：**\n- **MCPToolkit**：连接任何 [Model Context Protocol](https:\u002F\u002Fgithub.com\u002Fwong2\u002Fawesome-mcp-servers) 服务器\n\n### ⚙️ 高级配置系统\n\n基于 YAML 的灵活配置，支持多配置文件：\n\n```yaml\n# config\u002Fprofiles\u002Fcrypto_agent.yaml\nagents:\n  executor:\n    llm:\n      model: \"openrouter\u002Fanthropic\u002Fclaude-3.5-sonnet\"\n      temperature: 0.7\n    toolkits:\n      - class_name: \"CoinGeckoToolkit\"\n        en","2025-10-22T00:43:44",{"id":154,"version":65,"summary_zh":155,"released_at":156},360482,"# v0.1.0-beta\n\n## 变更内容\n* Recursive Open Meta Agent 初次测试版发布\n* 核心自主研究代理功能\n* 实现了3个自定义代理\n* 自定义工具集成系统\n* E2B 代码执行 + 文件读写系统\n* 项目上下文管理\n* 全面的日志记录系统\n\n\n## 配置\n1. 将 `.env.example` 复制为 `.env`\n2. 添加您的 API 密钥\n3. 在 `custom_tools.json` 中配置自定义工具（可选）\n\n## 已知问题\n* 节点不稳定 - 由于 API 调用失败或结构化输出失败，可能会出现破坏性变更\n* 各 API 的速率限制\n* 节点超时\n\n## 完整更新日志\n* 初始发布\n\n**注意：** 本版本为测试版，不建议用于生产环境。","2025-09-04T07:49:07"]