CSV-AI v2: a Streamlit front end for chatting with CSV files

The problem CSV-AI addresses, and who it is written for

Most people who receive a CSV do not want to write pandas code first. They want to know the column types, how many values are missing, which columns correlate, and what a plain-language summary of the file looks like. CSV-AI packages those questions into one Streamlit dashboard so the answer arrives without a notebook. The README frames the app as a way to "interact with, summarize, and analyze your CSV files in one convenient place," and the v2 rewrite keeps that product idea while changing the machinery underneath.

The intended user is someone who can run a Python environment and hold an API key, but who is not going to build a retrieval pipeline. That includes analysts doing ad hoc file review, engineers who want a local UI rather than a hosted service, and anyone who prefers a local Ollama model over sending rows to a vendor. It is not aimed at scheduled ETL jobs or at teams that need a documented HTTP contract, because the shipped entry point is a Streamlit script rather than a server API.

How the v2 architecture splits data, prompts and providers

The repository layout is the clearest statement of intent. Everything lives under an app/ package with separate directories for config, llm, data, prompts, services, ui and utils. The README describes the services layer (ChatService, SummaryService, AnalysisService) as UI-free, which is the constraint that makes a later FastAPI adapter plausible: no Streamlit import reaches the service code.

The data flow for a chat turn is roughly: the CSV loader reads the file, the profiler and sampler reduce it to a schema plus a small representative sample, the prompt-context builder assembles that into a system prompt drawn from the versioned prompts directory, and the provider-agnostic LLM interface forwards it to OpenAI, Anthropic or Ollama. The README notes that chat answers are "schema- and sample-aware" and that responses stream token by token. This is a deliberate break from v1, which used FAISS retrieval over CSV chunks; the v2 table argues the schema plus sample approach is "cheaper, more accurate." That claim is the author's, not something the repository demonstrates, and it is the single biggest behavioural change to be aware of when migrating.

The Analyze view does not depend on the model for its numbers. According to the README, it renders deterministic pandas statistics alongside an LLM analyst narrative, with charts, missingness and correlations. That separation matters: if the model produces a poor narrative, the underlying counts and correlations are still computed by pandas. The Summarize view moved in the opposite direction, from a LangChain map-reduce chain to a single structured prompt, which the README says replaces the old flow.

Installing CSV-AI locally and running a first analysis

The quick start in the README assumes Python 3.10 or newer, which matches the requires-python field in pyproject.toml. Clone the repository, create a virtual environment, install the pinned requirement ranges, copy the example environment file, and start Streamlit. On Windows the activation line differs, and the README gives that variant inline.

git clone https://github.com/Safiullah-Rahu/CSV-AI.git
cd CSV-AI

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
streamlit run streamlit_app.py

After the server starts, the README says to open http://localhost:8501 and upload a CSV. The default port comes from Streamlit itself; the Dockerfile makes it explicit with --server.port=8501, and docker-compose.yml maps 8501:8501.

Configuration resolves in a fixed order: environment variables first, then the .env file, then Streamlit secrets. The documented keys are OPENAI_API_KEY, ANTHROPIC_API_KEY, OLLAMA_BASE_URL (default http://localhost:11434), DEFAULT_PROVIDER (openai, anthropic or ollama), DEFAULT_MODEL (default gpt-4o-mini), DEFAULT_TEMPERATURE (0.0 to 1.5, default 0.2) and DEFAULT_MAX_TOKENS (default 1024).

If you prefer containers, the compose file builds the image, loads .env through env_file, and defines a healthcheck against http://localhost:8501/_stcore/health. The Dockerfile uses python:3.11-slim, installs build-essential, copies requirements.txt before the rest of the source, and runs Streamlit with --server.address=0.0.0.0 so the port is reachable from outside the container.

docker compose up --build

For development, requirements-dev.txt adds the test and lint tooling. The README lists pytest, ruff check . and black . as the three commands to run.

Where CSV-AI is weaker than its README suggests

The README describes a "future API split" and calls a FastAPI layer "a small adapter," but no such adapter exists in the top-level entries. If your plan is to call CSV-AI from another service, you are writing that layer yourself against services that the README claims are pure Python. The claim is plausible given the directory structure, but it is unverified here.

Token cost and privacy are the other constraints. Chat context is a schema plus a sample, not the full file, so the model never sees every row. That reduces cost and keeps large files inside the token budget, but it also means a question about a rare value in an unsampled region of the file may get an answer grounded in nothing. The README does not document how the sample is chosen or how large it is; the sampler lives in app/data and is not described further. For files where the interesting signal is in the tail, that is the wrong tool.

Provider configuration is a second failure mode. DEFAULT_PROVIDER is openai and DEFAULT_MODEL is gpt-4o-mini until the user changes them in the sidebar. If you intend to run fully local, forgetting to set DEFAULT_PROVIDER=ollama means the app will try to reach OpenAI, and without OPENAI_API_KEY that request fails. Nothing in the README describes an offline mode or a fallback chain between providers. Finally, there are no retrieved releases for this repository, so version 2.0.0 in pyproject.toml is the only version identifier available; there is no changelog to consult when something breaks after an upgrade.

How CSV-AI differs from Streamlit's own dataframe chat example

The obvious comparison is Streamlit's built-in chat-with-dataframe pattern, which typically hands the model a pandas DataFrame and lets it generate and execute code. CSV-AI v1 followed that route through LangChain's create_pandas_dataframe_agent, and v2 deliberately moved away from it. The difference is who computes the answer. An agent approach lets the model write pandas expressions, which is flexible but makes the numeric output depend on generated code. CSV-AI v2 computes statistics in pandas and asks the model only for narrative, so the counts and correlations do not vary between runs.

The cost of that choice is scope. An agent can answer a question the profiler never anticipated by writing a new expression; CSV-AI can only answer from the schema, the sample and the precomputed statistics. For exploratory work on an unfamiliar file, the agent pattern is more open-ended. For repeatable reporting where you want the same numbers every time, the deterministic-first design is the better fit. The README's own comparison table frames the change as replacing the pandas agent with "deterministic pandas stats + LLM narrative," which is an accurate summary of the trade.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-05-20. That is the only maintenance signal available here: there are no retrieved releases and no changelog in the top-level entries, so upgrade planning has to rely on the v1 versus v2 table in the README and on ARCHITECTURE.md.

Upgrading from v1 is a rewrite rather than a version bump. The README's comparison shows the LLM layer moving from LangChain's chat_models and embeddings modules to native SDKs (openai>=1.40, anthropic>=0.34), chat context moving from FAISS retrieval to schema plus sample, summarization moving from load_summarize_chain(map_reduce) to a single prompt, and configuration moving from inline os.environ access to pydantic-settings. Any local fork that patched the old app.py will not apply cleanly to the app/ package. The dependency list is short and the ranges are open-ended (>=), so a fresh install can pull newer minor versions of streamlit, pandas or the provider SDKs than the author last ran; pinning is left to the deployer.

The licence is MIT, declared both in the LICENSE file and in pyproject.toml as license = { text = "MIT" }. MIT permits commercial use and modification provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice; if you redistribute CSV-AI inside a product, have counsel confirm the notice requirements.

Editorial conclusion

Adopt CSV-AI v2 if you want a self-hosted Streamlit dashboard that keeps deterministic pandas statistics next to an LLM narrative, and you are comfortable supplying your own API key or running Ollama locally. Do not adopt it if you need a stable Python API for a data pipeline: the README describes the service layer as UI-free but says the FastAPI split is still a future step, so the only shipped entry point is streamlit_app.py. Before relying on it, verify which provider the sidebar selects by default, confirm that DEFAULT_MODEL matches a model your account can call, and read ARCHITECTURE.md for the layer boundaries the README only sketches.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. Safiullah-Rahu/CSV-AI on GitHub