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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Command-line interface for running Stata commands via PyStata
 License: MIT
 Keywords: stata,cli,statistics,data-science
@@ -13,6 +13,8 @@ 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)
@@ -52,6 +54,7 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
 | **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
 
@@ -259,6 +262,18 @@ 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).

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

@@ -1,5 +1,7 @@
 # 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)
@@ -39,6 +41,7 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
 | **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
 
@@ -246,6 +249,18 @@ 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).

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

@@ -1,6 +1,6 @@
 [project]
 name = "stata-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Command-line interface for running Stata commands via PyStata"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -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.3.0 → stata_cli-0.4.0}/src/stata_cli/main.py

@@ -406,6 +406,45 @@ def frame_cmd(ctx):
     click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
 
 
+# ── Skill command ────────────────────────────────────────────────────────
+
+@cli.command("skill")
+@click.argument("topic", required=False, default=None)
+@click.option("--list", "list_topics", is_flag=True, default=False, help="List all available topics.")
+@click.pass_context
+def skill_cmd(ctx, topic, list_topics):
+    """Built-in Stata reference library.
+
+    Without arguments, shows the overview (gotchas, common patterns, routing table).
+    With a topic name, shows the detailed reference for that topic.
+
+    \b
+    Examples:
+      stata-cli skill                  # overview
+      stata-cli skill --list           # list all topics
+      stata-cli skill regression       # linear regression reference
+      stata-cli skill did              # difference-in-differences
+      stata-cli skill reghdfe          # reghdfe package guide
+    """
+    from .skill_registry import get_overview, get_topic, list_topics as _list_topics
+
+    if list_topics:
+        click.echo(_list_topics())
+        return
+
+    if topic is None:
+        click.echo(get_overview())
+        return
+
+    content = get_topic(topic)
+    if content is None:
+        click.echo(f"Unknown topic: {topic}", err=True)
+        click.echo("Run 'stata-cli skill --list' to see available topics.", err=True)
+        _exit(EXIT_USAGE_ERROR)
+    else:
+        click.echo(content)
+
+
 # ── Daemon subcommands ───────────────────────────────────────────────────
 
 @cli.group()

stata_cli-0.4.0/src/stata_cli/skill_registry.py

@@ -0,0 +1,171 @@
+"""stata-cli skill — built-in Stata reference library."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+SKILLS_DIR = Path(__file__).parent / "skills"
+
+TOPIC_CATALOG: List[Tuple[str, str, str]] = [
+    # (topic_name, category, description)
+    # Data Operations
+    ("basics", "Data Operations", "Getting started, use, save, describe, browse, sysuse"),
+    ("data-import-export", "Data Operations", "import delimited/excel, export, ODBC, web data"),
+    ("data-management", "Data Operations", "generate, replace, merge, reshape, collapse, egen, encode/decode"),
+    ("variables-operators", "Data Operations", "Variable types, missing values, operators, if/in qualifiers"),
+    ("string-functions", "Data Operations", "substr(), regexm(), split, strtrim(), Unicode"),
+    ("date-time-functions", "Data Operations", "date(), clock(), %td/%tc formats, mdy(), business calendars"),
+    ("mathematical-functions", "Data Operations", "round(), log(), exp(), cond(), distributions, random numbers"),
+    # Statistics & Econometrics
+    ("descriptive-statistics", "Statistics & Econometrics", "summarize, tabulate, correlate, tabstat, codebook"),
+    ("linear-regression", "Statistics & Econometrics", "regress, vce(robust), vce(cluster), margins, predict, ivregress"),
+    ("panel-data", "Statistics & Econometrics", "xtset, xtreg fe/re, Hausman test, dynamic panels"),
+    ("time-series", "Statistics & Econometrics", "tsset, ARIMA, VAR, dfuller, pperron, irf, forecasting"),
+    ("limited-dependent-variables", "Statistics & Econometrics", "logit, probit, tobit, poisson, nbreg, mlogit, ologit"),
+    ("survey-data-analysis", "Statistics & Econometrics", "svyset, svy:, subpop(), complex survey design"),
+    ("bootstrap-simulation", "Statistics & Econometrics", "bootstrap, simulate, permute, Monte Carlo"),
+    ("missing-data-handling", "Statistics & Econometrics", "mi impute, mi estimate, FIML, misstable"),
+    ("maximum-likelihood", "Statistics & Econometrics", "ml model, custom likelihood functions, ml init"),
+    ("gmm-estimation", "Statistics & Econometrics", "gmm, moment conditions, estat overid, J-test"),
+    # Causal Inference
+    ("treatment-effects", "Causal Inference", "teffects ra/ipw/ipwra/aipw, ATE/ATT/ATET"),
+    ("difference-in-differences", "Causal Inference", "DiD, parallel trends, event studies, staggered adoption"),
+    ("regression-discontinuity", "Causal Inference", "Sharp/fuzzy RD, bandwidth selection, rdplot"),
+    ("matching-methods", "Causal Inference", "PSM, nearest neighbor, kernel matching, teffects nnmatch"),
+    ("sample-selection", "Causal Inference", "heckman, heckprobit, exclusion restrictions"),
+    # Advanced Methods
+    ("survival-analysis", "Advanced Methods", "stset, stcox, streg, Kaplan-Meier, parametric models"),
+    ("sem-factor-analysis", "Advanced Methods", "sem, gsem, CFA, path analysis, alpha, reliability"),
+    ("nonparametric-methods", "Advanced Methods", "kdensity, rank tests, qreg, npregress"),
+    ("spatial-analysis", "Advanced Methods", "spmatrix, spregress, spatial weights, Moran's I"),
+    ("machine-learning", "Advanced Methods", "lasso, elasticnet, cvlasso, cross-validation"),
+    # Graphics
+    ("graphics", "Graphics", "twoway, scatter, line, bar, histogram, graph combine, graph export"),
+    # Programming
+    ("programming-basics", "Programming", "local, global, foreach, forvalues, program define, syntax"),
+    ("advanced-programming", "Programming", "syntax, mata, classes, tempfile/tempvar"),
+    ("mata-introduction", "Programming", "Mata basics, when to use Mata vs ado, data types"),
+    ("mata-programming", "Programming", "Mata functions, flow control, structures, pointers"),
+    ("mata-matrix-operations", "Programming", "Matrix creation, decompositions, solvers, st_matrix()"),
+    ("mata-data-access", "Programming", "st_data(), st_view(), st_store(), performance tips"),
+    # Output & Workflow
+    ("tables-reporting", "Output & Workflow", "putexcel, putdocx, putpdf, LaTeX, collect"),
+    ("workflow-best-practices", "Output & Workflow", "Project structure, master do-files, version control"),
+    ("external-tools-integration", "Output & Workflow", "Python via python:, R via rsource, shell, Git"),
+    # Community Packages
+    ("reghdfe", "Community Packages", "High-dimensional fixed effects OLS"),
+    ("estout", "Community Packages", "Publication-quality regression tables (esttab/estout)"),
+    ("outreg2", "Community Packages", "Alternative regression table exporter (Word/Excel/TeX)"),
+    ("asdoc", "Community Packages", "One-command Word document creation for any Stata output"),
+    ("tabout", "Community Packages", "Cross-tabulations and summary tables to file"),
+    ("coefplot", "Community Packages", "Coefficient plots from stored estimates"),
+    ("graph-schemes", "Community Packages", "grstyle, schemepack, plotplain — better graph themes"),
+    ("did", "Community Packages", "Modern DiD: csdid, did_multiplegt, did_imputation"),
+    ("event-study", "Community Packages", "eventstudyinteract, eventdd — event study estimators"),
+    ("rdrobust", "Community Packages", "Robust RD estimation with optimal bandwidth"),
+    ("psmatch2", "Community Packages", "Propensity score matching (nearest neighbor, kernel)"),
+    ("synth", "Community Packages", "Synthetic control method (synth, synth_runner)"),
+    ("ivreg2", "Community Packages", "Enhanced IV/2SLS with additional diagnostics"),
+    ("xtabond2", "Community Packages", "Dynamic panel GMM (Arellano-Bond/Blundell-Bond)"),
+    ("binsreg", "Community Packages", "Binned scatter plots with CI"),
+    ("nprobust", "Community Packages", "Nonparametric kernel estimation and inference"),
+    ("diagnostics", "Community Packages", "bacondecomp, xttest3, collinearity, heteroskedasticity"),
+    ("winsor", "Community Packages", "Winsorizing and trimming: winsor2, winsor"),
+    ("data-manipulation", "Community Packages", "gtools (fast collapse/egen), rangestat, egenmore"),
+    ("package-management", "Community Packages", "ssc install, net install, ado update"),
+]
+
+# Build lookup: topic name -> (category, description)
+_TOPIC_MAP: Dict[str, Tuple[str, str]] = {t[0]: (t[1], t[2]) for t in TOPIC_CATALOG}
+
+# Short aliases for convenience
+_ALIASES: Dict[str, str] = {
+    "basics": "basics-getting-started",
+    "regression": "linear-regression",
+    "panel": "panel-data",
+    "rd": "regression-discontinuity",
+    "diff-in-diff": "difference-in-differences",
+    "matching": "matching-methods",
+    "ts": "time-series",
+    "logit": "limited-dependent-variables",
+    "probit": "limited-dependent-variables",
+    "tobit": "limited-dependent-variables",
+    "survival": "survival-analysis",
+    "sem": "sem-factor-analysis",
+    "ml": "maximum-likelihood",
+    "gmm": "gmm-estimation",
+    "survey": "survey-data-analysis",
+    "bootstrap": "bootstrap-simulation",
+    "mi": "missing-data-handling",
+    "mata": "mata-introduction",
+    "strings": "string-functions",
+    "dates": "date-time-functions",
+    "math": "mathematical-functions",
+    "tables": "tables-reporting",
+    "workflow": "workflow-best-practices",
+    "external": "external-tools-integration",
+    "nonparametric": "nonparametric-methods",
+    "spatial": "spatial-analysis",
+    "lasso": "machine-learning",
+    "missing": "missing-data-handling",
+    "heckman": "sample-selection",
+    "selection": "sample-selection",
+    "iv": "ivreg2",
+    "gtools": "data-manipulation",
+}
+
+
+def _resolve_topic(name: str) -> Optional[str]:
+    """Resolve a topic name (with alias support) to its file stem."""
+    name = name.lower().strip()
+    if name in _ALIASES:
+        name = _ALIASES[name]
+    # Try references/ then packages/
+    for subdir in ("references", "packages"):
+        path = SKILLS_DIR / subdir / f"{name}.md"
+        if path.exists():
+            return str(path)
+    # Try partial match
+    for subdir in ("references", "packages"):
+        d = SKILLS_DIR / subdir
+        if d.is_dir():
+            for f in d.iterdir():
+                if f.suffix == ".md" and name in f.stem:
+                    return str(f)
+    return None
+
+
+def get_overview() -> str:
+    """Return the skill overview content."""
+    overview_path = SKILLS_DIR / "overview.md"
+    if overview_path.exists():
+        return overview_path.read_text(encoding="utf-8")
+    return "Skill overview not found."
+
+
+def get_topic(name: str) -> Optional[str]:
+    """Return content of a specific topic, or None if not found."""
+    path = _resolve_topic(name)
+    if path:
+        return Path(path).read_text(encoding="utf-8")
+    return None
+
+
+def list_topics() -> str:
+    """Return a formatted topic listing grouped by category."""
+    lines = []
+    current_cat = ""
+    for topic_name, category, description in TOPIC_CATALOG:
+        if category != current_cat:
+            if current_cat:
+                lines.append("")
+            lines.append(category)
+            current_cat = category
+        lines.append(f"  {topic_name:<30s} {description}")
+    return "\n".join(lines)
+
+
+def get_all_topic_names() -> List[str]:
+    """Return list of all valid topic names."""
+    return [t[0] for t in TOPIC_CATALOG]

stata_cli-0.4.0/src/stata_cli/skills/overview.md

@@ -0,0 +1,196 @@
+# stata-cli skill
+
+Stata reference library built into stata-cli. Covers syntax, data management,
+econometrics, causal inference, graphics, Mata programming, and 20+ community
+packages. Use `stata-cli skill <topic>` to read a specific reference.
+
+## Critical Gotchas
+
+### Missing Values Sort to +Infinity
+Stata's `.` (and `.a`-`.z`) are **greater than all numbers**.
+```stata
+* WRONG — includes observations where income is missing!
+gen high_income = (income > 50000)
+
+* RIGHT
+gen high_income = (income > 50000) if !missing(income)
+```
+
+### `=` vs `==`
+`=` is assignment; `==` is comparison.
+```stata
+* WRONG — syntax error
+gen employed = 1 if status = 1
+
+* RIGHT
+gen employed = 1 if status == 1
+```
+
+### Local Macro Syntax
+Locals use `` `name' `` (backtick + single-quote). Globals use `$name`.
+```stata
+local controls "age education income"
+regress wage `controls'        // correct
+regress wage `controls         // WRONG — missing closing quote
+```
+
+### `by` Requires Prior Sort (Use `bysort`)
+```stata
+bysort id: gen first = (_n == 1)    // RIGHT — bysort sorts automatically
+```
+
+### Factor Variable Notation
+Use `i.` for categorical, `c.` for continuous.
+```stata
+* WRONG — treats race as continuous
+regress wage race education
+
+* RIGHT — creates dummies
+regress wage i.race education
+```
+
+### `merge` Always Check `_merge`
+```stata
+merge 1:1 id using other.dta
+tab _merge
+drop _merge
+```
+
+### Stored Results: `r()` vs `e()` vs `s()`
+- `r()` — r-class (summarize, tabulate)
+- `e()` — e-class (regress, logit)
+- `s()` — s-class (parsing)
+
+A new estimation command **overwrites** previous `e()` results. Use `estimates store`.
+
+## Common Patterns
+
+### Regression Table Workflow
+```stata
+eststo clear
+eststo: regress y x1 x2, vce(robust)
+eststo: regress y x1 x2 x3, vce(robust)
+esttab using "results.tex", replace se star(* 0.10 ** 0.05 *** 0.01) label booktabs
+```
+
+### Panel Data Setup
+```stata
+xtset panelid timevar
+reghdfe y x1 x2, absorb(panelid timevar) vce(cluster panelid)
+```
+
+### Difference-in-Differences
+```stata
+* Classic 2x2 DiD
+gen post = (year >= treatment_year)
+gen treat_post = treated * post
+regress y treated post treat_post, vce(cluster id)
+
+* Modern staggered DiD (Callaway & Sant'Anna)
+csdid y x1 x2, ivar(id) time(year) gvar(first_treat) agg(event)
+```
+
+### Data Cleaning Pipeline
+```stata
+import delimited "raw_data.csv", clear varnames(1)
+rename *, lower
+destring income, replace force
+replace income = . if income < 0
+label variable income "Annual household income (USD)"
+compress
+save "clean_data.dta", replace
+```
+
+## Topic Routing Table
+
+Use `stata-cli skill <topic>` to read a specific reference.
+Use `stata-cli skill --list` to see all topics with descriptions.
+
+### Data Operations
+| Topic | Key Commands |
+|-------|-------------|
+| `basics` | use, save, describe, browse, sysuse |
+| `data-import-export` | import delimited/excel, export, ODBC |
+| `data-management` | generate, replace, merge, reshape, collapse, egen |
+| `variables-operators` | Variable types, missing values, if/in qualifiers |
+| `string-functions` | substr(), regexm(), split, Unicode |
+| `date-time-functions` | date(), clock(), %td/%tc formats |
+| `mathematical-functions` | round(), log(), cond(), distributions |
+
+### Statistics & Econometrics
+| Topic | Key Commands |
+|-------|-------------|
+| `descriptive-statistics` | summarize, tabulate, correlate, tabstat |
+| `linear-regression` | regress, vce(robust), margins, predict |
+| `panel-data` | xtset, xtreg fe/re, Hausman test |
+| `time-series` | tsset, ARIMA, VAR, unit root tests |
+| `limited-dependent` | logit, probit, tobit, poisson, mlogit |
+| `survey-data` | svyset, svy:, subpop(), complex design |
+| `bootstrap-simulation` | bootstrap, simulate, Monte Carlo |
+| `missing-data` | mi impute, mi estimate, FIML |
+| `maximum-likelihood` | ml model, custom likelihood |
+| `gmm-estimation` | gmm, moment conditions, J-test |
+
+### Causal Inference
+| Topic | Key Commands |
+|-------|-------------|
+| `treatment-effects` | teffects ra/ipw/aipw, ATE/ATT |
+| `difference-in-differences` | DiD, event study, staggered adoption |
+| `regression-discontinuity` | Sharp/fuzzy RD, bandwidth selection |
+| `matching-methods` | PSM, nearest neighbor, kernel matching |
+| `sample-selection` | heckman, exclusion restrictions |
+
+### Advanced Methods
+| Topic | Key Commands |
+|-------|-------------|
+| `survival-analysis` | stset, stcox, streg, Kaplan-Meier |
+| `sem-factor-analysis` | sem, gsem, CFA, path analysis |
+| `nonparametric-methods` | kdensity, qreg, npregress |
+| `spatial-analysis` | spmatrix, spregress, Moran's I |
+| `machine-learning` | lasso, elasticnet, cross-validation |
+
+### Graphics
+| Topic | Key Commands |
+|-------|-------------|
+| `graphics` | twoway, scatter, histogram, graph export |
+
+### Programming
+| Topic | Key Commands |
+|-------|-------------|
+| `programming-basics` | local, global, foreach, program define |
+| `advanced-programming` | syntax, mata, tempfile/tempvar |
+| `mata-introduction` | Mata basics, when to use Mata |
+| `mata-programming` | Mata functions, structures, pointers |
+| `mata-matrix-operations` | Matrix decompositions, st_matrix() |
+| `mata-data-access` | st_data(), st_view(), st_store() |
+
+### Output & Workflow
+| Topic | Key Commands |
+|-------|-------------|
+| `tables-reporting` | putexcel, putdocx, LaTeX, collect |
+| `workflow-best-practices` | Project structure, version control |
+| `external-tools` | Python via python:, R, shell commands |
+
+### Community Packages
+| Topic | What It Does |
+|-------|-------------|
+| `reghdfe` | High-dimensional fixed effects OLS |
+| `estout` | Publication-quality regression tables (esttab) |
+| `outreg2` | Alternative table exporter (Word/Excel/TeX) |
+| `asdoc` | One-command Word document creation |
+| `coefplot` | Coefficient plots from stored estimates |
+| `did` | Modern DiD estimators (csdid, did_multiplegt) |
+| `event-study` | eventstudyinteract, eventdd |
+| `rdrobust` | Robust RD estimation + optimal bandwidth |
+| `psmatch2` | Propensity score matching |
+| `synth` | Synthetic control method |
+| `ivreg2` | Enhanced IV/2SLS with diagnostics |
+| `xtabond2` | Dynamic panel GMM (Arellano-Bond) |
+| `binsreg` | Binned scatter plots with CI |
+| `data-manipulation` | gtools (fast collapse/egen), rangestat |
+| `diagnostics` | bacondecomp, xttest3, heteroskedasticity |
+| `graph-schemes` | grstyle, schemepack, plotplain |
+| `nprobust` | Nonparametric kernel estimation |
+| `winsor` | Winsorizing and trimming (winsor2) |
+| `tabout` | Cross-tabulations to file |
+| `package-management` | ssc install, net install, ado update |