soothe-nano

PyPI version Ask DeepWiki

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-sdk          shared contracts (protocols, events)
        ↓
soothe-nano         SootheNanoAgent + toolkits + subagents + MCP

create_nano_agent(config)
        │
        ├─ model + middleware stack
        ├─ tools (builtin groups + yours)
        ├─ subagents (planner, research, browser, …)
        ├─ skills (progressive discovery)
        └─ MCP (on-demand activation)

Features

Area What nano provides
Tools Builtin groups: shell, file ops, HTTP, search, data, image, …
Subagents Ready: plan, deep/academic research, browser
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

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
Skills / tools in context Base support Progressive loading
Workspace Pluggable backends Scoped workspace + security defaults
Config Code-first YAML / SootheConfig factory

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 subagents
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/

Library examples live in examples/:

  1. Pure model (no tools)
  2. With tools
  3. With memory
  4. With subagents
  5. Full composition
python packages/soothe-nano/examples/01_pure_nano_example.py

Productive CLI (reference: fj-ai)

fj-ai is a production one-shot coding CLI built only on soothe-nano (no soothe daemon). Use it as the integration blueprint:

pip install fj-ai   # or: uv tool install fj-ai
fj explain this repo
fj -f what did we decide last time?

Integration pattern

A headless CLI typically does four things on top of nano:

  1. Load config — ~/.soothe/config/nano.yml, or zero-config from OPENAI_API_KEY / ANTHROPIC_API_KEY
  2. Force SQLite for standalone runs (threads survive across process exits)
  3. Build the agent with create_nano_agent, pin workspace, attach a checkpointer
  4. Stream agent.astream(...) and close the aiosqlite connection on exit

Minimal sketch (same shape as fj_ai/agent.py):

from __future__ import annotations

import asyncio
from contextlib import asynccontextmanager
from pathlib import Path
from typing import Any, AsyncIterator

from soothe_nano import SootheNanoAgent, create_nano_agent
from soothe_nano.config import SOOTHE_HOME, SootheConfig
from soothe_nano.resolve import resolve_checkpointer


def load_config(path: Path | None = None) -> SootheConfig:
    cfg = path or (SOOTHE_HOME / "config" / "nano.yml")
    if cfg.is_file():
        return SootheConfig.from_yaml_file(str(cfg))
    return SootheConfig()  # OPENAI_API_KEY / ANTHROPIC_API_KEY


def apply_cli_defaults(config: SootheConfig) -> SootheConfig:
    durability = config.agent.protocols.durability.model_copy(
        update={"backend": "sqlite", "checkpointer": "sqlite"}
    )
    protocols = config.agent.protocols.model_copy(update={"durability": durability})
    agent = config.agent.model_copy(update={"protocols": protocols})
    persistence = config.persistence.model_copy(update={"default_backend": "sqlite"})
    return config.model_copy(update={"agent": agent, "persistence": persistence})


@asynccontextmanager
async def open_sqlite_checkpointer(config: SootheConfig) -> AsyncIterator[Any | None]:
    result = resolve_checkpointer(apply_cli_defaults(config))
    db_path = result[1] if isinstance(result, tuple) and isinstance(result[1], str) else None
    if not db_path:
        yield None
        return

    import aiosqlite
    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
    from soothe_sdk.utils.serde import create_soothe_serde

    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
    conn = await aiosqlite.connect(db_path)
    checkpointer = AsyncSqliteSaver(conn, serde=create_soothe_serde())
    await checkpointer.setup()
    try:
        yield checkpointer
    finally:
        await conn.close()  # required — aiosqlite uses a non-daemon thread


async def build_agent(
    config: SootheConfig,
    *,
    checkpointer: Any | None = None,
) -> SootheNanoAgent:
    agent = create_nano_agent(apply_cli_defaults(config))
    if checkpointer is not None:
        agent.graph.checkpointer = checkpointer
    return agent


async def run_once(query: str, *, thread_id: str) -> None:
    config = load_config()
    async with open_sqlite_checkpointer(config) as checkpointer:
        agent = await build_agent(config, checkpointer=checkpointer)
        async for chunk in agent.astream(
            query,
            config={"configurable": {"thread_id": thread_id}},
            stream_mode=["messages", "updates", "custom"],
        ):
            # render tokens / tool progress to stdout (see fj_ai/stream.py)
            _ = chunk


if __name__ == "__main__":
    asyncio.run(run_once("summarize this repo", thread_id="cli-demo"))

What fj adds on top of nano

Concern fj-ai approach
UX One-shot fj <query…>; -f / -t resume threads; -l list
Persistence SQLite checkpointer under $SOOTHE_DATA_DIR
Skills Package builtin/ via register_builtin_skill_root
Workspace SOOTHE_WORKSPACE / cwd for file + shell tools
Streaming Quiet progress line + full final answer (stream.py)
Setup fj setup writes ~/.soothe/config/nano.yml

For a full TUI / StrangeLoop host on the same stack, see mirasoth/soothe. For the slim CLI product, clone caesar0301/fj-ai.

Package layout

soothe_nano/
  agent/       SootheNanoAgent, create_nano_agent
  config/      SootheConfig
  toolkits/    Builtin tool groups
  subagents/   plan, research, browser, …
  middleware/  Progressive tools/skills, workspace, policy
  skills/      Catalog + progressive search
  mcp/         MCP registry / adapters
  backends/    Persistence helpers

Development

From packages/soothe-nano/:

make help              # list targets
make sync             # sync dev deps
make format lint       # format + lint
make test-unit         # unit tests
make test-integration  # integration tests (--run-integration)
make examples          # run examples
make build             # build dist/

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.2.28)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Xiaming.Chen from gravatar.com Xiaming.Chen

License

MIT License (MIT)

Requires

Python <3.15, >=3.11

Provides Extra

dev

Tags

agents ai coreagent deepagents langgraph llm nano soothe

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

soothe_nano-1.2.10.tar.gz (1.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

soothe_nano-1.2.10-py3-none-any.whl (1.6 MB view details)

Uploaded Python 3

File details

Details for the file soothe_nano-1.2.10.tar.gz.

File metadata

  • Download URL: soothe_nano-1.2.10.tar.gz
  • Upload date:
  • Size: 1.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for soothe_nano-1.2.10.tar.gz
Algorithm Hash digest
SHA256 cfec63338c5317ac3346fb7da9e6b84694ec8e0b502031bb04a57d6b20dc76be
MD5 0ae71485606d165fd71e18a4787cbefc
BLAKE2b-256 6b8ff67ee2d91f921b3f423a17c43bf3224c40d6b27f1bf2adbb06dc4759181c

See more details on using hashes here.

File details

Details for the file soothe_nano-1.2.10-py3-none-any.whl.

File metadata

  • Download URL: soothe_nano-1.2.10-py3-none-any.whl
  • Upload date:
  • Size: 1.6 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for soothe_nano-1.2.10-py3-none-any.whl
Algorithm Hash digest
SHA256 7571cdb10d22d21ce786b037f7a4a15cc43e80270254b552c06c95a54e0a68f1
MD5 1da3732b464d96ba5f0fddba21c71494
BLAKE2b-256 ef225656b467b3abf2ba5c52f375763a05f803f7d13b55a0b583db1c02eaae29

See more details on using hashes here.

Release history Release notifications | RSS feed

1.2.28

2 files

1.2.27

2 files

1.2.26

2 files

1.2.25

2 files

1.2.24

2 files

1.2.23

2 files

1.2.22

2 files

1.2.21

2 files

1.2.20

2 files

1.2.19

2 files

1.2.18

2 files

1.2.17

2 files

1.2.16

2 files

1.2.15

2 files

1.2.14

2 files

1.2.13

2 files

1.2.12

2 files

This release

1.2.10 This release

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.19

2 files

1.1.17

2 files

1.1.16

2 files

1.1.15

2 files

1.1.14

2 files

1.1.13

2 files

1.1.12

2 files

1.1.11

2 files

1.1.10

2 files

1.1.9

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.15

2 files

1.0.14

2 files

1.0.13

2 files

1.0.12

2 files

1.0.11

2 files

1.0.10

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.9.11

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page