nudemos 0.1.0__tar.gz

nudemos-0.1.0/.gitignore

@@ -0,0 +1,103 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+# The nuspace-ui package links its build/ to the vite output so an editable
+# install serves it. A symlink, not a directory, but say so explicitly.
+!pkgs/ts/nuspace-ui/python/nuspace_ui/build
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# uv
+uv.lock
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDEs
+.idea/
+.vscode/
+
+.DS_Store
+
+# Profiling
+*.prof
+*.lprof
+
+# Benchmarking
+benchmark_results/
+*.benchmark
+*.benchmarks
+
+# Ruff
+.ruff_cache/
+
+# Misc
+/*playground
+.db*/
+.state*/
+.logs*/
+
+# syncthing
+.stfolder
+
+# nuspace-ui (vite / node)
+node_modules/
+!src/nuspace/web/ui/dist/
+src/nuspace/web/ui/dist/*
+!src/nuspace/web/ui/dist/.gitkeep
+
+*.db/
+*.nuspace/
+# Local archive of the v0 prototype (reference only, never edited)
+_archive/

nudemos-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: nudemos
+Version: 0.1.0
+Summary: The Nu demos as nuspace Planes: a counter, a sampled series, a film base and MNIST trained live.
+Project-URL: Repository, https://github.com/nustackdev/nuverse
+Author-email: Gor Arakelyan <gorarkln@gmail.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: nuspace
+Provides-Extra: agents
+Requires-Dist: nustd[cc]; extra == 'agents'
+Provides-Extra: memes
+Requires-Dist: nustd[http]; extra == 'memes'
+Provides-Extra: mnist
+Requires-Dist: torch>=2.2; extra == 'mnist'
+Requires-Dist: torchvision>=0.17; extra == 'mnist'
+Description-Content-Type: text/markdown
+
+# nudemos
+
+The Nu demos as [nuspace](https://github.com/nustackdev/nuspace) Planes `+` creates, under Demos:
+
+- **Counter**: a count ticking once a second, kept in its cell's state.
+- **Sampled**: a series that grows forever, charted from a reservoir sample.
+- **Movies**: a film base where every film and person is its own live page.
+- **MNIST**: train a small CNN, steer it while it trains, and track every run. Needs the `mnist` extra.
+- **Memes**: a live terminal over the meme market on Solana: launches, trades and every coin's page, synced from public mainnet. Needs the `memes` extra.
+- **Agents**: Claude Code sessions run, watched, steered and orchestrated from a space. One agent is one Claude Code session in a page, driven by a short Nu loop; fan-out with a judge, chains and task boards are a few lines of Nu each. Needs the `agents` extra and a logged-in `claude` CLI, no API key.
+- **Nu demos**: all three at once, nested under one plane.
+
+```
+pip install nudemos
+```
+
+nuspace finds it on install through the `nuspace.extensions` entry point. You don't import it yourself.
+
+## MNIST
+
+Launch picks the knobs (optimizer, learning rate, batch size, channels, epochs, dropout) and starts a run: a page, and a headless job under it that trains in its own process. A run page shows the curves, twelve test digits and what the model reads in each, and every layer's weights and gradients over training. Drag the learning rate while it trains, stop it, resume it. Compare lines the runs up. Read puts a run's model to work: pick a run and its latest or best checkpoint, draw a digit, and it reads it on every stroke, showing the 28x28 image the model sees. Pick a run that is still training, or just launch one (the page follows the newest run until you pick), and the same drawing is read again as each checkpoint lands.
+
+Nu owns the loop, torch owns the step: the job cell is a Nu loop over a trainer resource, reading its learning rate from state each chunk. Close the space mid run and open it again: the run carries on from its last checkpoint.
+
+Models live in the space, not in files: each run keeps its latest checkpoint (what it resumes from) and the weights at its best test score, in its own state.
+
+```
+pip install "nudemos[mnist]"
+```
+
+MNIST downloads once, on the first run, into `~/.cache/nuverse-mnist` (`$NUVERSE_MNIST_DATA` to move it). Runs train on cuda, or mps on Apple silicon, else the cpu (`$NUVERSE_MNIST_DEVICE` to pick). Three epochs take about a minute on a laptop cpu.

nudemos-0.1.0/README.md

@@ -0,0 +1,31 @@
+# nudemos
+
+The Nu demos as [nuspace](https://github.com/nustackdev/nuspace) Planes `+` creates, under Demos:
+
+- **Counter**: a count ticking once a second, kept in its cell's state.
+- **Sampled**: a series that grows forever, charted from a reservoir sample.
+- **Movies**: a film base where every film and person is its own live page.
+- **MNIST**: train a small CNN, steer it while it trains, and track every run. Needs the `mnist` extra.
+- **Memes**: a live terminal over the meme market on Solana: launches, trades and every coin's page, synced from public mainnet. Needs the `memes` extra.
+- **Agents**: Claude Code sessions run, watched, steered and orchestrated from a space. One agent is one Claude Code session in a page, driven by a short Nu loop; fan-out with a judge, chains and task boards are a few lines of Nu each. Needs the `agents` extra and a logged-in `claude` CLI, no API key.
+- **Nu demos**: all three at once, nested under one plane.
+
+```
+pip install nudemos
+```
+
+nuspace finds it on install through the `nuspace.extensions` entry point. You don't import it yourself.
+
+## MNIST
+
+Launch picks the knobs (optimizer, learning rate, batch size, channels, epochs, dropout) and starts a run: a page, and a headless job under it that trains in its own process. A run page shows the curves, twelve test digits and what the model reads in each, and every layer's weights and gradients over training. Drag the learning rate while it trains, stop it, resume it. Compare lines the runs up. Read puts a run's model to work: pick a run and its latest or best checkpoint, draw a digit, and it reads it on every stroke, showing the 28x28 image the model sees. Pick a run that is still training, or just launch one (the page follows the newest run until you pick), and the same drawing is read again as each checkpoint lands.
+
+Nu owns the loop, torch owns the step: the job cell is a Nu loop over a trainer resource, reading its learning rate from state each chunk. Close the space mid run and open it again: the run carries on from its last checkpoint.
+
+Models live in the space, not in files: each run keeps its latest checkpoint (what it resumes from) and the weights at its best test score, in its own state.
+
+```
+pip install "nudemos[mnist]"
+```
+
+MNIST downloads once, on the first run, into `~/.cache/nuverse-mnist` (`$NUVERSE_MNIST_DATA` to move it). Runs train on cuda, or mps on Apple silicon, else the cpu (`$NUVERSE_MNIST_DEVICE` to pick). Three epochs take about a minute on a laptop cpu.

nudemos-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nudemos"
+version = "0.1.0"
+description = "The Nu demos as nuspace Planes: a counter, a sampled series, a film base and MNIST trained live."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Gor Arakelyan", email = "gorarkln@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "nuspace",
+]
+
+[project.optional-dependencies]
+mnist = [
+    "torch>=2.2",
+    "torchvision>=0.17",
+]
+# The memes demo's JSON-RPC calls go through nustd.http.
+memes = [
+    "nustd[http]",
+]
+# The agents demo drives Claude Code through nustd.cc, on the local claude login.
+agents = [
+    "nustd[cc]",
+]
+
+[project.urls]
+Repository = "https://github.com/nustackdev/nuverse"
+
+[project.entry-points."nuspace.extensions"]
+nudemos = "nudemos:extension"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nudemos"]

nudemos-0.1.0/src/nudemos/__init__.py

@@ -0,0 +1,43 @@
+"""nudemos: the Nu demos as nuspace Planes.
+
+- :mod:`.counter`: a count ticking once a second, in its cell's state.
+- :mod:`.sampled`: a kh57 series growing forever, charted from a sample.
+- :mod:`.tour`: the two above, nested under one plane.
+- :mod:`.movies`: a film base, every film and person its own live page.
+- :mod:`.mnist`: a CNN trained on MNIST, steered live, every run tracked. Needs the ``mnist`` extra.
+- :mod:`.memes`: a live terminal over a meme market, synced from Solana.
+- :mod:`.agents`: Claude Code sessions, run, steered and orchestrated from a space.
+
+nuspace finds this package through the ``nuspace.extensions`` entry point,
+which names :func:`extension`. Nothing is imported here at module scope.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from nuspace import Extension
+
+
+__all__ = ["extension"]
+
+
+def extension() -> Extension:
+    """The tour and the demo planes, as one extension."""
+    from nuspace import Extension
+
+    from . import agents, counter, memes, mnist, movies, sampled, tour
+
+    return Extension(
+        planes=(
+            tour.PLANE,
+            counter.PLANE,
+            sampled.PLANE,
+            movies.PLANE,
+            mnist.PLANE,
+            memes.PLANE,
+            agents.PLANE,
+        )
+    )

nudemos-0.1.0/src/nudemos/agents/__init__.py

@@ -0,0 +1,44 @@
+"""The ``agents`` Plane: Claude Code sessions run, watched, steered and orchestrated from a space.
+
+Nu is the control plane, Claude Code does the work. One agent is one Claude
+Code session: a page that streams its transcript, and a headless job under
+the page whose one cell is a short Nu loop over a ``nustd.cc.Session``
+(:mod:`.job`), taking each message from the agent's state and streaming the
+turn back into it. The pages around it only read and steer that state.
+
+Orchestration is plain Nu over agents, no framework: a flow is a headless job
+whose cell asks agents, waits on them and reads their answers through a
+:class:`~.flows.Team` (:mod:`.flows`). Three ship, each a plane under this one
+showing its cell in full: Fan-out and judge, Chain, Task board.
+
+- :mod:`.claude`, :mod:`.job`: the Claude Code endpoint, and the agent's loop over it.
+- :mod:`.launch`: making an agent, saying something to it, stopping and resuming it.
+- :mod:`.flows`: the :class:`~.flows.Team` terms and the three flows, as cell sources.
+- :mod:`.board`, :mod:`.page`, :mod:`.orchestrate`: the planes, as cell sources.
+- :mod:`.views`, :mod:`.state`: what the cells read and how they shape it.
+
+Talking to Claude Code needs the ``claude-agent-sdk`` package (the ``cc`` extra
+of nustd) and a logged-in ``claude`` CLI. No API key: it runs on the login.
+"""
+
+from __future__ import annotations
+
+from nuspace import Plane
+
+from . import board, orchestrate
+
+
+__all__ = ["PLANE"]
+
+
+PLANE = Plane(
+    "agents",
+    "Agents",
+    icon="bot",
+    description="Claude Code sessions, run, steered and orchestrated from a space.",
+    meta={"editable": True, "full_width": True},
+    cells=(("intro", board.INTRO), ("new", board.NEW), ("board", board.BOARD)),
+    children=(orchestrate.FANOUT_PLANE, orchestrate.CHAIN_PLANE, orchestrate.TASKS_PLANE),
+    group="Demos",
+    backend="async",
+)

nudemos-0.1.0/src/nudemos/agents/board.py

@@ -0,0 +1,189 @@
+"""The Agents plane's own cells: what it is, a form that starts agents, and a card per agent.
+
+- ``intro``: what the plane is, and where the flows are.
+- ``new``: name, folder, model, permission mode and a brief, and two buttons:
+  Start agent makes one agent page with its job (:func:`~.launch.launch`) and
+  opens it; Run the demo starts the Fan-out flow on the built-in scenario,
+  three builders and a judge.
+- ``board``: every agent as a card, live: its status, what it is doing, what it cost.
+"""
+
+from __future__ import annotations
+
+
+__all__ = ["BOARD", "INTRO", "NEW"]
+
+
+INTRO = '''\
+import nu
+import nustd.ui
+from nuspace import ops
+from nuspace.system.utils import snap
+
+TEXT = """\\
+Claude Code sessions, run, watched, steered and orchestrated from a space, with Nu as the control plane.
+
+One agent is one Claude Code session: a page that streams everything it says and does, and a headless job \\
+under it that runs a short Nu loop over the session. Say something and it is the agent's next turn. \\
+Stop it mid-turn, resume it later: it picks up the same conversation, even after the space restarts.
+
+Orchestration is a few lines of Nu over agents, each flow a plane with its cell in full: \\
+**Fan-out** (N agents on one brief, a judge picks the best), **Chain** (research, build, review) \\
+and **Task board** (idle agents pull the next task).
+"""
+
+
+class Links(nustd.ui.Row):
+    fanout = nustd.ui.LinkRef.slot()
+    chain = nustd.ui.LinkRef.slot()
+    tasks = nustd.ui.LinkRef.slot()
+
+
+class View(nustd.ui.Column):
+    text = nustd.ui.MarkdownRef.slot()
+    links = Links.slot(gap=4)
+
+
+def links(kids):
+    def to(i):
+        return nu.Str("/") + nu.Str(nu.List(kids)[i])
+
+    L = View.links
+    return (
+        L.fanout.set(href=to(0), label="Fan-out and judge") >> L.chain.set(href=to(1), label="Chain")
+        >> L.tasks.set(href=to(2), label="Task board")
+    )
+
+
+def out(plane):
+    return View.text.set(TEXT) >> nu.let(snap(ops.children(plane)), links) >> nu.ForeverDo(nu.Delay(3600.0))
+'''
+
+
+NEW = """\
+import nu
+import nustd.ui
+from nuspace import ops
+from nuspace.system.utils import snap
+from nudemos.agents import views
+from nudemos.agents.claude import READY
+from nudemos.agents.flows import SCENARIO, launch_flow
+from nudemos.agents.launch import launch
+from nudemos.agents.state import agents_of, flows_of, made_by
+
+
+def pick(options):
+    return type("Pick", (nustd.ui.Field,), {"choice": nustd.ui.SelectRef.slot(options=options)})
+
+
+class Who(nustd.ui.Grid):
+    name = nustd.ui.InputRef.slot(label="Name", placeholder="Name it, or leave it to us")
+    cwd = nustd.ui.InputRef.slot(label="Working folder", placeholder="A fresh temp folder")
+    model = pick(views.MODELS).slot(label="Model")
+    mode = pick(views.MODES).slot(label="Permission mode")
+
+
+class Go(nustd.ui.Row):
+    start = nustd.ui.ButtonRef.slot(label="Start agent", icon="play")
+    demo = nustd.ui.ButtonRef.slot(label="Run the demo: 3 builders and a judge", variant="secondary", icon="git-fork")
+
+
+class View(nustd.ui.Column):
+    nav = nustd.ui.NavRef.slot()
+    notice = nustd.ui.MarkdownRef.slot()
+    head = nustd.ui.HeadingRef.slot(level=4)
+    who = Who.slot(columns=4, min_width=180, gap=3)
+    brief = nustd.ui.TextAreaRef.slot(rows=3, auto_resize=True, placeholder="The brief: what should it do?")
+    go = Go.slot(gap=2, align="end")
+
+
+W = View.who
+
+
+def started(root):
+    # One agent from what the form says, its page opened.
+    def made(spec):
+        def opened(page):
+            return launch(root, spec, page=page) >> views.go(View.nav, nu.Str("/") + nu.Str(page))
+
+        return nu.let("", opened) >> W.name.set("") >> View.brief.set("")
+
+    count = snap(agents_of(root).len())
+    spec = views.spec_of(
+        nu.Str(W.name), nu.Str(W.cwd), nu.Str(W.model.choice), nu.Str(W.mode.choice), nu.Str(View.brief), count
+    )
+    return nu.let(spec, made)
+
+
+def demo(root):
+    # The built-in scenario: the Fan-out flow, three builders and a judge, on one brief.
+    fanout = nu.First(ops.children(root).iter().filter(lambda p: made_by(p) == "agents_fanout"))
+
+    def run(plane):
+        name = nu.Str("Fan-out ") + nu.str(nu.Int(snap(flows_of(plane).len())) + 1)
+        spec = nu.Dict.of(brief=SCENARIO, n=3, tasks=[])
+        return launch_flow(nu.Str(plane), root, "fanout", spec, name)
+
+    return nu.let(snap(nu.str(fanout).fallback("")), run)
+
+
+def defaults():
+    return (
+        View.head.set("New agent") >> W.name.set("") >> W.cwd.set("")
+        >> W.model.choice.set(views.MODELS[0]) >> W.mode.choice.set(views.MODES[0])
+        >> View.brief.set("") >> View.go.start.set("Start agent", icon="play")
+        >> View.go.demo.set("Run the demo: 3 builders and a judge", variant="secondary", icon="git-fork")
+    )
+
+
+def out(plane):
+    if not READY:
+        return View.notice.set(views.MISSING) >> nu.ForeverDo(nu.Delay(3600.0))
+    root = nu.Str(plane)
+    return defaults() >> nu.ParallelAsync(
+        nu.ReactForever(View.go.start.on_click(), started(root)),
+        nu.ReactForever(View.go.demo.on_click(), demo(root)),
+    )
+"""
+
+
+BOARD = """\
+import nu
+import nustd.ui
+from nuspace.shapes import Space
+from nuspace.system.utils import redraws
+from nudemos.agents import views
+
+
+class AgentCard(nustd.ui.Card):
+    pill = nustd.ui.StatusPillRef.slot()
+    doing = nustd.ui.TextRef.slot()
+    stats = nustd.ui.TextRef.slot()
+    open = nustd.ui.LinkRef.slot(label="Open")
+
+
+class View(nustd.ui.Column):
+    head = nustd.ui.HeadingRef.slot(level=4)
+    empty = nustd.ui.EmptyStateRef.slot(label="No agents yet", description="Start one above, or run the demo.")
+    cards = nustd.ui.GridRef.slot(AgentCard, columns=3, min_width=280, gap=3)
+
+
+def card(c):
+    k = View.cards[c["key"]]
+    return (
+        k.set_title(c["name"]) >> k.set_subtitle(c["where"]) >> k.pill.set(c["status"], tone=c["tone"])
+        >> k.doing.set(c["doing"]) >> k.stats.set(c["stats"]) >> k.open.set(href=c["href"], label="Open")
+    )
+
+
+def draw(cards):
+    each = nu.ForEachDo(nu.List(cards), card)
+    return nu.IfDo(nu.List(cards).len() > 0, View.empty.erase() >> each)
+
+
+def out(plane):
+    kids = Space.planes[plane].children.on_change()
+    return View.head.set("All agents") >> View.empty.set("No agents yet") >> redraws(
+        [kids], views.cards(views.board(plane)), draw, every=1.0
+    )
+"""

nudemos-0.1.0/src/nudemos/agents/claude.py

@@ -0,0 +1,31 @@
+"""The Service an agent's job speaks to Claude Code through.
+
+One streamed endpoint over ``nustd.cc``: a call is one turn, its events
+handed over as they happen. Here, in a module, and not in the job's cell,
+so the term that names it can travel to the job's worker process.
+
+Importing this needs the ``claude-agent-sdk`` package; the planes check for
+it before they start any agent (:data:`READY`).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+
+import nu
+
+
+__all__ = ["READY", "Claude"]
+
+
+#: Whether the Claude Agent SDK is here to talk to Claude Code with.
+READY = importlib.util.find_spec("claude_agent_sdk") is not None
+
+
+if READY:
+    import nustd.cc
+
+    class Claude(nu.Service):
+        """An agent's one Claude Code endpoint: a turn, streamed."""
+
+        say = nustd.cc.StreamRef.method()