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

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 tools
03_nano_with_memory_example.py — With memory
04_nano_with_subagents_example.py — With subagents
05_nano_full_composition_example.py — Full composition
06_nano_computer_use_example.py — Desktop GUI automation
07_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.

Metadata

Release files for soothe-nano 1.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for soothe-nano 1.4.2
File	Size	Uploaded
soothe_nano-1.4.2.tar.gz	1.4 MB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for soothe-nano 1.4.2
File	Interpreter	ABI	Platform	Reset
soothe_nano-1.4.2-py3-none-any.whl 1.6 MB Oct 13, 2026	Python 3	none	any	Details

Total release size: 3.0 MB

Release files / soothe_nano-1.4.2.tar.gz

Download URL	soothe_nano-1.4.2.tar.gz
Size	1.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`0c005e2a123f3bf35abc7f3a48a909632340d2b78b9c1f5b8a65efa28496b610`
BLAKE2b-256 checksum How to use checksums	`e52be38e627927fc059cfc5f6ac79117539770c8fd32307ccbee2db4becb6c8d`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / soothe_nano-1.4.2-py3-none-any.whl

Download URL	soothe_nano-1.4.2-py3-none-any.whl
Size	1.6 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`7bb9de6e304a50bbd091e098947b40baa7f787a940c76e856e6a1d3848bdc41a`
BLAKE2b-256 checksum How to use checksums	`78c9284664606b41aae95b7c679065576f49c57c02efa1c2c73438a77edff483`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`