Metadata-Version: 2.4
Name: jupyter-chat-widget
Version: 0.2.0
Summary: A simple chat UI widget for Jupyter notebooks
Project-URL: Homepage, https://github.com/zansara/jupyter-chat-widget
Project-URL: Documentation, https://github.com/zansara/jupyter-chat-widget#readme
Project-URL: Repository, https://github.com/zansara/jupyter-chat-widget
Project-URL: Issues, https://github.com/zansara/jupyter-chat-widget/issues
Author-email: github@zansara.dev
License-Expression: MIT
License-File: LICENSE
Keywords: chat,ipywidgets,jupyter,llm,notebook,ui
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: ipywidgets<8.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# jupyter-chat-widget

A simple chat UI widget for Jupyter notebooks with streaming response support, designed to integrate easily with LLM APIs.

[![CI](https://github.com/zansara/jupyter-chat-widget/workflows/CI/badge.svg)](https://github.com/zansara/jupyter-chat-widget/actions)
[![Docs](https://github.com/zansara/jupyter-chat-widget/workflows/Deploy%20Docs/badge.svg)](https://zansara.github.io/jupyter-chat-widget/)
[![PyPI version](https://badge.fury.io/py/jupyter-chat-widget.svg)](https://badge.fury.io/py/jupyter-chat-widget)
[![Python versions](https://img.shields.io/pypi/pyversions/jupyter-chat-widget.svg)](https://pypi.org/project/jupyter-chat-widget/)

## Installation

```bash
pip install jupyter-chat-widget
```

## Quick Start

```python
from jupyter_chat_widget import ChatUI

# Create the chat widget
chat = ChatUI()

# Define a handler for user messages
def handle_message(message: str) -> None:
    # Stream a response token by token
    for word in message.split():
        chat.append(word + " ")

# Connect the handler
chat.connect(handle_message)
```

## Documentation

See the [live documentation](https://zansara.github.io/jupyter-chat-widget/) or the [example notebook](examples/basic_usage.ipynb) in `examples/`.

## API Reference

### `ChatUI`

The main chat widget class.

#### Methods

| Method | Description |
|--------|-------------|
| `connect(callback)` | Connect a callback function to handle user messages |
| `append(token)` | Append text to the current assistant response (streaming) |
| `rewrite(text)` | Replace the entire assistant response |
| `clear()` | Clear all chat history and current response |

#### Example: Streaming Responses

```python
from jupyter_chat_widget import ChatUI
from time import sleep

chat = ChatUI()

def slow_echo(message: str) -> None:
    """Echo back the message word by word."""
    for word in message.split():
        sleep(0.5)  # Simulate processing time
        chat.append(word + " ")
    chat.rewrite(f"You said: {message}")

chat.connect(slow_echo)
```

#### Example: Integration with LLM

```python
from jupyter_chat_widget import ChatUI

chat = ChatUI()

def llm_handler(message: str) -> None:
    """Stream responses from an LLM API."""
    # Replace with your LLM API call
    for token in your_llm_api.stream(message):
        chat.append(token)

chat.connect(llm_handler)
```

## Development

```bash
# Clone the repository
git clone https://github.com/zansara/jupyter-chat-widget.git
cd jupyter-chat-widget

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src tests
ruff format src tests

# Build the package
python -m build
```

### Pre-commit Hooks

```bash
# Install pre-commit hooks
pre-commit install

# Run hooks on all files
pre-commit run --all-files
```

## License

MIT License - see [LICENSE](LICENSE) for details.
