[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-amakelov--mandala":3,"tool-amakelov--mandala":61},[4,18,26,36,44,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":10,"last_commit_at":24,"category_tags":25,"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":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"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 真正成长为懂上",159636,2,"2026-04-17T23:33:34",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":75,"owner_location":75,"owner_email":76,"owner_twitter":72,"owner_website":77,"owner_url":78,"languages":79,"stars":88,"forks":89,"last_commit_at":90,"license":91,"difficulty_score":92,"env_os":93,"env_gpu":94,"env_ram":95,"env_deps":96,"category_tags":104,"github_topics":106,"view_count":32,"oss_zip_url":75,"oss_zip_packed_at":75,"status":17,"created_at":111,"updated_at":112,"faqs":113,"releases":149},9007,"amakelov\u002Fmandala","mandala","A simple & elegant experiment tracking framework that integrates persistence logic & best practices directly into Python","mandala 是一款简洁优雅的 Python 实验追踪框架，旨在让开发者无需编写繁琐的存储代码，即可自动保存、查询和版本化计算过程。它主要解决了机器学习及各类科学计算中实验管理困难、重复计算浪费资源以及依赖关系难以追踪的痛点。\n\n通过简单的 `@op` 装饰器，mandala 能自动捕获函数的输入、输出、代码逻辑及依赖项。其核心优势在于“智能复用”：一旦检测到相同的函数调用，它将直接返回过往结果，避免重复运算，从而大幅提升迭代效率。此外，mandala 引入了独特的 ComputationFrame 数据结构，能自动将复杂的命令式代码执行过程组织成高层级的计算图，直观呈现变量间的反馈循环、分支合并等关系，并支持像操作表格一样轻松查询和分析实验数据。\n\n这款工具特别适合机器学习研究员、数据科学家以及需要频繁进行实验迭代的 Python 开发者。无论是构建端到端的持久化程序，还是探索异构的计算网络，mandala 都能让你在专注于纯 Python 逻辑的同时，享受高效、透明的实验管理体验。","\u003Cdiv align=\"center\">\n  \u003Cbr>\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Famakelov_mandala_readme_c6489e569bed.png\" height=128 alt=\"logo\" align=\"center\">\n  \u003Cbr>\n\u003Ca href=\"#install\">Install\u003C\u002Fa> |\n\u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F01_hello.ipynb\">\n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"Open In Colab\"\u002F>\u003C\u002Fa> | \n\u003Ca href=\"#tutorials\">Tutorials\u003C\u002Fa> |\n\u003Ca href=\"https:\u002F\u002Famakelov.github.io\u002Fmandala\u002F\">Docs\u003C\u002Fa> |\n\u003Ca href=\"#blogs--papers\">Blogs\u003C\u002Fa> |\n\u003Ca href=\"#faqs\">FAQs\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n# Automatically save, query & version Python computations\n`mandala` eliminates the effort and code overhead of ML experiment tracking (and\nbeyond) with two generic tools:\n\n1. The `@op` decorator:\n    - **captures inputs, outputs and code (+dependencies)** of Python\n    function calls\n    - automatically reuses past results & **never computes the same call twice**\n    - **designed to be composed** into end-to-end persisted programs, enabling\n    efficient iterative development in plain-Python, without thinking about the\n    storage backend.\n\n\u003Ctable style=\"border-collapse: collapse; border: none;\">\n  \u003Ctr>\n    \u003Ctd style=\"border: none;\">\n      \u003Col start=\"2\">\n    \u003Cli>\n        The \u003Ca href=\"https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Fblog\u002F01_cf\u002F\">ComputationFrame\u003C\u002Fa> data structure:\n        \u003Cul>\n        \u003Cli>\n            \u003Cstrong>automatically organizes executions of imperative\n            code\u003C\u002Fstrong> into a high-level computation graph of variables and\n            operations. Detects patterns like feedback loops, branching\u002Fmerging\n            and aggregation\u002Findexing\n        \u003C\u002Fli>\n        \u003Cli>\n            \u003Cstrong>queries relationships between variables\u003C\u002Fstrong> by extracting a dataframe where columns are variables and operations in the graph, and each row contains values\u002Fcalls of a (possibly partial) execution of the graph\n        \u003C\u002Fli>\n        \u003Cli>\n            \u003Cstrong>automates exploration and high-level operations\u003C\u002Fstrong> over heterogeneous \"webs\" of \u003Ccode>@op\u003C\u002Fcode> calls\n        \u003C\u002Fli>\n        \u003C\u002Ful>\n    \u003C\u002Fli>\n    \u003C\u002Fol>\n    \u003C\u002Ftd style=\"border: none;\">\n    \u003Ctd>\u003Cimg src=\"output.svg\" alt=\"Description\" width=\"2700\"\u002F>\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## Video demo\nA quick demo of running computations in `mandala` and simultaneously updating a view of the corresponding `ComputationFrame` and the dataframe extracted from it (code can\nbe found [here](https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002F_demos\u002Fcf_vid.ipynb)):\n\nhttps:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fassets\u002F1467702\u002F85185599-10fb-479e-bf02-442873732906\n\n# Install\n```\npip install pymandala\n```\nor\n```\npip install git+https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\n```\n\n# Tutorials \n- Quickstart: \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F01_hello.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"Open In Colab\"\u002F>\u003C\u002Fa> | [read in docs](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Ftutorials\u002F01_hello\u002F)\n- `ComputationFrame`s: \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Fblog\u002F01_cf.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"Open In Colab\"\u002F>\u003C\u002Fa>  | [read in docs](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Fblog\u002F01_cf\u002F)\n- Toy ML project: \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F02_ml.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"Open In Colab\"\u002F>\u003C\u002Fa> | [read in docs](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Ftutorials\u002F02_ml\u002F)\n\n# Blogs & papers\n- [Tidy Computations](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Fblog\u002F01_cf\u002F): introduces\nthe `ComputationFrame` data structure and its applications\n- [Practical Dependency Tracking for Python Function\nCalls](https:\u002F\u002Famakelov.github.io\u002Fblog\u002Fdeps\u002F): describes the motivations and designs behind `mandala`'s dependency tracking system\n- The [paper](https:\u002F\u002Famakelov.github.io\u002Fscipy-mandala.pdf), which is to\nappear in the SciPy 2024 proceedings.\n- A [discussion on Hacker News](https:\u002F\u002Fnews.ycombinator.com\u002Fitem?id=40940181)\n\n# FAQs\n\n## How is this different from other experiment tracking frameworks?\nCompared to popular tools like W&B, MLFlow or Comet, `mandala`:\n- **is integrated with the actual Python code execution on a more granular\nlevel**\n    - the function call is the synchronized unit of persistence, versioning and\n    querying, as opposed to an entire script or notebook, leading to more\n    efficient reuse and incremental development.\n    - going even further, Python collections (e.g. `list, dict`) can be made\n    transparent to the storage system, so that individual elements are stored\n    and tracked separately and can be reused across collections and calls.\n    - since it's memoization-based as opposed to logging-based, you don't have\n    to think about how to name any of the things you log.\n- **provides the `ComputationFrame` data structure**, a powerful & simple way to\nrepresent, query and manipulate complex saved computations.\n- **automatically resolves the version of every `@op` call** from the current\nstate of the codebase and the inputs to the call.\n\n## How is the `@op` cache invalidated?\n- given inputs for a call to an `@op`, e.g. `f`, it searches for a past call\nto `f` on inputs with the same contents (as determined by a hash function) where the dependencies accessed by this call (including `f`\nitself) have versions compatible with their current state.\n- compatibility between versions of a function is decided by the user: you\nhave the freedom to mark certain changes as compatible with past results, though\nsee the [limitations](#limitations) about marking changes as compatible.\n- internally, `mandala` uses slightly modified `joblib` hashing to compute a\ncontent hash for Python objects. This is practical for many use cases, but\nnot perfect, as discussed in the [limitations](#limitations) section.\n\n## Can I change the code of `@op`s, and what happens if I do?\n- a frequent use case: you have some `@op` you've been using, then want to\nextend its functionality in a way that doesn't invalidate the past results.\nThe recommended way is to add a new argument `a`, and provide a default\nvalue for it wrapped with `NewArgDefault(x)`. When a value equal to `x` is\npassed for this argument, the storage falls back on calls before \n- beyond changes like this, you probably want to use the versioning system to\ndetect dependencies of `@op`s and changes to them. See the\n[documentation](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Ftopics\u002F04_versions\u002F).\n\n## Is it production-ready?\n- `mandala` is in alpha, and the API is subject to change.\n- moreover, there are known performance bottlenecks that may make working with \nstorages of 10k+ calls slow.\n\n## How self-contained is it?\n- `mandala`'s core is a few kLoCs and only depends on `pandas` and `joblib`. \n- for visualization of `ComputationFrame`s, you should have `dot` installed\non the system level, and\u002For the Python `graphviz` library installed.\n\n# Limitations\n- The versioning system is currently not feature-rich and documented enough for\nrealistic use cases. For example, it doesn't support removing old versions in a\nconsistent way, or restricting `ComputationFrame`s by function versions.\nMoreover, many of the error messages are not informative enough and\u002For don't\nsuggest solutions.\n- When using versioning and you mark a change as compatible with past results,\nyou should be careful if the change introduced new dependencies that are not\ntracked by `mandala`. Changes to such \"invisible\" dependencies may remain \nunnoticed by the storage system, leading you to believe that certain results \nare up to date when they are not.\n- See the \"gotchas\" notebook for mistakes to avoid: \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002Fgotchas.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"Open In Colab\"\u002F>\u003C\u002Fa>\n\n# Roadmap for future features\n**Overall**\n- [x] support for named outputs in `@op`s\n- [ ] support for renaming `@op`s and their inputs\u002Foutputs\n\n**Memoization**\n- [ ] add custom serialization for chosen objects\n- [ ] figure out a solution that ignores small numerical error in content hashing\n- [ ] improve the documentation on collections\n- [ ] support parallelization of `@op` execution via e.g. `dask` or `ray`\n- [ ] support for inputs\u002Foutputs to exclude from the storage\n\n**Computation frames**\n- [x] add support for cycles in the computation graph\n- [ ] improve heuristics for the `expand_...` methods\n- [ ] add tools for restricting a CF to specific subsets of variable values via predicates\n- [ ] improve support & examples for using collections\n- [ ] add support for merging or splitting nodes in the CF and similar simplifications\n\n**Versioning**\n- [ ] support ways to remove old versions in a consistent way\n- [ ] improve documentation and error messages\n- [ ] test this system more thoroughly\n- [ ] support restricting CFs by function versions\n- [ ] support ways to manually add dependencies to versions in order to avoid the \"invisible dependency\" problem\n\n**Performance**\n- [ ] improve performance of the in-memory cache\n- [ ] improve performance of `ComputationFrame` operations\n\n# Galaxybrained vision\nAspirationally, `mandala` is about much more than ML experiment tracking. The\nmain goal is to **make persistence logic & best practices a natural extension of Python**.\nOnce this is achieved, the purely \"computational\" code you must write anyway\ndoubles as a storage interface. It's hard to think of a simpler and more\nreliable way to manage computational artifacts.\n\n## A first-principles approach to managing computational artifacts\nWhat we want from our storage are ways to\n- refer to artifacts with short, unambiguous descriptions: \"here's [big messy Python object] I computed, which to me\nmeans [human-readable description]\"\n- save artifacts: \"save [big messy Python object]\"\n- refer to artifacts and load them at a later time: \"give me [human-readable description] that I computed before\"\n- know when you've already computed something: \"have I computed [human-readable description]?\"\n- query results in more complicated ways: \"give me all the things that satisfy\n[higher-level human-readable description]\", which in practice means some\npredicate over combinations of artifacts.\n- get a report of how artifacts were generated: \"what code went into [human-readable description]?\"\n\nThe key observation is that **execution traces** can already answer ~all of\nthese questions.\n\n# Related work\n`mandala` combines ideas from, and shares similarities with, many technologies.\nHere are some useful points of comparison:\n- **memoization**: \n  - the [`provenance`](https:\u002F\u002Fgithub.com\u002Fbmabey\u002Fprovenance) library is quite\n  similar to the memoization part of `mandala`, but lacks the querying and\n  dependency tracking features.\n  - standard Python memoization solutions are [`joblib.Memory`](https:\u002F\u002Fjoblib.readthedocs.io\u002Fen\u002Flatest\u002Fgenerated\u002Fjoblib.Memory.html)\n  and\n  [`functools.lru_cache`](https:\u002F\u002Fdocs.python.org\u002F3\u002Flibrary\u002Ffunctools.html#functools.lru_cache).\n  `mandala` uses `joblib` serialization and hashing under the hood.\n  - [`incpy`](https:\u002F\u002Fgithub.com\u002Fpajju\u002FIncPy) is a project that integrates\n    memoization with the python interpreter itself. \n  - [`funsies`](https:\u002F\u002Fgithub.com\u002Faspuru-guzik-group\u002Ffunsies) is a\n    memoization-based distributed workflow executor that uses an analogous notion\n    of hashing to `mandala` to keep track of which computations have already been done. It\n    works on the level of scripts (not functions), and lacks queriability and\n    versioning.\n  - [`koji`](https:\u002F\u002Farxiv.org\u002Fabs\u002F1901.01908) is a design for an incremental\n    computation data processing framework that unifies over different resource\n    types (files or services). It also uses an analogous notion of hashing to\n    keep track of computations. \n- **computation frames**:\n  - computation frames are special cases of [relational\n  databases](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FRelational_database): each function\n  node in the computation graph has a table of calls, where columns are all the\n  input\u002Foutput edge labels connected to the function. Similarly, each variable\n  node is a single-column table of all the `Ref`s in the variable. Foreign key\n  constraints relate the functions' columns to the variables, and various joins \n  over the tables express various notions of joint computational history of\n  variables. \n  - computation frames are also related to [graph\n  databases](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FGraph_database), in the sense that\n  some of the relevant queries over computation frames, e.g. ones having to do\n  with reachability along `@op`s, are special cases of queries over graph\n  databases. The internal representation of the `Storage` is also closer to \n  a graph database than a relational one.\n  - computation frames are also related to some ideas from applied [category\n  theory](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FCategory_theory), such as using functors\n  from a finite category to the category of sets (*copresheaves*) as a blueprint\n  for a \"universal\" in-memory data structure that is (again) equivalent to a\n  relational database; see e.g.  [this\n  paper](https:\u002F\u002Fcompositionality-journal.org\u002Fpapers\u002Fcompositionality-4-5\u002F),\n  which describes this categorical construction.\n- **versioning**:\n  - the revision history of each function in the codebase is organized in a \"mini-[`git`](https:\u002F\u002Fgit-scm.com\u002F) repository\" that shares only the most basic\n    features with `git`: it is a\n    [content-addressable](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FContent-addressable_storage)\n    tree, where each edge tracks a diff from the content at one endpoint to that\n    at the other. Additional metadata indicates equivalence classes of\n    semantically equivalent contents.\n  - [semantic versioning](https:\u002F\u002Fsemver.org\u002F) is another popular code\n    versioning system. `mandala` is similar to `semver` in that it allows you to\n    make backward-compatible changes to the interface and logic of dependencies.\n    It is different in that versions are still labeled by content, instead of by\n    \"non-canonical\" numbers.\n  - the [unison programming language](https:\u002F\u002Fwww.unison-lang.org\u002Flearn\u002Fthe-big-idea\u002F) represents\n    functions by the hash of their content (syntax tree, to be exact).\n","\u003Cdiv align=\"center\">\n  \u003Cbr>\n    \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Famakelov_mandala_readme_c6489e569bed.png\" height=128 alt=\"logo\" align=\"center\">\n  \u003Cbr>\n\u003Ca href=\"#install\">安装\u003C\u002Fa> |\n\u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F01_hello.ipynb\">\n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"在Colab中打开\"\u002F>\u003C\u002Fa> | \n\u003Ca href=\"#tutorials\">教程\u003C\u002Fa> |\n\u003Ca href=\"https:\u002F\u002Famakelov.github.io\u002Fmandala\u002F\">文档\u003C\u002Fa> |\n\u003Ca href=\"#blogs--papers\">博客与论文\u003C\u002Fa> |\n\u003Ca href=\"#faqs\">常见问题\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n# 自动保存、查询并版本化 Python 计算\n`mandala` 通过两种通用工具，消除了机器学习实验跟踪（以及更多）所需的努力和代码开销：\n\n1. `@op` 装饰器：\n    - **捕获 Python 函数调用的输入、输出及代码（包括依赖关系）**\n    - 自动重用过往结果，**绝不会对同一调用重复计算**\n    - **专为组合成端到端持久化程序而设计**，从而在纯 Python 中实现高效的迭代开发，无需考虑存储后端。\n\n\u003Ctable style=\"border-collapse: collapse; border: none;\">\n  \u003Ctr>\n    \u003Ctd style=\"border: none;\">\n      \u003Col start=\"2\">\n    \u003Cli>\n        \u003Ca href=\"https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Fblog\u002F01_cf\u002F\">ComputationFrame\u003C\u002Fa> 数据结构：\n        \u003Cul>\n        \u003Cli>\n            \u003Cstrong>自动将命令式代码的执行组织为变量和操作的高层计算图\u003C\u002Fstrong>。能够检测反馈循环、分支\u002F合并以及聚合\u002F索引等模式。\n        \u003C\u002Fli>\n        \u003Cli>\n            \u003Cstrong>查询变量之间的关系\u003C\u002Fstrong>，通过提取一个数据框，其中列代表计算图中的变量和操作，每行包含计算图部分执行的值或调用。\n        \u003C\u002Fli>\n        \u003Cli>\n            \u003Cstrong>自动化对异构的 `@op` 调用网络进行探索和高层操作\u003C\u002Fstrong>。\n        \u003C\u002Fli>\n        \u003C\u002Ful>\n    \u003C\u002Fli>\n    \u003C\u002Fol>\n    \u003C\u002Ftd style=\"border: none;\">\n    \u003Ctd>\u003Cimg src=\"output.svg\" alt=\"描述\" width=\"2700\"\u002F>\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## 视频演示\n快速演示如何在 `mandala` 中运行计算，同时更新对应的 `ComputationFrame` 视图及其提取的数据框（代码可在[这里](https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002F_demos\u002Fcf_vid.ipynb)找到）：\n\nhttps:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fassets\u002F1467702\u002F85185599-10fb-479e-bf02-442873732906\n\n# 安装\n```\npip install pymandala\n```\n或者\n```\npip install git+https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\n```\n\n# 教程\n- 快速入门： \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F01_hello.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"在Colab中打开\"\u002F>\u003C\u002Fa> | [阅读文档](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Ftutorials\u002F01_hello\u002F)\n- `ComputationFrame`s： \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Fblog\u002F01_cf.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"在Colab中打开\"\u002F>\u003C\u002Fa>  | [阅读文档](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Fblog\u002F01_cf\u002F)\n- 玩具机器学习项目： \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F02_ml.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"在Colab中打开\"\u002F>\u003C\u002Fa> | [阅读文档](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Ftutorials\u002F02_ml\u002F)\n\n# 博客与论文\n- [整洁计算](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Fblog\u002F01_cf\u002F)：介绍 `ComputationFrame` 数据结构及其应用\n- [Python 函数调用的实用依赖跟踪](https:\u002F\u002Famakelov.github.io\u002Fblog\u002Fdeps\u002F)：描述 `mandala` 依赖跟踪系统的设计动机与实现细节\n- 该[论文](https:\u002F\u002Famakelov.github.io\u002Fscipy-mandala.pdf)即将发表于 SciPy 2024 会议论文集。\n- 在[Hacker News](https:\u002F\u002Fnews.ycombinator.com\u002Fitem?id=40940181)上的讨论\n\n# 常见问题\n\n## 这与其他实验跟踪框架有何不同？\n与 W&B、MLFlow 或 Comet 等流行工具相比，`mandala`：\n- **更细粒度地与实际 Python 代码执行集成**\n    - 函数调用是持久化、版本管理和查询的同步单元，而非整个脚本或笔记本，从而实现更高效的复用和增量开发。\n    - 更进一步，Python 集合类型（如 `list`、`dict`）可以对存储系统透明化，使得单个元素被单独存储和跟踪，并可在不同集合和调用之间复用。\n    - 由于基于记忆化而非日志记录，您无需考虑如何命名所记录的内容。\n- **提供 `ComputationFrame` 数据结构**，这是一种强大且简单的方法，用于表示、查询和操作复杂的已保存计算。\n- **自动从当前代码库状态和调用输入中解析每个 `@op` 调用的版本号**。\n\n## `@op` 缓存是如何失效的？\n- 对于某个 `@op` 函数的调用，例如 `f`，系统会搜索过去使用相同内容输入（由哈希函数决定）的调用，且这些调用所访问的依赖项（包括 `f` 自身）的版本与当前状态兼容。\n- 函数版本之间的兼容性由用户决定：您可以自由标记某些更改与过往结果兼容，但关于标记兼容性的限制，请参阅[限制](#limitations)部分。\n- 内部而言，`mandala` 使用略微修改后的 `joblib` 哈希算法来计算 Python 对象的内容哈希值。这在许多场景下非常实用，但并不完美，具体讨论请参见[限制](#limitations)部分。\n\n## 我可以修改 `@op` 的代码吗？如果修改了会发生什么？\n- 常见用例：您一直在使用某个 `@op`，随后希望扩展其功能而不使过往结果失效。推荐的做法是添加一个新参数 `a`，并为其提供一个包裹在 `NewArgDefault(x)` 中的默认值。当传入等于 `x` 的值时，存储系统会回退到之前的调用。\n- 除此之外，您可能需要利用版本控制系统来检测 `@op` 的依赖关系及其变化。详情请参阅[文档](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002Ftopics\u002F04_versions\u002F)。\n\n## 是否已准备好投入生产环境？\n- `mandala` 目前处于 Alpha 阶段，API 可能会发生变化。\n- 此外，已知存在性能瓶颈，可能导致处理超过 1 万次调用的存储时速度较慢。\n\n## 它有多自包含？\n- `mandala` 的核心只有几千行代码，并且仅依赖于 `pandas` 和 `joblib`。\n- 为了可视化 `ComputationFrame`，您需要在系统级别安装 `dot` 工具，和\u002F或安装 Python 的 `graphviz` 库。\n\n# 局限性\n- 目前的版本控制系统功能不够丰富，文档也不够完善，无法满足实际使用场景的需求。例如，它不支持以一致的方式删除旧版本，也无法根据函数版本限制 `ComputationFrame`。此外，许多错误信息不够清晰，也未提供解决方案建议。\n- 在使用版本控制时，如果您将某次更改标记为与历史结果兼容，需格外小心：如果此次更改引入了未被 `mandala` 跟踪的新依赖项，这些“隐形”依赖的变化可能不会被存储系统察觉，从而导致您误以为某些结果是最新的，而实际上并非如此。\n- 请参阅“注意事项”笔记本，了解需要避免的常见错误： \u003Ca href=\"https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002Fgotchas.ipynb\"> \n  \u003Cimg src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" alt=\"在 Colab 中打开\"\u002F>\u003C\u002Fa>\n\n# 未来功能路线图\n**总体**\n- [x] 支持 `@op` 中的命名输出\n- [ ] 支持重命名 `@op` 及其输入\u002F输出\n\n**记忆化**\n- [ ] 为选定对象添加自定义序列化\n- [ ] 找到一种忽略内容哈希中微小数值误差的解决方案\n- [ ] 改进集合相关的文档\n- [ ] 通过例如 `dask` 或 `ray` 支持并行执行 `@op`\n- [ ] 支持从存储中排除特定的输入\u002F输出\n\n**计算框架**\n- [x] 添加对计算图中循环的支持\n- [ ] 改进 `expand_...` 方法的启发式算法\n- [ ] 增加通过谓词将 CF 限制到变量值特定子集的工具\n- [ ] 改进集合的使用支持及示例\n- [ ] 添加对 CF 中节点合并、拆分等简化操作的支持\n\n**版本控制**\n- [ ] 支持以一致方式删除旧版本\n- [ ] 改进文档和错误信息\n- [ ] 对该系统进行更全面的测试\n- [ ] 支持按函数版本限制 CF\n- [ ] 支持手动为版本添加依赖项，以避免“隐形依赖”问题\n\n**性能**\n- [ ] 提升内存缓存的性能\n- [ ] 提升 `ComputationFrame` 操作的性能\n\n# 高远愿景\n从理想角度来看，`mandala` 的意义远不止于机器学习实验跟踪。其主要目标是 **让持久化逻辑与最佳实践成为 Python 的自然延伸**。一旦实现这一点，您原本就必须编写的纯“计算”代码，同时也将成为存储接口。很难再找到比这更简单、更可靠的方式来管理计算产物了。\n\n## 一种基于第一性原理的计算产物管理方法\n我们期望存储系统能够提供以下功能：\n- 用简短且无歧义的描述引用产物：“这是我计算出的[庞大而复杂的 Python 对象]，对我而言，它代表[人类可读的描述]”\n- 保存产物：“保存[庞大而复杂的 Python 对象]”\n- 在后续时间点引用并加载产物：“请给我之前计算出的[人类可读的描述]”\n- 确认是否已计算过某产物：“我是否已经计算过[人类可读的描述]？”\n- 以更复杂的方式查询结果：“请给我所有满足[更高层次的人类可读描述]的事物”，这在实践中意味着对多个产物组合施加某种谓词条件。\n- 获取产物生成过程的报告：“用于生成[人类可读的描述]的代码是什么？”\n\n关键的观察是，**执行轨迹**几乎可以回答上述所有问题。\n\n# 相关工作\n`mandala` 结合了多种技术的思想，并与之存在相似之处。\n以下是一些有用的对比点：\n- **记忆化**：\n  - [`provenance`](https:\u002F\u002Fgithub.com\u002Fbmabey\u002Fprovenance) 库在记忆化方面与 `mandala` 非常相似，但缺少查询和依赖关系跟踪的功能。\n  - 标准的 Python 记忆化解决方案包括 [`joblib.Memory`](https:\u002F\u002Fjoblib.readthedocs.io\u002Fen\u002Flatest\u002Fgenerated\u002Fjoblib.Memory.html) 和 [`functools.lru_cache`](https:\u002F\u002Fdocs.python.org\u002F3\u002Flibrary\u002Ffunctools.html#functools.lru_cache)。`mandala` 在底层使用了 `joblib` 的序列化和哈希机制。\n  - [`incpy`](https:\u002F\u002Fgithub.com\u002Fpajju\u002FIncPy) 是一个将记忆化直接集成到 Python 解释器中的项目。\n  - [`funsies`](https:\u002F\u002Fgithub.com\u002Faspuru-guzik-group\u002Ffunsies) 是一个基于记忆化的分布式工作流执行器，它使用与 `mandala` 类似的哈希机制来跟踪哪些计算已经完成。该工具作用于脚本级别（而非函数级别），并且缺乏可查询性和版本管理功能。\n  - [`koji`](https:\u002F\u002Farxiv.org\u002Fabs\u002F1901.01908) 是一种增量计算数据处理框架的设计，能够统一处理不同类型的资源（文件或服务）。它同样采用类似的哈希机制来跟踪计算过程。\n- **计算框架**：\n  - 计算框架是 [关系数据库](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FRelational_database) 的特例：计算图中的每个函数节点都有一张调用表，其列对应所有连接到该函数的输入输出边标签。类似地，每个变量节点则是一张单列表，记录该变量中的所有 `Ref`。外键约束将函数的列与变量关联起来，而通过表之间的各种连接操作可以表达变量联合计算历史的不同概念。\n  - 计算框架也与 [图数据库](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FGraph_database) 存在联系，因为对计算框架的一些相关查询，例如涉及沿 `@op` 边可达性的查询，实际上是图数据库查询的特例。此外，`Storage` 的内部表示形式更接近图数据库，而非关系数据库。\n  - 计算框架还与应用 [范畴论](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FCategory_theory) 中的一些思想相关，例如将有限范畴到集合范畴的函子（即“余层”）用作“通用”内存数据结构的蓝图，这种结构再次等价于关系数据库；参见例如 [这篇论文](https:\u002F\u002Fcompositionality-journal.org\u002Fpapers\u002Fcompositionality-4-5\u002F)，其中描述了这一范畴论构造。\n- **版本管理**：\n  - 代码库中每个函数的修订历史被组织在一个“迷你 [`git`](https:\u002F\u002Fgit-scm.com\u002F) 仓库”中，该仓库仅保留了 `git` 的最基本功能：它是一个 [内容寻址存储](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FContent-addressable_storage) 树，每条边记录从一端内容到另一端内容的差异。附加元数据用于标识语义等价的内容类。\n  - [语义化版本控制](https:\u002F\u002Fsemver.org\u002F) 是另一种流行的代码版本管理系统。`mandala` 与 `semver` 的相似之处在于，它允许对依赖项的接口和逻辑进行向后兼容的更改。二者的不同之处在于，`mandala` 仍然以内容本身来标记版本，而不是使用“非规范”的数字。\n  - [Unison 编程语言](https:\u002F\u002Fwww.unison-lang.org\u002Flearn\u002Fthe-big-idea\u002F) 则通过函数内容的哈希值（确切地说是语法树的哈希值）来表示函数。","# Mandala 快速上手指南\n\nMandala 是一个用于自动保存、查询和版本化 Python 计算的开源工具。它通过 `@op` 装饰器实现细粒度的函数级缓存与复用，并利用 `ComputationFrame` 数据结构将命令式代码执行自动组织为可查询的计算图，特别适合机器学习实验追踪及迭代开发。\n\n## 环境准备\n\n*   **系统要求**：支持 Linux、macOS 和 Windows。\n*   **Python 版本**：建议 Python 3.8 及以上。\n*   **核心依赖**：安装后会自动包含 `pandas` 和 `joblib`。\n*   **可选依赖（可视化）**：若需可视化 `ComputationFrame` 计算图，请确保系统已安装 Graphviz (`dot` 命令) 或 Python `graphviz` 库。\n    *   Ubuntu\u002FDebian: `sudo apt-get install graphviz`\n    *   macOS: `brew install graphviz`\n    *   Windows: 下载并安装 Graphviz 安装包并将 bin 目录加入环境变量。\n\n## 安装步骤\n\n推荐使用 pip 进行安装。国内用户可使用清华或阿里镜像源加速下载。\n\n**方式一：从 PyPI 安装（推荐）**\n\n```bash\npip install pymandala -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n**方式二：从 GitHub 源码安装（获取最新特性）**\n\n```bash\npip install git+https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n## 基本使用\n\nMandala 的核心在于使用 `@op` 装饰器标记函数。一旦标记，该函数的输入、输出及代码依赖将被自动捕获。相同的输入和代码状态不会重复计算，而是直接返回缓存结果。\n\n### 1. 最简单的示例\n\n以下示例展示了如何定义一个带缓存的计算函数，并演示第二次调用时如何直接复用结果。\n\n```python\nfrom mandala.core import OpStore\n\n# 初始化存储后端 (默认使用本地临时目录)\nstore = OpStore()\n\n# 使用 @op 装饰器标记函数\n@store.op\ndef expensive_computation(x, y):\n    print(f\"正在计算 {x} + {y}...\")  # 仅在首次执行或缓存失效时打印\n    return x + y\n\n# 第一次调用：实际执行计算\nresult1 = expensive_computation(2, 3)\nprint(f\"结果 1: {result1}\") \n# 输出:\n# 正在计算 2 + 3...\n# 结果 1: 5\n\n# 第二次调用：相同参数，直接复用缓存，不执行函数体\nresult2 = expensive_computation(2, 3)\nprint(f\"结果 2: {result2}\")\n# 输出:\n# 结果 2: 5 (注意：没有打印 \"正在计算...\"，说明未重复执行)\n\n# 参数变化：重新执行计算\nresult3 = expensive_computation(2, 4)\nprint(f\"结果 3: {result3}\")\n# 输出:\n# 正在计算 2 + 4...\n# 结果 3: 6\n```\n\n### 2. 查询计算历史 (ComputationFrame)\n\nMandala 允许你将一系列 `@op` 调用组织成数据框（DataFrame）进行查询和分析。\n\n```python\n# 假设已经运行了多次 expensive_computation\n# 提取计算帧 (ComputationFrame)\ncf = store.get_computation_frame()\n\n# 查看包含所有变量和操作的数据框\ndf = cf.to_dataframe()\nprint(df.head())\n\n# 你可以像操作 pandas DataFrame 一样筛选特定的计算结果\n# 例如：找出所有第一个参数为 2 的计算记录\nfiltered = df[df['arg_x'] == 2]\nprint(filtered)\n```\n\n### 3. 开始你的第一个教程\n\n想要更深入地了解如何在 ML 项目中使用或查看交互式演示，可以访问官方 Colab 教程：\n\n*   **快速入门**: [Open in Colab](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F01_hello.ipynb)\n*   **ML 项目实战**: [Open in Colab](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Famakelov\u002Fmandala\u002Fblob\u002Fmaster\u002Fdocs_source\u002Ftutorials\u002F02_ml.ipynb)","某数据科学团队正在迭代一个复杂的特征工程流水线，需要频繁调整预处理参数并重新训练模型以寻找最优解。\n\n### 没有 mandala 时\n- **重复计算浪费资源**：每次微调上游参数，整个流水线都会从头运行，即使中间步骤的逻辑未变，也导致大量算力浪费在重复计算上。\n- **实验记录混乱**：开发者需手动编写代码将输入参数、输出结果和代码版本保存到数据库或文件中，容易遗漏关键依赖信息，导致实验不可复现。\n- **结果追溯困难**：当发现某个模型效果异常时，难以快速反向查询是哪些特定的输入数据或代码变更导致了该结果，缺乏自动化的血缘关系图谱。\n- **开发流程割裂**：为了持久化存储，必须在业务逻辑中嵌入大量样板代码，破坏了纯 Python 开发的流畅性，增加了维护负担。\n\n### 使用 mandala 后\n- **智能缓存加速迭代**：通过 `@op` 装饰器，mandala 自动识别函数输入与代码指纹，若参数未变则直接复用历史结果，彻底消除重复计算，将迭代速度提升数倍。\n- **零样本自动持久化**：无需编写任何存储逻辑，mandala 自动捕获所有函数的输入、输出及依赖关系并持久保存，确保每个实验细节都可完整复现。\n- **可视化血缘查询**：利用 `ComputationFrame` 数据结构，团队可将复杂的执行过程转化为 DataFrame，轻松查询变量间的因果关系，秒级定位问题根源。\n- **原生代码体验**：开发者只需关注核心算法逻辑，mandala 将存储与管理透明化地融入标准 Python 流程，实现了“写即存”的高效开发模式。\n\nmandala 通过将持久化逻辑无缝植入 Python 代码，让数据团队从繁琐的实验管理中解放出来，专注于真正的算法创新。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Famakelov_mandala_c56454fd.png","amakelov","Alex Makelov","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Famakelov_42a52088.jpg",null,"aleksandar.makelov@gmail.com","amakelov.github.io","https:\u002F\u002Fgithub.com\u002Famakelov",[80,84],{"name":81,"color":82,"percentage":83},"Jupyter Notebook","#DA5B0B",66.9,{"name":85,"color":86,"percentage":87},"Python","#3572A5",33.1,540,16,"2026-04-08T15:30:33","Apache-2.0",1,"未说明 (基于 Python 和 joblib，通常支持 Linux, macOS, Windows)","未说明 (无需 GPU，纯 Python 计算工具)","未说明 (核心轻量级，但处理 10k+ 调用时可能存在性能瓶颈)",{"notes":97,"python":98,"dependencies":99},"该工具处于 Alpha 阶段，API 可能会发生变化。核心仅依赖 pandas 和 joblib。若需可视化计算框架（ComputationFrame），需在系统层面安装 'dot' 命令或安装 Python 'graphviz' 库。当存储调用次数超过 1 万次时，已知存在性能瓶颈。","未说明 (需支持 pandas 和 joblib 的 Python 版本)",[100,101,102,103],"pandas","joblib","graphviz (可选，用于可视化 ComputationFrame)","dot (系统级命令，可选，用于可视化)",[16,14,105],"其他",[107,108,109,110],"data-science","experiment-tracking","machine-learning","incremental-computation","2026-03-27T02:49:30.150509","2026-04-18T17:06:05.012333",[114,119,124,129,134,139,144],{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},40397,"如何安装 Mandala？是否支持通过 PyPi 安装？","项目现已在 PyPi 上发布，包名为 `pymandala`。你可以使用命令 `pip install pymandala` 进行安装。安装后，导入方式仍为 `import mandala`。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F29",{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},40398,"计算帧（Computation Frames）的主要用途是什么？仅仅用于可视化吗？","计算帧的主要用途是以一种比记忆化（memoization）更声明式的方式来检查和操作存储内容，而不仅仅是为了可视化。可视化只是为了帮助理解概念和提供接口。记忆化是一种“命令式”的存储访问方式，依赖于你拥有生成结果的代码或确切知道输入参数；而计算帧旨在解决这一局限，与记忆化模块配合使用，为计算实验提供完整的数据管理方案。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F30",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},40399,"在 `with storage.query():` 代码块中调用函数时，为什么传入普通值会报错 \"value must be a `ValQuery` or `Ref`\"？","目前在 `with storage.query():` 块中，函数的所有输入必须是占位符（如 `Q()`）或其他函数的输出，不支持直接传入原始值（如数字 21）。如果未来支持该功能，其效果是将查询中的第一个参数固定为该值，从而在匹配时只使用该特定值，这对于避免加载大型数据框后再过滤的场景非常有用。当前解决方法是修改代码，确保所有输入均为占位符或引用。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F10",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},40400,"遇到 \"ModuleNotFoundError: No module named 'prettytable'\" 错误该如何解决？","`prettytable` 已被设置为软依赖（soft dependency）。如果遇到此错误，请手动安装该库：`pip install prettytable`。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F17",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},40401,"定义操作函数时，如果参数名仅大小写不同（例如 `x` 和 `X`），为什么会报 \"duplicate column name\" 错误？","这是因为操作符的参数名在底层处理中是不区分大小写的，导致 `x` 和 `X` 被视为相同的列名从而引发冲突。该问题已在 0.2.0beta 版本中修复，建议升级到此版本或更高版本以避免此错误。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F13",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},40402,"Mandala 是如何为输出分配唯一标识符（UID）的？是基于内容哈希还是因果哈希？","项目目前决定采用“内容哈希”（content hashing）策略。这意味着一旦函数计算出输出，就会对其进行内容哈希处理并以此作为 UID。这样做的好处是：如果不同的调用计算出相同的结果，不会重复存储；意外解包再重新包装输出也不会破坏 UID。虽然对大对象哈希需要时间且对象不再具有唯一的生成历史代码，但这被认为是更安全、更透明的选择。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F3",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},40403,"`@track` 装饰器是否会忽略其下方的其他装饰器？","是的，早期版本中存在此问题，即 `@track` 装饰器可能会有效忽略其下方的其他装饰器（例如 `@stuff`）。该问题已通过提交 c354062 部分解决，建议更新到包含此修复的最新版本。","https:\u002F\u002Fgithub.com\u002Famakelov\u002Fmandala\u002Fissues\u002F24",[150,155],{"id":151,"version":152,"summary_zh":153,"released_at":154},323773,"v0.2.0-alpha","此版本：\n- 引入了 `ComputationFrame` 作为查询存储的方式\n- 进行了一系列破坏性变更和改进，其中最重要的是：\n  - 现在任何函数都可以使用 `@op` 装饰器（无需为输出添加类型注解，也不再要求固定的输入\u002F输出集合）\n  - 现在可以直接使用 `with storage:`，而无需再写 `with storage.run():`\n  - `@op` 装饰器支持通过 `output_names` 指定命名输出\n  - 为了让 `@op` 的集合类型输入\u002F输出对存储透明，可以使用自定义的类型注解构造函数 `MList`、`MDict` 等\n- 重写了并简化了大部分记忆化机制的内部实现\n- 推出了更加详尽的[文档](https:\u002F\u002Famakelov.github.io\u002Fmandala\u002F)","2024-07-11T16:00:42",{"id":156,"version":157,"summary_zh":158,"released_at":159},323774,"v0.1.0","这是一个稳定且经过充分测试的版本，自约2023年初以来基本未作改动。\n\n接下来将预览一下它与当前开发版的主要区别：\n\n- 本版本中的查询机制将在下一版本中被“计算框架”取代。计算框架提供了一种更为灵活、更自然的声明式存储探索方式。具体来说：\n  - `with storage.query():` 上下文及相关语义将被移除；\n  - 相应地，`storage.similar` 等函数及其内部实现也将被移除。\n- 本版本中对 `@op` 的诸多限制将在下一版本中被解除：\n  - 将允许使用可变位置参数或可变关键字参数；\n  - 将允许输出数量可变；\n  - 不再强制要求输出注解。\n- `with storage.run():` 将被 `with storage:` 替代。\n- 面向用户的 `storage` 方法将进行大量破坏性变更；具体细节请参阅正式发布的版本文档。","2024-06-21T20:35:23"]