stata-code 0.3.0__py3-none-any.whl

stata_code-0.3.0.dist-info/METADATA

@@ -0,0 +1,389 @@
+Metadata-Version: 2.4
+Name: stata-code
+Version: 0.3.0
+Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
+Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
+Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
+Project-URL: Issues, https://github.com/brycewang-stanford/stata-code/issues
+Project-URL: Changelog, https://github.com/brycewang-stanford/stata-code/blob/main/CHANGELOG.md
+Author-email: Bryce Wang <brycewang@stanford.edu>
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSE-POLICY.md
+Keywords: causal-inference,jupyter,mcp,pystata,stata,vscode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: ipykernel>=6.0; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: kernel
+Requires-Dist: ipykernel>=6.0; extra == 'kernel'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# stata-code
+
+> 面向 LLM 智能体的 Stata 桥接工具 - **一个 Python 核心，多种前端入口**。
+> Agent-native Stata bridge - **one Python core, multiple frontends**.
+
+`stata-code` 让你可以从现代开发环境中驱动 Stata：LLM 智能体（Claude Code、Cursor、Claude Desktop）、Jupyter notebook，或计划中的 VS Code 编辑器入口。它们共享同一个 Python 核心，并返回稳定、结构化、**适合智能体读取**的结果格式。
+
+`stata-code` lets you drive Stata from modern environments: an LLM agent (Claude Code, Cursor, Claude Desktop), a Jupyter notebook, or a planned VS Code editor session. All frontends share one Python core and return a stable, structured, **agent-friendly** result schema.
+
+```text
+                    ┌────────────────────────────────────────┐
+                    │     stata-code core (Python)           │
+                    │                                        │
+                    │   • pystata adapter (Stata 17+)        │
+                    │   • v1.0 unified result schema         │
+                    │   • token-economy defaults             │
+                    │   • multi-session via Stata frames     │
+                    │   • typed errors + suggestions         │
+                    └────────────────────────────────────────┘
+                       ↑              ↑              ↑
+              ┌────────┴────┐  ┌──────┴─────┐  ┌────┴────────────┐
+              │  Jupyter    │  │  MCP       │  │  VS Code glue   │
+              │  kernel     │  │  server    │  │  (planned)      │
+              └─────────────┘  └────────────┘  └─────────────────┘
+```
+
+**当前状态 / Status: v0.2 (May 2026)** - core、MCP server 和 Jupyter kernel 已经可以在 Stata 18 MP 上端到端运行。当前测试：144 passing（88 个不需要 Stata 的单元测试 + 56 个真实 Stata 集成测试）。许可证：**MIT**。
+
+**Status: v0.2 (May 2026)** - the core, MCP server, and Jupyter kernel work end-to-end against Stata 18 MP. Current test suite: 144 passing tests (88 no-Stata unit tests + 56 real-Stata integration tests). License: **MIT**.
+
+---
+
+## 为什么做这个项目 / Why this exists
+
+Stata 的 AI / agent 工具生态现在比较分散，详见 [References-tools.md](References-tools.md)：
+
+The Stata AI / agent tooling landscape is fragmented; see [References-tools.md](References-tools.md):
+
+- 现有 MCP server（[SepineTam/stata-mcp](https://github.com/sepinetam/stata-mcp)、[tmonk/mcp-stata](https://github.com/tmonk/mcp-stata)）使用 **AGPL-3.0**，不适合闭源或商业集成。
+  Existing MCP servers ([SepineTam/stata-mcp](https://github.com/sepinetam/stata-mcp), [tmonk/mcp-stata](https://github.com/tmonk/mcp-stata)) are **AGPL-3.0**, which is not a fit for closed-source or commercial integration.
+
+- 常用的 VS Code AI 插件（[hanlulong/stata-mcp](https://github.com/hanlulong/stata-mcp)）是 MIT，但 MCP server 被打包在插件内部，不方便单独复用。
+  The popular VS Code AI extension ([hanlulong/stata-mcp](https://github.com/hanlulong/stata-mcp)) is MIT, but it bundles the MCP server inside the extension, making standalone reuse awkward.
+
+- 每个工具都用自己的方式封装 `pystata`，返回结构不统一，智能体需要为不同工具写特殊处理。
+  Each tool wraps `pystata` with its own result shape, so agents have to special-case each integration.
+
+- 很多工具一开始是为人类交互设计的，再接到 MCP 上；它们经常把 200 行日志和 base64 图片直接塞进回复，默认就大量消耗 token。
+  Many existing tools were designed for humans first and then bolted onto MCP; they often dump long logs and base64 graph blobs into every reply, burning tokens by default.
+
+`stata-code` 要填补的就是这个空位：
+
+`stata-code` is designed to fill that gap:
+
+1. **MIT 许可证**，没有 copyleft 传染问题。
+   **MIT-licensed**, with no copyleft contagion.
+
+2. 所有前端共享同一个结果格式：[SCHEMA.md](SCHEMA.md)。
+   One shared result schema for every frontend: [SCHEMA.md](SCHEMA.md).
+
+3. 默认面向智能体：typed errors、结构化 `r()` / `e()`、log refs、graph refs、suggestion seeds。
+   Agent-native by default: typed errors, structured `r()` / `e()`, log refs, graph refs, and suggestion seeds.
+
+4. 一个 core，多个入口：Jupyter kernel、MCP server、计划中的 VS Code glue。
+   One core, multiple frontends: Jupyter kernel, MCP server, and planned VS Code glue.
+
+如果你关心 AGPL/GPL Stata 项目的 clean-room 边界，请看 [LICENSE-POLICY.md](LICENSE-POLICY.md)。
+
+For the project's clean-room policy around AGPL/GPL Stata projects, see [LICENSE-POLICY.md](LICENSE-POLICY.md).
+
+---
+
+## 安装 / Install
+
+要求：**Stata 17+**（自带 `pystata`）和 **Python 3.10+**。
+
+Requirements: **Stata 17+** (with `pystata` shipped by Stata) and **Python 3.10+**.
+
+```bash
+# from PyPI
+pip install stata-code
+
+# with the MCP server and Jupyter kernel extras
+pip install "stata-code[mcp,kernel]"
+
+# or from source (editable install for development)
+git clone https://github.com/brycewang-stanford/stata-code.git
+cd stata-code
+pip install -e ".[mcp,kernel]"
+```
+
+> **Naming note.** The PyPI distribution is `stata-code` (hyphen), but
+> the Python import is `stata_code` (underscore — Python identifiers
+> can't contain hyphens). Same convention as `scikit-learn` →
+> `import sklearn`. So: `pip install stata-code`,
+> `from stata_code import run`.
+
+注意：`pystata` **不在 PyPI 上**，它随 Stata 一起安装。`stata-code` 会自动在 macOS 的 `/Applications/Stata/utilities/pystata` 以及 Linux / Windows 的对应位置寻找它。如果你的 Stata 安装在其他位置，请在导入前把 `pystata` 加到 `PYTHONPATH`。
+
+Note: `pystata` is **not** on PyPI; it ships with Stata. `stata-code` auto-discovers it on macOS at `/Applications/Stata/utilities/pystata` and at equivalent Linux / Windows paths. If your install is elsewhere, add it to `PYTHONPATH` before importing.
+
+---
+
+## 快速开始 / Quick Start
+
+完整 cookbook 在 [`examples/`](examples/)：基础回归、DiD、图形、多 session、大矩阵。
+
+See [`examples/`](examples/) for end-to-end cookbook entries: basic regression, DiD, graphs, multi-session, and large matrices.
+
+### 作为 Python library / As a Python Library
+
+```python
+from stata_code import run
+
+r = run("sysuse auto, clear")
+r = run("regress mpg weight")
+
+if r.ok:
+    print(r.results.e.scalars["r2"])           # 0.6515 (native float)
+    print(r.results.e.macros["cmd"])           # "regress"
+    b = r.results.e.matrices["b"]
+    print(dict(zip(b.cols, b.values[0])))      # {"weight": -0.006, "_cons": 39.44}
+else:
+    print(r.error.kind, r.error.message)       # ErrorKind.VARNAME_NOT_FOUND, "..."
+    for s in r.error.suggestions:
+        print("hint:", s.action)               # "Did you mean `mpg`?"
+```
+
+### 作为 MCP server / As an MCP Server
+
+安装后，`stata-code-mcp` 会出现在你的 `PATH` 中。把下面的配置加到 Claude Code（`~/.claude/mcp.json` 或 Claude Code settings UI）、Cursor、Claude Desktop 等支持 MCP 的客户端里：
+
+After install, `stata-code-mcp` is on your `PATH`. Add this to Claude Code (`~/.claude/mcp.json` or the Claude Code settings UI), Cursor, Claude Desktop, or another MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "stata": {
+      "command": "stata-code-mcp"
+    }
+  }
+}
+```
+
+也可以直接以 module 方式运行：
+
+Or run it as a module:
+
+```bash
+python -m stata_code.mcp
+```
+
+MCP server 注册了 8 个工具：
+
+The MCP server registers 8 tools:
+
+| Tool | 用途 / Purpose |
+| --- | --- |
+| `stata_run` | 执行 Stata code，返回 v1.0 RunResult JSON / Execute Stata code and return a v1.0 RunResult JSON |
+| `stata_info` | 返回 Stata edition、version 和 capabilities / Report Stata edition, version, and capabilities |
+| `get_log` | 通过 `log://` ref 获取完整日志 / Fetch the full log behind a `log://` ref |
+| `get_graph` | 通过 `graph://` ref 获取图形 bytes (`ImageContent`) / Fetch graph bytes behind a `graph://` ref |
+| `get_matrix` | 通过 `matrix://` ref 获取矩阵 `{rows, cols, values}` / Fetch matrix payloads behind a `matrix://` ref |
+| `list_sessions` | 列出 live sessions / Enumerate live sessions |
+| `cancel_session` | 协作式取消某个 session 的下一次 `stata_run` / Cooperatively cancel the next `stata_run` for a session |
+| `reset_session` | 清空某个 session 的数据 / Drop a session's data |
+
+### 作为 Jupyter kernel / As a Jupyter Kernel
+
+```bash
+stata-code-kernel install --user
+```
+
+也可以直接以 module 方式安装：
+
+Or install it as a module:
+
+```bash
+python -m stata_code.kernel install --user
+```
+
+然后打开 notebook，选择 **Stata** kernel。Stata 命令会在 cell 中运行，日志、图形和 warnings 会以内联方式显示。
+
+Then open a notebook and select the **Stata** kernel. Stata commands run in cells; logs, graphs, and warnings render inline.
+
+---
+
+## 默认节省 token / Token-Economy Defaults
+
+典型的 `stata_run` 响应比现有 MCP server 直接返回日志和图片的方式小约 **10 倍**。核心设计有三点：
+
+A typical `stata_run` response is about **10x smaller** than servers that dump logs and images directly. Three design choices drive this:
+
+1. **日志默认只返回 `head` + `tail` + `ref`**。默认各 20 行；完整日志可以按需用 `get_log(ref)` 获取。Stata 回归日志可能有约 6,000 tokens，`stata-code` 默认约 600 tokens。
+   **Logs return `head` + `tail` + `ref`** by default. Full logs are fetched on demand via `get_log(ref)`. A Stata regression log can be about 6,000 tokens; `stata-code` returns about 600 by default.
+
+2. **图形默认返回 refs，不内联 base64**。一个 30 KB PNG 转成 base64 约 50,000 tokens；返回 ref 可以让智能体只在真正需要渲染时再取 bytes。
+   **Graphs return refs, not inline base64**. A 30 KB PNG can become about 50,000 base64 tokens; returning a ref avoids that unless the agent actually needs the bytes.
+
+3. **错误是结构化 typed errors**。智能体可以判断 `err.kind == "varname_not_found"`，而不是正则解析英文日志。
+   **Errors are typed**. Agents can check `err.kind == "varname_not_found"` instead of regex-parsing English logs.
+
+例如，变量名写错时返回的是结构化错误：
+
+For example, a misspelled variable returns a structured error:
+
+```json
+{
+  "ok": false,
+  "rc": 111,
+  "error": {
+    "kind": "varname_not_found",
+    "varname": "mpgg",
+    "line": 3,
+    "context": {
+      "before": ["use auto"],
+      "failing": "summarize mpgg",
+      "after": []
+    },
+    "suggestions": [
+      {"action": "Did you mean `mpg`?", "command": "describe"}
+    ]
+  }
+}
+```
+
+完整 schema 见 [SCHEMA.md](SCHEMA.md)。
+
+The full schema is in [SCHEMA.md](SCHEMA.md).
+
+---
+
+## 架构 / Architecture
+
+```text
+stata_code/
+├── core/
+│   ├── _runtime.py    # process-singleton pystata wrapper
+│   ├── _refs.py       # LRU ref store for log/graph/matrix payloads
+│   ├── schema.py      # Pydantic v2 models for the v1.0 result schema
+│   ├── errors.py      # rc → ErrorKind mapping + suggestion seeds
+│   └── runner.py      # the one execute(); collects everything via sfi
+├── mcp/
+│   └── server.py      # MCP server (8 tools)
+└── kernel/
+    └── kernel.py      # Jupyter kernel
+```
+
+`runner.py` 是唯一直接接触 Stata 的地方。Jupyter kernel 和 MCP server 都只导入它，然后把结果翻译成各自的传输格式。
+
+`runner.py` is the only place that touches Stata. The Jupyter kernel and MCP server both import from it and only translate results into their own transports.
+
+---
+
+## 对比 / Comparison
+
+| | stata-code | SepineTam/stata-mcp | hanlulong/stata-mcp | nbstata |
+| --- | --- | --- | --- | --- |
+| License / 许可证 | **MIT** | AGPL-3.0 | MIT | GPL-3.0 |
+| Standalone MCP / 独立 MCP | ✓ | ✓ | bundled with VS Code | - |
+| Jupyter kernel | ✓ | - | - | ✓ |
+| Unified result schema / 统一结果格式 | ✓ ([SCHEMA.md](SCHEMA.md)) | per-tool | per-tool | per-tool |
+| Token-economy defaults / 默认节省 token | ✓ (log refs, graph refs) | - | - | - |
+| Typed errors + suggestions / 结构化错误和建议 | ✓ (32 kinds) | - | - | - |
+| Multi-session / 多 session | ✓ (Stata frames) | partial | - | - |
+| Mature ecosystem / 生态成熟度 | early | ✓ (statamcp.com, cookbook) | ✓ (11k installs) | ✓ |
+
+`stata-code` 是这个问题空间里更年轻的、MIT 许可证的、agent-native 的替代方案。AGPL 方案里，SepineTam 的 `stata-mcp` 目前更成熟；`stata-code` 的目标是服务那些不能接受 copyleft 传染、又需要结构化智能体接口的场景。
+
+`stata-code` is the younger, MIT-licensed, agent-native alternative in this problem space. Among the AGPL options, SepineTam's `stata-mcp` is currently more mature; `stata-code` is aimed at cases where copyleft contagion is unacceptable and agents need structured results.
+
+---
+
+## 路线图 / Roadmap
+
+### 已完成 / Done (v0.2 - May 2026)
+
+- v1.0 result schema ([SCHEMA.md](SCHEMA.md))
+- 基于 `pystata` 的 runner，支持 native-typed `r()`、`e()`、matrices
+- Multi-session via Stata frames
+- Per-line error attribution: line number、context、commands_executed
+- Graph capture: `png` / `svg` / `pdf` with ref store
+- Log truncation with ref store
+- Warning extraction: 5 categories + generic notes
+- 32-kind error taxonomy with canonical suggestions
+- MCP server: 8 tools
+- Jupyter kernel: rewired to the v1.0 pipeline
+- Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
+- Cooperative cancellation: `cancel(session_id)` / MCP `cancel_session`
+- JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
+- VS Code extension scaffold ([`vscode/`](vscode/)): `Run Selection`、graph webview、MCP child-process spawn
+- Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))
+
+### 下一步 / Next Up
+
+- **v0.3** - Console fallback for Stata 11-16, re-implemented against the v1.0 schema
+- **v0.3** - Hard timeout / mid-Stata interrupt; design and tradeoffs in [`docs/design/hard_timeout.md`](docs/design/hard_timeout.md)
+- **v0.4** - VS Code Marketplace publishing; the scaffold and graph webview already work in dev host
+- **v1.0** - Stable schema, PyPI / VS Code Marketplace publishing
+
+明确不做的范围见 [SCHEMA.md §7](SCHEMA.md)。
+
+See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
+
+---
+
+## 测试 / Testing
+
+```bash
+pip install -e ".[dev,mcp,kernel]"
+pytest                              # full suite (144 tests)
+pytest -m "not stata_required"      # CI subset; no Stata needed
+pytest -m "stata_required" -v       # Stata-only integration tests
+```
+
+`stata_required` marker 标记真实 Stata 集成测试。CI 使用 `pytest -m "not stata_required"`，因此不会收集这些测试。本地没有 Stata 时，这些测试也会用 `"pystata / Stata 17+ not available"` 信息 cleanly skip。
+
+The `stata_required` marker tags the real-Stata integration tests. CI uses `pytest -m "not stata_required"` so it does not collect them. Locally without Stata, those tests skip cleanly with the `"pystata / Stata 17+ not available"` message.
+
+---
+
+## 贡献 / Contributing
+
+- 提 PR 前请先读 [LICENSE-POLICY.md](LICENSE-POLICY.md)。
+  Read [LICENSE-POLICY.md](LICENSE-POLICY.md) before opening a PR.
+
+- 第一个 PR description 里请加一行 acknowledgement，模板在 policy 文件里。
+  Add a one-line acknowledgement to your first PR description; the template is in the policy file.
+
+- 新增 schema field 或 runner 行为时必须补测试。
+  Tests are required for any new schema field or runner behavior.
+
+---
+
+## 许可证 / License
+
+代码使用 [MIT](./LICENSE)。[LICENSE-POLICY.md](LICENSE-POLICY.md) 说明本项目如何处理和其他 Stata 项目的关系。
+
+The code is licensed under [MIT](./LICENSE). [LICENSE-POLICY.md](LICENSE-POLICY.md) explains how this project relates to other Stata projects.
+
+## 商标声明 / Trademark Notice
+
+Stata 是 StataCorp LLC 的注册商标。本项目是独立项目，不隶属于 StataCorp，也未获得 StataCorp 背书。
+
+Stata is a registered trademark of StataCorp LLC. This project is independent and not affiliated with or endorsed by StataCorp.
+
+## 致谢 / Acknowledgements
+
+本项目参考和学习的 Stata 工具生态整理在 [References-tools.md](References-tools.md)。其中列出的项目保留各自的许可证和作者归属；复用前请查看对应仓库。
+
+The Stata tooling landscape that this project builds on and learns from is surveyed in [References-tools.md](References-tools.md). All listed projects retain their own licenses and authorship; please consult each repository before reuse.

stata_code-0.3.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+stata_code/__init__.py,sha256=ewOqfKF7JfN7dobC4XDoijd1kcMNhNX8-L7jMSlXnKk,2072
+stata_code/core/__init__.py,sha256=ycnmNHt7rkNgym7PIO-dP2r9JnfTUN3Sd5D4DEs_qmE,1420
+stata_code/core/_pool.py,sha256=8FlKxXF7sbfQrH2ST8vi-7ij7qeqMGtpUGosrNdk8U8,30632
+stata_code/core/_refs.py,sha256=8eEbYfA3QEVZTx6O7fjndLu5uO5xrP8mV3MJs9eBCYY,2691
+stata_code/core/_runtime.py,sha256=c4paNhAqFNtiixccD_Xt5L7vqafA7z10PVpZSEBad_c,5734
+stata_code/core/errors.py,sha256=dAR_ZeEX9WXVtO5aDC0TK3TRXuEGeG4AiBB2ecAdVB4,15970
+stata_code/core/runner.py,sha256=FfhRKXId-fEbGZFTxOLfPSlkjzazg2sR6b3mmO1cu20,38428
+stata_code/core/schema.py,sha256=SDqE33S74rnlN94qxwe_qKpcWw_DseSm2jIWSPNtfQI,10749
+stata_code/kernel/__init__.py,sha256=YmDgfF2dpCjIxkrmbInYxDBSNwSO60LoU_pmLikXlY4,178
+stata_code/kernel/__main__.py,sha256=LN7NI2cXzcUdSG8pjT0OECuRC_Bt8K70P2R_QN-h6UY,185
+stata_code/kernel/kernel.py,sha256=lKsOgIJsujDCH68QtOWdo4AHoQUsLbID-euxlZVtZBo,13240
+stata_code/mcp/__init__.py,sha256=OX8fbkpo0MMA7F7B1yCZyKxVkKnr6KSUR6DN-8TMtfQ,68
+stata_code/mcp/__main__.py,sha256=F2-yxmtXuMuLH9Z1-QjDtLMypdpvAlTQEUKW3qWA_go,172
+stata_code/mcp/server.py,sha256=MbMkVHljP_ZMVEmWwCplcgPI1rb81FVCHpBnDZ-yxbc,14434
+stata_code-0.3.0.dist-info/METADATA,sha256=oWdPXSJC8zVc5qbJLs68GxnzFqHINm-oQENXDqHwNgo,19036
+stata_code-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stata_code-0.3.0.dist-info/entry_points.txt,sha256=nb-7yrLNWetJQYFkQdpNVtFIEXC5mIX6r0bxbKPIiDE,120
+stata_code-0.3.0.dist-info/licenses/LICENSE,sha256=6kG2eA5OSA5BHqSs_dUWiGqsOkWpnK6Zy5XxjM9ZlqQ,1065
+stata_code-0.3.0.dist-info/licenses/LICENSE-POLICY.md,sha256=1XpLv9v1JJQ5Cf4EIO9bcj4cj6LMSXQiz-Sugjc61s4,6565
+stata_code-0.3.0.dist-info/RECORD,,

stata_code-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stata_code-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+stata-code-kernel = stata_code.kernel.kernel:run_main
+stata-code-mcp = stata_code.mcp.server:run_main

stata_code-0.3.0.dist-info/licenses/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.dist-info/licenses/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.