Set up Cloud Agent dev environment (AGENTS.md)

[hutaobo]

Summary

Sets up the Cloud Agent development environment for spatho (Agentic Spatial Pathologist) and documents the durable, non-obvious startup context in AGENTS.md. No application code was changed.

Environment setup

• Installs the package + dev deps into the system Python (PEP 668, --break-system-packages): python3 -m pip install -e .[dev].
• Force-pins histoseg==0.1.9.2. The latest published histoseg (0.1.9.3) removed the top-level Pattern1IsolineConfig export and renamed histoseg.contours -> histoseg.contour, which breaks the legacy Gradio app main.py. pyproject.toml only requires histoseg>=0.1.9.2, so a plain install otherwise resolves to the broken 0.1.9.3. 0.1.9.2 is compatible with both the spatho test suite and the Gradio app.

The above two commands are captured in the environment update script.

Verification

Surface	Command	Result
Tests	python3 -m pytest	83 passed
Build	python3 -m build	sdist + wheel built
CLI	spatho list-organ-packs / config-schema / init-workflow / doctor	produced schema + workflow JSON, doctor validated
Gradio app	python3 main.py (port 7860)	full end-to-end run: upload -> dendrogram -> select structures -> contour analysis

The Gradio app was driven end-to-end in a browser: uploaded synthetic cells.parquet + clusters.csv, built a cophenetic dendrogram (6 clusters -> 4 candidate structures), selected structures, and ran the multi-structure contour analysis (finished successfully, exported Xenium Explorer GeoJSON/CSV + contour preview).

Dendrogram, candidate structures, and cophenetic heatmap
Final contour preview with finished-successfully status and run summary
spatho_gradio_end_to_end_demo.mp4

Note

python3 -m twine check dist/* currently fails on a Metadata-2.4 license-expression/license-file mismatch between setuptools and twine. This is a packaging/tooling version issue (publish-only), not a repo bug, so no code was changed.

_{To show artifacts inline, enable in settings.}

  

Sourcery 摘要

记录开发和一致性验证 spatho 所需的 Cloud Agent 设置和运行时指南。

增强功能：

• 在 AGENTS.md 中记录 Cloud Agent 开发环境、代码库结构、依赖约束以及常用开发命令。

构建：

• 记录系统级 Python 安装所需的方法，以及本地设置所需的兼容版 histoseg 依赖固定版本。

文档：

• 添加持久的贡献者指南，涵盖测试、构建、CLI 工作流和旧版 Gradio 应用的运行方式，并说明已知的打包工具限制。

Original summary in English

Summary by Sourcery

Document the Cloud Agent setup and runtime guidance needed to develop and validate spatho consistently.

Enhancements:

• Document the Cloud Agent development environment, repository surfaces, dependency constraints, and common development commands in AGENTS.md.

Build:

• Record the required system-level Python installation approach and the compatible histoseg dependency pin for local setup.

Documentation:

• Add durable contributor guidance for running tests, builds, CLI workflows, and the legacy Gradio application, including known packaging-tooling limitations.

[sourcery-ai]

审查者指南

添加 AGENTS.md 作为持久化的 Cloud Agent 指南，记录仓库结构、Python 和 CLI 工作流、Gradio 操作、打包注意事项，以及旧版应用兼容性所需的 HistoSeg 版本固定。

文件级变更

变更	详细信息	文件
记录仓库的 Cloud Agent 布局、依赖约束和常见开发工作流。	标识受维护的软件包/CLI、旧版 Gradio 应用以及可选 HTTP 服务的边界。 记录 Python 安装约定、PATH 要求、测试/构建命令和 CLI 用法。 记录 Gradio 输入、运行时输出、公开设置以及端到端工作流。	AGENTS.md
记录使旧版 Gradio 应用保持正常运行所需的 HistoSeg 兼容性解决方案。	解释 HistoSeg 0.1.9.3 中不兼容的 API 变更。 记录软件包测试和 Gradio 应用都需要固定使用 histoseg==0.1.9.2。 提供用于保留该版本固定的手动重新安装命令。	AGENTS.md

---

提示和命令

与 Sourcery 交互

• 触发新的审查： 在拉取请求中评论 @sourcery-ai review。
• 继续讨论： 直接回复 Sourcery 的审查评论。
• 根据审查评论生成 GitHub issue： 回复审查评论，请 Sourcery 根据该评论创建 issue。你也可以回复审查评论并使用 @sourcery-ai issue，根据该评论创建 issue。
• 生成拉取请求标题： 在拉取请求标题的任意位置写入 @sourcery-ai，即可随时生成标题。你也可以在拉取请求中评论 @sourcery-ai title，随时生成或重新生成标题。
• 生成拉取请求摘要： 在拉取请求正文中任意位置写入 @sourcery-ai summary，即可在指定位置随时生成 PR 摘要。你也可以在拉取请求中评论 @sourcery-ai summary，随时生成或重新生成摘要。
• 生成审查者指南： 在拉取请求中评论 @sourcery-ai guide，即可随时生成或重新生成审查者指南。
• 解决所有 Sourcery 评论： 在拉取请求中评论 @sourcery-ai resolve，即可解决所有 Sourcery 评论。如果你已经处理完所有评论且不想再看到它们，此功能会很有用。
• 忽略所有 Sourcery 审查： 在拉取请求中评论 @sourcery-ai dismiss，即可忽略所有现有的 Sourcery 审查。如果你想通过新的审查重新开始，此功能尤其有用——别忘了评论 @sourcery-ai review 以触发新的审查！

自定义你的体验

访问你的控制面板以：

• 启用或禁用审查功能，例如 Sourcery 生成的拉取请求摘要、审查者指南等。
• 更改审查语言。
• 添加、删除或编辑自定义审查说明。
• 调整其他审查设置。

获取帮助

• 如有问题或反馈，请联系我们的支持团队。
• 访问我们的文档获取详细指南和信息。
• 关注我们在 X/Twitter、LinkedIn 或 GitHub 上的账号，与 Sourcery 团队保持联系。

Original review guide in English

Reviewer's Guide

Adds AGENTS.md as durable Cloud Agent guidance, documenting repository surfaces, Python and CLI workflows, Gradio operation, packaging caveats, and the HistoSeg version pin required for legacy app compatibility.

File-Level Changes

Change	Details	Files
Documents the repository’s Cloud Agent layout, dependency constraints, and common development workflows.	Identifies the maintained package/CLI, legacy Gradio app, and optional HTTP service boundaries. Records Python installation conventions, PATH requirements, test/build commands, and CLI usage. Documents Gradio inputs, runtime outputs, exposure settings, and the end-to-end workflow.	AGENTS.md
Captures the HistoSeg compatibility workaround required to keep the legacy Gradio application functional.	Explains the breaking API changes in HistoSeg 0.1.9.3. Documents the required histoseg==0.1.9.2 pin for both package tests and the Gradio app. Provides the manual reinstall command needed to preserve the pin.	AGENTS.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.