agentbuild

Tools to make agent research easier.

Install

pip install agentbuild

Jupyter: %load_cells

Copy the code of cells from another notebook into the current cell, the way %load does for files.

%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
%load_cells other.ipynb -c 7f3a9c21 --run          # run those cells instead of copying them
%load_cells other.ipynb -c 7f3a9c21 --print        # print their code instead of copying it

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.

• --run runs the chosen cells' code in the current session instead of copying it. Magics in that code, such as %pip, work as they would in a cell.
• --print prints the code instead of replacing the current cell, for notebook apps that can't replace a cell's contents. This is the default on Databricks, whose notebooks can't (it's detected through the DATABRICKS_RUNTIME_VERSION environment variable).

To load the extension in every session, add this to ~/.ipython/profile_default/ipython_config.py:

c.InteractiveShellApp.extensions = ["agentbuild.jupyter"]

LLM calls: agentbuild.leanllm

One small client for OpenAI, Anthropic, Gemini and any OpenAI-compatible server (Azure OpenAI, Ollama, vLLM, OpenRouter), with retries, failover, load balancing and an on-disk response cache. Install the SDKs of the providers you use:

pip install "agentbuild[openai,anthropic,gemini]"

Keys come from OPENAI_API_KEY, ANTHROPIC_API_KEY and GEMINI_API_KEY.

from agentbuild.leanllm import LLM, Deployment

reply = LLM("openai/gpt-4o-mini").chat("Summarize this chunk: ...")
print(reply.text)

llm = LLM(
    route=[
        # Tier 1: two deployments of one model share the load
        [
            "openai/gpt-4o-mini",
            Deployment(
                "openai/gpt-4o-mini",
                base_url="https://my-azure.openai.azure.com/openai/v1",
                api_key_env="AZURE_OPENAI_KEY",
            ),
        ],
        # Later tiers are used only when every deployment above has failed
        ["anthropic/claude-haiku-4-5"],
        ["gemini/gemini-2.5-flash"],
    ],
    cache="/tmp/llm_cache",  # a folder on local disk; None disables caching
    retries=2,  # per deployment, before moving on
    timeout=120,  # seconds per request
    cooldown=60,  # seconds a failing deployment is skipped
)
reply = llm.chat(
    [
        {"role": "system", "content": "Answer only from the context."},
        {"role": "user", "content": prompt},
    ],
    temperature=0,
    max_tokens=500,
)
reply.text, reply.finish_reason, reply.served_by, reply.cached, reply.usage, reply.attempts

vectors = LLM("openai/text-embedding-3-small", cache="/tmp/llm_cache").embed(chunks)

• A deployment's key can also be given directly, as Deployment(..., api_key=key); it is kept out of reprs and logs.

• For an Azure OpenAI resource that cannot use the v1 endpoint yet, pass the same values as openai.AzureOpenAI: Deployment("openai/<deployment name>", base_url=<azure_endpoint>, api_version="2024-10-21", api_key=key).

• await llm.achat(...) and await llm.aembed(...) behave the same, asynchronously.

• cache=False skips the cache for one call; cache="refresh" calls the provider and overwrites the entry. A cached answer comes back even at a temperature above 0. Embeddings are cached one text at a time, so only new texts are sent. If the cache cannot be read or written, calls carry on without it and log a warning.

• Keep the cache folder on a local disk. On Databricks, LLM refuses one under /Workspace (where a notebook's relative paths land), /dbfs or /Volumes, because SQLite corrupts its files there.

• llm.cache_save(path) writes the cache's entries to one compressed file, which can go anywhere. llm.cache_load(path) adds the entries from such a file that the cache lacks, so it also merges caches. Both return a count. To keep a Databricks cache across clusters:

  llm = LLM("openai/gpt-4o-mini", cache="/tmp/llm_cache")
  llm.cache_load("/Workspace/Users/me/llm_cache.gz")  # 0 on the first run: no file yet
  ...
  llm.cache_save("/Workspace/Users/me/llm_cache.gz")
  

• provider_options={"gemini": {"thinking_config": {"thinking_budget": 0}}} passes options to one provider's API and is ignored by the others. Gemini 2.5 models think by default, and thinking counts against max_tokens.

• A BadRequest (400, 422) is raised at once, with no failover. When every deployment fails, AllProvidersFailed.attempts lists each try: a.deployment, a.error, a.duration_s.

• Each attempt is logged on the agentbuild.leanllm logger; on_attempt=callback receives it too.

See docs/leanllm_submodule.md for the full behaviour.

Development

Requires uv and make.

make install       # install the package + dev tools, set up git hooks
make help          # list all commands

Common commands:

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

make publish       # build and upload to PyPI (needs a PyPI token)