huggingface / smolagents

The GitHub description calls this project 'smolagents: a barebones library for agents that think in code' — the maintainers' wording, carried in repository metadata rather than established by analysis. The metadata homepage is https://huggingface.co/docs/smolagents. The code is almost entirely Python: about 988,225 language bytes versus 326 bytes of Makefile. The LICENSE file and the platform metadata agree on Apache-2.0. The analyzed snapshot has 185 files under docs (81), examples (34), src (21), tests (28), .github (10) and 11 at the root. Metadata records release v1.26.0 published 2026-05-29 and 29,313 stars as of 2026-09-14.

There is no single recorded launcher; the eight recorded Python __main__ guard excerpts differ: six call main(), examples/open_deep_research/app.py's recorded guard calls demo.launch(), and examples/smolagents_benchmark/run.py's recorded excerpt is an args-parsing block. Eight files have such guards: src/smolagents/cli.py, src/smolagents/vision_web_browser.py, examples/structured_output_tool.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, and examples/smolagents_benchmark/run.py. Two more, examples/async_agent/main.py and examples/server/main.py, are flagged as likely executable entrypoints by filename heuristic. The recorded static flows stop early at external boundaries: examples/open_deep_research/run.py's guard calls main(), one recorded bounded path for it terminates at the unresolved load_dotenv boundary, and the analyzer's flow record separately shows main -> parse_args -> unresolved parser.parse_args; examples/open_deep_research/app.py's guard path includes create_agent and GradioUI calls and ends at demo.launch(), all external/unresolved; examples/async_agent/main.py reaches Route and Starlette names that also stay unresolved. The analyzer's summary singles out examples/structured_output_tool.py as the apparent main starting place.

The analyzer treats docs, src and tests as subsystem-like top-level directories; examples and .github complete the layout. By resolved static call degree, the most connected module is src/smolagents/local_python_executor.py at 195 incoming and 190 outgoing calls. The analyzer labels such modules 'service/core candidate' from call degree plus entrypoint membership — an inference, not runtime evidence. Next are src/smolagents/models.py (60 in / 66 out), src/smolagents/utils.py (56 in / 8 out) and src/smolagents/agents.py (16 in / 80 out); agents.py's outgoing-heavy profile suggests it calls widely across the codebase. Among examples, examples/open_deep_research/scripts/mdconvert.py is the most connected (30 in / 29 out); in the test tree, tests/test_agents.py reaches 89 in / 89 out.

Dependency records exist only for the examples' two requirements.txt manifests: four records for examples/async_agent (smolagents, starlette, anyio, uvicorn) and 39 for examples/open_deep_research — from anthropic >=0.37.1, transformers >=4.46.0 and torch >=2.2.2 through pandas, Pillow, pypdf and many format-processing or domain libraries. Several records carry no version at all, and torch and python-pptx each appear twice in the open_deep_research manifest. pyproject.toml dependency tables were not parsed, so the core package's own dependencies are not established here. Install, run and build inference is partial, and installation commands are not verified. The tests tree holds 28 test-like files, including tests/conftest.py. tests/test_agents.py is heavily connected (89 in / 89 out) and defines fake model stand-ins such as FakeToolCallModel and FakeCodeModel.

A workable first pass: (1) README.md and pyproject.toml — both analyzer-flagged project-level important files — for the self-description and packaging metadata; (2) LICENSE, which carries the Apache-2.0 text; (3) the agent classes in src/smolagents/agents.py (MultiStepAgent, ToolCallingAgent, CodeAgent) together with the tool layer in src/smolagents/tools.py (Tool, tool decorator, ToolCollection, load_tool); (4) src/smolagents/local_python_executor.py, the most connected module; (5) one runnable example — examples/open_deep_research/run.py or examples/structured_output_tool.py — read next to its __main__ guard; (6) a final look at where static paths terminate at unresolved external boundaries.

Symbols worth opening early: src/smolagents/agents.py defines MultiStepAgent, ToolCallingAgent and CodeAgent plus RunResult and PromptTemplates. src/smolagents/models.py centres on ChatMessage, ChatMessageToolCall and ChatMessageStreamDelta, with agglomerate_stream_deltas merging stream deltas. src/smolagents/tools.py exposes the Tool class, a tool decorator, ToolCollection, load_tool and launch_gradio_demo. src/smolagents/local_python_executor.py provides safer_eval, safer_func, check_safer_result, InterpreterError, ExecutionTimeoutError and a timeout helper. Those names suggest a deliberately restricted code-execution layer — an inference from naming, not a security assessment. src/smolagents/remote_executors.py defines RemotePythonExecutor alongside E2BExecutor, DockerExecutor, ModalExecutor and BlaxelExecutor. examples/open_deep_research/scripts/mdconvert.py defines DocumentConverter plus converters for HTML, PDF, DOCX, XLSX, PPTX, YouTube and Wikipedia content. src/smolagents/utils.py collects agent error types (AgentError, AgentMaxStepsError) with parse_json_blob and extract_code_from_text.

Everything above comes from static analysis; no code was executed and no installation command was verified. Of 7,633 recorded static relations, 6,888 are external or unresolved and 745 resolve locally. Reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring and dynamic dispatch are not resolved by the analyzer. Dependency records cover only requirements-style manifests — pyproject.toml dependency tables were not parsed — so the core package's dependencies are unknown here. README claim extraction is line-based and may capture code lines, so any README-derived statement should be treated as an author claim at best. What the agents actually do when run is not established by this packet.