Metadata-Version: 2.4
Name: letterbook-ai-chat
Version: 1.1.0
Summary: Python SDK for sending AI chat turns and explicit support conversations to Letterbook
Author: Letterbook
License: MIT
Keywords: ai,chat,helpdesk,letterbook,support
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: otel
Requires-Dist: opentelemetry-api<1.34,>=1.0; (python_version < '3.9') and extra == 'otel'
Requires-Dist: opentelemetry-api<1.42,>=1.0; (python_version >= '3.9' and python_version < '3.10') and extra == 'otel'
Requires-Dist: opentelemetry-api<2.0,>=1.0; (python_version >= '3.10') and extra == 'otel'
Description-Content-Type: text/markdown

# Letterbook Python SDK

Send AI chat turns or explicit support events to Letterbook so customer issues become conversations.

## Turn-based detection

Each `record_turn` call captures one turn in the conversation. It does not create a ticket by itself. Letterbook queues the turns, waits for the conversation to go quiet, scans the transcript on the backend with an LLM, and creates a ticket only when it finds a relevant customer issue.

```python
import letterbook

result = letterbook.record_turn(
    user_id="user123",
    event="user_message",
    model="gpt_4",
    input="The checkout page is broken and I was charged twice.",
    output="I am sorry, I cannot fix billing issues from here.",
    convo_id="conv789",
    customer_email="customer@example.com",
    debounce_seconds=300,
    properties={
        "system_prompt": "you are a helpful assistant",
        "experiment": "experiment_a",
    },
    attachments=[
        {
            "type": "text",
            "name": "Additional Info",
            "value": "A very long document",
            "role": "input",
        }
    ],
)

print(result.queued, result.evaluation_after_seconds)
```

Set `LETTERBOOK_API_KEY`, or instantiate `letterbook.Letterbook(api_key=...)` for explicit configuration.
Set `debounce_seconds` to control how long Letterbook waits after the last message before evaluating the conversation.
If OpenTelemetry is configured in your app, the SDK automatically propagates the active trace context with each capture request. You can install `letterbook-ai-chat[otel]` if your app does not already include OpenTelemetry.

If `customer_email` is omitted, the SDK looks for `properties["customer_email"]`, `properties["email"]`, or an email-shaped `user_id`.
Email is only required if Letterbook promotes the capture to a ticket.

`letterbook.capture_turn(...)` and `letterbook.capture(...)` are deprecated compatibility aliases for `letterbook.record_turn(...)`.

## Push-based conversation creation

When your app already knows a tool call should create a support conversation, call `create_conversation` directly.

```python
conversation = letterbook.create_conversation(
    customer_email="customer@example.com",
    customer_name="Customer",
    subject="Checkout tool failed",
    message="The checkout tool failed after charging the card twice.",
    priority="high",
    external_id="tool-call-123",
    metadata={
        "source": "ai_tool",
        "session_id": "session_789",
    },
)

print(conversation.id, conversation.url)
```

## API-key REST helpers

The SDK also wraps the existing API-key endpoints:

```python
letterbook.list_conversations(status="open", page_size=50)
letterbook.get_conversation("conv_123")
letterbook.add_conversation_note(
    "conv_123",
    author_email="agent@example.com",
    content="Investigated from the external workflow.",
    mentioned_user_emails=["teammate@example.com"],
)
letterbook.delete_user("user_123", confirm_email="agent@example.com")
```

## Framework adapters

Framework adapters are optional and do not add hard dependencies to the base SDK. Install the framework package separately, then import adapters from `letterbook.integrations`.
Pass a stable `convo_id` such as your chat session, thread, or conversation id when using turn-based detection. Framework run/event ids are per model call and are not used as fallbacks because they split one transcript into separate evaluations.

LangChain:

```python
from langchain_openai import ChatOpenAI
from letterbook.integrations import create_langchain_callback_handler

handler = create_langchain_callback_handler(
    user_id="user123",
    model="gpt_4",
    convo_id="conv789",
    customer_email="customer@example.com",
)

model = ChatOpenAI(callbacks=[handler])
```

LlamaIndex:

```python
from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from letterbook.integrations import create_llamaindex_callback_handler

handler = create_llamaindex_callback_handler(
    user_id="user123",
    model="gpt_4",
    convo_id="conv789",
    customer_email="customer@example.com",
)

Settings.callback_manager = CallbackManager([handler])
```
