v2: modernized -- modular architecture, multi-provider LLM, modern UI

Author: Safiullah-Rahu

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.gitignore
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+.env
+.env.*
+!.env.example
+.streamlit/secrets.toml
+tests
+*.md
+!README.md

.env.example

@@ -0,0 +1,17 @@
+# --- LLM provider credentials ---
+# Fill in only the providers you intend to use.
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+
+# --- Local Ollama (optional) ---
+OLLAMA_BASE_URL=http://localhost:11434
+
+# --- Defaults ---
+DEFAULT_PROVIDER=openai
+DEFAULT_MODEL=gpt-4o-mini
+DEFAULT_TEMPERATURE=0.2
+DEFAULT_MAX_TOKENS=1024
+
+# --- App ---
+ENVIRONMENT=dev
+LOG_LEVEL=INFO

.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.example
+.streamlit/secrets.toml
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+.ipynb_checkpoints/
+.DS_Store
+Thumbs.db
+*.log
+build/
+dist/

.streamlit/config.toml

@@ -0,0 +1,14 @@
+# Streamlit configuration.
+# Keep settings minimal so the user's OS theme drives the look-and-feel.
+
+[server]
+maxUploadSize = 200          # MB. Bump for big CSVs.
+headless = true
+
+[browser]
+gatherUsageStats = false
+
+[theme]
+# Leaving "base" unset means we respect the user's system preference (light/dark).
+primaryColor = "#7C3AED"
+font = "sans serif"

.streamlit/secrets.toml.example

@@ -0,0 +1,6 @@
+# Copy this file to .streamlit/secrets.toml (gitignored).
+# Streamlit Community Cloud reads these as st.secrets[...].
+
+OPENAI_API_KEY = ""
+ANTHROPIC_API_KEY = ""
+OLLAMA_BASE_URL = "http://localhost:11434"

ARCHITECTURE.md

@@ -0,0 +1,94 @@
+# Architecture
+
+CSV-AI v2 is a layered Streamlit application designed so that the **business logic is independent of the UI**. The same `services/` package could be served from FastAPI, a CLI, or a Discord bot tomorrow without changes.
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│                         streamlit_app.py                          │
+│                          (thin entry)                             │
+└──────────────────────────┬────────────────────────────────────────┘
+                           │
+                  ┌────────▼────────┐
+                  │     app.ui      │
+                  │  pages + comps  │   ← Streamlit lives here only
+                  └────────┬────────┘
+                           │
+                  ┌────────▼────────┐
+                  │  app.services   │
+                  │  Chat·Summary·  │   ← pure Python; UI-free
+                  │     Analysis    │
+                  └────────┬────────┘
+            ┌──────────────┼──────────────┐
+            ▼              ▼              ▼
+    ┌────────────┐  ┌────────────┐  ┌────────────┐
+    │  app.data  │  │  app.llm   │  │ app.prompts │
+    │ load·prof  │  │  provider  │  │  templates  │
+    │  sample    │  │   layer    │  │             │
+    └────────────┘  └────┬───────┘  └────────────┘
+                         │
+            ┌────────────┼────────────┐
+            ▼            ▼            ▼
+        OpenAI       Anthropic      Ollama
+```
+
+## Why each layer exists
+
+### `app.config`
+Single source of truth for settings via `pydantic-settings`. Reads `.env`, OS env, and (best-effort) Streamlit secrets. Anything that needs an API key or a default should call `get_settings()` rather than reading `os.environ`.
+
+### `app.llm`
+A provider-agnostic interface (`LLMProvider`) with three concrete implementations. Adding a new backend (Mistral API, Bedrock, …) is one file plus one factory entry. Keeping streaming in the interface forces every provider to behave consistently for the chat UI.
+
+### `app.data`
+Pure-pandas. **Never** imports Streamlit or any LLM SDK. Three concerns:
+- `loader.py` — robust CSV reading (encoding fallback chain, delimiter sniffing).
+- `profiler.py` — fast statistical profile (rows, dtypes, missing %, correlations, samples).
+- `sampler.py` + `context.py` — turn a DataFrame into an LLM-friendly markdown context.
+
+### `app.prompts`
+System prompts as constants. Versioning prompts in code (not strings sprinkled through services) keeps prompt iteration reviewable in git.
+
+### `app.services`
+Three services map 1:1 to the three product workflows. Each takes a `provider` and a `df`, exposes a non-streaming and streaming method, and never imports Streamlit. They're trivially callable from FastAPI later.
+
+### `app.ui`
+The only place we import Streamlit. Page modules render; component modules are reusable. Session state is centralized in `state.py` so key names stay consistent.
+
+### `app.utils`
+Cross-cutting: logging, exception hierarchy, token counting. No business logic.
+
+## Key design choices
+
+**No FAISS / no retrieval for chat.** The original CSV-AI embedded every row chunk into FAISS and retrieved on every question. For small files this was wasted compute; for analytical questions ("what's the average X?") it was actively worse than just showing the model the schema. v2 sends a structured schema + a smart sample. Result: lower latency, lower cost, fewer hallucinations.
+
+**Deterministic stats first, LLM second.** The Analyze page computes the actual numbers with pandas, then asks the LLM to write the narrative around those numbers. The LLM never invents arithmetic — pure-LLM dataframe agents do.
+
+**Streaming everywhere.** Every provider yields token chunks. The UI uses `st.empty()` plus `st.markdown` with a trailing cursor for the classic typewriter feel.
+
+**Custom-model escape hatch.** The sidebar's model picker has a `custom...` option so new model ids (e.g. tomorrow's `gpt-5`) work without a code change.
+
+**Future API split.** Because services don't import Streamlit, exposing an HTTP layer is mostly:
+
+```python
+@app.post("/chat")
+def chat(req: ChatReq) -> ChatResp:
+    provider = build_provider(req.provider, model=req.model, ...)
+    df = pd.read_csv(req.csv_path)
+    service = ChatService(provider=provider, df=df)
+    return ChatResp(answer=service.ask(req.question))
+```
+
+## Adding a new LLM provider
+
+1. Create `app/llm/<name>_provider.py` subclassing `LLMProvider`. Implement `complete` and `stream`.
+2. Register it in `app/llm/factory.py` (`_PROVIDERS`).
+3. Add suggested models to `_MODEL_CATALOGUE` in the same file.
+4. Extend `Settings` with any new credential fields.
+5. Update the sidebar's `_render_provider_section` if it needs a non-standard field (e.g. a region).
+
+## Adding a new page
+
+1. Create `app/ui/pages/<name>.py` with a `render()` function.
+2. Add it to `PAGE_RENDERERS` in `app/main.py` and `PAGES` in `app/ui/components/sidebar.py`.
+
+That's it. No central router to wire up.

DEPLOYMENT.md

@@ -0,0 +1,141 @@
+# Deployment
+
+CSV-AI v2 is structured to deploy three ways out of the box, with a fourth (API split) being a small future task.
+
+## 1. Streamlit Community Cloud
+
+1. Push this repo to GitHub.
+2. On [streamlit.io/cloud](https://streamlit.io/cloud), create a new app pointing at this repo.
+3. Set **Main file path** to `streamlit_app.py`.
+4. Under **Settings → Secrets**, paste:
+
+   ```toml
+   OPENAI_API_KEY = "sk-..."
+   ANTHROPIC_API_KEY = "sk-ant-..."
+   ```
+
+5. Deploy. `requirements.txt` is picked up automatically.
+
+> Streamlit Cloud's sandbox can't reach a local Ollama instance — pick `openai` or `anthropic` as your default provider in `Settings → Advanced`.
+
+## 2. Local development
+
+```bash
+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-dev.txt
+cp .env.example .env       # fill in keys
+streamlit run streamlit_app.py
+```
+
+Optional — run a local Ollama:
+
+```bash
+ollama serve &
+ollama pull llama3.1
+# then in the sidebar: provider = ollama, model = llama3.1
+```
+
+## 3. Docker / Docker Compose
+
+```bash
+cp .env.example .env       # fill in keys
+docker compose up --build
+```
+
+Open <http://localhost:8501>. The container runs `streamlit run streamlit_app.py` on port 8501 with a healthcheck.
+
+For a bare-metal Docker run:
+
+```bash
+docker build -t csv-ai .
+docker run --rm -p 8501:8501 --env-file .env csv-ai
+```
+
+## 4. Generic VPS
+
+The Dockerfile is the recommended path on any Linux VPS — drop it behind nginx with an SSL terminator. If you want to skip Docker:
+
+```bash
+# As a non-root user on the VPS:
+git clone https://github.com/Safiullah-Rahu/CSV-AI.git /opt/csv-ai
+cd /opt/csv-ai
+python3.11 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env       # fill in keys
+
+# Run as a systemd unit (see snippet below):
+sudo systemctl enable --now csv-ai.service
+```
+
+`csv-ai.service`:
+
+```ini
+[Unit]
+Description=CSV-AI Streamlit app
+After=network.target
+
+[Service]
+User=csvai
+WorkingDirectory=/opt/csv-ai
+EnvironmentFile=/opt/csv-ai/.env
+ExecStart=/opt/csv-ai/.venv/bin/streamlit run streamlit_app.py --server.port=8501 --server.address=127.0.0.1
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Front it with nginx:
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name csv-ai.example.com;
+    # SSL certs ...
+    location / {
+        proxy_pass http://127.0.0.1:8501;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 300;
+    }
+}
+```
+
+## 5. Future: API/backend split
+
+`app/services/` has no Streamlit imports, so wrapping it in FastAPI is mostly mechanical:
+
+```python
+# api/main.py — future
+from fastapi import FastAPI
+from pydantic import BaseModel
+import pandas as pd
+
+from app.llm.factory import build_provider
+from app.services import ChatService
+
+api = FastAPI()
+
+class ChatReq(BaseModel):
+    provider: str
+    model: str
+    question: str
+    csv_path: str
+
+@api.post("/chat")
+def chat(req: ChatReq):
+    provider = build_provider(req.provider, model=req.model)
+    df = pd.read_csv(req.csv_path)
+    return {"answer": ChatService(provider=provider, df=df).ask(req.question)}
+```
+
+Same engine, different transport. The Streamlit app can stay, become a thin client of the API, or both can run side-by-side.
+
+## Health checks & observability
+
+- The Streamlit endpoint `/_stcore/health` returns 200 when ready (used by the Dockerfile healthcheck).
+- Logs go to stderr under the `csvai.*` namespace (see `app/utils/logging.py`). Set `LOG_LEVEL=DEBUG` for verbose output.

Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1.6
+
+FROM python:3.11-slim AS base
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    STREAMLIT_SERVER_HEADLESS=true \
+    STREAMLIT_SERVER_ENABLE_CORS=false
+
+WORKDIR /app
+
+# System deps: minimal — pandas wheels are precompiled on x86_64.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . ./
+
+EXPOSE 8501
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s \
+    CMD curl -fsS http://localhost:8501/_stcore/health || exit 1
+
+CMD ["streamlit", "run", "streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Safiullah Rahu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.