soothe-nano
A ready-to-run coding agent you can drop into a script, CLI, or app.
Built on soothe-deepagents (filesystem, shell, subagents, skills, MCP). Nano adds the pieces you usually wire yourself: workspace safety, progressive tools/skills, research subagents, and a config-driven factory.
Vision
Give builders a production-shaped SootheNanoAgent in a few lines of Python.
- Start small — chat, tools, or full composition
- Stay portable — embed in notebooks, CLIs, or your own service
- Compose what you need — tools, memory, subagents, skills, and MCP via config
Architecture
soothe-deepagents agent harness (FS, shell, memory, skills base)
↓
soothe-nano SootheNanoAgent + toolkits + subagents + MCP
+ shared contracts (protocols, events, plugin API)
create_nano_agent(config)
│
├─ model + middleware stack
├─ tools (builtin groups + yours)
├─ subagents (planner, research, browser, computer_use, …)
├─ skills (progressive discovery)
└─ MCP (on-demand activation)
Features
| Area | What nano provides |
|---|---|
| Tools | Builtin groups: shell, file ops, HTTP, search, data, image, datetime |
| Subagents | Ready: plan, deep/academic research, browser_use, computer_use |
| Skills / tools in context | Progressive loading — activate what the turn needs |
| Workspace | Scoped workspace + security defaults |
| Config | YAML / SootheConfig factory |
| Memory | Optional long-term memory via protocols |
| MCP | Registry and on-demand adapters |
| Plugins | Decorator API (@plugin, @tool, @tool_group, @subagent) with discovery, registry, and lifecycle |
| Observability | Langfuse tracing hooks, event registry, verbosity tiers |
| Resilience | PersistentRetryRunner for 429/529/transient errors with exponential backoff + model fallback |
vs deepagents
| deepagents | soothe-nano | |
|---|---|---|
| What you get | Opinionated harness | Harness plus coding product defaults |
| Tools | Bring your own | Builtin groups out of the box |
| Subagents | You define them | Ready plan / research / browser / computer_use |
| Skills / tools in context | Base support | Progressive loading |
| Workspace | Pluggable backends | Scoped workspace + security defaults |
| Config | Code-first | YAML / SootheConfig factory |
| Plugin authoring | — | Decorator API + discovery + registry |
| Shared contracts | — | Protocols, events, plugin API (self-contained since 1.4) |
Use deepagents when you want a minimal harness and full control.
Use nano when you want a coding agent that already knows how to work in a repo.
When to use nano
| Scenario | Fit |
|---|---|
| Coding assistant in a repo | ✅ Files, shell, plan out of the box |
| Research / browsing agent | ✅ Deep research, academic, browser_use subagents |
| Desktop GUI automation | ✅ computer_use subagent (screenshots, clicks, keyboard) |
| Embed in your product | ✅ Library API, no daemon required |
| One-shot / headless CLI | ✅ See fj-ai |
| Plugin / toolkit author | ✅ Depends on nano only |
| Simple Q&A chat | ✅ Strip tools/subagents as needed |
Install
uv add soothe-nano
Sandbox execution
Run the agent's shell and filesystem tools inside an ArcBox microVM while framework state stays on the host — see docs/arcbox-backend.md.
Quick start
Quick start
from soothe_nano import create_nano_agent
from soothe_nano.config import SootheConfig
agent = create_nano_agent(SootheConfig())
# agent.ainvoke / streaming — see examples/
For interactive + background execution in one runtime, use the dual-mode factory:
from soothe_nano import create_dual_mode_nano_agent, InteractionMode
from soothe_nano.config import SootheConfig
agent = create_dual_mode_nano_agent(SootheConfig(), mode=InteractionMode.INTERACTIVE)
Examples
Library examples live in examples/:
01_pure_nano_example.py— Pure model (no tools)02_nano_with_tools_example.py— With tools03_nano_with_memory_example.py— With memory04_nano_with_subagents_example.py— With subagents05_nano_full_composition_example.py— Full composition06_nano_computer_use_example.py— Desktop GUI automation07_nano_computer_use_weixin_favorites.py— WeChat favorites harvesting
LLM provider examples in examples/llm/ (OpenAI, Gemini, OpenRouter, Anthropic, Ollama, DashScope/custom OpenAI-compatible endpoints, structured output, multi-provider factory):
python examples/01_pure_nano_example.py
Plugin authoring
from soothe_nano.plugin import plugin, tool, subagent
@plugin("my-toolkit")
class MyToolkit:
@tool
def do_thing(self, x: str) -> str:
"""Do a thing."""
return f"did: {x}"
Plugins are discovered from entry points, config, or the filesystem and loaded with dependency resolution via the PluginLifecycleManager.
1 maintainer
Metadata
1 maintainer
Release files for soothe-nano 2.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| soothe_nano-2.0.3.tar.gz | 1.4 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| soothe_nano-2.0.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.0 MB
Release files / soothe_nano-2.0.3.tar.gz
| Download URL | soothe_nano-2.0.3.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f7332357e00aeee1a1b1ce32e1f3356ecc1c30caa0fac58b0ca5f064324d75f
|
|
BLAKE2b-256 checksum How to use checksums |
0b9690d01ed443f65251fb6e306c573b17ad26fa2d2b50cfb7f57603da2dae32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / soothe_nano-2.0.3-py3-none-any.whl
| Download URL | soothe_nano-2.0.3-py3-none-any.whl |
|---|---|
| Size | 1.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
963cbc98fb746e16a4a671dc0679aea6e0abf6f6b1a2693bda021409abbbae8a
|
|
BLAKE2b-256 checksum How to use checksums |
7a527b0867c2ec0cab427b98691513ad4cc9493d826a55453b974e48339ef647
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for soothe-nano 2.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
