Metadata-Version: 2.5
Name: langchain-surgemesh
Version: 0.1.0
Summary: LangChain tools for Surgemesh: quote, publish and track social posts from an agent.
Project-URL: Homepage, https://surgemesh.com
Project-URL: Documentation, https://surgemesh.com/docs
Project-URL: Source, https://github.com/novusindex/surgemesh
Author-email: Novus Index LLC <dev@surgemesh.com>
Maintainer-email: Novus Index LLC <dev@surgemesh.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,langchain,mcp,social media,surgemesh,tools
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Requires-Dist: langchain-core<2,>=0.3
Requires-Dist: pydantic<3,>=2
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# langchain-surgemesh

LangChain tools for [Surgemesh](https://surgemesh.com), agent-first social publishing. Your agent can quote the exact price of a post, schedule it to one or more social channels, check its prepaid credit, and track delivery, all through one API key.

> **Preview:** quotes, channel connects and sandbox posts work today. Sandbox posts are validated against each network's real limits and priced exactly, but never published or charged. Live posting and payments are coming soon.

## Install

```bash
pip install langchain-surgemesh
```

## Get an API key

```bash
curl -X POST https://api.surgemesh.com/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email": "you@example.com", "accept_terms": true}'
```

The response holds your `api_key` (shown once). Then:

```bash
export SURGEMESH_API_KEY=sm_...
```

## Quick start

```python
from langchain.agents import create_agent
from langchain_surgemesh import SurgemeshToolkit

toolkit = SurgemeshToolkit()            # reads SURGEMESH_API_KEY
agent = create_agent("openai:gpt-4.1", toolkit.get_tools())

agent.invoke({"messages": "List my Surgemesh channels, quote a post for 2026-11-03T15:00:00Z, "
                          "then schedule 'Hello from our agent' to my sandbox channel at that time."})
```

## Tools

| Tool | What it does | Spends credit? |
|---|---|---|
| `quote_post` | Exact price for a time and number of channels (or a network mix), plus cheaper nearby times. Returns a `quote_id`. | No |
| `publish_post` | Schedules a post to channel ids from `list_channels`. Needs a `quote_id` from `quote_post` or an `idempotency_key`. | Yes, at the quoted price |
| `list_channels` | Channels this key can post to (connected accounts and sandbox test channels). | No |
| `get_balance` | Prepaid credit (`credit_usd`), plan and sandbox allowance. | No |
| `get_post_status` | Status, price and per-channel delivery state of a post. | No |

You can also use each tool on its own: `SurgemeshQuotePostTool`, `SurgemeshPublishPostTool`, `SurgemeshListChannelsTool`, `SurgemeshGetBalanceTool`, `SurgemeshGetPostStatusTool`. Use the toolkit when you want `publish_post` to accept a `quote_id` from `quote_post`; tools created by one toolkit share their quotes.

## Safety rules built in

- **Nothing posts on its own.** The tools act only when your agent calls them. Installing the package or building the toolkit makes no requests.
- **Quote first.** `publish_post` refuses to run without a `quote_id` from `quote_post` or an explicit `idempotency_key`. With a `quote_id`, the quoted price becomes the post's price cap (`max_price_usd`), so the post is refused rather than charged more.
- **Exactly once.** Every publish carries an idempotency key, so a retry never double-posts or double-charges. A `quote_id` is used for one post.
- **Clear credit errors.** If the account lacks prepaid credit, the tool says so plainly (nothing is scheduled or charged) and points to cheaper times or adding credit.

To ask a person before anything is published, put `publish_post` behind your framework's human-in-the-loop step.

## Configuration

| Setting | Default |
|---|---|
| `api_key` / `SURGEMESH_API_KEY` | required for everything except `quote_post` |
| `base_url` / `SURGEMESH_BASE_URL` | `https://api.surgemesh.com` |

```python
toolkit = SurgemeshToolkit.from_api_key(api_key="sm_...", base_url="https://api.surgemesh.com")
```

Errors raise `SurgemeshError` (with `status`, `code` and `hint`); `InsufficientCreditError` and `QuoteRequiredError` are subclasses. Inside an agent, tools return the error message to the model instead of crashing the run.

## Zero-code alternative: the Surgemesh MCP server

Surgemesh is also a remote MCP server (`com.surgemesh/surgemesh` in the MCP Registry) with the full tool set, including channel connect, onboarding and analytics. With [`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):

```python
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent

client = MultiServerMCPClient({
    "surgemesh": {
        "transport": "streamable_http",
        "url": "https://api.surgemesh.com/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['SURGEMESH_API_KEY']}"},
    }
})
tools = await client.get_tools()
agent = create_agent("openai:gpt-4.1", tools)
```

Use this package when you want a small, typed tool set with the quote-first guard; use MCP when you want every Surgemesh tool.

## Links

- Website: https://surgemesh.com
- API reference (OpenAPI): https://api.surgemesh.com/openapi.json
- Agent guide: https://surgemesh.com/agents
- Terms: https://surgemesh.com/terms · Privacy: https://surgemesh.com/privacy

## License

Apache License 2.0. Copyright 2026 Novus Index, LLC. See LICENSE and NOTICE. "Surgemesh" is a trademark of Novus Index, LLC; the license grants no trademark rights (see TRADEMARKS.md in the repository root). Contact: dev@surgemesh.com
