Metadata-Version: 2.5
Name: soothe-nano
Version: 1.4.2
Summary: Soothe Nano — batteries-included SootheNanoAgent on deepagents
Project-URL: Homepage, https://github.com/mirasoth/soothe-nano
Project-URL: Documentation, https://soothe.readthedocs.io
Project-URL: Repository, https://github.com/mirasoth/soothe-nano
License: MIT
Keywords: agents,ai,coreagent,deepagents,langgraph,llm,nano,soothe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: browser-use<0.13.0,>=0.11.0
Requires-Dist: deepxiv-sdk>=0.2.5
Requires-Dist: docx2txt>=0.8.0
Requires-Dist: jsonschema<5.0.0,>=4.0.0
Requires-Dist: langchain-community<1.0.0,>=0.4.0
Requires-Dist: langchain-core<2.0.0,>=1.6.0
Requires-Dist: langchain-mcp-adapters<0.4.0,>=0.3.0
Requires-Dist: langchain-openai<2.0.0,>=1.0.0
Requires-Dist: langchain-quickjs<1.0.0,>=0.3.0
Requires-Dist: langchain-tavily>=0.2.18
Requires-Dist: langchain<2.0.0,>=1.4.0
Requires-Dist: langgraph-checkpoint-postgres<4.0.0,>=3.1.2
Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.1.1
Requires-Dist: langgraph-checkpoint<5.0.0,>=4.2.0
Requires-Dist: langgraph<2.0.0,>=1.2.14
Requires-Dist: litellm<2.0.0,>=1.0.0
Requires-Dist: mcp<2.0.0,>=1.24.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: packaging>=23.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pathspec<2.0.0,>=0.12.0
Requires-Dist: psycopg[binary,pool]<4.0.0,>=3.2.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pydantic-settings<3.0.0,>=2.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Requires-Dist: requests<3.0.0,>=2.32.3
Requires-Dist: soothe-deepagents<1.0.0,>=0.8.6
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: tarzi<0.3.0,>=0.2.3
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: wcmatch>=10.1
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.12.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# soothe-nano

[![PyPI version](https://img.shields.io/pypi/v/soothe-nano.svg?label=PyPI&color=blue)](https://pypi.org/project/soothe-nano/)
[![Python](https://img.shields.io/pypi/pyversions/soothe-nano.svg?label=Python)](https://pypi.org/project/soothe-nano/)

A **ready-to-run coding agent** you can drop into a script, CLI, or app.

Built on [soothe-deepagents](https://github.com/mirasoth/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)
```

```text
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](https://github.com/caesar0301/fj-ai) |
| Plugin / toolkit author | ✅ Depends on nano only |
| Simple Q&A chat | ✅ Strip tools/subagents as needed |

## Install

```bash
uv add soothe-nano
```

## Quick start

```python
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:

```python
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/`:

1. `01_pure_nano_example.py` — Pure model (no tools)
2. `02_nano_with_tools_example.py` — With tools
3. `03_nano_with_memory_example.py` — With memory
4. `04_nano_with_subagents_example.py` — With subagents
5. `05_nano_full_composition_example.py` — Full composition
6. `06_nano_computer_use_example.py` — Desktop GUI automation
7. `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):

```bash
python examples/01_pure_nano_example.py
```

## Plugin authoring

```python
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`.
