Metadata-Version: 2.5
Name: marimo-pets
Version: 0.1.0
Summary: Floating notebook companions with cell awareness and contextual AI help.
Project-URL: Homepage, https://github.com/ktaletsk/marimo-pets
Project-URL: Repository, https://github.com/ktaletsk/marimo-pets
Project-URL: Issues, https://github.com/ktaletsk/marimo-pets/issues
Author: Konstantin Taletskiy
License-Expression: MIT
License-File: LICENSE
Keywords: anywidget,marimo,notebook,pets,widget
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: anywidget<1,>=0.9.18
Requires-Dist: pydantic-ai>=2.42.0
Requires-Dist: traitlets<6,>=5.14
Provides-Extra: marimo
Requires-Dist: marimo==0.24.0; extra == 'marimo'
Description-Content-Type: text/markdown

# marimo-pets 🌱

A little company for your code. Floating, draggable notebook companions built
with [anywidget](https://anywidget.dev/): **Mo the mossball**, **Clippy**,
**Jimothy the raccoon**, and **Crab**, in that order.

Your pet can celebrate a finished task, react to Python, and help you ask marimo's
AI about the cell you're working on.

## Install

From PyPI:

```sh
pip install "marimo-pets[marimo]"
```

From a checkout:

```sh
pip install -e ".[marimo]"
marimo edit examples/companions.py
```

You can also install the source directly:

```sh
pip install "marimo-pets[marimo] @ git+https://github.com/ktaletsk/marimo-pets.git"
```

Requires Python 3.10+. The `marimo` extra installs the tested marimo 0.24.0 version.
Runtime dependencies include anywidget, traitlets, and pydantic-ai.

## Meet your companion

```python
from marimo_pets import NotebookPet

pet = NotebookPet()  # Mo by default
pet
```

Display the instance once per page. Choose an avatar in the dashboard or set
`mode="clippy"`, `mode="jimothy"`, or `mode="crab"` when constructing it.

Drag the avatar, speech bubble, or name bar. Arrow keys move a focused avatar or
name bar. Click to pet, give a pep talk, or send your pal for a nap. **Wander**
adds an occasional stroll; movement respects reduced-motion preferences.

```python
pet.say("Let's figure this out.", mood="thinking")
pet.celebrate("The experiment worked!")
pet.snooze()
pet.mode = "crab"
pet.position = [80, 140]
pet.wander = True

with pet.task("Running an experiment…", done="All done!"):
    result = sum(range(100_000))
```

`task()` celebrates success and propagates exceptions or cancellation after
displaying a supportive message. Speech is rendered as literal text.

| Attribute | Default | Meaning |
| --- | --- | --- |
| `mode` | `"mo"` | `mo`, `clippy`, `jimothy`, or `crab` |
| `mood` | `"idle"` | `idle`, `thinking`, `celebrating`, or `sleeping` |
| `message` | Avatar greeting | Speech bubble text |
| `pets` | `0` | Number of pets received |
| `visible` | `True` | Show or hide the companion |
| `minimized` | `False` | Collapse the speech and secondary actions |
| `wander` | `False` | Enable occasional wandering |
| `position` | `[]` | Initial automatic placement, or `[left, top]` in viewport pixels |

Position, mood, and other traits synchronize between Python and rendered views.
Each browser clamps the position to its own viewport. Use one displayed instance
per page to get one floating pet.

## Help with this

Click a notebook cell or select text, then choose **Help with this** on your pal.
The **What Mo sees** inspector shows the chosen cell, cells in view, code, and
selected text. Its title follows the selected avatar.

- **Ask marimo AI** opens marimo's chat and submits your question with native
  cell-output or error references. Cells without a usable reference include code
  in the prompt instead.
- **Open as draft** prepares a question for review and preserves an existing
  visible chat draft.
- **Question preview** shows the prompt and offers a copy button.

The pet uses your configured marimo AI provider and chat settings. Awareness
stays local to this browser view until you ask; it is not synchronized to Python
or other viewers. It observes this notebook document, not your desktop or other
tabs. Marimo may add further notebook context or output images according to its
normal chat settings. The generated prompt asks for an answer in chat, without
editing or running cells unless you explicitly ask.

**Experimental:** native chat support currently targets one verified marimo
0.24.0 frontend build. Its adapter uses internal frontend interfaces, so other
builds fall back to DOM context and a copyable question. See
[compatibility and context details](docs/compatibility.md).

## React to petting in marimo

In the cell that creates the pet:

```python
pet = NotebookPet()
get_pets, set_pets = mo.state(pet.pets)
pet.observe(lambda _: set_pets(pet.pets), names=["pets"])
pet
```

In another cell:

```python
mo.md(f"**{get_pets()}** pets received.")
```

The [example notebook](examples/companions.py) demonstrates this along with a
Python task and contextual help.

## Develop

```sh
uv sync
uv run marimo edit examples/companions.py
uv run pytest
node --test tests/frontend/*.test.mjs
uv run ruff check .
uv run ruff format --check .
uv run marimo check examples/companions.py
uv build
uv run twine check dist/*
```

Python lives in `src/marimo_pets/pet.py`; the bundled frontend is
`src/marimo_pets/static/widget.js`. There is no JavaScript build step. For live
frontend updates, launch marimo with `ANYWIDGET_HMR=1`.

## Credits

Inspired by Vincent Warmerdam's
[wigglystuff FloatingPanel](https://koaning.github.io/wigglystuff/reference/floating-panel/).
Mo's body, little feet, and sprout are inspired by
[Mo the Mossball from Wanderland](https://taletskiy.com/blogs/wanderland/).
Jimothy is the very round raccoon; Crab is a separate mode, for parity.
The avatars are SVG illustrations bundled with the widget.

[MIT license](LICENSE).
