feat: initial setup

.github/workflows/release.yaml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  github_release:
+    name: GitHub Release
+    runs-on: ubuntu-latest
+    outputs:
+      new_release_published: ${{ steps.semantic.outputs.new_release_published }}
+      new_release_version: ${{ steps.semantic.outputs.new_release_version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+
+      - name: Install semantic-release plugins
+        run: |
+          npm install -g semantic-release \
+            @semantic-release/commit-analyzer \
+            @semantic-release/release-notes-generator \
+            @semantic-release/exec \
+            @semantic-release/github \
+            @semantic-release/git \
+            conventional-changelog-conventionalcommits
+
+      - name: Semantic Release (dry-run)
+        env:
+          GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+        run: npx semantic-release --dry-run
+
+      - name: Semantic Release
+        id: semantic
+        env:
+          GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+        run: npx semantic-release
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: github_release
+    if: needs.github_release.outputs.new_release_published == 'true'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Pull latest changes
+        run: git pull origin main
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  push:
+    branches: ["*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install tox
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install uv
+          uv tool install tox --with tox-uv
+
+      - name: Run tox
+        run: tox

.releaserc.yaml

@@ -0,0 +1,77 @@
+branches:
+  - main
+
+tagFormat: ${version}
+
+plugins:
+  - - "@semantic-release/commit-analyzer"
+    - preset: conventionalcommits
+      releaseRules:
+        - type: feat
+          release: minor
+        - type: fix
+          release: patch
+        - type: perf
+          release: patch
+        - type: docs
+          release: patch
+        - type: refactor
+          release: patch
+        - type: style
+          release: patch
+        - type: ci
+          release: patch
+        - type: build
+          release: patch
+        - type: chore
+          release: patch
+        - type: test
+          release: patch
+
+  - - "@semantic-release/release-notes-generator"
+    - preset: conventionalcommits
+      presetConfig:
+        types:
+          - type: feat
+            section: "Features"
+            hidden: false
+          - type: fix
+            section: "Bug Fixes"
+            hidden: false
+          - type: perf
+            section: "Performance"
+            hidden: false
+          - type: docs
+            section: "Documentation"
+            hidden: false
+          - type: refactor
+            section: "Refactoring"
+            hidden: false
+          - type: style
+            section: "Style"
+            hidden: false
+          - type: ci
+            section: "CI/CD"
+            hidden: false
+          - type: build
+            section: "Build"
+            hidden: false
+          - type: chore
+            section: "Chores"
+            hidden: false
+          - type: test
+            section: "Tests"
+            hidden: false
+
+  - - "@semantic-release/exec"
+    - prepareCmd: "sed -i 's/^version = .*$/version = \"${nextRelease.version}\"/' pyproject.toml"
+
+  - - "@semantic-release/github"
+    - releaseNameTemplate: "Version ${nextRelease.version}"
+
+  - - "@semantic-release/git"
+    - assets:
+        - pyproject.toml
+      message: "chore(release): ${nextRelease.version}"
+
+repositoryUrl: "https://github.com/mloda-ai/mloda-plugin-template"

AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+**Required reading:** Must start by reading [README.md](README.md) for project overview, structure, key files, and common tasks.

CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+Must follow [AGENTS.md](AGENTS.md) for AI guidance and documentation links.

README.md

@@ -1 +1,135 @@
-# mloda-plugin-template
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/mloda-ai/mloda-plugin-template/blob/main/LICENSE)
+[![mloda](https://img.shields.io/badge/built%20with-mloda-blue.svg)](https://github.com/mloda-ai/mloda)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+# mloda-plugin-template
+
+> **A GitHub template for creating standalone mloda plugins.** Part of the [mloda](https://github.com/mloda-ai/mloda) ecosystem for open data access. Visit [mloda.ai](https://mloda.ai) for an overview and business context, the [GitHub repository](https://github.com/mloda-ai/mloda) for technical context, or the [documentation](https://mloda-ai.github.io/mloda/) for detailed guides.
+
+Create your own FeatureGroups, ComputeFrameworks, and Extenders as standalone packages. See the [Getting Started guide](docs/getting-started.md) to create your repository, then follow the setup steps below.
+
+## Related Repositories
+
+- **[mloda](https://github.com/mloda-ai/mloda)**: The core library for open data access. Declaratively define what data you need, not how to get it. mloda handles feature resolution, dependency management, and compute framework abstraction automatically.
+
+- **[mloda-registry](https://github.com/mloda-ai/mloda-registry)**: The central hub for discovering and sharing mloda plugins. Browse community-contributed FeatureGroups, find integration guides, and publish your own plugins for others to use.
+
+## Structure
+
+```
+placeholder/
+├── feature_groups/
+│   └── my_plugin/
+│       ├── __init__.py           # Package exports
+│       ├── my_feature_group.py   # Example FeatureGroup implementation
+│       └── tests/
+│           └── test_my_feature_group.py
+├── compute_frameworks/
+│   └── my_framework/
+│       ├── __init__.py
+│       └── my_compute_framework.py
+└── extenders/
+    └── my_extender/
+        ├── __init__.py
+        └── my_extender.py
+```
+
+## Key Files
+
+- `placeholder/` - Root namespace (users rename to company name)
+- `pyproject.toml` - Package config (users edit directly, not auto-generated)
+- `.github/workflows/test.yml` - CI workflow running pytest
+
+## Common Tasks
+
+### Setup Your Plugin
+
+Follow these steps to customize the template for your organization:
+
+#### 1. Rename the directory
+
+```bash
+mv placeholder acme
+```
+
+#### 2. Update pyproject.toml
+
+Edit the following fields in `pyproject.toml`:
+
+- `name`: Change `"placeholder-my-plugin"` to `"acme-my-plugin"`
+- `authors`: Update name and email
+- `description`: Update to describe your plugin
+- `tool.setuptools.packages.find.include`: Change `["placeholder*"]` to `["acme*"]`
+- `tool.pytest.ini_options.testpaths`: Change `["placeholder", "tests"]` to `["acme", "tests"]`
+
+#### 3. Update Python imports
+
+Update imports in these files (change `from placeholder.` to `from acme.`):
+
+- `acme/feature_groups/my_plugin/__init__.py`
+- `acme/feature_groups/my_plugin/tests/test_my_feature_group.py`
+- `acme/compute_frameworks/my_plugin/__init__.py`
+- `acme/compute_frameworks/my_plugin/tests/test_my_compute_framework.py`
+- `acme/extenders/my_plugin/__init__.py`
+- `acme/extenders/my_plugin/tests/test_my_extender.py`
+
+#### 4. Verify setup
+
+```bash
+uv venv && source .venv/bin/activate && uv pip install -e ".[dev]" && tox
+```
+
+### Development Setup with uv
+
+**Install uv** (if not already installed):
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Create virtual environment and install dependencies:**
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+**Run all checks with tox:**
+```bash
+# Install tox with uv backend
+uv tool install tox --with tox-uv
+
+# Run all checks (pytest, ruff, mypy, bandit)
+tox
+```
+
+### Run individual checks
+
+```bash
+# Tests only
+pytest
+
+# Format check
+ruff format --check --line-length 120 .
+
+# Lint check
+ruff check .
+
+# Type check
+mypy --strict --ignore-missing-imports .
+
+# Security check
+bandit -c pyproject.toml -r -q .
+```
+
+### Add new FeatureGroup
+Create new directory under `placeholder/feature_groups/` following the `my_plugin/` pattern.
+
+## Related Documentation
+
+Guides for plugin development can be found in mloda-registry:
+
+- https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/
+
+## Architecture Overview
+
+- [Repository structure and relationships](https://github.com/mloda-ai/mloda-registry/blob/main/docs/architecture/00_repositories.md)

docs/getting-started.md

@@ -0,0 +1,50 @@
+# Getting Started
+
+There are two ways to create your own mloda plugin from this template.
+
+## Option 1: Use as Template (Recommended)
+
+GitHub's template feature creates a new repository with all files but a clean commit history.
+
+1. Click the green **"Use this template"** button on the [repository page](https://github.com/mloda-ai/mloda-plugin-template)
+2. Choose **"Create a new repository"**
+3. Name your repository (e.g., `acme-features`, `acme-data-plugins`, or `mycompany-feature-groups`)
+
+   > **Note:** Please don't use "mloda" in your package or repository name. However, you can use formulations like "for mloda" or "mloda-compatible" in descriptions.
+
+4. Choose public or private visibility
+5. Click **"Create repository"**
+
+**Advantages:**
+- Clean commit history (starts fresh)
+- No fork relationship to maintain
+- Your repo is completely independent
+- One-click setup in GitHub UI
+
+## Option 2: Fork
+
+Forking creates a copy that maintains a connection to the original repository.
+
+1. Click the **"Fork"** button on the [repository page](https://github.com/mloda-ai/mloda-plugin-template)
+2. Choose your account or organization
+3. Name your forked repository
+4. Click **"Create fork"**
+
+**Advantages:**
+- Can pull updates from the original template
+- Familiar workflow for open source contributors
+
+**Disadvantages:**
+- Maintains fork relationship (shows "forked from" on your repo)
+- Copies entire commit history
+- GitHub may suggest contributing back to the original
+
+## After Creating Your Repository
+
+Regardless of which option you chose, follow the setup steps in the [README](../README.md#setup-your-plugin) to customize the template:
+
+1. Clone your new repository locally
+2. Rename the `placeholder/` directory
+3. Update `pyproject.toml`
+4. Update Python imports
+5. Verify with `tox`

placeholder/compute_frameworks/__init__.py

@@ -0,0 +1 @@
+"""Compute frameworks namespace package."""