stata-code 0.3.0__tar.gz

stata_code-0.3.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Stata-specific
+*.gph
+*.smcl
+*.dta
+!tests/fixtures/*.dta

stata_code-0.3.0/CHANGELOG.md

@@ -0,0 +1,205 @@
+# Changelog
+
+All notable changes to `stata-code` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project adheres
+to semver-major.minor for the result schema (see `SCHEMA.md` §6).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-05-07
+
+### Changed
+
+- **PyPI distribution renamed to `stata-code`.** Previously published as
+  `stata_code`. Install with `pip install stata-code` going forward; the
+  Python import name remains `stata_code` (Python identifier rules — same
+  pattern as `scikit-learn` → `import sklearn`). Existing users on
+  `pip install stata_code` will keep working until that PyPI project
+  stops receiving new versions, but should migrate.
+- **Project URLs in `pyproject.toml` corrected** to
+  `github.com/brycewang-stanford/stata-code` (the actual repository
+  URL — the previous metadata had `stata_code`).
+- **MCP server announces itself as `stata-code`** (was `stata_code`).
+  This is the protocol-level server name; tool ids
+  (`stata_run`, `get_log`, etc.) are unchanged.
+- **VSCode extension display name unified to `stata-code`** in the
+  Marketplace, activity-bar tile, command-palette `category`, output
+  channel, all toast messages, and webview title. Code identifiers
+  (`stataCode.*` command / view / setting ids; npm `name`
+  `stata-code-vscode`) are unchanged so existing keybindings keep
+  working.
+- **Version aligned across surfaces.** `pyproject.toml`,
+  `stata_code/__init__.py`, `stata_code/mcp/server.py`,
+  `vscode/package.json`, and the VSCode MCP-client handshake all
+  declare `0.3.0`.
+
+### Added
+
+- **VSCode extension v0.3 — full UI surface** (`vscode/`). Beyond the
+  v0.1 "run from command palette" scaffold, the extension now ships
+  every common GUI affordance, so users who don't drive Stata through
+  Claude Code / Cursor can still operate the same MCP server from the
+  editor:
+  - **Editor title-bar ▶ button** (`editor/title/run` menu) and
+    editor right-click menu entries (`Run Selection` / `Run Active File`).
+  - **Status bar item** showing the current session; click for a
+    QuickPick (`Switch session…` / `Cancel` / `Reset`). The icon
+    swaps to a spinner during runs and the run progress notification
+    now has a Cancel button (cooperative cancellation through the
+    MCP `cancel_session` tool).
+  - **Activity-bar sidebar** with four views: live `Sessions` (with
+    inline Cancel/Reset/Close per item — `main` is non-closable;
+    locally-known but not-yet-started sessions persist via
+    `workspaceState`), `Last Result` (collapsible
+    `r()` / `e()` / warnings / dataset / log / graphs), `Graphs`
+    history (click-to-open + per-item Save…), and `Logs`
+    history (click-to-open + per-item Save…). Section-header buttons
+    for Clear (logs / graphs) and New / Refresh (sessions).
+  - **Inline error decorations.** Failed runs now publish a
+    `DiagnosticCollection` entry on the failing file/line, complete
+    with the typed error message, failing snippet, and any
+    suggestions surfaced in `runResult.error.suggestions`. Hover
+    shows the full text; the Problems panel lists the entry under
+    `source: stata-code, code: <error.kind>`.
+  - **Code-lens "Run Cell" support.** Lines starting with `* %%`
+    get an inline `▶ Run Cell` lens; clicking submits the code
+    between markers. Cell ranges map back to the original file
+    lines so error squigglies still anchor correctly.
+  - **Graph webview action buttons.** The webview now uses a strict
+    nonce-based CSP and exposes `Save as…`, `Open externally`, and
+    `Refresh` per-graph and panel-level buttons. PNG/SVG/PDF bytes
+    still flow lazily through `get_graph(ref)`.
+  - Bumped the extension version to `0.2.0`.
+
+- **Matrix size cap + `get_matrix(ref)`.** Matrices larger than
+  `MATRIX_INLINE_CELL_CAP` (default 10,000 cells) now drop their
+  `values` from the envelope and surface a `matrix://<request_id>/<r|e>/
+  <name>` ref instead. Callers fetch the values via `get_matrix(ref)`,
+  which mirrors the existing `get_log` / `get_graph` pattern. The MCP
+  server gains a seventh tool, `get_matrix`, returning JSON
+  `{rows, cols, values}`. Closes the last open §3.4 todo from
+  SCHEMA.md and prevents pathological commands (e.g., `correlate` over
+  hundreds of variables) from blowing up the result envelope.
+
+- **VSCode extension scaffold** (`vscode/`). TypeScript extension that
+  spawns `stata-code-mcp` over stdio and registers four commands
+  (`Run Selection`, `Run Active File`, `Show Graphs`, `Show Last
+  Result`). Hand-rolled TypeScript types in
+  `vscode/src/types/runResult.ts` mirror the Pydantic envelope;
+  `npm run gen-types` regenerates a full copy from
+  `schema/run_result.schema.json` for cross-checking. Source-only —
+  build with `npm install && npm run compile`.
+
+- **VSCode graph webview** (`vscode/src/graphPanel.ts`). Successful
+  runs that capture graphs auto-open a side-by-side webview that
+  renders PNG / SVG / PDF inline. The webview lazily fetches each
+  graph's bytes via `get_graph(ref)` rather than embedding them in
+  the original `RunResult`, so token economy is preserved end-to-end
+  (an agent driving the same MCP server pays nothing extra for
+  inlining). Strict CSP (`default-src 'none'`, no scripts).
+  Marketplace publishing still deferred.
+
+- **`stata_required` pytest marker.** Integration tests against a
+  real Stata installation are now tagged with the marker; CI runs
+  `pytest -m "not stata_required"`, completing in ~1.5s instead of
+  ~19s. Local without Stata, the same tests still skip cleanly.
+
+- **Cooperative cancellation.** New `cancel(session_id)` /
+  `clear_cancel(session_id)` / `is_cancel_pending(session_id)` Python
+  API plus the MCP `cancel_session` tool (eighth tool). A pending
+  cancel short-circuits the next `execute()` call for that session
+  and returns a `RunResult` with `ok=false`, `rc=-3` (synthetic),
+  `error.kind="cancelled"`. The flag is one-shot per cancel, isolated
+  per session, and thread-safe. Note: this is *cooperative* — it does
+  not interrupt code that is currently mid-`stata.run()` (pystata is
+  in-process and has no clean cancel primitive). Hard interruption
+  remains deferred to the subprocess-based runtime planned for v0.3+.
+
+### Changed
+
+- **MCP server tool count is now 8** (added `get_matrix`,
+  `cancel_session`).
+
+## [0.2.0] — 2026-05-07
+
+The first release that actually ships an end-to-end Stata pipeline. The v1.0
+result schema is the load-bearing artifact; everything below is implemented
+against it and end-to-end-tested on Stata 18 MP.
+
+### Added
+
+- **`SCHEMA.md` v1.0** — normative result-envelope contract: `ok` / `rc`,
+  typed `error` (32 `kind` values), structured `r()` / `e()` (scalars,
+  macros, matrices), `dataset` snapshot with variable list, log
+  head+tail+ref, graph refs with PNG/SVG/PDF support, multi-session id,
+  forward-compat clauses.
+- **`stata_code.run()`** (= `execute()`) — the real-Stata pipeline. Uses
+  pystata in-process; collects native-typed return values via `sfi`;
+  builds a `RunResult` end to end.
+- **`get_log` / `get_graph` / `list_sessions` / `reset_session`** —
+  auxiliary tools per `SCHEMA.md` §5.
+- **MCP server** (`stata_code.mcp.server`) — six tools: `stata_run`,
+  `stata_info`, `get_log`, `get_graph`, `list_sessions`,
+  `reset_session`. Console script: `stata-code-mcp`. Module entry:
+  `python -m stata_code.mcp`.
+- **Jupyter kernel** (`stata_code.kernel`) rewired to the v1.0 pipeline.
+  Defaults tuned for notebooks (`include_full_log=True`,
+  `include_graphs="inline"`). Console script: `stata-code-kernel`.
+  Module entry: `python -m stata_code.kernel`.
+- **Multi-session via Stata frames**. `session_id="main"` maps to the
+  default frame; other ids create/route to same-named frames.
+- **Per-line error attribution** — `error.line`, `commands_executed`,
+  and `context.{before, failing, after}` are populated by parsing
+  pystata's multi-line transcript.
+- **Warning extraction** — five built-in patterns
+  (`omitted_collinear`, `convergence`, `singular`, `boundary`, generic
+  `note`) + dedup.
+- **Graph capture pipeline** — `graph dir` snapshot delta + `graph
+  display` + `graph export`; PNG `width`/`height` parsed from IHDR;
+  bytes stored under a `_refs` LRU.
+- **`_refs` LRU eviction** — bounded ref store (default 256 entries)
+  to keep long-running MCP processes from growing unboundedly.
+- **`LICENSE-POLICY.md`** — clean-room policy that forbids opening
+  AGPL/GPL Stata project source.
+- **138 tests** covering schema, runner integration, MCP, kernel,
+  `_refs`, and error helpers. Real-Stata tests run against Stata 18 MP
+  when available.
+
+### Changed
+
+- Top-level `stata_code.run()` now returns the new `RunResult` (Pydantic
+  v2). The legacy `StataResult` dataclass and the `capture_graphs`/
+  `capture_log`/`timeout` keyword arguments are gone.
+- Wheel build now ships **all** of `stata_code` (`core`, `mcp`,
+  `kernel`). Previously the wheel only contained `core`.
+
+### Removed
+
+- **Legacy modules** — `core/pystata_adapter.py`, `core/console_fallback.py`,
+  `core/result.py`, `core/version.py`. Their behavior is now provided by
+  `core/runner.py`, `core/_runtime.py`, `core/schema.py`.
+- **Legacy tests** — `tests/test_result.py`, `tests/test_version.py`,
+  `tests/test_integration.py`. Coverage moved to `tests/test_runner.py`,
+  `tests/test_schema.py`, and `tests/test_mcp.py`.
+
+### Migration notes
+
+| Before (v0.1) | After (v0.2) |
+| --- | --- |
+| `from stata_code import run` returns `StataResult` | Returns `RunResult` |
+| `result.log` (string) | `result.log.head` / `result.log.tail` (and `get_log(ref)` for full) |
+| `result.results["r(mean)"]` | `result.results.r.scalars["mean"]` (native float) |
+| `result.error` (string) | `result.error.kind` (typed) + `result.error.message` |
+| `result.graphs[0].data` (bytes) | `result.graphs[0].ref` + `get_graph(ref)` |
+| `run(code, capture_graphs=True)` | `run(code, include_graphs="ref" \| "inline" \| "none")` |
+| `run(code, timeout=120)` | `run(code, timeout_ms=120_000)` |
+
+`pystata` is no longer declared as a runtime dependency in
+`pyproject.toml` — it is sourced from your local Stata install per the
+documented `_runtime` discovery path.
+
+## [0.1.0] — 2026-04
+
+Initial scaffolding. `pystata_adapter`, `console_fallback`, basic kernel
+and MCP server, `References-tools.md` survey, project vision in
+`README.md`. Largely superseded by 0.2.

stata_code-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brycew6m
+
+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.

stata_code-0.3.0/LICENSE-POLICY.md

@@ -0,0 +1,125 @@
+# License Policy
+
+`stata_code` is released under the **MIT License**. To keep the codebase legally clean and freely usable downstream (including by commercial and closed-source projects), this repository follows a strict **protocol-first, clean-room** development policy. This document is the binding policy; contributors must read it before opening a pull request.
+
+---
+
+## 1. Project license
+
+- **License:** MIT (see `LICENSE`).
+- **Goal:** Anyone — including commercial and closed-source projects — can integrate, fork, or redistribute `stata_code` without copyleft obligations.
+
+This goal is incompatible with deriving from AGPL-3.0 / GPL-3.0 source code. The rules below exist to prevent that.
+
+---
+
+## 2. The three categories of references
+
+Every external project relevant to `stata_code` falls into one of three buckets:
+
+### 2.1 Open standards & vendor docs (always allowed)
+
+These define **public protocols and APIs**. Reading them, citing them, and implementing against them does not contaminate our code.
+
+- **Anthropic MCP specification** — protocol shape, message formats, tool registration semantics.
+- **Jupyter kernel protocol** — `kernel_info`, `execute_request`, message routing.
+- **Language Server Protocol (LSP)** — for any future LSP work.
+- **StataCorp pystata documentation** — official Python API surface.
+- **StataCorp Stata documentation** (`help`, manuals) — `r()`, `e()`, `_rc`, system values.
+- **Stata `.dta` file format documentation** — published by StataCorp.
+- **Anthropic / OpenAI tool-use docs** — function-calling shapes.
+
+### 2.2 Permissively-licensed projects (allowed with attribution if reused)
+
+MIT, BSD, Apache 2.0, ISC. Reading source is allowed; copying must follow the license terms (preserve copyright notice, etc.). Even when allowed, we **prefer independent implementation** to keep authorship clean.
+
+- `kylebarron/stata-enhanced` — MIT (TextMate grammar; we do not reuse it).
+- `kylebarron/stata-exec` — MIT (Atom; not reused).
+- `kylebarron/language-stata` — MIT (Atom grammar; not reused).
+- `hanlulong/stata-mcp` — MIT (we do not consult its source; see §4).
+- `lbraglia/RStata` — design reference only.
+- `euglevi/stata-language-server` — MIT.
+
+### 2.3 Copyleft projects (source code forbidden)
+
+**Source code of these projects must not be read by anyone contributing to `stata_code`.** Their READMEs, public issues, demos, screenshots, and documentation describing user-facing behavior are fine — copyright protects expression, not ideas. But the source itself contaminates.
+
+- `SepineTam/stata-mcp` — AGPL-3.0
+- `tmonk/mcp-stata` — AGPL-3.0
+- `tmonk/stata-workbench` — AGPL-3.0
+- `kylebarron/stata_kernel` — GPL-3.0
+- `hugetim/nbstata` — GPL-3.0
+
+If new copyleft Stata projects appear, add them here in the same PR that first references them.
+
+---
+
+## 3. The clean-room rule
+
+When designing or implementing any feature that overlaps with a copyleft project's behavior:
+
+1. **Do not open the copyleft project's source files.** Not in a browser, not in `git clone`, not in an IDE.
+2. **You may** read its README, feature list, screenshots, public issues, blog posts, and conference talks describing what it does.
+3. **You may** read the underlying public protocol or API spec (MCP, pystata, etc.) and implement against that.
+4. **You may** look at the inputs and outputs (call its tools, observe responses) — black-box behavioral observation is fine.
+5. **Design from first principles.** Our schema (`SCHEMA.md`) was designed from agent-token-economy principles and the public pystata API. It was not derived by simplifying or rearranging anyone else's schema.
+
+If you find yourself thinking *"how does project X handle Y?"*, the answer is: read its docs and observe its behavior. Do not open its source.
+
+---
+
+## 4. If you accidentally read forbidden source
+
+It happens. Honesty is the only safe response.
+
+1. **Stop reading immediately.** Close the file.
+2. **Disclose in the PR or issue.** Note what you read and approximately how much.
+3. **Wait at least 30 days** before contributing code in the affected area. If the area is small (one function), a fresh contributor implements it. If broad, that contributor sits out the area indefinitely.
+4. **Do not** quote, paraphrase, or rewrite from memory.
+
+This is the same posture used by clean-room reverse-engineering teams. It is conservative on purpose.
+
+---
+
+## 5. Adding a new reference
+
+When introducing any new external project to documentation, code, or discussion:
+
+1. Add it to one of the three lists in §2 of this file in the same PR.
+2. State its license explicitly (check `LICENSE` file, not `package.json`/`README` — those drift).
+3. If copyleft, the PR must not include any code; only the bucket-3 listing.
+
+Reviewers should reject PRs that mention an external project without classifying it.
+
+---
+
+## 6. Dependencies vs. derivation
+
+Note the difference:
+
+- **Depending** on an MIT/BSD/Apache library at runtime is fine and does not contaminate.
+- **Depending** on a GPL/AGPL library at runtime *does* contaminate the distributed package; we don't do that for any package we ship under MIT.
+- **Depending** on a GPL/AGPL library only in a separate, GPL-licensed sub-package (e.g., `stata-code-jupyter-glue`) is acceptable as long as the MIT core does not import it. Any such split must be called out at the top of the README and in `pyproject.toml`.
+
+---
+
+## 7. Why this matters
+
+Stata is a small ecosystem with active and vigilant maintainers, several of whom have publicly enforced their AGPL terms. A clean license posture:
+
+- Keeps `stata_code` usable by any downstream — universities, central banks, commercial vendors.
+- Prevents "rip-off" accusations that have already been levied at fork-style projects in the space.
+- Makes future fundraising, hiring, and acquisitions trivial on the IP side.
+- Protects contributors personally — clean-room compliance is auditable.
+
+The cost of this policy is small (some independent design work). The cost of getting it wrong is irreversible: a contaminated codebase cannot be "scrubbed" of AGPL after the fact; only rewritten from scratch by uncontaminated authors.
+
+---
+
+## 8. Acknowledgement on first contribution
+
+Every first-time contributor to `stata_code` adds the following line to their first PR description:
+
+> I have read `LICENSE-POLICY.md` and confirm I have not consulted source code from the copyleft projects listed therein for the purposes of this contribution.
+
+Maintainers may decline contributions without this acknowledgement.