stata-agent 0.1.0__tar.gz

stata_agent-0.1.0/.github/workflows/build-test.yml

@@ -0,0 +1,101 @@
+name: Build & Test
+
+on:
+  push:
+    branches:
+      - '*'
+      - '**'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history including tags
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --python ${{ matrix.python-version }} --all-extras --dev
+        timeout-minutes: 10
+
+      - name: Run tests that don't require Stata
+        run: |
+          uv run pytest -v -m "not requires_stata"
+        timeout-minutes: 15
+
+      - name: Build package
+        run: |
+          uv build
+        timeout-minutes: 5
+
+      - name: Test installation in clean environment
+        shell: bash
+        run: |
+          # Create fresh venv using the uv-managed Python
+          uv run python -m venv test_venv
+
+          # Activate and install
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            source test_venv/Scripts/activate
+          else
+            source test_venv/bin/activate
+          fi
+
+          # Install built wheel
+          pip install dist/*.whl
+
+          # Test critical imports and version (dynamic check)
+          python -c "
+          import importlib.resources
+          import importlib.metadata
+          import stata_agent
+          _v = importlib.metadata.version('stata-agent')
+          print(f'[OK] Import successful (v{_v})')
+          # Verify plugin/skills are bundled
+          p = importlib.resources.files('stata_agent') / 'plugin'
+          print(f'[OK] Plugin dir: {p}')
+          assert p.is_dir(), 'Plugin directory missing from wheel'
+          skills = list((p / 'skills').iterdir())
+          print(f'[OK] Skills: {[s.name for s in skills]}')
+          "
+
+          # Verify entry point
+          which stata-agent || where stata-agent
+          echo "[OK] Entry point installed"
+        timeout-minutes: 10
+
+      - name: Upload build artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: |
+            dist/
+            *.log
+          retention-days: 7

stata_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  # release:
+  #   types: [published]
+  # workflow_dispatch disabled — manual publish blocked until versioning is fixed.
+  # workflow_dispatch:
+  #   inputs:
+  #     ref:
+  #       description: "Tag or branch to publish"
+  #       required: true
+  #       default: "main"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stata-agent
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify wheel contents (plugin/skills bundling)
+        shell: bash
+        run: |
+          # Create fresh venv and install wheel
+          uv run python -m venv /tmp/test-venv
+          source /tmp/test-venv/bin/activate
+          pip install dist/*.whl
+          python -c "
+          import importlib.resources
+          import importlib.metadata
+          import stata_agent
+          _v = importlib.metadata.version('stata-agent')
+          print(f'[OK] Import successful (v{_v})')
+          # Verify plugin/skills are bundled in the wheel
+          p = importlib.resources.files('stata_agent') / 'plugin'
+          print(f'Plugin dir: {p}')
+          assert p.is_dir(), 'Plugin directory missing from wheel'
+          skills = list((p / 'skills').iterdir())
+          print(f'Skills: {[s.name for s in skills]}')
+          "
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

stata_agent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  # push trigger disabled — manual workflow_dispatch only.
+  # Automatic releases kept bumping version incorrectly.
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stata-agent
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install Hatch (version tooling)
+        run: uv tool install hatch
+
+      - name: Install release dependencies
+        run: |
+          uv sync --python 3.14 --all-extras --dev
+
+      - name: Run tests that don't require Stata
+        run: uv run pytest -v -m "not requires_stata"
+
+      - name: Build package
+        run: uv build
+
+      - name: Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release version
+
+      - name: Trigger PyPI publish
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: "publish.yml",
+              ref: context.ref
+            })

stata_agent-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+.DS_Store
+__pycache__/
+.pytest_cache/
+*.pyc
+*.egg-info/
+build/
+dist/
+wheels/
+.venv
+.coverage
+htmlcov/
+
+# Stata log files
+*.log
+*.smcl
+stata.log
+
+# Random artifact files from fuzz testing
+benchmarks/history/
+
+# Bool-as-path bug artifacts (historical)
+True.log
+False.log
+
+# pi agent workspace — not part of the project
+.pi/
+
+# Generated benchmark dataset (90+ MB)
+testdata/large_benchmark.dta

stata_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.0 (2026-05-15)
+
+### Features
+
+- Initial release of stata-agent: CLI-native Stata integration for AI agents.
+- Run Stata code, inspect data, retrieve results, export graphs, and test do-files.
+- Daemon mode for persistent Stata sessions.
+- Mock backend for testing without a Stata license.
+- Statest: Stata-native test runner with JUnit output.
+- Plugin system with skills for AI agent integration (Claude Code, Codex, Gemini).
+- Cross-platform installer scripts (macOS, Linux, Windows).

stata_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,149 @@
+# Contributing to stata-agent
+
+Thank you for your interest in contributing to stata-agent! This guide will help you set up your development environment, run tests, and understand the project structure.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Building the Project](#building-the-project)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+
+## Development Setup
+
+### Prerequisites
+
+- **Stata 17+** (Required for integration tests)
+- **Python 3.11+**
+- **uv** (Recommended) or pip
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/tmonk/stata-agent.git
+   cd stata-agent
+   ```
+
+2. Install dependencies with uv:
+   ```bash
+   uv sync --dev
+   ```
+
+   Or with pip:
+   ```bash
+   pip install -e .[dev]
+   ```
+
+## Building the Project
+
+The project uses **hatchling** as the Python build backend. To build wheels:
+
+```bash
+uv build
+```
+
+Or using the build module directly:
+
+```bash
+python -m build
+```
+
+## Testing
+
+The test suite is organised with pytest markers.
+
+### All Tests (Requires Stata)
+
+```bash
+uv run pytest
+```
+
+### Tests Without Stata (Fast/CI)
+
+```bash
+uv run pytest -v -m "not requires_stata"
+```
+
+### Test Coverage
+
+Generate a coverage report:
+
+```bash
+uv run pytest --cov=stata_agent --cov-report=term-missing
+```
+
+Or generate an HTML report:
+
+```bash
+uv run pytest --cov=stata_agent --cov-report=html
+open htmlcov/index.html  # View the report
+```
+
+### Writing Tests
+
+When adding new tests:
+
+1. **Mark Stata-dependent tests**:
+   ```python
+   import pytest
+
+   # At module level for all tests
+   pytestmark = pytest.mark.requires_stata
+
+   # Or for individual tests
+   @pytest.mark.requires_stata
+   def test_my_stata_feature():
+       pass
+   ```
+
+2. **Mark slow tests**:
+   ```python
+   @pytest.mark.slow
+   def test_expensive_operation():
+       pass
+   ```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+
+2. **Develop and Test**:
+   - Add tests in `tests/`.
+   - Ensure `pytest -v -m "not requires_stata"` passes.
+
+3. **Commit with clear messages**:
+   Follow conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `perf:`, `test:`).
+
+4. **Push and create a pull request**:
+   ```bash
+   git push origin feature/my-feature
+   ```
+
+### CI/CD
+
+GitHub Actions automatically runs on all PRs:
+- Runs all non-Stata tests (`pytest -v -m "not requires_stata"`)
+- Tests on Ubuntu, macOS, and Windows with Python 3.11–3.14
+- Builds the package and tests entry points
+
+## Project Structure
+
+- `src/stata_agent/`: Python source code.
+- `tests/`: Test suite (unit, integration, benchmarks, statest, install).
+- `scripts/`: Utilities for installation and version syncing.
+- `worker/`: Cloudflare Worker for update checks.
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/tmonk/stata-agent/issues)
+- **Author**: [Thomas Monk](https://tdmonk.com)
+
+## License
+
+By contributing to stata-agent, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0.