agentbuild 0.0.1__py3-none-any.whl

agentbuild/__init__.py

@@ -0,0 +1,10 @@
+"""Tools to make agent research easier."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agentbuild")
+except PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

agentbuild/jupyter.py

@@ -0,0 +1,162 @@
+"""IPython magics for working with Jupyter notebooks.
+
+Load them in a notebook with ``%load_ext agentbuild.jupyter``. Notebooks exported from
+Databricks work too: their cells are identified by the Databricks cell ID (``nuid``) and can
+also be referred to by their title.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from IPython.core.error import UsageError
+from IPython.core.magic import Magics, line_magic, magics_class
+from IPython.core.magic_arguments import argument, magic_arguments, parse_argstring
+
+Cell = dict[str, Any]
+
+DATABRICKS_CELL_METADATA = "application/vnd.databricks.v1+cell"
+
+
+def read_notebook_cells(path: str | Path) -> list[Cell]:
+    """Return the cells of a notebook file."""
+    with open(Path(path).expanduser(), encoding="utf-8") as f:
+        notebook = json.load(f)
+    if notebook.get("nbformat") != 4:
+        raise ValueError(f"{path} is not an nbformat 4 notebook")
+    return notebook["cells"]
+
+
+def cell_source(cell: Cell) -> str:
+    source = cell.get("source", "")
+    return "".join(source) if isinstance(source, list) else source
+
+
+def _databricks_metadata(cell: Cell) -> dict[str, Any]:
+    return cell.get("metadata", {}).get(DATABRICKS_CELL_METADATA) or {}
+
+
+def cell_ids(cell: Cell) -> list[str]:
+    """Return the cell's Jupyter ID and Databricks ID (``nuid``), whichever it has."""
+    ids = [cell.get("id"), _databricks_metadata(cell).get("nuid")]
+    return [i for i in ids if i]
+
+
+def cell_title(cell: Cell) -> str:
+    """Return the cell's Databricks title, or "" if it has none."""
+    return _databricks_metadata(cell).get("title") or ""
+
+
+def find_cell(cells: list[Cell], ref: str) -> Cell:
+    """Return the one cell that ``ref`` names.
+
+    ``ref`` is tried, in order, as an exact cell ID, an exact Databricks title, a title
+    ignoring case, and the start of a cell ID.
+    """
+    matchers: list[Callable[[Cell], bool]] = [
+        lambda cell: ref in cell_ids(cell),
+        lambda cell: ref == cell_title(cell),
+        lambda cell: ref.casefold() == cell_title(cell).casefold(),
+        lambda cell: any(i.startswith(ref) for i in cell_ids(cell)),
+    ]
+    for matches in matchers:
+        positions = [i for i, cell in enumerate(cells) if matches(cell)]
+        if len(positions) == 1:
+            return cells[positions[0]]
+        if positions:
+            listed = ", ".join(f"#{i}" for i in positions)
+            raise ValueError(f"{ref!r} matches more than one cell: {listed}")
+    hint = ""
+    if not any(map(cell_ids, cells)):
+        hint = " (the notebook has no cell IDs; open and save it in a recent Jupyter to add them)"
+    raise ValueError(f"no cell matches {ref!r}{hint}")
+
+
+def join_cells(cells: list[Cell], refs: list[str]) -> str:
+    """Return the code of the cells that ``refs`` name, joined in the order given."""
+    chosen = [find_cell(cells, ref) for ref in refs]
+    for ref, cell in zip(refs, chosen, strict=True):
+        cell_type = cell.get("cell_type")
+        if cell_type != "code":
+            raise ValueError(f"{ref!r} is a {cell_type} cell, not a code cell")
+    return "\n\n".join(cell_source(cell).strip("\n") for cell in chosen)
+
+
+def short_ids(ids: list[str | None]) -> list[str]:
+    """Shorten IDs to the shortest length, at least 8, at which they stay unique."""
+    real = [i for i in ids if i]
+    length = 8
+    while len({i[:length] for i in real}) < len(set(real)):
+        length += 1
+    return [i[:length] if i else "-" for i in ids]
+
+
+def format_cell_table(cells: list[Cell]) -> str:
+    """Return a table of each cell's position, ID, type, title and first line."""
+    ids = short_ids([next(iter(cell_ids(cell)), None) for cell in cells])
+    titles = [cell_title(cell) for cell in cells]
+    has_titles = any(titles)
+    header = ["#", "id", "type", *(["title"] if has_titles else []), "first line"]
+    rows = [header]
+    for i, (cell, short_id, title) in enumerate(zip(cells, ids, titles, strict=True)):
+        first_line = next(iter(cell_source(cell).strip().splitlines()), "")
+        title_column = [title[:40]] if has_titles else []
+        rows.append([str(i), short_id, cell.get("cell_type", "?"), *title_column, first_line[:60]])
+    widths = [max(len(row[k]) for row in rows) for k in range(len(header))]
+    return "\n".join(
+        "  ".join(value.ljust(width) for value, width in zip(row, widths, strict=True)).rstrip()
+        for row in rows
+    )
+
+
+def _unquote(value: str) -> str:
+    # IPython splits magic arguments without removing quotes, so that Windows paths keep
+    # their backslashes. Remove one pair of matching quotes here instead.
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value
+
+
+@magics_class
+class NotebookMagics(Magics):
+    @magic_arguments()
+    @argument("path", help="Notebook file, absolute or relative to the working directory.")
+    @argument(
+        "-c",
+        "--cells",
+        nargs="+",
+        metavar="CELL",
+        help=(
+            "Cells to copy, in the order to paste them. Each is a cell ID, the start of one, "
+            "or a Databricks cell title (quote titles that contain spaces)."
+        ),
+    )
+    @line_magic
+    def load_cells(self, line: str) -> None:
+        """Copy the code of cells from another notebook into the current cell.
+
+        Like %load, this replaces the current cell with a commented-out copy of
+        the magic line followed by the copied code. Without --cells, it lists
+        the notebook's cells, with their IDs and titles, instead.
+        """
+        args = parse_argstring(self.load_cells, line)
+        try:
+            cells = read_notebook_cells(_unquote(args.path))
+        except (OSError, ValueError) as e:
+            raise UsageError(str(e)) from e
+        if not args.cells:
+            print(format_cell_table(cells))
+            return
+        try:
+            code = join_cells(cells, [_unquote(ref) for ref in args.cells])
+        except ValueError as e:
+            hint = f"Run `%load_cells {args.path}` to list the notebook's cells."
+            raise UsageError(f"{e}\n{hint}") from e
+        self.shell.set_next_input(f"# %load_cells {line}\n{code}", replace=True)
+
+
+def load_ipython_extension(ipython: Any) -> None:
+    ipython.register_magics(NotebookMagics)

agentbuild-0.0.1.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: agentbuild
+Version: 0.0.1
+Summary: Tools to make agent research easier.
+Author: trducng
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: ipython>=8
+Description-Content-Type: text/markdown
+
+# agentbuild
+
+Tools to make agent research easier.
+
+## Install
+
+```bash
+pip install agentbuild
+```
+
+## Jupyter: `%load_cells`
+
+Copy the code of cells from another notebook into the current cell, the way `%load` does for
+files.
+
+```python
+%load_ext agentbuild.jupyter
+
+%load_cells other.ipynb                            # list the notebook's cells, IDs and titles
+%load_cells other.ipynb --cells 7f3a9c21 b2e4d0aa  # copy those cells into this cell
+%load_cells "my export.ipynb" -c "Import Libraries" 7f3a
+```
+
+Each cell after `--cells` (or `-c`) can be:
+
+- a cell ID: the Jupyter cell ID, or for notebooks exported from Databricks, the Databricks cell ID
+  (`nuid`);
+- the start of a cell ID, such as the 8 characters the listing shows;
+- a Databricks cell title, matched exactly or ignoring case. Quote titles that contain spaces.
+
+If a value matches more than one cell, the magic stops with an error instead of guessing.
+
+Running the magic with `--cells` replaces the current cell with a commented-out copy of the magic
+line, followed by the code of the chosen cells in the order given. Run the cell again to execute
+that code. Relative paths are resolved from the kernel's working directory, which is normally the
+notebook's folder.
+
+To load the extension in every session, add this to
+`~/.ipython/profile_default/ipython_config.py`:
+
+```python
+c.InteractiveShellApp.extensions = ["agentbuild.jupyter"]
+```
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) and `make`.
+
+```bash
+make install       # install the package + dev tools, set up git hooks
+make help          # list all commands
+```
+
+Common commands:
+
+```bash
+make test          # run tests
+make test-matrix   # run tests on Python 3.11-3.15 (override with PYTHONS="3.11 3.12")
+make cov           # run tests with a coverage report
+make lint          # lint + format check
+make format        # auto-fix lint issues and format
+make check         # run the same checks as CI
+```
+
+## Release
+
+```bash
+make publish       # build and upload to PyPI (needs a PyPI token)
+```

agentbuild-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+agentbuild/__init__.py,sha256=CCOwo0Tlu7ovAovriTsnfhivqej1Zg4y0N5au2V4ZS0,277
+agentbuild/jupyter.py,sha256=i0xGtcBI5KmmWcGrshaUme7kylWY6Co_qyyUkdoP0cA,6362
+agentbuild/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentbuild-0.0.1.dist-info/METADATA,sha256=CtPNcwbySLdNJV8aXBUOrCyx66fHQiZm92Mx5NOJ9Kk,2342
+agentbuild-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentbuild-0.0.1.dist-info/RECORD,,

agentbuild-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any