BambooAI Data Analyst
Analyze datasets in a persistent Python kernel and replay the evidence behind every reported number.
- Source repo
- pgalko/BambooAI
- Stars
- ★ 838
- Last updated
- 6d ago
- License
- MIT
- Primary language
- Python
- FA score
- 85/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A working data analyst wants to explore a CSV or Parquet file with generated pandas, statistical, and visualization code while retaining every intermediate cell for inspection.
- Not a fit if
- Teams that cannot run Docker or Python 3.11+
- Users unwilling to supply paid model API keys
- Existing code still using the 1.x notebook library interface
- Source review
- 85/100 · Good
What does this agent do, and when should you use it?
BambooAI is an LLM-driven analyst for tabular data, delivered as a local web application, a single-question CLI, and a hosted service. It conducts an analysis as a sequence of cells in a persistent Python kernel, checkpointing each committed cell and rolling back failed attempts. Once the analyst writes a report, BambooAI assembles the cited cells into a script, executes them against the original data in a fresh kernel, and checks the reported numbers. Model-written code runs in a locally exposed Docker executor by default, with an unisolated local subprocess and a separately operated executor also supported. Ten hosted providers plus Ollama and vLLM can fill independently configured analyst, reviewer, rewriting, search, and memory seats.
BambooAI loads a primary CSV, Parquet, JSON, or XLSX dataset into the kernel as df and makes additional uploaded files available by path. The turn loop in analyst/session.py follows analyst/contract.md and accepts a fixed action set: CELL executes Python, SHOW retrieves a previous cell's full output, NAMES lists kernel variables, RECALL reads the dataset memory pack, SEARCH obtains grounded web results, ASK pauses for a user answer, and REPORT ends the run. Successful cells create checkpoints, failed cells restore the previous namespace, and follow-up questions can continue from variables left by an earlier run. The report records a best estimate, uncertainty, applicable conditions, method, and supporting cells and figures, usually including one to three Plotly charts. After REPORT, the cited cells are replayed in a fresh kernel, quoted numbers are compared with the new output, figures are captured from that reproduction, and the Rewriter seat produces a plain-language edition. Saving a run invokes the Knowledge Distiller to record practical column meanings, pitfalls, and successful methods in memory/<user>/memory_pack.yaml.
- A working data analyst wants to explore a CSV or Parquet file with generated pandas, statistical, and visualization code while retaining every intermediate cell for inspection.
- A researcher needs the computations cited by a report rerun from the original data before accepting its numerical conclusions.
- A sports scientist wants to analyze training or physiology records loaded for a selected date range from Intervals.icu, Endura, or SweatStack.
- A team needs a chain of follow-up questions that can reuse variables and computations already present in a warm Python kernel.
- A privacy-conscious organization wants a self-hosted analyst whose model seats can all run through local Ollama or vLLM servers.
- An analyst handling a longer investigation wants Adaptive mode to pause periodically for a stronger Reviewer model to inspect and redirect the run.
How do you install or deploy this agent?
The recommended setup requires Python 3.11 or newer and a running Docker Desktop installation on macOS or Windows, or Docker Engine on Linux. Run:
pip install bambooai
bambooai serveOn first use, BambooAI creates ~/bambooai, writes its .env file, builds the executor image, and opens http://127.0.0.1:5001. Add at least one provider credential to ~/bambooai/.env; OPENROUTER_API_KEY alone can reach every model in the default configuration. Add GEMINI_API_KEY if grounded web search is required, then run bambooai serve again.
To install from source:
git clone https://github.com/pgalko/BambooAI.git && cd BambooAI
python3 -m venv .venv && source .venv/bin/activatepip install -e .
bambooai serveThe same analyst is also offered without installation at bambooai.org. Users who explicitly accept unisolated execution may start bambooai serve --compute local, but executor-based data integrations are unavailable in that mode.
How do you use this agent?
Start bambooai serve, open the local web application, upload a CSV, Parquet, JSON, or XLSX file, and ask a question. Select Quick, Deep, or Adaptive according to the scope; under the shipped performance preset these allow 4, 15, and 50 analyst turns, with an Adaptive review every 8 turns. Models & Compute selects the cost, performance, or max preset, while Usage reports calls, tokens, and costs. Ask a follow-up to retain the previous kernel state, start a new question for fresh state, or save a run to create dataset memory for later RECALL actions.
A single analysis can run without the web UI through OpenRouter:
export OPENROUTER_API_KEY=...
python -m analyst.cli --csv data.csv --question "Is there a trend in weekly load?" --preset deep --model x-ai/grok-4.6 --effort highFor local inference, configure a seat with provider set to ollama in LLM_CONFIG_template.json and set REMOTE_OLLAMA=http://localhost:11434 in .env. REMOTE_VLLM provides the corresponding vLLM endpoint.
What are this agent's strengths and limitations?
- Cited computations are replayed from the original data in a fresh kernel, and the closing card states how many reported numbers reproduced.
- A persistent kernel supports cell-by-cell investigation and stateful follow-ups, while per-cell checkpoints protect the namespace from failed executions.
- Docker isolation is the default boundary for model-written code, with an option to operate the executor separately.
- The Analyst, Reviewer, Rewriter, Knowledge Distiller, and other seats can use different models, providers, reasoning efforts, token limits, and temperatures.
- The documented provider set spans OpenRouter, OpenAI, Anthropic, Google, Groq, Mistral, xAI, DeepSeek, Ollama, and vLLM, including a fully local configuration path.
- Cells, outputs, figures, prompts, per-call tokens, latency, and cost remain inspectable, and reports can be exported as PDFs.
- The default isolated deployment requires Python 3.11 or newer plus a running Docker installation, and the first executor image build takes several minutes.
- Unless every seat uses local Ollama or vLLM, adopters must supply provider credentials and pay the associated model charges; the default configuration can rely on OpenRouter.
- Grounded web search specifically requires a Gemini API key and Google AI grounding; SEARCH is disabled without that key.
- The Docker-free local compute mode has no execution isolation and cannot use Intervals.icu, Endura, or SweatStack integrations because their fetching occurs inside the executor.
- Intervals.icu and Endura require user credentials, while SweatStack additionally requires the adopter to register an application and configure its client ID and secret.
- Version 2 replaces the version 1 notebook-library interface, so users of from bambooai import BambooAI must remain on bambooai<2 or migrate to the new architecture.
How does this agent compare with similar options?
The default local deployment places the analysis kernel, replay, and integration fetching in a Docker executor, providing isolation. The --compute local alternative removes the Docker requirement but runs an unisolated subprocess and disables executor-based integrations. A separately managed executor can instead be reached through EXECUTION_MODE=api and EXECUTOR_API_BASE_URL, while bambooai.org offers the same analyst as a no-install hosted service. Compared with BambooAI 1.x's notebook-library interface, version 2 uses a web application, persistent kernel, and executor architecture; the old interface remains available only through bambooai<2 and the v1 branch.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| BambooAI Data Analyst This agent | 85 · Good | Web appFree + model costs | ★ 838 | 6d ago | Python | OpenAI API · Claude API |
| DATAGEN Research Assistant | 44 · Major gaps | CLIFree + model costs | ★ 1.8k | 11d ago | Python | OpenAI API · Claude API |
| Web Search Plus for Hermes | 92 · Excellent | Agent plugin / skillFree | ★ 440 | 6d ago | Python | — |
| Business Analytics Agent | 60 · Some gaps | Desktop appFree + model costs | ★ 2.6k | 1d ago | JavaScript | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Model-written code runs by default in a localhost-bound Docker executor, and the working-directory scope, provider traffic, local-mode risk, logging, and integration flows are described clearly; per-cell checkpoints and failed-cell rollback are strongly evidenced. ASK supplies a confirmation path, but ordinary generated cells execute automatically, while remote executors and --host 0.0.0.0 enlarge exposure, so least privilege, confirmation, and external-effects handling are not complete. Keys reside in .env and integration credentials are encrypted, but prompts or data may reach configured providers and detailed logs may retain sensitive content; no comprehensive retention, redaction, or deletion policy is shown. Many dependencies are broadly or entirely unpinned, with no visible vulnerability scan or SBOM, so dependency security is only basic. Author, license, contact routes, and search citation behavior are identified, although publisher identity is not enterprise-verified and some product provenance claims remain self-asserted.
The README, architecture description, tests, and CI consistently support the persistent kernel, rollback, replay, report-number checking, and failure ceiling, earning full self-consistency and failure-message scores. Tests explicitly cover syntax failures, repeated failures, condensed diagnostics, rollback notices, and forced reporting. Dependencies are available through PyPI, Docker, numerous providers, and Ollama/vLLM alternatives; however, most versions are not pinned and the browser end-to-end and package tests are described as local pre-push checks rather than CI-enforced checks, reducing dependency availability.
The intended users, sports-science and general tabular scenarios, Quick/Deep/Adaptive modes, and technical/plain-language outputs are well defined. The fixed CELL, SHOW, NAMES, RECALL, SEARCH, ASK, and REPORT contract, search budget, consecutive-failure ceiling, and Docker/local distinctions provide precise triggers and strong capability boundaries. Python 3.11+, Docker, relocatable storage, ten providers, local models, and remote executors demonstrate thorough environment fit, with no material static-source gap in these criteria.
The README has strong navigation and comprehensive installation, quick-start, configuration, architecture, logging, development, and contact sections; pip, source, and hosted paths are documented. The MIT text agrees with package metadata and classifiers. Naming is mostly stable, but the substantial 1.x-to-2.x product shift and the templ_formating spelling in the configuration example prevent full marks. Examples are extensive but there is no real FAQ; limitations are scattered across Docker, local compute, search-key, and budget discussions rather than maintained as a complete known-limitations section. Version 2.0.0, a v1 branch note, and tag publishing are shown, but no formal changelog is supplied. The named author, email, issue tracker, discussions, and release workflow establish a maintenance route, while team ownership, support commitments, and governance remain unspecified.
Outputs include inspectable cells, plots, technical and plain-language reports, citations, replay status, PDF export, and per-call telemetry, making the static product design highly usable. Persistent state, failure rollback, sourced search, dataset memory, and fresh-kernel replay offer clear marginal value over a basic analysis chat. Mode budgets, token/time/cost displays, cost presets, and zero-price local-model configuration provide thorough cost-benefit controls; this evaluates documented design and source evidence, not an executed result.
Major claims trace to named modules, the analyst contract, workflows, and detailed tests; the README, pyproject, CI, release workflow, and tests cross-corroborate packaging, isolation, rollback, replay, and installation relationships. The report contract separates estimates, uncertainty, conditions, methods, and cell references, and numeric guards flag unsupported figures. However, repository-external or process claims such as the hosted service being the same analyst and local tests running before every push lack independent corroboration, and the README does not always distinguish CI-enforced facts from maintainer assertions, so fact/inference separation is not complete.
- Model-generated code retains data-processing power; keep the default Docker isolation and avoid unisolated local mode for untrusted data.
- When remote models or Gemini search are configured, data, prompts, or queries may be sent to third parties; review each provider's data policy before using sensitive datasets.
- Logs contain complete prompts, responses, and usage and may capture source data or analysis details; restrict access and define retention and secure-deletion procedures.
- Most dependencies are not locked and no supply-chain vulnerability scan is shown; create a lockfile and SBOM and scan dependencies and container images before production use.
- Exposing the app on 0.0.0.0 or using a remote executor calls for additional authentication, TLS, network controls, and executor isolation.
- This assessment uses only the supplied static files; the application, tests, containers, and replay flow were not executed.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
BambooAI 2.7.1 — the Usage dialog, rebuilt Every number BambooAI shows about itself should be as inspectable as the numbers it shows about your data. 2.7.1 rebuilds the Usage dialog (gear menu → Usage) on that principle: what the analyses cost and where the money and the time went, computed from the record of model calls, nothing written by a model. What it shows A period — the last 24 hours, 7, 30 or 90 days, this month or last month, in your own days — against the period before it, and Export CSV for the rows themselves. …View on GitHub ↗ -
Release notes excerpt
BambooAI 2.7.0 — datasets by athlete A coach works with several athletes. 2.7.0 makes the athlete the unit everywhere data is kept, loaded, cached and run: one store per athlete on the executor's disk, one Intervals.icu key per athlete, one athlete at a time on the Data tab, and routines whose history and comparisons stay within one athlete's runs. The executor image is rebuilt (v74). The store, per athlete …View on GitHub ↗ -
Release notes excerpt
BambooAI 2.6.1 — the reach record The kernel now records what each cell of an analysis touched outside the data, and the app reports it when the chain ends. The analysis itself is unchanged; the executor image is rebuilt (v65). What is recorded For every cell the analyst runs, the kernel keeps a record of the doors it went through: - Network. Each host the cell connected to, with the port, the bytes sent and received (TLS included), a listening port it opened, a name it resolved without connecting, a connection that failed. …View on GitHub ↗