Metadata-Version: 2.4
Name: arborito-sdk
Version: 0.1.1
Summary: Python SDK for Arborito courses — load .arborito archives and Quiz V2 challenges. Not the browser Arcade SDK (window.arborito).
Author-email: TreeSys <support@treesys.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/treesys-org/arborito-sdk
Project-URL: Repository, https://github.com/treesys-org/arborito-sdk
Project-URL: Documentation, https://github.com/treesys-org/arborito/blob/main/docs/sdk-spec.md
Project-URL: Bug Tracker, https://github.com/treesys-org/arborito-sdk/issues
Keywords: arborito,education,quiz,e-learning,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# Arborito Python SDK

**Python package for Arborito courses** — load `.arborito` exports, parse Quiz V2 `@quiz` blocks, and build your own games or tools.

This repo is **standalone**: clone it, `pip install -e .`, ship a course file with your app. You do not need the Arborito GUI.

Part of the **Treesys ecosystem** (four pillars): [`arborito`](https://github.com/treesys-org/arborito) (app), [`arborito-games`](https://github.com/treesys-org/arborito-games) (browser Arcade), **this repo** (Python), plus public courses published from the app.

## Two SDKs — do not mix them up

| | **Arcade SDK** (browser) | **Python SDK** (this repo) |
|---|--------------------------|----------------------------|
| **Surface** | `window.arborito` | `import arborito_sdk` |
| **Runs in** | HTML cartridge inside the Arborito app | Your Python process (Pygame, CLI, bot, …) |
| **Who picks the course** | The player (module in Arcade) | You at startup (`from_arborito`, `from_library`) |
| **Install** | Bundled with Arborito — no pip | `pip install -e .` |
| **CLI** | — | `arborito-sdk` |
| **Games repo** | [arborito-games](https://github.com/treesys-org/arborito-games) cartridges | This repo + `examples/` |

## Install

**Current version:** `0.1.1` (see `pyproject.toml`).

**From PyPI** — after the first release tag is published:

```bash
pip install arborito-sdk
```

**From GitHub** (recommended until PyPI is live):

```bash
pip install git+https://github.com/treesys-org/arborito-sdk.git
```

**Development** (editable):

```bash
git clone https://github.com/treesys-org/arborito-sdk.git
cd arborito-sdk
pip install -e ".[dev]"
pytest tests/ -q
```

Nostr loads need **`websocket-client`** (declared in `pyproject.toml` and installed automatically with `pip install arborito-sdk` or `pip install -e .`). If you see `No module named 'websocket'`, your environment skipped dependencies — run:

```bash
pip install 'websocket-client>=1.7.0'
# or
pip install --force-reinstall -e .
```

## CLI

Full command reference: **[CLI.md](CLI.md)**.

```bash
arborito-sdk                         # interactive menu + emoji footer
arborito-sdk list course.arborito
arborito-sdk go "Lesson title" course.arborito
arborito-sdk module list course.arborito
arborito-sdk ai ask "question" course.arborito
arborito-sdk ai doctor
arborito-sdk forest join ABCD-EF23
arborito-sdk session login myuser
arborito-sdk story play --module "Chapter" course.arborito
arborito-sdk play narrative --module "Chapter" course.arborito
arborito-sdk lesson read course.arborito
arborito-sdk script json tree course.arborito
arborito-sdk info course.arborito
arborito-sdk show course.arborito
arborito-sdk refresh course.arborito
arborito-sdk quiz course.arborito --rounds 10 --lang ES
arborito-sdk share refresh --code ABCD-EF23
arborito-sdk care due
```

Or: `python -m arborito_sdk list course.arborito`

## Library

```python
from arborito_sdk import Arborito

api = Arborito.from_arborito("course.arborito", lang="EN")
api.tree.modules()
api.module.playlist(api.module.find("Environment"))
api.ask.with_context("what is covered here?", module="Environment")
packet = api.story.start("Chapter 1")  # or api.play.narrative(...)
api.content.games(api.lesson.at(0))          # @game Arcade links
api.play.startLesson(api.lesson.at(0))
```

### API namespaces

| Namespace | Role |
|-----------|------|
| `tree` | Course info, root, find, modules |
| `module` | Playlist, readme, find |
| `lesson` | `by_id`, `set_playlist`, cursor |
| `content` | blocks, frontmatter, `@game` links, `@info` tags |
| `story` | `start`, `advance` (frontmatter narrative) |
| `ask` | `with_context`, `npc`, `json` |
| `play` | `boot`, `startLesson`, `narrative`, `games_in_lesson` |

## Example

`examples/minimal_quiz.py` (~60 lines) — load an export, list lessons, render one quiz card:

```bash
python examples/minimal_quiz.py path/to/course.arborito EN
```

For a full interactive session: `arborito-sdk quiz course.arborito --rounds 10`.

## Loaders

| Method | Status |
|--------|--------|
| `Arborito.from_arborito(path)` | ✅ Ship a pinned `.arborito` with your game (required for course-based games) |
| `Arborito.from_library(root)` / `from_static_data(...)` | ✅ JSON tree under `data/nodes/<lang>/` |
| `Arborito.from_share_code(code, lang=…)` | ✅ Resolve `XXXX-XXXX` on default Arborito relays |
| `Arborito.from_nostr(pub, universe_id, lang=…)` | ✅ Direct `nostr://` reference |
| `subscribe` / `refresh` | ✅ Reload when the publisher updates the bundle |

Export a course from Arborito: **Forest → Branches → Export**.

Python games load a **`.arborito` at startup** (file path, share code, or Nostr ref) — same lesson contract as the browser Arcade.

## Nostr (public trees)

Loads published courses the same way as the Arborito app: share codes (`XXXX-XXXX`) or `nostr://<pub>/<universeId>`. Default relays are Arborito’s suggested bundle (override with `ARBORITO_NOSTR_RELAYS` or `--relay` on the CLI).

```python
api = Arborito.from_share_code("ABCD-EF23", lang="ES")
api.refresh()  # after publisher updates
```

## CI / PyPI

| Trigger | What runs |
|---------|-----------|
| Push to `main` | **SDK Quality** — build wheel + smoke tests |
| Push tag `vX.Y.Z` (e.g. `v0.1.1`) | **Publish to PyPI** — only if PyPI trusted publisher is configured |
| Manual | GitHub Actions → **SDK Quality** or **Publish to PyPI** → Run workflow |

**GitSync → GitHub only.** Treesys maintainers sync this repo from the local monorepo with `gitsync.py`; that does **not** upload to PyPI. To release on PyPI: bump `version` in `pyproject.toml`, GitSync, then push git tag `v0.1.1` matching that version.

### First PyPI release (one-time setup)

1. Create a free account at [pypi.org](https://pypi.org/account/register/).
2. On PyPI → **Your projects** → **Add new project** → name: `arborito-sdk`.
3. On PyPI → project → **Publishing** → **Add a new trusted publisher**:
   - Owner: `treesys-org`
   - Repository: `arborito-sdk`
   - Workflow: `sdk-publish.yml`
   - Environment: *(leave empty)*
4. GitSync the repo to GitHub (needs PAT scope `workflow` for `.github/workflows/`).
5. Bump `version` in `pyproject.toml`, sync, then push git tag `v0.1.1` matching that version.

After setup, users install with `pip install arborito-sdk`. Until the first tag publish, use `pip install git+https://github.com/treesys-org/arborito-sdk.git`.

## Docs

Full API contract (browser + Python): [arborito/docs/sdk-spec.md](https://github.com/treesys-org/arborito/blob/main/docs/sdk-spec.md)

Quiz authoring format: [arborito/docs/QUIZZES-AND-EXAMS.md](https://github.com/treesys-org/arborito/blob/main/docs/QUIZZES-AND-EXAMS.md)

## License

GPL-3.0-or-later — see [`LICENSE`](LICENSE). Third-party runtime dependency: [`NOTICE`](NOTICE).

## Privacy / GDPR

This package is a **developer library**: it loads course files you point at (local `.arborito`, Nostr relays you configure). It does not run a service, collect telemetry, or store learner accounts. **GDPR applies to your app** if you process personal data of EU users (progress, accounts, analytics) — that is your responsibility as the app author, not something this pip package needs a cookie banner for.
