stata-cli 0.2.2__tar.gz → 0.4.0__tar.gz

{stata_cli-0.2.2 → stata_cli-0.4.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: stata-cli
-Version: 0.2.2
+Version: 0.4.0
 Summary: Command-line interface for running Stata commands via PyStata
 License: MIT
 Keywords: stata,cli,statistics,data-science
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.0
 Provides-Extra: data
@@ -13,8 +13,12 @@ Requires-Dist: pandas; extra == "data"
 
 # stata-cli
 
+> **Stata CLI Is All Reg Monkeys Need**
+
+![stata-cli banner](assets/banner.png)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://www.python.org/)
 [![npm version](https://img.shields.io/npm/v/stata-cli.svg)](https://www.npmjs.com/package/stata-cli)
 
 [中文版](README.zh.md) | [English](README.md)
@@ -39,18 +43,25 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Run Code** | Execute inline Stata code, multi-line blocks, or pipe from stdin |
 | **Do Files** | Run `.do` files with `///` line continuation support and graph auto-naming |
 | **Data Viewer** | View current dataset as JSON with `if`-condition filtering and row limits |
+| **Variable Metadata** | Inspect variable names, types, formats, and labels via `vars` |
+| **Stored Results** | Retrieve r(), e(), s() results as structured JSON via `return` |
+| **Matrix Access** | Read Stata matrices (e.g. `e(b)`, `e(V)`) as JSON via `matrix` |
+| **Value Labels** | List and inspect value labels via `labels` |
+| **Macro Access** | Get/set Stata macros including `c()`, `e()`, `r()` system macros |
+| **Frame Management** | List Stata frames and current working frame via `frame` |
 | **Help System** | Browse Stata help topics with SMCL-to-plain-text conversion |
-| **Graph Export** | Auto-detect and export graphs as PNG to `~/.stata-cli/graphs/` |
+| **Graph Export** | Auto-detect and export graphs as PNG/SVG/PDF to `~/.stata-cli/graphs/` |
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
-| **Output Control** | Compact mode, JSON output, token limit management with full-output file save |
+| **Output Control** | Compact mode, JSON output, token limit management, log file output |
 | **Interruption** | Send break signal to stop long-running commands |
+| **Skill Library** | Built-in Stata reference with 57 topics: syntax, econometrics, causal inference, packages |
 
 ## Installation & Quick Start
 
 ### Requirements
 
 - **Stata 17+** installed on your machine (provides the PyStata library)
-- Python 3.10+
+- Python 3.9+
 
 ### Quick Start (Human Users)
 
@@ -197,6 +208,72 @@ stata-cli detect
 
 Prints the auto-detected Stata installation path.
 
+### `return` — Retrieve Stored Results
+
+```bash
+stata-cli return r         # r() results (after summarize, etc.)
+stata-cli return e         # e() results (after regress, etc.)
+stata-cli return s         # s() results
+```
+
+Returns r(), e(), or s() stored results as structured JSON — scalars, macros, and matrix references.
+
+### `vars` — Variable Metadata
+
+```bash
+stata-cli vars                # all variables
+stata-cli vars price mpg      # specific variables
+```
+
+Returns variable names, types, formats, and labels as JSON. More structured than `describe`.
+
+### `matrix` — Read Stata Matrices
+
+```bash
+stata-cli matrix e(b)         # coefficient vector
+stata-cli matrix e(V)         # variance-covariance matrix
+```
+
+Returns matrix data, dimensions, and row/column names as JSON.
+
+### `labels` — Value Labels
+
+```bash
+stata-cli labels               # list all value label names
+stata-cli labels origin        # show value-label mapping
+stata-cli labels --var foreign # show label attached to a variable
+```
+
+### `macro` — Get/Set Macros
+
+```bash
+stata-cli macro get "c(current_date)"
+stata-cli macro get "e(cmd)"
+stata-cli macro set myvar "hello"
+```
+
+Access Stata macros including system macros (`c()`, `e()`, `r()`).
+
+### `frame` — List Frames
+
+```bash
+stata-cli frame
+```
+
+Shows all Stata frames and the current working frame.
+
+### `skill` — Stata Reference Library
+
+```bash
+stata-cli skill                # overview: gotchas, patterns, topic routing table
+stata-cli skill --list         # list all 57 topics with descriptions
+stata-cli skill regression     # linear regression reference
+stata-cli skill did            # difference-in-differences guide
+stata-cli skill reghdfe        # reghdfe package guide
+```
+
+Built-in reference library covering data management, econometrics, causal inference, graphics, Mata programming, and 20+ community packages. Aliases supported (e.g. `did` for `difference-in-differences`, `panel` for `panel-data`).
+
 ## Daemon Mode
 
 The daemon keeps PyStata alive in the background — reduces execution time from **~2-3s to ~85ms** (35x speedup).
@@ -234,6 +311,8 @@ The daemon auto-shuts down after 1 hour of inactivity (configurable with `--idle
 | `--max-tokens N` | Max output tokens (0=unlimited) | 0 |
 | `--no-daemon` | Force direct execution | off |
 | `--graphs-dir PATH` | Graph export directory | `~/.stata-cli/graphs/` |
+| `--graph-format [png\|svg\|pdf]` | Graph export format | `png` |
+| `--log PATH` | Save output to a log file | off |
 
 ### JSON Output
 
@@ -313,6 +392,21 @@ regress price mpg weight
 predict yhat
 list make price yhat in 1/5"
 
+# Retrieve regression results as structured JSON
+stata-cli return e
+
+# Get coefficient matrix
+stata-cli matrix e(b)
+
+# Inspect variable metadata
+stata-cli vars price mpg weight
+
+# Check value labels
+stata-cli labels --var foreign
+
+# Read system macros
+stata-cli macro get "c(N)"
+
 # Check data after loading
 stata-cli data --if "price>10000"
 
@@ -325,6 +419,9 @@ describe"
 
 # JSON mode for structured parsing
 stata-cli --json run "display 1+1"
+
+# Export graph as SVG
+stata-cli --graph-format svg run "scatter price mpg"
 ```
 
 ## Contributing

{stata_cli-0.2.2 → stata_cli-0.4.0}/README.md

@@ -1,7 +1,11 @@
 # stata-cli
 
+> **Stata CLI Is All Reg Monkeys Need**
+
+![stata-cli banner](assets/banner.png)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://www.python.org/)
 [![npm version](https://img.shields.io/npm/v/stata-cli.svg)](https://www.npmjs.com/package/stata-cli)
 
 [中文版](README.zh.md) | [English](README.md)
@@ -26,18 +30,25 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Run Code** | Execute inline Stata code, multi-line blocks, or pipe from stdin |
 | **Do Files** | Run `.do` files with `///` line continuation support and graph auto-naming |
 | **Data Viewer** | View current dataset as JSON with `if`-condition filtering and row limits |
+| **Variable Metadata** | Inspect variable names, types, formats, and labels via `vars` |
+| **Stored Results** | Retrieve r(), e(), s() results as structured JSON via `return` |
+| **Matrix Access** | Read Stata matrices (e.g. `e(b)`, `e(V)`) as JSON via `matrix` |
+| **Value Labels** | List and inspect value labels via `labels` |
+| **Macro Access** | Get/set Stata macros including `c()`, `e()`, `r()` system macros |
+| **Frame Management** | List Stata frames and current working frame via `frame` |
 | **Help System** | Browse Stata help topics with SMCL-to-plain-text conversion |
-| **Graph Export** | Auto-detect and export graphs as PNG to `~/.stata-cli/graphs/` |
+| **Graph Export** | Auto-detect and export graphs as PNG/SVG/PDF to `~/.stata-cli/graphs/` |
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
-| **Output Control** | Compact mode, JSON output, token limit management with full-output file save |
+| **Output Control** | Compact mode, JSON output, token limit management, log file output |
 | **Interruption** | Send break signal to stop long-running commands |
+| **Skill Library** | Built-in Stata reference with 57 topics: syntax, econometrics, causal inference, packages |
 
 ## Installation & Quick Start
 
 ### Requirements
 
 - **Stata 17+** installed on your machine (provides the PyStata library)
-- Python 3.10+
+- Python 3.9+
 
 ### Quick Start (Human Users)
 
@@ -184,6 +195,72 @@ stata-cli detect
 
 Prints the auto-detected Stata installation path.
 
+### `return` — Retrieve Stored Results
+
+```bash
+stata-cli return r         # r() results (after summarize, etc.)
+stata-cli return e         # e() results (after regress, etc.)
+stata-cli return s         # s() results
+```
+
+Returns r(), e(), or s() stored results as structured JSON — scalars, macros, and matrix references.
+
+### `vars` — Variable Metadata
+
+```bash
+stata-cli vars                # all variables
+stata-cli vars price mpg      # specific variables
+```
+
+Returns variable names, types, formats, and labels as JSON. More structured than `describe`.
+
+### `matrix` — Read Stata Matrices
+
+```bash
+stata-cli matrix e(b)         # coefficient vector
+stata-cli matrix e(V)         # variance-covariance matrix
+```
+
+Returns matrix data, dimensions, and row/column names as JSON.
+
+### `labels` — Value Labels
+
+```bash
+stata-cli labels               # list all value label names
+stata-cli labels origin        # show value-label mapping
+stata-cli labels --var foreign # show label attached to a variable
+```
+
+### `macro` — Get/Set Macros
+
+```bash
+stata-cli macro get "c(current_date)"
+stata-cli macro get "e(cmd)"
+stata-cli macro set myvar "hello"
+```
+
+Access Stata macros including system macros (`c()`, `e()`, `r()`).
+
+### `frame` — List Frames
+
+```bash
+stata-cli frame
+```
+
+Shows all Stata frames and the current working frame.
+
+### `skill` — Stata Reference Library
+
+```bash
+stata-cli skill                # overview: gotchas, patterns, topic routing table
+stata-cli skill --list         # list all 57 topics with descriptions
+stata-cli skill regression     # linear regression reference
+stata-cli skill did            # difference-in-differences guide
+stata-cli skill reghdfe        # reghdfe package guide
+```
+
+Built-in reference library covering data management, econometrics, causal inference, graphics, Mata programming, and 20+ community packages. Aliases supported (e.g. `did` for `difference-in-differences`, `panel` for `panel-data`).
+
 ## Daemon Mode
 
 The daemon keeps PyStata alive in the background — reduces execution time from **~2-3s to ~85ms** (35x speedup).
@@ -221,6 +298,8 @@ The daemon auto-shuts down after 1 hour of inactivity (configurable with `--idle
 | `--max-tokens N` | Max output tokens (0=unlimited) | 0 |
 | `--no-daemon` | Force direct execution | off |
 | `--graphs-dir PATH` | Graph export directory | `~/.stata-cli/graphs/` |
+| `--graph-format [png\|svg\|pdf]` | Graph export format | `png` |
+| `--log PATH` | Save output to a log file | off |
 
 ### JSON Output
 
@@ -300,6 +379,21 @@ regress price mpg weight
 predict yhat
 list make price yhat in 1/5"
 
+# Retrieve regression results as structured JSON
+stata-cli return e
+
+# Get coefficient matrix
+stata-cli matrix e(b)
+
+# Inspect variable metadata
+stata-cli vars price mpg weight
+
+# Check value labels
+stata-cli labels --var foreign
+
+# Read system macros
+stata-cli macro get "c(N)"
+
 # Check data after loading
 stata-cli data --if "price>10000"
 
@@ -312,6 +406,9 @@ describe"
 
 # JSON mode for structured parsing
 stata-cli --json run "display 1+1"
+
+# Export graph as SVG
+stata-cli --graph-format svg run "scatter price mpg"
 ```
 
 ## Contributing

{stata_cli-0.2.2 → stata_cli-0.4.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "stata-cli"
-version = "0.2.2"
+version = "0.4.0"
 description = "Command-line interface for running Stata commands via PyStata"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 license = {text = "MIT"}
 keywords = ["stata", "cli", "statistics", "data-science"]
 
@@ -23,3 +23,6 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+stata_cli = ["skills/**/*.md"]

stata_cli-0.4.0/src/stata_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{stata_cli-0.2.2 → stata_cli-0.4.0}/src/stata_cli/daemon.py

@@ -162,6 +162,37 @@ class DaemonServer:
             ok = self._engine.stop()
             _send_msg(conn, {"status": "ok" if ok else "no_op"})
 
+        elif cmd_type == "get_return":
+            data = self._engine.get_return(rtype=payload.get("rtype", "r"))
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_vars":
+            data = self._engine.get_vars()
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_matrix":
+            data = self._engine.get_matrix(payload.get("name", ""))
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_labels":
+            data = self._engine.get_labels(
+                name=payload.get("name"),
+                var=payload.get("var"),
+            )
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_macro":
+            data = self._engine.get_macro(payload.get("name", ""))
+            _send_msg(conn, data)
+
+        elif cmd_type == "set_macro":
+            data = self._engine.set_macro(payload.get("name", ""), payload.get("value", ""))
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_frames":
+            data = self._engine.get_frames()
+            _send_msg(conn, data)
+
         elif cmd_type == "status":
             _send_msg(conn, {
                 "status": "ok",

{stata_cli-0.2.2 → stata_cli-0.4.0}/src/stata_cli/engine.py

@@ -50,14 +50,18 @@ _EXISTING_GRAPHN_RE = re.compile(r"\bname\s*\(\s*graph(\d+)", re.IGNORECASE)
 class StataEngine:
     """Thin wrapper around PyStata for single-process command execution."""
 
-    def __init__(self, stata_path: str, edition: str = "mp", graphs_dir: Optional[str] = None):
+    def __init__(self, stata_path: str, edition: str = "mp", graphs_dir: Optional[str] = None, graph_format: str = "png"):
         self.stata_path = stata_path
         self.edition = edition.lower()
         self.graphs_dir = graphs_dir or get_graphs_root()
+        self.graph_format = graph_format.lower()
         self._stata = None
         self._stlib = None
         self._initialized = False
         self._stop_sent = False
+        self._last_r: dict = {}
+        self._last_e: dict = {}
+        self._last_s: dict = {}
 
     def _ensure_initialized(self) -> None:
         if self._initialized:
@@ -89,6 +93,13 @@ class StataEngine:
 
         self._stata = stata_module
 
+        if self.graph_format != "png":
+            try:
+                from pystata import config as pystata_config  # type: ignore[import-untyped]
+                pystata_config.set_graph_format(self.graph_format)
+            except Exception:
+                pass
+
         try:
             from pystata.config import stlib as stlib_module  # type: ignore[import-untyped]
             self._stlib = stlib_module
@@ -113,19 +124,27 @@ class StataEngine:
         )
         log_file_stata = log_file.replace("\\", "/")
 
-        wrapped = (
+        setup = (
             f'capture log close _all\n'
             f'log using "{log_file_stata}", replace text\n'
-            f'{code}\n'
-            f'capture log close _all\n'
         )
+        teardown = 'capture log close _all\n'
 
         start = time.time()
         try:
             old_stdout = sys.stdout
             sys.stdout = io.StringIO()
             try:
-                self._stata.run(wrapped, echo=True, inline=False)
+                self._stata.run(setup + code, echo=True, inline=False)
+            finally:
+                sys.stdout = old_stdout
+
+            self._capture_stored_results()
+
+            old_stdout = sys.stdout
+            sys.stdout = io.StringIO()
+            try:
+                self._stata.run(teardown, echo=False, inline=False)
             finally:
                 captured_stdout = sys.stdout.getvalue()
                 sys.stdout = old_stdout
@@ -300,6 +319,119 @@ class StataEngine:
 
         return result
 
+    def get_return(self, rtype: str = "r") -> Dict[str, Any]:
+        """Retrieve stored results: r(), e(), or s()."""
+        self._ensure_initialized()
+        try:
+            if rtype == "r":
+                return {"status": "success", "type": "r", "results": dict(self._last_r)}
+            elif rtype == "e":
+                return {"status": "success", "type": "e", "results": dict(self._last_e)}
+            elif rtype == "s":
+                return {"status": "success", "type": "s", "results": dict(self._last_s)}
+            else:
+                return {"status": "error", "error": f"Unknown return type: {rtype}"}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_vars(self) -> Dict[str, Any]:
+        """Return variable metadata for the current dataset."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            nvar = sfi.Data.getVarCount()
+            nobs = sfi.Data.getObsTotal()
+            variables = []
+            for i in range(nvar):
+                name = sfi.Data.getVarName(i)
+                variables.append({
+                    "name": name,
+                    "type": sfi.Data.getVarType(i),
+                    "format": sfi.Data.getVarFormat(i),
+                    "label": sfi.Data.getVarLabel(i),
+                    "is_string": sfi.Data.isVarTypeStr(i),
+                })
+            return {
+                "status": "success",
+                "n_vars": nvar,
+                "n_obs": nobs,
+                "variables": variables,
+            }
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_matrix(self, name: str) -> Dict[str, Any]:
+        """Return a Stata matrix as a dict."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            nrows = sfi.Matrix.getRowTotal(name)
+            ncols = sfi.Matrix.getColTotal(name)
+            row_names = sfi.Matrix.getRowNames(name)
+            col_names = sfi.Matrix.getColNames(name)
+            data = sfi.Matrix.get(name)
+            return {
+                "status": "success",
+                "name": name,
+                "rows": nrows,
+                "cols": ncols,
+                "row_names": row_names,
+                "col_names": col_names,
+                "data": data,
+            }
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_labels(self, name: Optional[str] = None, var: Optional[str] = None) -> Dict[str, Any]:
+        """Return value labels."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            if var:
+                label_name = sfi.ValueLabel.getVarValueLabel(var)
+                if not label_name:
+                    return {"status": "success", "variable": var, "label_name": "", "labels": {}}
+                mapping = sfi.ValueLabel.getValueLabels(label_name)
+                return {"status": "success", "variable": var, "label_name": label_name, "labels": mapping}
+            if name:
+                mapping = sfi.ValueLabel.getValueLabels(name)
+                return {"status": "success", "name": name, "labels": mapping}
+            names = sfi.ValueLabel.getNames()
+            return {"status": "success", "names": names}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_macro(self, name: str) -> Dict[str, Any]:
+        """Get the value of a Stata macro."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            value = sfi.Macro.getGlobal(name)
+            return {"status": "success", "name": name, "value": value}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def set_macro(self, name: str, value: str) -> Dict[str, Any]:
+        """Set a Stata global macro."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            sfi.Macro.setGlobal(name, value)
+            return {"status": "success", "name": name, "value": value}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_frames(self) -> Dict[str, Any]:
+        """Return list of Stata frames and the current working frame."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            frames = sfi.Frame.getFrames()
+            cwf = sfi.Frame.getCWF()
+            return {"status": "success", "frames": frames, "current": cwf}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
     def stop(self) -> bool:
         """Interrupt a running Stata command. Returns True if signal sent."""
         if self._stop_sent or self._stlib is None:
@@ -316,6 +448,44 @@ class StataEngine:
 
     # ── graph detection ──────────────────────────────────────────────────
 
+    def _capture_stored_results(self) -> None:
+        """Snapshot r(), e(), s() results via sfi before log close clears them."""
+        try:
+            import sfi  # type: ignore[import-untyped]
+        except ImportError:
+            return
+
+        for rtype, store in [("r", "_last_r"), ("e", "_last_e"), ("s", "_last_s")]:
+            result: Dict[str, Any] = {}
+            cat = f"{rtype}()"
+            try:
+                scalar_names = sfi.SFIToolkit.listReturn(cat, "scalar")
+                if scalar_names and scalar_names.strip():
+                    for name in scalar_names.strip().split():
+                        try:
+                            result[name] = sfi.Scalar.getValue(f"{rtype}({name})")
+                        except Exception:
+                            pass
+
+                macro_names = sfi.SFIToolkit.listReturn(cat, "macro")
+                if macro_names and macro_names.strip():
+                    for name in macro_names.strip().split():
+                        try:
+                            result[name] = sfi.Macro.getGlobal(f"{rtype}({name})")
+                        except Exception:
+                            pass
+
+                if rtype != "s":
+                    matrix_names = sfi.SFIToolkit.listReturn(cat, "matrix")
+                    if matrix_names and matrix_names.strip():
+                        for name in matrix_names.strip().split():
+                            result[f"matrix:{name}"] = f"[matrix, use 'stata-cli matrix {rtype}({name})']"
+            except Exception:
+                pass
+            setattr(self, store, result)
+
+    # ── graph detection (continued) ─────────────────────────────────────
+
     def _reset_graph_tracking(self) -> None:
         if self._stlib is None:
             return
@@ -348,12 +518,15 @@ class StataEngine:
                     self._stlib.StataSO_Execute(
                         get_encode_str(f"quietly graph display {gname}"), False
                     )
-                    graph_file = os.path.join(batch["batch_dir"], f"{gname}.png")
+                    ext = self.graph_format
+                    graph_file = os.path.join(batch["batch_dir"], f"{gname}.{ext}")
                     graph_file_stata = graph_file.replace("\\", "/")
+                    fmt_opt = f"as({ext}) " if ext != "png" else ""
+                    size_opt = "width(800) height(600)" if ext == "png" else ""
                     export_cmd = (
                         f'quietly graph export "{graph_file_stata}", '
-                        f"name({gname}) replace width(800) height(600)"
-                    )
+                        f"{fmt_opt}name({gname}) replace {size_opt}"
+                    ).rstrip()
                     rc = self._stlib.StataSO_Execute(get_encode_str(export_cmd), False)
                     if rc != 0:
                         continue