huggingface / smolagents · 架構

GitHub metadata 記錄的主要語言是 Python，repository 自己的描述稱它為 smolagents，「a barebones library for agents that think in code」。

分析器的摘要算到 185 個被分析的檔案，圍繞 docs、examples、src 和 tests 組織，其中有 28 個類測試檔案；子系統記錄把 docs、src 和 tests 標為可能的子系統。

回報的頂層檔案數：docs 81、examples 34、src 21、tests 28、.github 10，另有 11 個根目錄層級的檔案。

• src/smolagents 裡有 cli.py 和 vision_web_browser.py 這類檔案，兩者都被標為可能的進入點。
• examples/ 裡是可以執行的腳本，每個範例都有自己的 requirements 清單檔，例如 examples/async_agent/requirements.txt 和 examples/open_deep_research/requirements.txt。

回報了十個進入點：八個檔案帶有明確的 __main__ 執行守衛（examples/structured_output_tool.py、src/smolagents/cli.py、src/smolagents/vision_web_browser.py、examples/open_deep_research/app.py、examples/open_deep_research/run.py、examples/open_deep_research/run_gaia.py、examples/plan_customization/plan_customization.py、examples/smolagents_benchmark/run.py），examples/async_agent/main.py 和 examples/server/main.py 則是依檔名啟發式規則找到的候選。

摘要把 examples/structured_output_tool.py 稱為看起來的主要起點，一條教學陳述則指向 examples/async_agent/main.py。重建結果回報了 90 條有界執行路徑；這裡個別記錄了其中十條。

在記錄到的路徑中：

• examples/async_agent/main.py 的兩條路徑都停在 Route 和 Starlette；
• examples/open_deep_research/app.py 的三條路徑停在 create_agent、GradioUI 和 demo.launch；
• examples/open_deep_research/run.py 的五條路徑停在 load_dotenv、login、os.getenv 和 threading.Lock。

十條的結局都一樣：終止原因是 'unresolved_boundary'，沒有截斷，也沒有偵測到循環。

分析資料裡全部 20 筆模組角色記錄，都是分析器從已解析的靜態呼叫次數和是否屬於進入點推論出來的；沒有一筆有執行時的證據確認。

• src/smolagents/local_python_executor.py 是列出的模組中呼叫次數最高的：195 個呼入和 190 個呼出。
• src/smolagents/models.py（60 入／66 出）和 src/smolagents/agents.py（16 入／80 出）是 service/core 候選。
• src/smolagents/utils.py（56 入／8 出）和 src/smolagents/_function_type_hints_utils.py（24 入／18 出）也是核心候選。
• 其他 src/smolagents 的候選：tools.py（5/24）、remote_executors.py（7/22）、monitoring.py（17/1）、memory.py（16/1）、gradio_ui.py（9/9）、agent_types.py（10/5）、serialization.py（10/4）。
• 在 examples/open_deep_research/scripts 裡：mdconvert.py（30/29）、gaia_scorer.py（12/12）、run_agents.py（4/4）。
• entry/orchestration 候選：src/smolagents/cli.py、src/smolagents/vision_web_browser.py、examples/open_deep_research/run_gaia.py、examples/plan_customization/plan_customization.py。
• tests/test_agents.py 是連結次數最高的測試模組（89 入／89 出）。

記錄到的邊大多離開了可分析的範圍：7633 條靜態關係中有 6888 條是外部或未解析，只有 745 條解析到本地目標。

記錄到的路徑停在：

• Route 和 Starlette，從 examples/async_agent/main.py 到達；starlette 也是那個範例宣告的執行期依賴；
• create_agent、GradioUI 和 demo.launch，從 examples/open_deep_research/app.py 到達；分析資料沒有確定這些目標定義在哪裡；
• load_dotenv、login、os.getenv 和 threading.Lock，從 examples/open_deep_research/run.py 到達。

記錄到的十條路徑之所以結束，都是因為下一個目標是外部或未解析的，而不是另一個被分析的模組。

分析器也記錄了：反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派都沒有解析。

記錄到的關係分成 6700 個呼叫和 933 個 import（總共 7633 條）；重建結果另外回報了 615 條已解析的靜態呼叫關係，分析資料沒有調和這個數字和 745 條本地邊之間的差異。

清單檔證據：

• examples/async_agent/requirements.txt 宣告 smolagents、starlette、anyio 和 uvicorn 為執行期依賴：這個範例把函式庫本身也列了進去。
• examples/open_deep_research/requirements.txt 產生的記錄包括 anthropic（>=0.37.1）、openai（>=1.52.2）、transformers（>=4.46.0）和 torch（>=2.2.2）。
• 記錄只涵蓋 requirements 形式的清單檔：pyproject.toml 的依賴表不會被解析，所以缺少 src 套件本身的依賴。

內部耦合：local_python_executor.py（195）和 models.py（60）的呼入次數很高，依推論暗示 src/smolagents 有很大一部分是被其他地方呼叫的，但分析資料沒有列出呼叫者。

程式執行時各個部分怎麼接在一起，這裡無法確定：分析器不解析框架在執行期的接線、動態分派、反射、動態 import、monkey-patching、產生的程式碼或執行期依賴注入。

也在這次分析範圍之外的：

• 安裝和執行／建置的行為只有部分推論，安裝指令也沒有驗證；
• 來自 README 的陳述是逐行擷取的，最多只算作者自述；
• manifest 的能力欄位描述的是分析器本身，不是 repository，所以不算在證據裡；
• 確實有測試（依摘要有 28 個類測試檔案），但它們在執行時驗證了什麼，無法確定。

最後，7633 條關係中有 6888 條是外部或未解析，所以這份資料裡缺少某條連結，並不能證明兩個部分彼此獨立。

README.md、pyproject.toml 和 LICENSE 被歸為專案層級的重要檔案。

分析資料裡的一條教學陳述建議：先從清單檔和重要符號開始，再追蹤有界執行路徑，並在改程式之前檢查未解析的邊界。