agentbuild 0.0.1__tar.gz

agentbuild-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest

agentbuild-0.0.1/.gitignore

@@ -0,0 +1,26 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Build / packaging
+build/
+dist/
+*.egg-info/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

agentbuild-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.1
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

agentbuild-0.0.1/Makefile

@@ -0,0 +1,57 @@
+.DEFAULT_GOAL := help
+
+# Python versions for `make test-matrix`. Override with: make test-matrix PYTHONS="3.11 3.12"
+PYTHONS ?= 3.11 3.12 3.13 3.14 3.15
+
+# Use the activated virtualenv if there is one, otherwise uv's project .venv.
+UV_ENV := $(if $(VIRTUAL_ENV),--active)
+RUN := uv run $(UV_ENV)
+
+.PHONY: help install lint format test cov test-matrix pre-commit check build publish upgrade clean
+
+help: ## Show available commands
+	@awk 'BEGIN {FS = ":.*## "} /^[a-zA-Z_-]+:.*## / {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install the package and dev tools, and set up git hooks
+	uv sync $(UV_ENV)
+	$(RUN) pre-commit install
+
+lint: ## Lint with ruff and check formatting
+	$(RUN) ruff check .
+	$(RUN) ruff format --check .
+
+format: ## Auto-fix lint issues and format code
+	$(RUN) ruff check --fix .
+	$(RUN) ruff format .
+
+test: ## Run tests on the current Python
+	$(RUN) pytest
+
+cov: ## Run tests with a coverage report
+	$(RUN) pytest --cov=agentbuild --cov-report=term-missing
+
+test-matrix: ## Run tests on every Python version in PYTHONS
+	@for v in $(PYTHONS); do \
+		echo "==> Python $$v"; \
+		uv run --isolated --python $$v pytest -q || exit 1; \
+	done
+
+pre-commit: ## Run all pre-commit hooks on all files
+	$(RUN) pre-commit run --all-files
+
+check: lint test ## Run the same checks as CI
+
+build: ## Build the sdist and wheel into dist/
+	rm -rf dist
+	uv build
+
+publish: build ## Build and upload to PyPI
+	uv publish
+
+upgrade: ## Upgrade locked dependencies and pre-commit hook versions
+	uv lock --upgrade
+	$(RUN) pre-commit autoupdate
+
+clean: ## Remove build artifacts and caches
+	rm -rf build dist .pytest_cache .ruff_cache .coverage htmlcov coverage.xml
+	find src tests -type d -name __pycache__ -exec rm -rf {} +

agentbuild-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,69 @@
+# 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/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentbuild"
+version = "0.0.1"
+description = "Tools to make agent research easier."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "trducng" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "ipython>=8",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.8",
+    "pre-commit>=4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentbuild"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]

agentbuild-0.0.1/src/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-0.0.1/src/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/tests/test_agentbuild.py

@@ -0,0 +1,6 @@
+import agentbuild
+
+
+def test_version() -> None:
+    assert isinstance(agentbuild.__version__, str)
+    assert agentbuild.__version__