Metadata-Version: 2.4
Name: snubber-langchain
Version: 0.1.1
Summary: LangChain adapter for Snubber
Author: Tanmay Devare
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: snubber-core>=0.1.1
Requires-Dist: langchain>=0.1.0

<p align="center">
  <img src="assets/snubber-logo.svg" alt="Snubber Logo" width="600">
</p>

<p align="center">
  <img src="assets/snubber-architecture.svg" alt="Snubber Architecture Diagram" width="90%" style="max-width: 900px;">
</p>

<p align="center">
  <em>Catch the shock. Stop AI agents from burning tokens on infinite loops.</em>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
  <a href="Cargo.toml"><img src="https://img.shields.io/badge/rustc-2024+-orange" alt="Rust Edition 2024"></a>
  <a href="src/lib.rs"><img src="https://img.shields.io/badge/no__std-compatible-success" alt="no_std compatible"></a>
  <a href="https://github.com/tanmaydevare/snubber"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status"></a>
</p>

---

# Snubber: Two Products, One Safety Layer

---

## What Is Snubber?

**Snubber** is the runtime safety layer for autonomous agents. It detects and blocks tool‑call loops before they burn tokens or crash your infrastructure. It works in any harness, any language, in under 70 microseconds.

We ship **two products** that serve different audiences:

---

## Product 1: Snubber Core

### The Engine

The Snubber Core is a **C ABI library** written in Rust (`no_std`). It does exactly one thing: it takes a tool call, checks it against a sliding window of recent calls, and returns a decision — `ALLOW`, `WARN`, `BLOCK_RETRY`, or `BLOCK_HALT`.

**Key properties:**
- **<2µs overhead** – zero allocations in the hot path
- **<200KB binary** – no runtime dependencies
- **C ABI** – embeds anywhere C runs (Python, Node.js, Go, Rust, C++)

**What it does:**
- **Semantic loop detection** (`ignore_args: true`) – catches the same tool with different arguments
- **Error‑aware counting** (`count_mode: ErrorsOnly`) – ignores legitimate polling
- **Circuit breaker** – per‑tool cooldown prevents retry storms
- **Output validation** – regex + JSON schema on tool outputs

**Who it’s for:**
- Harness developers (LangChain, CrewAI, AutoGen maintainers)
- Systems engineers embedding safety in custom agents
- Rust developers building agent frameworks

**Distribution:**
- Crates.io: `cargo add snubber`
- GitHub: `snubber-rs/snubber`
- Pre‑built binaries: `libsnubber.so`, `libsnubber.dylib`, `snubber.dll`

---

## Product 2: Snubber Adapters + Reference Harness

### The Drop‑In Safety Layer

For developers who don’t want to build from scratch, Snubber provides **ready‑to‑use adapters** that wrap the core into your existing agent harness. One line of code, instant safety.

**Available adapters:**
- **LangChain** – `pip install snubber-langchain`
- **CrewAI** – `pip install snubber-crewai`
- **AutoGen** – `pip install snubber-autogen`
- **LangGraph** – `pip install snubber-langgraph`
- **Node.js (coming soon)** – `npm install @snubber/langchain`

**Also included:**
- **Snubber Harness** – a complete, safety‑first Rust ReAct agent harness. It’s open‑source and serves as a reference implementation, showcasing how to build a harness with Snubber embedded as a first‑class primitive.

**Who it’s for:**
- Python developers using LangChain, CrewAI, AutoGen, or LangGraph
- Teams that want to drop safety into their existing codebase without rewriting
- Early adopters who want to see Snubber in action before committing

**Distribution:**
- PyPI: `pip install snubber-*`
- npm: `npm install @snubber/*`
- Docker: `docker run snubber/harness`

---

## How They Work Together

```
┌─────────────────────────────────────────────────────────────┐
│                      YOUR APPLICATION                       │
│  ┌─────────────────────────────────────────────────────┐    │
│  │   LangChain / CrewAI / AutoGen / LangGraph         │    │
│  └─────────────────────┬───────────────────────────────┘    │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────────┐    │
│  │   Snubber Adapter (Python / JS / Go)                │    │
│  │   – Calls the C ABI core                            │    │
│  │   – Intercepts tool calls                           │    │
│  │   – Injects SYSTEM INTERCEPT messages               │    │
│  └─────────────────────┬───────────────────────────────┘    │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────────┐    │
│  │   Snubber Core (libsnubber.so)                      │    │
│  │   – Sliding window                                  │    │
│  │   – Semantic detection                              │    │
│  │   – Circuit breaker                                 │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

---

## The Value Proposition

| User | Problem | Snubber Solution |
|------|---------|------------------|
| **Python developer** | LangChain loop detection is experimental | `pip install snubber-langchain` – instant safety |
| **Rust developer** | Need embeddable loop detection | `cargo add snubber` – <2µs, zero allocations |
| **Enterprise team** | 429 crashes, token waste | Snubber blocked loops in 4 harnesses, saved 100% of tokens |
| **Harness maintainer** | Want to add safety to your framework | Snubber Core – C ABI, embeddable anywhere |

---

## Summary

| Product | What It Is | Who It’s For | Get It |
|---------|------------|--------------|--------|
| **Snubber Core** | C ABI library (Rust `no_std`) | Framework devs, systems engineers | `cargo add snubber` |
| **Snubber Adapters** | Drop‑in wrappers for LangChain, CrewAI, AutoGen, LangGraph | Python agent developers | `pip install snubber-*` |
| **Snubber Harness** | Reference Rust ReAct agent harness | Rust developers, early adopters | `cargo install snubber-harness` |

---

## License

MIT — use it, fork it, ship it. See [LICENSE](LICENSE).
