Metadata-Version: 2.4
Name: wysebee
Version: 0.3.0
Summary: A simple cross-platform framework for your AI project.
Author-email: Jeff Xu <zxu@wysebee.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
License-File: LICENSE.txt
Requires-Dist: pyside6>=6.9.0
Requires-Dist: Jinja2>=3.1.2
Requires-Dist: typer>=0.15.2
Requires-Dist: colorama>=0.4.6
Requires-Dist: watchdog==6.0.0
Project-URL: Homepage, https://github.com/wysebee/wysebee
Project-URL: Issues, https://github.com/wysebee/wysebee/issues

# Wysebee

**Wysebee** is a cross-platform application framework for building modern apps with web-technology UIs and Python backends. Write your frontend in HTML/CSS/JS (React, Vanilla, or TypeScript via Vite) and your backend in Python — ship it as a native desktop app powered by **PySide (Qt)**, or as a **FastAPI** web service, from a single project layout.

---

## Features

- **One project, two targets.** Generate a desktop (PySide/Qt) or web (FastAPI) app with the same `wyse init` command.
- **Vite-powered frontends.** First-class support for `react`, `react-ts`, `vanilla`, and `vanilla-ts` templates.
- **Python ↔ JS bridge.** Desktop apps come wired with a `QWebChannel` bridge so your frontend can call Python methods and receive signals.
- **Native app menus.** Declare your menu bar in `menu/menu.json`; Wysebee wires each item to a backend method for you.
- **Drop-in backend.** Subclass `WysebeeBackend` and add `@Slot()` methods — they're instantly callable from JavaScript.
- **Hot reload in dev.** `wyse dev` watches your UI source and rebuilds/reloads the browser view automatically.

---

## Installation

```bash
pip install wysebee
```

This installs the `wyse` CLI alongside the `wysebee` Python package.

---

## Quick start

### 1. Create a new app

```bash
wyse init my-app
```

You'll be prompted to choose `desktop` or `web`. To select a Vite template other than the default React:

```bash
wyse init my-app --template vanilla-ts
```

Supported templates: `react` (default), `react-ts`, `vanilla`, `vanilla-ts`.

### 2. Run it

```bash
cd my-app
python main.py
```

For live reload during development:

```bash
wyse dev
```

### 3. Build the UI

```bash
wyse build --ui
```

---

## Generated project layout

### Desktop app

```
my-app/
├── main.py              # Entry point (QApplication + Wysebee + WysebeeAppMenu)
├── menu/
│   └── menu.json        # Declarative menu bar wired to backend methods
├── src/
│   ├── __init__.py
│   └── backend.py       # MyBackend(WysebeeBackend) — customize Python-side logic
├── ui/                  # Vite project (your frontend)
│   ├── index.html
│   ├── src/
│   └── templates/       # Built output loaded by the desktop window
└── requirements.txt
```

### Web app

```
my-app/
├── main.py              # FastAPI app serving the built UI
├── ui/                  # Vite project
│   └── templates/       # Built output mounted as static files
└── requirements.txt
```

---

## Wiring a native menu (desktop)

`menu/menu.json` maps menu items to methods on your backend by name:

```json
[
  {
    "label": "File",
    "submenu": [
      { "label": "Open", "action": "on_open" },
      { "label": "Save", "action": "on_save" },
      { "separator": true },
      { "label": "Exit", "action": "on_exit" }
    ]
  }
]
```

Implement those methods on your backend:

```python
from PySide6.QtWidgets import QApplication, QFileDialog
from PySide6.QtCore import Slot
from wysebee import WysebeeBackend

class MyBackend(WysebeeBackend):
    @Slot()
    def on_open(self):
        file_path, _ = QFileDialog.getOpenFileName(None, "Open File")
        # ...

    @Slot()
    def on_exit(self):
        QApplication.quit()
```

---

## Calling Python from JavaScript (desktop)

Wysebee exposes your backend to the frontend through `QWebChannel`. The generated `index.html` initializes it and attaches the backend to `window.wysebee`:

```js
window.wysebee.sendMessage("Hello from the frontend!");
```

Any `@Slot(str, result=str)` method on your backend is callable this way.

---

## CLI reference

| Command | Description |
| --- | --- |
| `wyse init <name> [--template ...]` | Scaffold a new desktop or web app. |
| `wyse dev` | Build the UI and run the app in development mode (hot reload). |
| `wyse build --ui` | Build only the frontend (`npm run build` inside `ui/`). |

---

## Links

- Homepage: [wysebee.io](https://wysebee.io)
- Source: [github.com/wysebee/wysebee](https://github.com/wysebee/wysebee)
- Issues: [github.com/wysebee/wysebee/issues](https://github.com/wysebee/wysebee/issues)

---

## License

MIT

