AutoDS-Copilot: Instructions file for Claude Code

CLAUDE.md — AutoDS Copilot

Context for any Claude session working in this repo. Read this first, then docs/MANUAL.md for the deep technical record of every feature.

What this project is

AutoDS Copilot turns a raw spreadsheet into a trustworthy, explained machine learning model, with no code required. You point it at a CSV and it explores the data, checks it for traps, cross validates dozens of models, trains the best one, handles class imbalance honestly, and writes up the result in plain language. A grounded AI copilot answers questions about the actual data, and an agent can plan the whole run for you to approve. It runs locally and needs no API key by default.

AutoDS has two modes. Model Studio (the main app at /app) predicts, as above. Decision Studio (at /studio, see docs/DECISION_STUDIO.md) is the no-code decision intelligence mode: it auto builds a dashboard, finds what is notable, and recommends a move with an estimated impact, with the same copilot over the data. Phases 1 and 2 are built (dashboard, what if, goal seeking, executive share view). Causal methods and optimization (Phase 3) are next.

It is a portfolio project by Vinith Kumar that demonstrates a full, production minded ML system: multi agent pipeline, RAG, MCP server, a grounded LLM copilot, and genuine ML rigor (leakage safety, imbalance handling, calibration, fairness, explainability).

How to run and test

python3 -m pip install -r requirements.txt
python3 run.py            # web console at the printed local URL
python3 -m pytest -q      # full offline test suite (no key, no network)

Optional LLM: copy .env.example to .env and set one provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, or a local Ollama). With none set, the tool runs fully offline on rule based text. .env is gitignored; never commit keys.

Architecture (where things live)

• autods/agents/graph.py the LangGraph pipeline of 9 specialist agents (loader, profiler, task detector, EDA, insight, cleaning, model recommender, trainer, evaluator) with human approval gates.
• autods/mcp_server.py exposes the pipeline as 9 MCP tools.
• autods/pipeline/ the ML engine: loader, preclean, task_detect, eda, quality, preprocess, model_select, leaderboard, train.py (leakage safe pipeline + imbalance strategies + balance_preview), evaluate.py (metrics + rigor + explainability diagnostics), rigor.py (resampling, threshold tuning, calibration, fairness), explain.py (permutation importance, error analysis), insights.py, report.py (the written analysis report).
• autods/rag/ retrieval: store.py, knowledge.py, generate.py (grounded LLM generators: answer, insights, rationale, executive summary, model comparison).
• autods/llm.py provider agnostic LLM layer (OpenAI, Anthropic, Ollama; complete and stream). autods/config.py settings and .env loading.
• autods/converse.py + autods/dataqa.py the conversational data copilot (routes a question to a safe pandas tool, answers from real numbers; also does multi-step why analysis that chains several tools, clarifying questions when a question is ambiguous, and suggested starter questions from the schema). Voice input is in the Ask UI via the browser speech API.
• autods/planner.py the agentic auto-pilot (cross validates, picks the best model, proposes a full plan to approve).
• autods/decision.py the Decision Studio engine (detects measure, dimension and time roles, then builds KPIs, a trend, breakdowns, key findings and a direction aware recommendation with an estimated impact, plus estimate_effect(s) for what if and goal_seek). Served by /studio, /api/studio/, /whatif and /goal under it, and the share view /studio//report, rendered by templates/studio.html and templates/studio_report.html with Chart.js.
• autods/web/ Flask app. app.py routes, templates/ (landing.html is a self contained redesigned marketing page; console.html is the SPA shell; partials/ are the step views), static/style.css the shared design system.