arborito-sdk 0.1.0__py3-none-any.whl

arborito_sdk/__init__.py

@@ -0,0 +1,36 @@
+"""Arborito Python SDK — load courses and Quiz V2 outside the browser.
+
+This is **not** the Arcade cartridge SDK injected as ``window.arborito`` in HTML
+games. Use this package for terminal tools, Pygame, desktop apps, bots, etc.
+
+Install: ``pip install -e .``  CLI: ``arborito-sdk``  Import: ``arborito_sdk``
+"""
+
+__version__ = '0.1.0'
+
+from .archive import load_arborito_archive
+from .client import Arborito, User, attach_helpers
+from .errors import (
+    AI_EMPTY_RESPONSE,
+    AI_NETWORK,
+    AI_PARSE_ERROR,
+    AI_SAGE_ERROR,
+    AI_TIMEOUT,
+    ArboritoError,
+    ERROR_CODES,
+)
+
+__all__ = [
+    '__version__',
+    "Arborito",
+    "User",
+    "attach_helpers",
+    "load_arborito_archive",
+    "ArboritoError",
+    "ERROR_CODES",
+    "AI_TIMEOUT",
+    "AI_SAGE_ERROR",
+    "AI_PARSE_ERROR",
+    "AI_EMPTY_RESPONSE",
+    "AI_NETWORK",
+]

arborito_sdk/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m arborito_sdk`` — same as the ``arborito-sdk`` CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

arborito_sdk/archive.py

@@ -0,0 +1,51 @@
+"""Load lessons from exported .arborito archives."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .quiz_v2 import (
+    clean_lesson_text,
+    load_arborito_archive as _load_archive,
+    parse_all_challenges_from_content,
+)
+
+
+def load_arborito_archive(path: str | Path, lang: str = "ES") -> list[dict[str, Any]]:
+    """Walk an `.arborito` ZIP and return its leaf/exam lessons in order.
+
+    The archive's folder layout is the source of truth (no `tree:` block in
+    the manifest), so we just reconstruct the in-memory tree and iterate
+    through every leaf / exam node, preserving the on-disk ordering.
+    """
+    data = _load_archive(path)
+    languages = (data.get("tree") or {}).get("languages") or {}
+    lang_key = lang.upper()
+    root = languages.get(lang_key) or languages.get("ES") or next(iter(languages.values()), None)
+    if not root:
+        raise ValueError(f"No language tree in {path}")
+
+    lessons: list[dict[str, Any]] = []
+
+    def walk(node: dict[str, Any]) -> None:
+        ntype = node.get("type")
+        if ntype in ("leaf", "exam"):
+            raw = node.get("content") or ""
+            challenges = parse_all_challenges_from_content(raw)
+            lesson: dict[str, Any] = {
+                "id": node["id"],
+                "title": node.get("name") or node["id"],
+                "text": clean_lesson_text(raw),
+                "raw": raw,
+            }
+            if challenges:
+                lesson["challenge"] = challenges[0]
+                lesson["challenges"] = challenges
+            lessons.append(lesson)
+        for child in node.get("children") or []:
+            if isinstance(child, dict):
+                walk(child)
+
+    walk(root)
+    return lessons

arborito_sdk/cli.py

@@ -0,0 +1,322 @@
+"""Arborito Python SDK CLI — browse ``.arborito`` courses from the terminal.
+
+Not the Arborito desktop app. Not the browser Arcade SDK (``window.arborito``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from .client import Arborito
+from .errors import ArboritoError
+from .nostr_protocol import normalize_tree_share_code, parse_nostr_tree_url
+
+
+_CLI_MSG = {
+    "ES": {
+        "pick": "Elige (número, q=salir): ",
+        "correct": "¡Correcto!",
+        "wrong": "Incorrecto —",
+        "skip_order": "(Modos chips/pasos: implementa tu propia UI con buildCard.)",
+        "skip_enter": "Enter para continuar, q=salir: ",
+        "correct_label": "Respuesta:",
+        "score": "Puntuación:",
+        "session_end": "Sesión terminada.",
+        "no_session": "No hay sesión jugable (árbol vacío o sin @quiz).",
+        "play_hint": "Consejo: exporta un curso con bloques @quiz, o ejecuta: arborito-sdk quiz course.arborito",
+        "play_start": "Sesión Arborito. Escribe respuestas; q para salir.\n",
+    },
+    "EN": {
+        "pick": "Pick (number, q=quit): ",
+        "correct": "Correct!",
+        "wrong": "Wrong —",
+        "skip_order": "(Chips/steps: build your own UI with buildCard.)",
+        "skip_enter": "Press Enter to continue, q=quit: ",
+        "correct_label": "Correct:",
+        "score": "Score:",
+        "session_end": "Session ended.",
+        "no_session": "No playable session (empty tree or no quiz blocks?).",
+        "play_hint": "Tip: export a course with @quiz blocks, or run: arborito-sdk quiz course.arborito",
+        "play_start": "Arborito play session. Type answers; q to quit.\n",
+    },
+}
+
+
+def _cli(lang: str) -> dict[str, str]:
+    key = lang.upper() if lang.upper() in _CLI_MSG else "EN"
+    return _CLI_MSG[key]
+
+
+def _load_api(path: Path, lang: str) -> Arborito:
+    if not path.is_file():
+        raise FileNotFoundError(f"Not found: {path}")
+    return Arborito.from_arborito(path, lang=lang, username="cli", avatar="🌳")
+
+
+def _load_api_source(
+    *,
+    lang: str,
+    arborito: Path | None = None,
+    code: str | None = None,
+    nostr_url: str | None = None,
+    relays: list[str] | None = None,
+) -> tuple[Arborito, str]:
+    if sum(1 for x in (arborito, code, nostr_url) if x) != 1:
+        raise ValueError("Provide exactly one source: file path, --code, or --nostr.")
+    if code:
+        api = Arborito.from_share_code(code, lang=lang, relays=relays, username="cli", avatar="🌳")
+        label = f"share:{normalize_tree_share_code(code) or code}"
+        return api, label
+    if nostr_url:
+        ref = parse_nostr_tree_url(nostr_url)
+        if not ref:
+            raise ValueError(f"Invalid Nostr tree URL: {nostr_url}")
+        api = Arborito.from_nostr(
+            ref["pub"],
+            ref["universe_id"],
+            lang=lang,
+            relays=relays,
+            username="cli",
+            avatar="🌳",
+        )
+        return api, f"nostr:{ref['pub'][:12]}…/{ref['universe_id']}"
+    assert arborito is not None
+    return _load_api(arborito, lang), str(arborito.name)
+
+
+def cmd_info(api: Arborito, label: str) -> int:
+    lessons = api.lesson.list()
+    challenges = sum(len(api.challenge.fromLesson(api.lesson.at(i))) for i in range(len(lessons)))
+    print(f"Course:      {label}")
+    print(f"Lessons:     {len(lessons)}")
+    print(f"Challenges:  {challenges}")
+    print(f"Language:    {api.user.lang}")
+    print(f"AI mode:     {api.getAIMode()}")
+    return 0
+
+
+def cmd_lessons(api: Arborito) -> int:
+    items = api.lesson.list()
+    for i, title in enumerate(items):
+        lesson = api.lesson.at(i)
+        n = len(api.challenge.fromLesson(lesson)) if lesson else 0
+        tag = f" ({n} quiz)" if n else ""
+        print(f"{i:3d}  {title}{tag}")
+    return 0
+
+
+def cmd_show(api: Arborito, index: int) -> int:
+    lesson = api.lesson.at(index)
+    if not lesson:
+        print(f"No lesson at index {index}", file=sys.stderr)
+        return 1
+    title = lesson.get("title") or "?"
+    text = (lesson.get("text") or "").strip()
+    print(f"# {title}\n")
+    print(text or "(empty body)")
+    challenges = api.challenge.fromLesson(lesson)
+    if challenges:
+        print(f"\n--- {len(challenges)} challenge block(s) ---")
+        for j, c in enumerate(challenges):
+            concept = c.get("core_concept") or "?"
+            modes = ", ".join(api.challenge.modes.playable(c)) or "none"
+            print(f"  [{j}] {concept} · modes: {modes}")
+    return 0
+
+
+def _read_line(prompt: str) -> Optional[str]:
+    try:
+        raw = input(prompt).strip()
+    except (EOFError, KeyboardInterrupt):
+        return None
+    if raw.lower() in ("q", "quit", "exit"):
+        return None
+    return raw
+
+
+def cmd_quiz(api: Arborito, rounds: int, mode_only: Optional[str]) -> int:
+    """Minimal interactive quiz (multiple / cloze / chips / …)."""
+    msg = _cli(api.user.lang)
+    score = 0
+    attempted = 0
+    lessons = [api.lesson.at(i) for i in range(len(api.lesson.list()))]
+    for lesson in lessons:
+        if attempted >= rounds:
+            break
+        if not lesson:
+            continue
+        for challenge in api.challenge.fromLesson(lesson):
+            if attempted >= rounds:
+                break
+            playable = api.challenge.modes.playable(challenge)
+            if mode_only:
+                if mode_only not in playable:
+                    continue
+                mode = mode_only
+            else:
+                if not playable:
+                    continue
+                mode = playable[0]
+            card = api.challenge.modes.buildCard(
+                challenge,
+                mode,
+                lesson_title=lesson.get("title") or "",
+                lang=api.user.lang,
+            )
+            if not card:
+                continue
+            attempted += 1
+            title = (lesson.get("title") or "?")[:50]
+            print(f"\n--- {attempted}/{rounds} · {title} [{mode}] ---")
+            print(f"Q: {card.get('question')}")
+            options = list(card.get("options") or [])
+            if mode in ("multiple", "recall", "cloze") and options:
+                for i, opt in enumerate(options, 1):
+                    print(f"  {i}) {opt}")
+                raw = _read_line(msg["pick"])
+                if raw is None:
+                    break
+                if raw.isdigit() and 1 <= int(raw) <= len(options):
+                    ok = options[int(raw) - 1].strip().lower() == str(card["correct"]).strip().lower()
+                    if ok:
+                        score += 1
+                        print(msg["correct"])
+                    else:
+                        print(f"{msg['wrong']} {card['correct']}")
+            elif mode in ("chips", "steps"):
+                chips = list(card.get("chips") or [])
+                for i, chip in enumerate(chips, 1):
+                    print(f"  {i}) {chip}")
+                print(msg["skip_order"])
+                raw = _read_line(msg["skip_enter"])
+                if raw is None:
+                    break
+            else:
+                print(f"({msg['correct_label']} {card.get('correct')})")
+                raw = _read_line(msg["skip_enter"])
+                if raw is None:
+                    break
+    print(f"\n{msg['score']} {score}/{attempted}")
+    return 0
+
+
+def cmd_play(api: Arborito) -> int:
+    msg = _cli(api.user.lang)
+    session = api.play.boot()
+    if not session:
+        print(msg["no_session"], file=sys.stderr)
+        print(msg["play_hint"], file=sys.stderr)
+        return 1
+    print(msg["play_start"])
+    while session and not session.get("done"):
+        task = session.get("currentTask")
+        if task:
+            q = task.get("question") or task.get("prompt") or task.get("label") or ""
+            if q:
+                print(q)
+        line = _read_line("> ")
+        if line is None:
+            break
+        result = api.play.submit(line or "")
+        reply = result.get("output") or result.get("message") or ""
+        if reply:
+            print(reply)
+        session = api.play.snapshot()
+    print(msg["session_end"])
+    return 0
+
+
+def _add_common_args(sp: argparse.ArgumentParser) -> None:
+    sp.add_argument("--lang", default="ES", help="Course language code (ES, EN, …).")
+    sp.add_argument(
+        "arborito",
+        nargs="?",
+        type=Path,
+        help="Path to a .arborito archive (omit when using --code or --nostr).",
+    )
+    sp.add_argument("--code", metavar="XXXX-XXXX", help="Public share code (loads from Nostr).")
+    sp.add_argument("--nostr", metavar="URL", help="nostr://<pubhex>/<universeId>")
+    sp.add_argument(
+        "--relay",
+        action="append",
+        dest="relays",
+        metavar="wss://…",
+        help="Extra relay (repeatable). Defaults match Arborito suggested relays.",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="arborito-sdk",
+        description="Arborito Python SDK — browse .arborito courses and run quizzes.",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    for name, help_text in (
+        ("info", "Summary of a course."),
+        ("lessons", "List lesson titles."),
+        ("show", "Print one lesson body."),
+        ("quiz", "Run an interactive quiz session."),
+        ("play", "Start a text play session (SDK play loop)."),
+        ("refresh", "Reload a Nostr-backed course if the publisher updated it."),
+    ):
+        sp = sub.add_parser(name, help=help_text)
+        _add_common_args(sp)
+        if name == "show":
+            sp.add_argument("--index", type=int, default=0, help="Lesson index (see `lessons`).")
+        if name == "quiz":
+            sp.add_argument("--rounds", type=int, default=5, help="Max challenges to play.")
+            sp.add_argument(
+                "--mode",
+                choices=["multiple", "recall", "cloze", "chips", "steps"],
+                help="Restrict to one quiz modality.",
+            )
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    lang = args.lang.upper()
+    relays = getattr(args, "relays", None)
+    try:
+        api, label = _load_api_source(
+            lang=lang,
+            arborito=getattr(args, "arborito", None),
+            code=getattr(args, "code", None),
+            nostr_url=getattr(args, "nostr", None),
+            relays=relays,
+        )
+    except FileNotFoundError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    except (ArboritoError, ValueError) as e:
+        print(f"Failed to load course: {e}", file=sys.stderr)
+        return 2
+
+    cmd = args.command
+    if cmd == "info":
+        return cmd_info(api, label)
+    if cmd == "lesson" or cmd == "lessons":
+        return cmd_lessons(api)
+    if cmd == "show":
+        return cmd_show(api, args.index)
+    if cmd == "quiz":
+        return cmd_quiz(api, args.rounds, getattr(args, "mode", None))
+    if cmd == "play":
+        return cmd_play(api)
+    if cmd == "refresh":
+        if not getattr(api, "_nostr_ref", None):
+            print("Not a Nostr-backed course (use --code or --nostr).", file=sys.stderr)
+            return 1
+        changed = api.refresh()
+        print("Updated from relays." if changed else "No change on relays.")
+        return 0
+    print(f"Unknown command: {cmd}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())