Metadata-Version: 2.4
Name: divoom-agent
Version: 0.1.0
Summary: Opinionated semantic API for Divoom ambient displays — ambient.thinking(), ambient.shipped(), etc.
Author: Orion Parrott
License: MIT
Keywords: divoom,ambient,ai-agent,led-matrix,pixel-art,status-display
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: divoom-protocol>=0.1
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Provides-Extra: voice
Requires-Dist: httpx>=0.27; extra == "voice"
Requires-Dist: numpy>=1.24; extra == "voice"
Provides-Extra: voice-full
Requires-Dist: httpx>=0.27; extra == "voice-full"
Requires-Dist: numpy>=1.24; extra == "voice-full"
Requires-Dist: sounddevice>=0.4; extra == "voice-full"
Requires-Dist: matplotlib>=3.7; extra == "voice-full"

# divoom-agent

Opinionated semantic ambient API for Divoom pixel panels. Translates concepts like "the agent is thinking" or "the build shipped" into visual patterns (color + animation).

This is the **middle layer** of a three-library stack:

```
divoom-protocol  ← bytes/BLE/encoder. No AI, no opinions.
divoom-agent     ← THIS PACKAGE. Semantic API. Opinions about color and motion live here.
divoom-agent-mcp ← MCP server. Exposes the agent to LLMs as tools.
```

## Status

Alpha. APIs may shift before 1.0. Built and validated against the v0.2 `divoom-protocol` BLE decode.

## Install

```bash
pip install -e .[dev]
pytest                              # run pattern unit tests
python examples/status_demo.py      # walk through the status vocabulary on a real panel
```

## API

```python
from divoom_agent import DivoomAgent

async with await DivoomAgent.create() as agent:
    # Ambient status — loops until replaced or stopped
    await agent.status_thinking()       # slow blue breath
    await agent.status_working()        # amber pulse
    await agent.status_success()        # green flash → dim green hold
    await agent.status_error()          # red flash → dim red hold
    await agent.status_alert(level=2)   # severity 1=yellow / 2=orange / 3=red

    # Discrete notifications
    await agent.notify_shipped()        # green checkmark
    await agent.notify_celebrate()      # rainbow burst
    await agent.notify_message()        # blue dot pulse

    # Progress
    await agent.progress_percentage(50) # static fill bar
    await agent.progress_indeterminate()# orbiting comet

    # Direct/raw escape hatches
    await agent.paint(pixels_16x16)     # 256 RGB tuples, your own pixel art
    await agent.color(255, 0, 255)      # solid Lighting magenta
    await agent.brightness(50)
    await agent.clear()                 # black panel
    await agent.clock()                 # built-in clock channel

    # Generative
    await agent.start_mondrian(fps=2.0) # ambient Mondrian cycle

    # Streaming control
    await agent.start_stream(frames, fps=4.0)
    await agent.stop_animation()        # cancel any running animation
```

Each method that starts an animation cancels the previous one — you don't need to manually stop before switching status. `paint()`, `color()`, and `clear()` also stop animations.

## Design philosophy

- **Small visual vocabulary, recognizable from across a room.** Blue=thinking, green=success, red=error, amber=working, yellow→orange→red for severity. Same conventions as traffic lights and OS notification badges.
- **Loops, not one-shots.** Status patterns loop indefinitely because ambient state is ambient — the panel keeps showing it until something changes.
- **Calm by default.** Thinking is a slow 2s breath, not a frantic flash. The panel should not demand attention; you should be able to glance at it.
- **Notifications are still loops.** A "shipped" notification holds the dim green so you don't miss it if you weren't looking when the flash happened. Move to a different status to clear.

## Customization

Visual patterns live in `divoom_agent/patterns.py`. Each is a small pure function that returns a list of 16x16 frames. Edit colors, brightness curves, or pulse rates there — no need to touch the agent state machine.

## License

MIT.
