Metadata-Version: 2.4
Name: langchain-claw-messenger
Version: 0.1.0
Summary: Send one controlled Claw Messenger message from LangChain and prove the matching reply in the tool
Author-email: Emotion Machine <hello@emotionmachine.ai>
License-Expression: Apache-2.0
Project-URL: Documentation, https://clawmessenger.com/docs
Project-URL: Homepage, https://clawmessenger.com
Project-URL: Repository, https://github.com/emotion-machine-org/claw-messenger
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pydantic :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core<2,>=0.3
Requires-Dist: websockets<17,>=13
Provides-Extra: test
Requires-Dist: build<2,>=1.2; extra == "test"
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: pytest-asyncio<2,>=0.24; extra == "test"
Requires-Dist: ruff<1,>=0.9; extra == "test"
Requires-Dist: twine<7,>=6; extra == "test"
Dynamic: license-file

# Claw Messenger for LangChain

Use this package to send one controlled plain-text message from LangChain to a registered E.164 phone and prove the same thread works when the matching reply reaches the active tool invocation.

It is intentionally not a persistent inbound listener, webhook server, delivery guarantee, group-messaging tool, or general conversation store. An accepted, delivered, or read outbound status is not proof that the two-way setup works. The controlled reply must reach the tool before it returns `proof_status: reply_received`.

## Install

Install the public package from PyPI:

```bash
python3 -m pip install langchain-claw-messenger
```

## Credentials

Set your API key outside code, notebooks, screenshots, and logs:

```bash
export CLAW_API_KEY="cm_live_REDACTED"
export CONTROLLED_TEST_PHONE_E164="+14155550101"
```

For a release proof, use a regenerated key for a test tenant and revoke it when the run is complete.

## Quick controlled proof

```python
import os

from langchain_claw_messenger import create_claw_messenger_tool

tool = create_claw_messenger_tool()
result = tool.invoke(
    {
        "recipient_e164": os.environ["CONTROLLED_TEST_PHONE_E164"],
        "message": "This is my Claw Messenger test. Reply yes.",
        "timeout_seconds": 300,
    }
)
print(result)
```

The person holding the controlled phone must reply in the same thread while the tool is waiting. Count the run as successful only when the returned JSON includes:

```json
{
  "proof_status": "reply_received",
  "reply_source": "controlled_recipient"
}
```

The named reply observation point for this proof is the active LangChain tool invocation. Do not count accepted, delivered, or read outbound status as reply proof.

Possible proof states are:

- `reply_received`: the matching reply reached this tool invocation.
- `send_failed`: Claw Messenger rejected or failed the outbound request.
- `reply_timeout`: no matching reply reached this invocation before its deadline.
- `configuration_error`: the key, recipient, message, or timeout was invalid.

In an async LangChain app, use `await tool.ainvoke(...)`. The synchronous `invoke` path deliberately refuses to nest another event loop.

## Agent use

Bind the returned `StructuredTool` to the LangChain model or agent runtime you already use:

```python
tools = [create_claw_messenger_tool()]

# Bind `tools` to your existing LangChain model or agent runtime.
# Instruct the agent to use only a registered recipient and to call setup
# complete only when proof_status is reply_received.
```

The tool reads `CLAW_API_KEY` by default. You can instead pass `api_key=` at construction time, but never put a real key in source control.

## Current scope

- One plain-text outbound message to one registered E.164 recipient.
- Truthful `send.result` status fields.
- One matching inbound reply observed during the same tool call.
- Sanitized message and chat identifier hints rather than raw identifiers.

The tool stops listening when it returns. Use your own long-running WebSocket consumer or webhook for persistent inbound handling.

## Release verification

Each release must pass the same checks used by the n8n and CrewAI packages:

1. Keep the package metadata and bundled `LICENSE` file on the approved Apache 2.0 license.
2. Use package-scoped PyPI publisher access without placing credentials in the repository, examples, screenshots, or logs.
3. Regenerate a test-tenant API key specifically for this proof. Never reuse a production key.
4. Name one controlled registered E.164 phone, a person ready to reply, and the active LangChain tool invocation as the reply observation point.
5. Build, test, check, and install the wheel in a clean virtual environment.
6. Send one short plain-text message, then reply once from the controlled phone in the same thread while the tool is waiting.
7. Retain only sanitized evidence showing `proof_status: reply_received` for the matching thread. Accepted, delivered, or read outbound status alone does not pass this gate.
8. Revoke the regenerated test key.
9. Publish only after explicit approval. Release notes and maintainer contact remain separate decisions.

Claw Messenger documentation: <https://clawmessenger.com/docs>
