Metadata-Version: 2.4
Name: soothe
Version: 0.2.7
Summary: Multi-agent harness built on deepagents and langchain/langgraph.
License: MIT
License-File: LICENSE
Keywords: agents,ai,langchain,langgraph,llm,multi-agent,subagents
Classifier: Development Status :: 3 - Alpha
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: anyio>=3.0.0
Requires-Dist: bubus>=1.5.6
Requires-Dist: deepagents<1.0.0,>=0.4.10
Requires-Dist: fastapi>=0.104.0
Requires-Dist: langchain-community<1.0.0,>=0.3.0
Requires-Dist: langchain-core<2.0.0,>=1.2.18
Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.2.0
Requires-Dist: langchain-openai<1.0.0,>=0.3.0
Requires-Dist: langchain<2.0.0,>=1.2.11
Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.0.0
Requires-Dist: langgraph<2.0.0,>=1.1.1
Requires-Dist: pexpect>=4.9.0
Requires-Dist: pydantic-settings<3.0.0,>=2.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: pyperclip>=1.8.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: soothe-sdk<1.0.0,>=0.1.3
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: textual>=0.40.0
Requires-Dist: typer<1.0.0,>=0.9.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: arxiv>=2.1.0; extra == 'all'
Requires-Dist: browser-use<=0.12.0,>=0.11.0; extra == 'all'
Requires-Dist: claude-agent-sdk<0.1.49,>=0.1.40; extra == 'all'
Requires-Dist: dashscope>=1.25.14; extra == 'all'
Requires-Dist: google-genai>=0.3.0; extra == 'all'
Requires-Dist: ipython>=8.0.0; extra == 'all'
Requires-Dist: langchain-ollama>=0.3.0; extra == 'all'
Requires-Dist: langchain-tavily>=0.2.17; extra == 'all'
Requires-Dist: langgraph-checkpoint-postgres<4.0.0,>=3.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.8.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: openpyxl>=3.1.0; extra == 'all'
Requires-Dist: pandas>=2.0.0; extra == 'all'
Requires-Dist: pexpect>=4.9.0; extra == 'all'
Requires-Dist: pgvector>=0.3; extra == 'all'
Requires-Dist: pillow>=10.0.0; extra == 'all'
Requires-Dist: psycopg[pool]>=3.1; extra == 'all'
Requires-Dist: pyarrow>=14.0.0; extra == 'all'
Requires-Dist: pymupdf>=1.24.0; extra == 'all'
Requires-Dist: rocksdict>=0.3; extra == 'all'
Requires-Dist: tavily-python>=0.5.0; extra == 'all'
Requires-Dist: weaviate-client>=4.0; extra == 'all'
Requires-Dist: wikipedia>=1.4.0; extra == 'all'
Requires-Dist: wizsearch<2.0.0,>=1.1.7; extra == 'all'
Requires-Dist: wizsearch<2.0.0,>=1.1.8; extra == 'all'
Provides-Extra: bash
Requires-Dist: pexpect>=4.9.0; extra == 'bash'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk<0.1.49,>=0.1.40; extra == 'claude'
Provides-Extra: cli
Requires-Dist: pexpect>=4.9.0; extra == 'cli'
Provides-Extra: dashscope
Requires-Dist: dashscope>=1.25.14; extra == 'dashscope'
Provides-Extra: document
Requires-Dist: pymupdf>=1.24.0; extra == 'document'
Provides-Extra: media
Requires-Dist: openai>=1.0.0; extra == 'media'
Requires-Dist: pillow>=10.0.0; extra == 'media'
Provides-Extra: ollama
Requires-Dist: langchain-ollama>=0.3.0; extra == 'ollama'
Provides-Extra: pgvector
Requires-Dist: langgraph-checkpoint-postgres<4.0.0,>=3.0.0; extra == 'pgvector'
Requires-Dist: pgvector>=0.3; extra == 'pgvector'
Requires-Dist: psycopg[pool]>=3.1; extra == 'pgvector'
Provides-Extra: python-executor
Requires-Dist: ipython>=8.0.0; extra == 'python-executor'
Requires-Dist: matplotlib>=3.8.0; extra == 'python-executor'
Provides-Extra: research
Requires-Dist: arxiv>=2.1.0; extra == 'research'
Requires-Dist: langchain-tavily>=0.2.17; extra == 'research'
Requires-Dist: tavily-python>=0.5.0; extra == 'research'
Requires-Dist: wikipedia>=1.4.0; extra == 'research'
Requires-Dist: wizsearch<2.0.0,>=1.1.8; extra == 'research'
Provides-Extra: rocksdb
Requires-Dist: rocksdict>=0.3; extra == 'rocksdb'
Provides-Extra: tabular
Requires-Dist: openpyxl>=3.1.0; extra == 'tabular'
Requires-Dist: pandas>=2.0.0; extra == 'tabular'
Requires-Dist: pyarrow>=14.0.0; extra == 'tabular'
Provides-Extra: video
Requires-Dist: google-genai>=0.3.0; extra == 'video'
Provides-Extra: weaviate
Requires-Dist: weaviate-client>=4.0; extra == 'weaviate'
Provides-Extra: websearch
Requires-Dist: browser-use<=0.12.0,>=0.11.0; extra == 'websearch'
Requires-Dist: langchain-tavily>=0.2.17; extra == 'websearch'
Requires-Dist: wizsearch<2.0.0,>=1.1.7; extra == 'websearch'
Description-Content-Type: text/markdown

# Soothe

<div align="center">
  <img src="assets/soothe-logo.png" alt="Soothe Logo" width="350" />

  #

  [![Python](https://img.shields.io/pypi/pyversions/soothe)](https://pypi.org/project/soothe/)
  [![PyPI Version](https://img.shields.io/pypi/v/soothe)](https://pypi.org/project/soothe/)
  [![License](https://img.shields.io/github/license/caesar0301/Soothe)](https://github.com/caesar0301/Soothe/blob/main/LICENSE)
  [![GitHub Stars](https://img.shields.io/github/stars/caesar0301/Soothe)](https://github.com/caesar0301/Soothe)
  [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/caesar0301/Soothe)

</div>

**Your 24/7 Autonomous AI Agent that Plans, Acts, and Delivers Results**

## What is Soothe?

Soothe is a protocol-driven AI orchestration framework that transforms how you work with AI. Unlike traditional chatbots that merely answer questions, Soothe acts as your intelligent digital colleague that:

- ✨ **Thinks Ahead** - Automatically plans multi-step workflows and adapts strategies based on results
- 🚀 **Acts Autonomously** - Executes complex tasks spanning web research, code execution, file operations, and browser automation
- 🧠 **Learns & Remembers** - Maintains persistent memory across sessions, so you never repeat yourself
- 🔒 **Stays Secure** - Enforces least-privilege policies and keeps your data under your control
- 🔌 **Extends Easily** - Plugin architecture lets you add custom tools and specialized subagents
- 🌐 **Works Anywhere** - Multi-transport daemon supports Unix, WebSocket, and HTTP REST connections

## Architecture

<div align="center">
  <img src="assets/logical-arch.png" alt="Arch" width="800" />
</div>

## Design Philosophy

### 🎯 Intelligent by Default

Soothe uses a **Plan → Execute** execution loop that automatically:
- Analyzes your request and decides the best approach
- Executes tools with structured outputs for reliable results
- Evaluates success and adjusts strategy without manual intervention
- Works for simple queries in milliseconds or complex tasks in minutes

No micromanagement needed—just state your goal and let Soothe deliver.

### 🧠 Persistent Memory & Context

Every conversation builds upon the last:
- **Session memory**: Accumulates knowledge within a thread
- **Cross-session memory**: Recalls important context from past interactions
- **Thread management**: Resume, archive, and organize conversation history
- **Goal tracking**: Long-running objectives persist across sessions

### 🔒 Security & Privacy First

Your infrastructure, your rules:
- **Local execution**: Browser automation, file operations, and code execution run on your machine
- **Policy enforcement**: Fine-grained access control with least-privilege defaults
- **No vendor lock-in**: Bring your own API keys, storage backends, and models
- **Flexible deployment**: Run as CLI, daemon, or integrate into your applications

### 🔌 Extensible Plugin System

Soothe grows with your needs:
- **Built-in tools**: Web search (Tavily, DuckDuckGo), code execution, file operations, browser automation
- **Specialized subagents**: Research, browser automation, planning, and more
- **MCP integration**: Connect to external services via Model Context Protocol
- **Custom plugins**: Create your own tools and subagents with decorator-based APIs

## What Can Soothe Do?

### 🔍 Deep Research & Synthesis
**Multi-source investigation in minutes, not hours**
- Web search with intelligent query generation (Tavily, DuckDuckGo)
- Academic paper discovery (ArXiv integration)
- Document analysis (PDF, DOCX, text files)
- Automatic summarization with citations
- Iterative refinement based on findings

**Example**: *"Research the latest advances in RAG architectures and compare three different approaches"*

### 🤖 Autonomous Task Execution
**From goal to deliverable without hand-holding**
- Multi-step workflow execution with automatic planning
- File operations with security policy enforcement
- Code execution in sandboxed environments
- Browser automation for web interactions
- Parallel tool execution for faster results

**Example**: *"Set up a new Python project with FastAPI, create the directory structure, and initialize git"*

### 📊 Long-Running Operations
**Work that spans hours or days, managed automatically**
- Background daemon mode with multi-transport support
- Thread management with resume capabilities
- Persistent state across sessions
- Progress tracking and artifact storage

**Example**: *"Monitor this website every 6 hours and alert me when the price drops below $50"*

### 🎨 Extensible via Plugins
**Custom capabilities for your unique workflows**
- Decorator-based tool creation (`@tool`)
- Subagent development with `CompiledSubAgent`
- MCP server integration for external services
- Custom event types and handlers

**Example**: Create a custom tool that queries your internal APIs and processes results

## Getting Started

### Quick Start (3 Steps)

1. **Install Soothe**:
   ```bash
   pip install soothe
   ```

2. **Set your API key**:
   ```bash
   export OPENAI_API_KEY=sk-your-key-here
   # or use Anthropic Claude:
   export ANTHROPIC_API_KEY=sk-ant-your-key-here
   ```

3. **Run your first task**:
   ```bash
   # Interactive TUI mode (default)
   soothe -p "Research the top 5 Python web frameworks and create a comparison table"

   # Or just launch TUI and type your query
   soothe
   ```

### Try Different Modes

**Interactive TUI** (default):
```bash
soothe -p "Analyze this codebase and suggest improvements"
```

**Headless single-shot**:
```bash
soothe -p "What is 2 + 2?" --no-tui
```

**Autonomous mode** for complex tasks:
```bash
soothe autopilot run "Set up a monitoring system that checks website uptime every 5 minutes"
```

The TUI shows:
- Tool execution in real-time
- Subagent activities and progress
- Structured event stream
- Keyboard shortcuts for control

### Run as a Background Daemon

For long-running operations and remote access:

```bash
# Start daemon
soothe daemon start

# Attach from any terminal
soothe daemon attach

# Or connect via WebSocket/HTTP
soothe daemon start --enable-websocket --enable-http
```

## Real-World Examples

### Research Workflow
```bash
# Default mode with automatic planning
soothe -p "Research best practices for securing REST APIs, summarize the top 5 recommendations, and create a checklist document"
```

### Codebase Analysis
```bash
# TUI mode shows real-time progress
soothe -p "Analyze the authentication module in src/auth/, identify potential security vulnerabilities, and suggest fixes"
```

### Autonomous Mode (Complex Tasks)
```bash
# Use autopilot for autonomous execution
soothe autopilot run "Set up a monitoring system that checks website uptime every 5 minutes and logs results to a database"
```

### Resume Previous Work
```bash
# List previous threads
soothe thread list

# Continue from where you left off
soothe thread continue <thread-id>
```

## Key Features

| Feature | Status | Description |
|---------|--------|-------------|
| **Intelligent Execution Loop** | ✅ Implemented | Plan → Execute architecture with automatic strategy adjustment |
| **Multi-Source Research** | ✅ Implemented | Web search, academic papers, documents with automatic synthesis |
| **Specialized Subagents** | ✅ Implemented | Browser automation, planning, research, skill creation |
| **Plugin System** | ✅ Implemented | Decorator-based tools and subagents with lifecycle management |
| **Multi-Transport Daemon** | ✅ Implemented | Unix socket, WebSocket, and HTTP REST support |
| **Thread Management** | ✅ Implemented | Persistent threads with resume, archive, and search |
| **Security Policies** | ✅ Implemented | Least-privilege access control with configurable policies |
| **Persistent Memory** | ✅ Implemented | Context and memory across sessions with vector storage support |

## Architecture Highlights

Soothe is built on a **protocol-driven architecture** that ensures flexibility and maintainability:

```
┌─────────────────────────────────────────────────────────┐
│  CLI / TUI Layer (User Interface)                       │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Daemon Layer (Multi-Transport Server)                  │
│  Unix Socket | WebSocket | HTTP REST                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Core Framework (Agent Factory & Runner)                │
│  Plan → Execute Loop                                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Protocol Layer (8 Swappable Protocols)                 │
│  Context | Memory | Planning | Policy | Durability |    │
│  Remote | Persistence | VectorStore                     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Capability Layer (Plugins)                             │
│  Tools | Subagents | MCP Servers                        │
└─────────────────────────────────────────────────────────┘
```

**Why This Matters**:
- **Swap any component** without changing your code
- **Add custom capabilities** via the plugin system
- **Scale from local CLI to remote daemon** seamlessly
- **Maintain isolation** between threads and sessions

## Learn More

### 📚 Documentation

- **[Wiki](docs/wiki/)** - End-user guides organized by topic
  - [Getting Started](docs/wiki/getting-started.md) - Installation and first steps
  - [CLI Reference](docs/wiki/cli-reference.md) - Complete command documentation
  - [Configuration](docs/wiki/configuration.md) - Environment variables and YAML config
  - [Troubleshooting](docs/wiki/troubleshooting.md) - Common issues and solutions

- **[User Guide](docs/user_guide.md)** - Comprehensive usage guide with examples

- **[RFCs & Specs](docs/specs/)** - Technical specifications and architecture design
  - [RFC-000](docs/specs/RFC-000-system-conceptual-design.md) - System conceptual design
  - [RFC-201](docs/specs/RFC-201-agentic-goal-execution.md) - Execution architecture
  - [RFC-600](docs/specs/RFC-600-plugin-extension-system.md) - Plugin system design

### 🛠️ For Developers

- **[CLAUDE.md](CLAUDE.md)** - Development guide for AI agents
- **[Implementation Guides](docs/impl/)** - Detailed implementation documentation

## License

MIT
