nuagent 0.1.2__tar.gz → 0.2.0__tar.gz

nuagent-0.2.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/

nuagent-0.2.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: nuagent
+Version: 0.2.0
+Summary: nuagent: the model answers in Nu, Nu runs the answer.
+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: nucore>=0.6.4
+Requires-Dist: nuskills>=0.1.0
+Requires-Dist: nustd[kv]>=0.6.4
+Provides-Extra: cc
+Requires-Dist: nustd[cc]; extra == 'cc'
+Provides-Extra: llm
+Requires-Dist: nustd[llm]; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# nuagent
+
+The model answers in Nu, Nu runs the answer. A small loop: prompt, reply, build, run, observe, repeat until the model ends the run. Storage and backends are presets around it.
+
+Early and unsettled: the package is a skeleton, the API is not there yet.

nuagent-0.2.0/README.md

@@ -0,0 +1,5 @@
+# nuagent
+
+The model answers in Nu, Nu runs the answer. A small loop: prompt, reply, build, run, observe, repeat until the model ends the run. Storage and backends are presets around it.
+
+Early and unsettled: the package is a skeleton, the API is not there yet.

nuagent-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nuagent"
+version = "0.2.0"
+description = "nuagent: the model answers in Nu, Nu runs the answer."
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Gor Arakelyan", email = "gorarkln@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    # The core needs only nu. nuspace hosting comes later as separate packages.
+    "nucore>=0.6.4",
+    "nustd[kv]>=0.6.4",
+    # The generic Nu prose the opening prompt is assembled from.
+    "nuskills>=0.1.0",
+]
+
+[project.optional-dependencies]
+# The cc backend drives Claude Code through nustd.cc, on the local claude login.
+cc = [
+    "nustd[cc]",
+]
+# The llm backend talks to a stateless endpoint through nustd.llm.
+llm = [
+    "nustd[llm]",
+]
+
+[project.urls]
+Repository = "https://github.com/nustackdev/nuverse"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nuagent"]

nuagent-0.2.0/src/nuagent/__init__.py

@@ -0,0 +1,9 @@
+"""nuagent: the model answers in Nu, Nu runs the answer.
+
+- :mod:`.core`: the loop, one turn after another until the model ends the run.
+- :mod:`.protocol`: what the model is told about replying in Nu.
+- :mod:`.prompt`: the opening prompt, the protocol plus nuskills, the catalogue and the world.
+- :mod:`.presets`: what you swap: the store and the backend.
+"""
+
+__version__ = "0.2.0"

nuagent-0.2.0/src/nuagent/core/__init__.py

@@ -0,0 +1,16 @@
+"""The loop: prompt, reply, extract, load, eval, observe, next prompt.
+
+- :mod:`.loop`: :func:`agent`, :func:`turn`, :func:`seed`, the mem
+  :class:`Run` the model ends the run through, and the :class:`Store` and
+  :class:`Backend` seams.
+- :mod:`.program`: :func:`extract` the program from a reply, :func:`attempt`
+  it into a typed outcome.
+"""
+
+from __future__ import annotations
+
+from .loop import Backend, Run, Store, agent, seed, turn
+from .program import FENCE, attempt, extract
+
+
+__all__ = ["FENCE", "Backend", "Run", "Store", "agent", "attempt", "extract", "seed", "turn"]

nuagent-0.2.0/src/nuagent/core/loop.py

@@ -0,0 +1,205 @@
+"""The loop: one turn, and that turn under a ``WhileDo`` until the model ends the run.
+
+A turn is one prompt and one response, then the program in it::
+
+    read the conversation        short bracket   -> plain data
+    ask(conversation)            no bracket      -> text
+    reply, message, program      short bracket
+    attempt(program)             no bracket      -> outcome    the program runs exactly once
+    outcome, observation         short bracket
+
+Every step writes a session slot, so a watcher reads the run's progress off
+state and the loop has no hooks. The conversation is a list that grows by
+append and is never rebuilt or cut.
+
+**The model ends the run, and nothing else does.** It redeclares the store's
+``run`` Shape in its own module and sets ``done`` in the program that
+finishes the work. There is no turn counter, budget or stall guard here, and
+no predicate over the world: a predicate tests what a program did, not
+whether the task is done. Limits like those are layers around the loop,
+never inside it.
+
+**The core knows no storage and no backend.** A :class:`Store` brings the
+session Shape (``messages``, ``reply``, ``program``, ``outcome``), the run
+Shape, and two brackets: ``bracket`` around the loop's own short session
+steps, ``rewrite`` around anything on the world (``done``, the state line,
+the model's program, which it gets through ``LoadNu``). Neither is ever held
+across the backend's answer or the program's run, so a store that locks
+(one sqlite file for session and world) never waits on itself. The backend
+is any :class:`Backend`: it answers a conversation with text and wraps the
+whole run in whatever it needs open for it (a process, a session id, a
+client). What it does between prompt and response is its own business.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+import nu
+from nuagent.protocol import observation
+
+from .program import attempt, extract
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from nu.lang import Nu, StrArg
+
+
+__all__ = ["Backend", "Run", "Store", "agent", "seed", "turn"]
+
+
+class Run(nu.Shape):
+    """The run itself, on mem: the model sets ``done`` and the loop stops after that turn.
+
+    Notes:
+        - Untagged and flat on purpose. The model redeclares it in its own
+          module, which makes a different class, and only an untagged Shape
+          is reached by both: a tagged one is a store the model's ``Run``
+          never writes, and the run would never end.
+        - The mem store's run. A store with its world elsewhere brings its
+          own one-slot Shape on that fabric.
+    """
+
+    done = nu.BoolRef.slot()
+
+
+class Store(Protocol):
+    """Where a run keeps its session and its world, and how a term reaches them.
+
+    Attributes:
+        session: the session Shape, slots ``messages``, ``reply``,
+            ``program`` and ``outcome``.
+        run: the world's one-slot Shape the model ends the run through.
+    """
+
+    session: type[nu.Shape]
+    run: type[nu.Shape]
+
+    def bracket(self, body: Nu) -> Nu:
+        """``body``, a short step on the session, ready to run on the session's store."""
+        ...
+
+    def rewrite(self, term: Nu) -> Nu:
+        """``term``, a read or write on the world, ready to run on the world's store.
+
+        The model's program is one: it reaches this through ``LoadNu``'s
+        ``rewrite``, so it gets its brackets without knowing it needs any.
+        """
+        ...
+
+    def bound(self, body: Nu) -> Nu:
+        """``body`` with the session's store and the world's bound around it."""
+        ...
+
+
+class Backend(Protocol):
+    """What the loop needs from a model: an answer, and a scope to run in."""
+
+    def ask(self, messages: Nu) -> Nu:
+        """The model's reply to the conversation, as a Str-yielding term.
+
+        Args:
+            messages: the conversation as plain data, a list of
+                ``{role, content}`` dicts read out of the session before the
+                ask. A stateless backend sends them all, a stateful one the
+                newest.
+        """
+        ...
+
+    def wrap(self, body: Nu) -> Nu:
+        """The whole run inside whatever the backend holds open for its lifetime."""
+        ...
+
+
+def seed(store: Store, prompt: StrArg) -> Nu:
+    """Open a run: the conversation is the prompt alone, and the run is not done.
+
+    Args:
+        store: the store the run keeps its session and world in.
+        prompt: the opening message as the caller composed it (the protocol,
+            the Nu prose, the task). Sent as the first ``user`` message, so
+            every backend reads the run the same way.
+
+    Returns:
+        A Command.
+
+    Notes:
+        - ``done`` is written False before the first turn. Unset it reads
+          EMPTY, the loop condition is never true, and no turn runs.
+    """
+    opening = nu.Dict.of(role="user", content=prompt)
+    return store.bracket(store.session.messages.set(nu.List.of(opening))) >> store.rewrite(
+        store.run.done.set(False)
+    )
+
+
+def turn(store: Store, ask: Callable[[Nu], Nu], *, state: Nu | None = None) -> Nu:
+    """One turn: ask, extract, attempt, observe.
+
+    Args:
+        store: the store the run keeps its session and world in.
+        ask: the backend's ``ask``.
+        state: what the model sees of the world after each run, a read on
+            the world. Omitted, the observation is the outcome alone.
+
+    Returns:
+        A term, one turn, ready to run once or under a loop.
+
+    Notes:
+        - The slow parts, the ask and the program's run, sit outside every
+          bracket. What crosses between steps is plain data held in a
+          ``nu.let``: the conversation, the reply, the source, the outcome.
+        - The program runs once. Its outcome is held, then written to a slot
+          and rendered into the observation from the held value.
+        - The reply goes into the conversation as soon as it is in, so the
+          conversation holds it even when what follows fails.
+    """
+    session = store.session
+
+    def asked(said: Nu) -> Nu:
+        """The conversation is read: ask it, then take the answer."""
+        return nu.let(ask(said), answered)
+
+    def answered(text: Nu) -> Nu:
+        """The reply is in: take the source out of it."""
+        return nu.let(extract(text), lambda source: kept(text, source))
+
+    def kept(text: Nu, source: Nu) -> Nu:
+        """Keep the reply, its message and its source, then run the source on the world."""
+        said = nu.Dict.of(role="assistant", content=text)
+        keep = (
+            session.reply.set(text) >> session.messages.append(said) >> session.program.set(source)
+        )
+        ran = attempt(source, reply=text, rewrite=store.rewrite)
+        return store.bracket(keep) >> nu.let(ran, observed)
+
+    def observed(out: Nu) -> Nu:
+        """The program ran: read the world for the observation, then keep both."""
+        return nu.let(store.rewrite(observation(out, state)), lambda told: noted(out, told))
+
+    def noted(out: Nu, told: Nu) -> Nu:
+        """Keep the outcome and send the observation as the next message."""
+        said = nu.Dict.of(role="user", content=told)
+        return store.bracket(session.outcome.set(out) >> session.messages.append(said))
+
+    return nu.let(store.bracket(session.messages.extract()), asked)
+
+
+def agent(store: Store, backend: Backend, prompt: StrArg, *, state: Nu | None = None) -> Nu:
+    """The whole run: seed, then turns until the model sets ``done``.
+
+    Args:
+        store: the store the run keeps its session and world in. Bind it
+            around this term with ``store.bound``.
+        backend: answers each turn and wraps the run.
+        prompt: the opening message.
+        state: what the model sees of the world after each run.
+
+    Returns:
+        The run as one term, inside the backend's wrap.
+    """
+    going = store.rewrite(store.run.done.not_())
+    body = seed(store, prompt) >> nu.WhileDo(going, turn(store, backend.ask, state=state))
+    return backend.wrap(body)

nuagent-0.2.0/src/nuagent/core/program.py

@@ -0,0 +1,134 @@
+"""The model's program: taken out of the reply, built, run once, and told as an outcome.
+
+Two terms, both evaluated inside the turn. A Python helper here would be a
+hole in the tree, and a tree with a hole runs nowhere but the host process.
+
+**Extract** takes the first fenced block. A model correcting itself quotes
+the broken version first, and a model adding an illustration puts it last,
+so neither choice is always right. First is the safer one: re-reading broken
+code costs a turn, running an illustration does something nobody asked for.
+A reply with no complete block is used whole, which is right for bare source
+and wrong for prose. Extract cannot tell the two apart. Attempt can.
+
+**Attempt** builds the program with ``LoadNu`` and runs it with ``Eval``,
+once. The store's ``rewrite`` lands the built term on the world (on kv it
+brackets it), and the yield is read out as plain data and repr'd inside that
+landing, while the store is still open. Its own yield is the outcome record, and the error type picks the branch
+that writes it: a ``ConstructionError`` is ``construct`` (or ``no_code``,
+when the reply had no fence to begin with), anything else ``runtime``.
+Nothing downstream reads labels out of text. The repr sits inside the inner
+catch, so a failure is never repr'd and never arrives quoted.
+
+A failure is the model's input, not the loop's crash. Source that builds and
+then raises is as much the model's mistake as source that does not parse,
+so both are caught and both become the next thing it reads.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import nu
+import nu.prog
+from nu.domains.shape.interactions import Extract
+from nuagent.protocol import CONSTRUCT, NO_CODE, OK, RUNTIME
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from nu.lang import Nu, StrArg
+
+
+__all__ = ["FENCE", "Shown", "attempt", "extract", "fenced"]
+
+
+#: What opens and closes a block. Code sits at the odd indices of the split.
+FENCE = "```"
+
+
+def fenced(reply: StrArg) -> Nu:
+    """Whether the reply holds a complete block: a Bool term, three chunks or more."""
+    return nu.Str(reply).split(FENCE).len() >= 3
+
+
+def extract(reply: StrArg) -> Nu:
+    """The source in the reply's first fenced block, or the whole reply when there is none.
+
+    Args:
+        reply: the model's text, a str or any Str-yielding term.
+
+    Returns:
+        A ``Str`` term: the block's body with its ``python``/``py`` tag gone,
+        stripped. Fewer than three chunks means no complete block, and then
+        it is the reply itself, stripped.
+    """
+    text = nu.Str(reply)
+    chunks = text.split(FENCE)
+    block = nu.Str(chunks[1]).removeprefix("python").removeprefix("py").strip()
+    return nu.Str(nu.If(fenced(reply), block, text.strip()))
+
+
+class Shown:
+    """A ``LoadNu`` rewrite: the program's yield as plain data, repr'd, then landed.
+
+    A class rather than a closure so a load carrying it pickles.
+
+    Args:
+        landing: the store's ``rewrite``. None leaves the term where it is.
+
+    Notes:
+        - The repr sits inside the landing, so a kv view the program yields
+          is read out while its bracket is open. Outside it, a view is a
+          lazy handle and its repr says nothing.
+    """
+
+    __slots__ = ("landing",)
+
+    def __init__(self, landing: Callable[[Nu], Nu] | None = None) -> None:
+        self.landing = landing
+
+    def __call__(self, term: Nu) -> Nu:
+        """The term's yield, materialised and repr'd, on the world."""
+        shown = nu.Repr(Extract(term))
+        return shown if self.landing is None else self.landing(shown)
+
+
+def attempt(
+    program: Nu, *, reply: StrArg | None = None, rewrite: Callable[[Nu], Nu] | None = None
+) -> Nu:
+    """Build the program, run it once, and yield what happened as an outcome record.
+
+    Args:
+        program: the source, a ``ProgramRef`` or any Str-yielding term.
+        reply: the raw reply the source came from. Given, a construction
+            failure on a reply with no complete fence is ``no_code``, so a
+            model is never handed a parser error about its own English.
+        rewrite: the store's ``rewrite``, applied to the built term before
+            it runs. Omitted, the term runs as it was built.
+
+    Returns:
+        A dict term, one of:
+        ``{kind: ok, value}``, ``{kind: no_code}``,
+        ``{kind: construct, message, line}`` (``line`` is None when the
+        failure has no source position), ``{kind: runtime, message}``.
+    """
+    ran = nu.Dict.of(kind=OK, value=nu.Eval(nu.LoadNu(program, rewrite=Shown(rewrite))))
+
+    def built(err: Nu) -> Nu:
+        """The construction failure, off the Diagnostic the error carries."""
+        diagnostic = err.exception.diagnostic
+        failed = nu.Dict.of(kind=CONSTRUCT, message=diagnostic.message, line=diagnostic.lineno)
+        if reply is None:
+            return failed
+        return nu.If(fenced(reply), failed, nu.Dict.of(kind=NO_CODE))
+
+    def raised(err: Nu) -> Nu:
+        """The runtime failure: the error's type, then its text."""
+        typed = nu.Str(nu.GetAttr(nu.Type(err.exception), "__name__"))
+        return nu.Dict.of(kind=RUNTIME, message=typed + ": " + err)
+
+    return nu.TryCatch(
+        nu.TryCatch(ran, catch=built, errors=nu.prog.ConstructionError),
+        catch=raised,
+    )

nuagent-0.2.0/src/nuagent/presets/__init__.py

@@ -0,0 +1 @@
+"""What you swap around the loop: the store and the backend."""

nuagent-0.2.0/src/nuagent/presets/backends/__init__.py

@@ -0,0 +1,11 @@
+"""Backends behind one interface, a conversation in and text out.
+
+Each is its own module with one class that satisfies
+:class:`nuagent.core.Backend`, imported by name so a run pays only for the
+backend it uses, and the core imports none of them:
+
+- :mod:`.cc`: Claude Code, stateful. One session for the run, the newest
+  message per turn (``nuagent[cc]``).
+- :mod:`.llm`: an OpenAI-compatible chat endpoint, stateless. The whole
+  conversation every turn (``nuagent[llm]``).
+"""