bead 0.1.0__tar.gz

bead-0.1.0/.bash_setup

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Setup script for pytest-codeblocks bash tests
+# This is sourced by bash before running each code block
+
+# Determine project root (where this script lives)
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Add bead CLI to PATH using absolute path
+export PATH="${PROJECT_ROOT}/.venv/bin:${PATH}"
+
+# Create cli_work directory if it doesn't exist and copy fixtures
+FIXTURES_SRC="${PROJECT_ROOT}/tests/fixtures/api_docs"
+FIXTURES_WORK="${PROJECT_ROOT}/tests/fixtures/cli_work"
+
+if [ ! -d "${FIXTURES_WORK}" ]; then
+    echo "Setting up CLI test fixtures..." >&2
+    mkdir -p "${FIXTURES_WORK}"
+    cp -r "${FIXTURES_SRC}"/* "${FIXTURES_WORK}/"
+fi
+
+# Change to fixtures directory
+cd "${FIXTURES_WORK}" || {
+    echo "ERROR: Failed to cd to ${FIXTURES_WORK}" >&2
+    exit 1
+}

bead-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,78 @@
+name: Bug Report
+description: Report a bug in bead
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the form below.
+
+        **Note**: For questions or help, please use [GitHub Discussions](https://github.com/FACTSlab/bead/discussions) instead.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched the existing issues and this is not a duplicate
+          required: true
+        - label: I am using the latest version of bead
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code example that reproduces the issue.
+      placeholder: |
+        ```python
+        from bead import ...
+
+        # Code that reproduces the bug
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include the full error traceback if applicable.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Please provide your environment details.
+      value: |
+        - bead version:
+        - Python version:
+        - OS:
+        - Installation method (uv/pip):
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or information about the problem.

bead-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Help
+    url: https://github.com/FACTSlab/bead/discussions
+    about: Please ask questions in GitHub Discussions instead of opening an issue.
+  - name: Documentation
+    url: https://bead.readthedocs.io
+    about: Check the documentation for guides and API reference.

bead-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,70 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please fill out the form below.
+
+        **Note**: For questions or discussion, please use [GitHub Discussions](https://github.com/FACTSlab/bead/discussions) first.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched the existing issues and this feature has not been requested
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve? Why is it needed?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How do you envision this feature working?
+      placeholder: |
+        I would like to be able to...
+
+        ```python
+        # Example of how it might work
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered other approaches or workarounds?
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of bead does this relate to?
+      options:
+        - Resources (lexicons, templates)
+        - Template filling
+        - Items (construction, models)
+        - Lists (partitioning, constraints)
+        - Deployment (jsPsych, JATOS)
+        - Active learning
+        - Simulation
+        - CLI
+        - Documentation
+        - Other
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, mockups, or examples.

bead-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,40 @@
+## Description
+
+<!-- Describe your changes in detail. What does this PR do? -->
+
+## Motivation
+
+<!-- Why is this change needed? Link to related issues if applicable. -->
+
+Fixes #
+
+## Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Tests (adding or updating tests)
+
+## Checklist
+
+<!-- Mark completed items with an "x" -->
+
+- [ ] I have read the [CONTRIBUTING](../CONTRIBUTING.md) guidelines
+- [ ] My code follows the project's style guidelines
+- [ ] I have run `uv run ruff check .` and `uv run ruff format .`
+- [ ] I have run `uv run pyright` with no errors
+- [ ] I have added tests that prove my fix/feature works
+- [ ] All tests pass (`uv run pytest tests/`)
+- [ ] I have updated documentation as needed
+
+## Testing
+
+<!-- Describe how you tested your changes -->
+
+## Screenshots (if applicable)
+
+<!-- Add screenshots to help explain your changes -->

bead-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,242 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # TypeScript jobs
+  ts-check:
+    name: TypeScript Check (Biome)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: bead/deployment/jspsych
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: bead/deployment/jspsych/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run Biome check (lint + format)
+        run: pnpm check
+
+  ts-typecheck:
+    name: TypeScript Type Check
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: bead/deployment/jspsych
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: bead/deployment/jspsych/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run type check
+        run: pnpm typecheck
+
+  ts-build:
+    name: TypeScript Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: bead/deployment/jspsych
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: bead/deployment/jspsych/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build TypeScript
+        run: pnpm build
+
+  ts-test:
+    name: TypeScript Test
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: bead/deployment/jspsych
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: bead/deployment/jspsych/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test
+
+  # Python jobs
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff linter
+        run: ruff check .
+
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Check formatting
+        run: ruff format --check .
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[dev,behavioral-analysis]"
+
+      - name: Run pyright
+        run: pyright
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: [ts-build]  # Python tests need TypeScript compiled
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: bead/deployment/jspsych/pnpm-lock.yaml
+
+      - name: Install TypeScript dependencies
+        working-directory: bead/deployment/jspsych
+        run: pnpm install
+
+      - name: Build TypeScript
+        working-directory: bead/deployment/jspsych
+        run: pnpm build
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Create virtual environment
+        run: python -m venv .venv
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies in venv
+        run: |
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -e ".[dev,api,training,stats,behavioral-analysis]"
+
+      - name: Set up test fixtures
+        run: |
+          mkdir -p tests/fixtures/cli_work
+          cp -r tests/fixtures/api_docs/* tests/fixtures/cli_work/
+
+      - name: Run tests
+        run: .venv/bin/pytest --codeblocks --cov=bead --cov-report=xml --cov-report=term-missing -m "not slow_model_training"
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

bead-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+          uv pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,70 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bead
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/bead
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

bead-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+design-notes/
+presentations/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+.coverage
+gallery/**/.cache
+gallery/**/lexicons/*.jsonl
+gallery/**/templates/*.jsonl
+gallery/**/filled_templates/*.jsonl
+gallery/**/items/*.jsonl
+gallery/**/lists/*.jsonl
+gallery/**/deployment/
+node_modules/
+bead/deployment/jspsych/dist/
+coverage/
+site/
+
+# Documentation test working directories (temporary copies of fixtures)
+tests/fixtures/api_work/
+tests/fixtures/cli_work/
+
+# Documentation test artifacts (created in project root if tests fail to cd)
+/constraints/
+/experiment/
+/items/
+/lexicons/
+/templates/
+/lists/
+/filled_templates/
+/responses/
+/exports/
+/trial_config_*.json
+/*.jzip
+.claude/

bead-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+# Pre-commit hooks for bead package
+#
+# Installation:
+#   pip install pre-commit
+#   pre-commit install
+#
+# Run manually:
+#   pre-commit run --all-files
+#
+# Update hook versions:
+#   pre-commit autoupdate
+
+repos:
+  # Docstring format validation (NumPy convention)
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 6.3.0
+    hooks:
+      - id: pydocstyle
+        args:
+          - --convention=numpy
+          # D105: Missing docstring in magic method (acceptable)
+          # D107: Missing docstring in __init__ (we document in class docstring)
+          # D202: No blank lines allowed after docstring (conflicts with ruff format)
+          - --add-ignore=D105,D107,D202
+        exclude: ^(tests/|bead/dsl/parser\.py|gallery/)
+
+  # Docstring-signature consistency validation
+  - repo: https://github.com/terrencepreilly/darglint
+    rev: v1.8.1
+    hooks:
+      - id: darglint
+        args:
+          # Verbosity level 2: full error messages
+          - -v
+          - "2"
+        exclude: ^(tests/|bead/dsl/parser\.py|bead/active_learning/|bead/simulation/)
+
+  # Additional code quality checks (optional but recommended)
+  # Uncomment to enable after Phase 2
+
+  # - repo: https://github.com/pre-commit/pre-commit-hooks
+  #   rev: v4.5.0
+  #   hooks:
+  #     - id: trailing-whitespace
+  #     - id: end-of-file-fixer
+  #     - id: check-yaml
+  #     - id: check-added-large-files
+  #     - id: check-merge-conflict
+  #     - id: check-toml
+  #     - id: mixed-line-ending

bead-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

bead-0.1.0/.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    post_create_environment:
+      - pip install uv
+    post_install:
+      - uv pip install --system -e ".[dev]"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: docs/requirements.txt