learnstat 0.2.0__tar.gz → 0.2.1__tar.gz

{learnstat-0.2.0 → learnstat-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learnstat
-Version: 0.2.0
+Version: 0.2.1
 Summary: An AI-assisted learning companion for statistical analysis with pandas, NumPy, SciPy and Matplotlib.
 License: MIT
 Project-URL: Homepage, https://github.com/umorfaruksupto/leanstat
@@ -54,6 +54,33 @@ pip install -e ".[all]"        # pandas, numpy, matplotlib, scipy, ipython
 pip install -e .               # core only: profiling, rules, recovery
 ```
 
+### Quick start (no commands to learn)
+
+```bash
+pip install learnstat
+learnstat
+```
+
+That is all. learnstat walks you through everything in plain English:
+
+1. **Pick your AI** (optional): choose the company, paste your key, choose a model. learnstat tests it and says OK or what is wrong.
+2. **Choose your data**: press Enter and a normal file window opens (CSV or Excel), or drag the file into the terminal.
+3. **Pick what to do from a menu** by typing a number:
+
+```
+  1) See a summary of my data
+  2) Ask the AI a question about my data
+  3) Get suggestions for a Python script
+  4) Run a Python script with automatic help
+  5) Write Python code here (my data is ready as "df")
+  6) Learn a statistics topic
+  7) Load a different data file
+  8) Change the AI (company, key, model)
+  9) Help
+```
+
+Nothing else needs to be memorised: every option asks for what it needs, and option 9 explains the menu. Skip the AI and everything still works with built-in rules.
+
 ### Add an AI (optional)
 
 Just run `learnstat`. If no AI is set up yet it offers a guided setup, and you can repeat it any time with `learnstat setup` (or `/ai` inside a session):
@@ -177,6 +204,7 @@ learnstat/
   config.py       saved AI accounts: provider, api_key, base_url, model
   providers.py    presets for the AI companies
   setup.py        guided terminal setup (company -> key -> model -> check)
+  guide.py        the numbered home menu students use
   session.py      ties it together; read_csv/track/check/run
   commands.py     slash commands
   ipython_ext.py  %load_ext learnstat

{learnstat-0.2.0 → learnstat-0.2.1}/README.md

@@ -24,6 +24,33 @@ pip install -e ".[all]"        # pandas, numpy, matplotlib, scipy, ipython
 pip install -e .               # core only: profiling, rules, recovery
 ```
 
+### Quick start (no commands to learn)
+
+```bash
+pip install learnstat
+learnstat
+```
+
+That is all. learnstat walks you through everything in plain English:
+
+1. **Pick your AI** (optional): choose the company, paste your key, choose a model. learnstat tests it and says OK or what is wrong.
+2. **Choose your data**: press Enter and a normal file window opens (CSV or Excel), or drag the file into the terminal.
+3. **Pick what to do from a menu** by typing a number:
+
+```
+  1) See a summary of my data
+  2) Ask the AI a question about my data
+  3) Get suggestions for a Python script
+  4) Run a Python script with automatic help
+  5) Write Python code here (my data is ready as "df")
+  6) Learn a statistics topic
+  7) Load a different data file
+  8) Change the AI (company, key, model)
+  9) Help
+```
+
+Nothing else needs to be memorised: every option asks for what it needs, and option 9 explains the menu. Skip the AI and everything still works with built-in rules.
+
 ### Add an AI (optional)
 
 Just run `learnstat`. If no AI is set up yet it offers a guided setup, and you can repeat it any time with `learnstat setup` (or `/ai` inside a session):
@@ -147,6 +174,7 @@ learnstat/
   config.py       saved AI accounts: provider, api_key, base_url, model
   providers.py    presets for the AI companies
   setup.py        guided terminal setup (company -> key -> model -> check)
+  guide.py        the numbered home menu students use
   session.py      ties it together; read_csv/track/check/run
   commands.py     slash commands
   ipython_ext.py  %load_ext learnstat

{learnstat-0.2.0 → learnstat-0.2.1}/learnstat/__init__.py

@@ -21,7 +21,7 @@ from .recovery import Executor, RunResult
 from .session import Session, get_session, set_session
 from .suggestions import Suggestion
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 
 def read_csv(path, name: str | None = None, **kwargs):

{learnstat-0.2.0 → learnstat-0.2.1}/learnstat/cli.py

@@ -118,8 +118,9 @@ def _repl(s: Session, data: str | None) -> int:
     ready = ["pd", "np"]
     if data:
         s.ns["df"] = s.read_csv(data)
+    if "df" in s.ns:
         ready.insert(0, "df")
-    print(f"learnstat REPL - AI: {s.ai_status}. Ready: {', '.join(ready)}. Type /help for commands, /ai to change the AI, Ctrl+Z/Ctrl+D to exit.")
+    print(f"learnstat REPL - AI: {s.ai_status}. Ready: {', '.join(ready)}. Type /help for commands, /ai to change the AI, 'menu' to go back, Ctrl+Z/Ctrl+D to exit.")
     buffer: list[str] = []
     while True:
         try:
@@ -127,6 +128,8 @@ def _repl(s: Session, data: str | None) -> int:
         except (EOFError, KeyboardInterrupt):
             print()
             return 0
+        if not buffer and line.strip().lower() in ("menu", "back", "exit", "quit", "exit()", "quit()"):
+            return 0
         if not buffer and is_command(line):
             print(s.command(line))
             continue
@@ -205,18 +208,6 @@ def cmd_config(args) -> int:
     return 0
 
 
-def _ask_data() -> str | None:
-    try:
-        print()
-        path = input("Dataset to load (CSV/Excel path, Enter to skip): ").strip().strip('"')
-    except (EOFError, KeyboardInterrupt):
-        return None
-    if path and not Path(path).exists():
-        print(f"  '{path}' was not found - starting without a dataset.")
-        return None
-    return path or None
-
-
 def _start(args, run_setup: bool) -> int:
     """The guided start: (optional) AI setup, a quick AI check, then the interactive session."""
     from . import config
@@ -251,8 +242,10 @@ def _start(args, run_setup: bool) -> int:
                 print()
                 print(f"X  {a.last_error}")
                 print("   Continuing with offline rules. Type /ai in the session to fix it.")
+    from .guide import run_guide
+
     s = _session(args)
-    return _repl(s, args.data or _ask_data())
+    return run_guide(s, repl=lambda: _repl(s, None), data=args.data)
 
 
 def cmd_setup(args) -> int:

learnstat-0.2.1/learnstat/guide.py

@@ -0,0 +1,266 @@
+"""The guided home screen: students pick numbers from a menu instead of learning commands.
+
+After the AI is set up, ``learnstat`` shows this menu. Every action asks for what it
+needs in plain English (pick a file in a window, type a question) and prints the result.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Callable
+
+from .session import Session
+from .setup import Cancelled, IO, run_wizard
+
+DATA_TYPES = [("Data files", "*.csv *.tsv *.txt *.xlsx *.xls *.json *.parquet"), ("All files", "*.*")]
+SCRIPT_TYPES = [("Python files", "*.py"), ("All files", "*.*")]
+
+MENU = """
+What would you like to do?
+
+  1) See a summary of my data
+  2) Ask the AI a question about my data
+  3) Get suggestions for a Python script
+  4) Run a Python script with automatic help
+  5) Write Python code here (my data is ready as "df")
+  6) Learn a statistics topic
+  7) Load a different data file
+  8) Change the AI (company, key, model)
+  9) Help
+  q) Quit"""
+
+HELP_TEXT = """
+How learnstat works
+-------------------
+1  Shows what is in your data: columns, types, missing values and possible problems.
+2  Type any question in your own words, for example "which column has the most missing values?".
+3  Pick a Python file. learnstat reads it (without running it) and suggests better statistics
+   or charts for your data. Enter a suggestion's number to get it explained.
+4  Runs your Python file. If it crashes on a simple mistake (like a misspelled column) learnstat
+   explains it and can fix it for you.
+5  A Python prompt with your data already loaded as df. Type "menu" to come back here.
+   Inside it, lines starting with / are shortcuts, and /help lists them.
+6  Short lessons, for example "t-test", "correlation" or "missing values".
+7  Load another file.     8  Switch to another AI company or key.
+
+The AI is optional: without it learnstat still gives rule-based suggestions and explanations."""
+
+PYTHON_TIPS = (
+    'Python prompt - your data is "df". Try: df.head()  or  df.describe()\n'
+    '  Type /help for shortcuts, "menu" to go back to the menu.'
+)
+
+
+def pick_file(title: str, types: list[tuple[str, str]]) -> str | None:
+    """Open the system file window. Returns None when cancelled or when no window is available."""
+    try:
+        import tkinter
+        from tkinter import filedialog
+
+        root = tkinter.Tk()
+        root.withdraw()
+        root.attributes("-topmost", True)
+        try:
+            path = filedialog.askopenfilename(title=title, filetypes=types)
+        finally:
+            root.destroy()
+        return path or None
+    except Exception:
+        return None
+
+
+def _clean(path: str) -> str:
+    return path.strip().strip("\"'")
+
+
+def ask_file(io: IO, pick: Callable, what: str, types: list[tuple[str, str]]) -> Path | None:
+    answer = io.line(f"\nChoose your {what}. Press Enter to browse, or paste / drag the file here (b = back): ")
+    if answer.lower() in ("b", "back"):
+        return None
+    if not answer:
+        chosen = pick(f"Choose your {what}", types)
+        if not chosen:
+            io.say("No file chosen. You can also paste the full path to the file.")
+            return None
+        answer = chosen
+    path = Path(_clean(answer)).expanduser()
+    if not path.is_file():
+        io.say(f"I can't find '{path}'. Check the name, or press Enter next time to browse for it.")
+        return None
+    return path
+
+
+def load_dataset(s: Session, io: IO, path: Path):
+    suffix = path.suffix.lower()
+    try:
+        if suffix in (".xlsx", ".xls"):
+            df = s.read_excel(path)
+        elif suffix == ".json":
+            df = s.read_json(path)
+        elif suffix == ".parquet":
+            df = s.read_parquet(path)
+        elif suffix == ".tsv":
+            df = s.read_csv(path, sep="\t")
+        else:
+            df = s.read_csv(path)
+    except ImportError as e:
+        io.say(f"Reading {suffix} files needs an extra package: {e}")
+        return None
+    except Exception as e:
+        io.say(f"I couldn't read that file as data ({type(e).__name__}: {e}).")
+        return None
+    s.ns["df"] = df
+    io.say('\nYour data is ready, and is available as "df" when you write Python code.')
+    return df
+
+
+# ---------------------------------------------------------------------------
+# menu actions
+
+
+def _summary(s: Session, io: IO) -> None:
+    if not s.datasets:
+        io.say("No data is loaded yet - choose 7 to load a file.")
+        return
+    io.say("\n" + s.profile_markdown())
+
+
+def _ask_ai(s: Session, io: IO) -> None:
+    if not s.assistant:
+        io.say(f"The AI is {s.ai_status}. Choose 8 to set one up - or use 6 for built-in lessons.")
+        return
+    io.say('\nAsk anything about your data. Example: "which columns have missing values?"')
+    while True:
+        question = io.line("\nYour question (Enter to go back): ")
+        if not question:
+            return
+        io.say("\nThinking ...")
+        io.say(s.command(f"/ask {question}"))
+
+
+def _read_script(io: IO, pick: Callable) -> tuple[Path, str] | None:
+    path = ask_file(io, pick, "Python file", SCRIPT_TYPES)
+    if path is None:
+        return None
+    code = path.read_text(encoding="utf-8")
+    try:
+        compile(code, str(path), "exec")
+    except SyntaxError as e:
+        io.say(f"There is a syntax error on line {e.lineno}: {e.msg}. Fix it and try again.")
+        return None
+    return path, code
+
+
+def _check_script(s: Session, io: IO, pick: Callable) -> None:
+    got = _read_script(io, pick)
+    if got is None:
+        return
+    path, code = got
+    found = s.check(code, show=False, extra_frames=s.profiles_for_code(code, base_dir=path.parent))
+    if not found:
+        io.say("\nNo suggestions - the rules found nothing to improve for this data.")
+        return
+    io.say(f"\n{len(found)} suggestion(s):\n")
+    for sug in found:
+        io.say(sug.render())
+        io.say("")
+    while True:
+        pick_id = io.line("Enter a suggestion number to have it explained (Enter to go back): ")
+        if not pick_id:
+            return
+        io.say("\n" + s.command(f"/describe {pick_id.lstrip('#')}") + "\n")
+
+
+def _run_script(s: Session, io: IO, pick: Callable) -> None:
+    got = _read_script(io, pick)
+    if got is None:
+        return
+    path, code = got
+    s.ns.update({"__name__": "__main__", "__file__": str(path.resolve())})
+    sys.path.insert(0, str(path.parent.resolve()))
+    s.check(code, extra_frames=s.profiles_for_code(code, base_dir=path.parent))
+    result = s.run(code, check=False, filename=str(path))
+    if result.ok:
+        io.say("\nDone - the script finished.")
+        if result.changed and io.yes("learnstat corrected something. Save a corrected copy next to your file?"):
+            out = path.with_suffix(".fixed.py")
+            out.write_text(result.final_code, encoding="utf-8")
+            io.say(f"Saved {out} (your original is unchanged).")
+    else:
+        io.say("\nThe script stopped with an error.")
+        if io.yes("Explain what went wrong?"):
+            io.say("\n" + s.command("/describe"))
+
+
+def _learn(s: Session, io: IO) -> None:
+    io.say('\nExamples: t-test, correlation, missing values, skewed data, pie charts, histograms')
+    topic = io.line("Topic (Enter for a lesson about your latest suggestion): ")
+    io.say("\n" + s.command(f"/learn {topic}".strip()))
+
+
+def _load(s: Session, io: IO, pick: Callable) -> None:
+    path = ask_file(io, pick, "data file (CSV or Excel)", DATA_TYPES)
+    if path is not None:
+        load_dataset(s, io, path)
+
+
+def _change_ai(s: Session, io: IO) -> None:
+    run_wizard(io)
+    s.connect_ai()
+    io.say(f"\nAI: {s.ai_status}")
+
+
+# ---------------------------------------------------------------------------
+
+
+def run_guide(s: Session, io: IO | None = None, pick: Callable = pick_file,
+              repl: Callable[[], object] | None = None, data: str | None = None) -> int:
+    """Show the home menu until the user quits."""
+    io = io or IO()
+    io.say("\n" + "=" * 60 + "\n learnstat - learn statistics with Python\n" + "=" * 60)
+    io.say(f"AI: {s.ai_status}")
+    try:
+        if data:
+            path = Path(_clean(data)).expanduser()
+            if path.is_file():
+                load_dataset(s, io, path)
+            else:
+                io.say(f"I can't find '{path}'.")
+        elif io.yes("\nLoad your data file now?"):
+            try:
+                _load(s, io, pick)
+            except Cancelled:
+                pass
+        actions: dict[str, Callable[[], None]] = {
+            "1": lambda: _summary(s, io),
+            "2": lambda: _ask_ai(s, io),
+            "3": lambda: _check_script(s, io, pick),
+            "4": lambda: _run_script(s, io, pick),
+            "6": lambda: _learn(s, io),
+            "7": lambda: _load(s, io, pick),
+            "8": lambda: _change_ai(s, io),
+            "9": lambda: io.say(HELP_TEXT),
+        }
+        if repl is not None:
+            def python_mode() -> None:
+                io.say("\n" + PYTHON_TIPS)
+                repl()
+            actions["5"] = python_mode
+        while True:
+            io.say(MENU)
+            choice = io.line("\nType a number: ").lower()
+            if choice in ("q", "quit", "exit"):
+                break
+            action = actions.get(choice)
+            if action is None:
+                io.say("Please type one of the numbers in the menu (or q to quit).")
+                continue
+            try:
+                action()
+            except Cancelled:
+                io.say("\n(back to the menu)")
+    except Cancelled:
+        pass
+    io.say("\nGoodbye - your dataset profiles are saved in .learnstat/ so next time is faster.")
+    return 0

{learnstat-0.2.0 → learnstat-0.2.1}/learnstat.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learnstat
-Version: 0.2.0
+Version: 0.2.1
 Summary: An AI-assisted learning companion for statistical analysis with pandas, NumPy, SciPy and Matplotlib.
 License: MIT
 Project-URL: Homepage, https://github.com/umorfaruksupto/leanstat
@@ -54,6 +54,33 @@ pip install -e ".[all]"        # pandas, numpy, matplotlib, scipy, ipython
 pip install -e .               # core only: profiling, rules, recovery
 ```
 
+### Quick start (no commands to learn)
+
+```bash
+pip install learnstat
+learnstat
+```
+
+That is all. learnstat walks you through everything in plain English:
+
+1. **Pick your AI** (optional): choose the company, paste your key, choose a model. learnstat tests it and says OK or what is wrong.
+2. **Choose your data**: press Enter and a normal file window opens (CSV or Excel), or drag the file into the terminal.
+3. **Pick what to do from a menu** by typing a number:
+
+```
+  1) See a summary of my data
+  2) Ask the AI a question about my data
+  3) Get suggestions for a Python script
+  4) Run a Python script with automatic help
+  5) Write Python code here (my data is ready as "df")
+  6) Learn a statistics topic
+  7) Load a different data file
+  8) Change the AI (company, key, model)
+  9) Help
+```
+
+Nothing else needs to be memorised: every option asks for what it needs, and option 9 explains the menu. Skip the AI and everything still works with built-in rules.
+
 ### Add an AI (optional)
 
 Just run `learnstat`. If no AI is set up yet it offers a guided setup, and you can repeat it any time with `learnstat setup` (or `/ai` inside a session):
@@ -177,6 +204,7 @@ learnstat/
   config.py       saved AI accounts: provider, api_key, base_url, model
   providers.py    presets for the AI companies
   setup.py        guided terminal setup (company -> key -> model -> check)
+  guide.py        the numbered home menu students use
   session.py      ties it together; read_csv/track/check/run
   commands.py     slash commands
   ipython_ext.py  %load_ext learnstat

{learnstat-0.2.0 → learnstat-0.2.1}/learnstat.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ learnstat/advisor.py
 learnstat/cli.py
 learnstat/commands.py
 learnstat/config.py
+learnstat/guide.py
 learnstat/ipython_ext.py
 learnstat/knowledge.py
 learnstat/llm.py

{learnstat-0.2.0 → learnstat-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "learnstat"
-version = "0.2.0"
+version = "0.2.1"
 description = "An AI-assisted learning companion for statistical analysis with pandas, NumPy, SciPy and Matplotlib."
 readme = "README.md"
 requires-python = ">=3.10"

{learnstat-0.2.0 → learnstat-0.2.1}/tests/test_ai_config.py

@@ -256,3 +256,66 @@ def test_ai_slash_list(server):
     s = Session(ai=False, out=lambda *_: None)
     out = dispatch(s, "/ai list")
     assert "x:" in out and "gpt-a" in out and "k1234567890" not in out
+
+
+# ---------------------------------------------------------------------------
+# guided menu
+
+
+def _guide_run(tmp_path, answers, files=None, **kw):
+    from learnstat.guide import run_guide
+    from learnstat.session import Session
+
+    s = Session(memory_dir=tmp_path / "mem", ai=False, out=lambda *_: None, confirm=lambda q: True)
+    script = Script(answers)
+    queue = list(files or [])
+    pick = lambda title, types: queue.pop(0) if queue else None
+    rc = run_guide(s, script.io(), pick=pick, **kw)
+    return s, script, rc
+
+
+def test_guide_load_data_with_file_window_and_summary(tmp_path):
+    csv = tmp_path / "survey.csv"
+    csv.write_text("age,income\n20,100\n30,200\n40,\n", encoding="utf-8")
+    # load now? y -> Enter opens the file window -> menu: 1 (summary) -> q
+    s, script, rc = _guide_run(tmp_path, ["y", "", "1", "q"], files=[str(csv)])
+    assert rc == 0 and "df" in s.ns and list(s.datasets) == ["survey"]
+    assert 'available as "df"' in script.text and "survey" in script.text
+
+
+def test_guide_missing_file_and_bad_menu_choice(tmp_path):
+    s, script, _ = _guide_run(tmp_path, ["y", str(tmp_path / "nope.csv"), "zzz", "q"])
+    assert "I can't find" in script.text and "Please type one of the numbers" in script.text
+
+
+def test_guide_check_script_and_explain(tmp_path):
+    csv = tmp_path / "survey.csv"
+    csv.write_text("country,income\n" + "\n".join(f"c{i % 12},{i * 10}" for i in range(60)) + "\n", encoding="utf-8")
+    py = tmp_path / "analysis.py"
+    py.write_text(f"import pandas as pd\ndf = pd.read_csv(r'{csv}')\ndf['country'].value_counts().plot.pie()\n", encoding="utf-8")
+    s, script, _ = _guide_run(tmp_path, ["n", "3", str(py), "1", "", "q"])
+    assert "suggestion(s)" in script.text and "Pie chart" in script.text
+    assert "In your code:" in script.text  # the /describe explanation
+
+
+def test_guide_run_script_with_automatic_help(tmp_path):
+    py = tmp_path / "ok.py"
+    py.write_text("total = 1 + 1\n", encoding="utf-8")
+    s, script, _ = _guide_run(tmp_path, ["n", "4", str(py), "q"])
+    assert "the script finished" in script.text and s.ns["total"] == 2
+
+
+def test_guide_without_ai_points_to_setup(tmp_path):
+    s, script, _ = _guide_run(tmp_path, ["n", "2", "q"])
+    assert "Choose 8" in script.text
+
+
+def test_guide_python_mode_returns_to_menu(tmp_path):
+    called = []
+    s, script, _ = _guide_run(tmp_path, ["n", "5", "q"], repl=lambda: called.append(1))
+    assert called == [1] and "Python prompt" in script.text
+
+
+def test_guide_ctrl_c_leaves_cleanly(tmp_path):
+    s, script, rc = _guide_run(tmp_path, [])  # input ends immediately (EOF)
+    assert rc == 0 and "Goodbye" in script.text