Imported from TomKaltofen/cedh-mulligan-simulator (AGENTS.md). Install upstream with npx skills add TomKaltofen/cedh-mulligan-simulator. Copyright stays with the author.

AGENTS.md

Must read README.md first.

This project uses the mloda framework. Assume any given task is related to mloda.

Environment

source .venv/bin/activate

Dependencies

Use uv to install dependencies:

uv sync --all-extras

Running checks

Use tox to run all checks:

tox

Run checks from the project virtualenv:

source .venv/bin/activate && tox

tox is the required final verification step after code or dependency changes. Running only pytest is not sufficient for completion.

Run individual checks

pytest
ruff format --check --line-length 120 .
ruff check .
mypy --strict --ignore-missing-imports .
bandit -c pyproject.toml -r -q .

Commit messages

Use Conventional Commit format for all commits so semantic versioning/release tooling can parse intent. Do not include Co-Authored-By lines or any other mention of AI agents in commit messages.

Examples:

• fix: handle empty feature set
• chore(deps): bump mloda to 0.4.6

Claude Code Skills

The mloda-registry provides Claude Code skills that assist with plugin development:

• https://github.com/mloda-ai/mloda-registry/tree/main/.claude/skills/

When helping with FeatureGroups, ComputeFrameworks, or Extenders, leverage these skills for pattern guidance and best practices.

Consider generating project-specific skills for your own plugin repository to provide tailored AI assistance for your implementation patterns and conventions.

mloda Feature Group Guides

Before building or adapting feature groups, consult the guides at: https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/

Decision Tree — Choosing a Pattern

Use 09-create-feature-group.md to pick the right pattern:

1. Does it load/generate data with no dependencies? → Root Feature (01-root-features)
   • Use DataCreator({"feat_a", "feat_b"}) from input_data() for synthetic/generated data.
   • Keys in the DataCreator set must match keys in the dict returned by calculate_feature.
2. Does it transform one or more existing features? → Derived Feature (02-derived-features)
   • Return dependencies from input_features(), compute in calculate_feature().
   • Default matching is by class name (e.g. class DoubledValue matches feature "DoubledValue").
3. Should it be reusable via naming pattern (input__operation)? → Chained Feature (03-chained-features)
4. Does it produce multiple output columns? → Multi-output (~ separator) (05-multi-output-features)

Core Concepts

• Options (11-options): group values are hashed and affect feature resolution. context values are metadata only. Nested dicts (like card registries) must go in context, not group.
• calculate_feature() (12-calculate-feature): Receives data (DataFrame/dict with dependencies computed) and features (FeatureSet with requested features, options, filters).
• Feature Naming (13-feature-naming): Class name (default), feature_names_supported() (explicit set), or PREFIX_PATTERN (regex). Separators: __ (chain), ~ (multi-output), & (multi-input).
• Feature Matching (14-feature-matching): Priority order — input data match → exact class name → prefix match → explicit names. Exactly one FeatureGroup must match per feature name.

Testing Strategy

Follow the 3-level approach from 10-testing-guide:

1. Unit (fast): Test match_feature_group_criteria(), input_features(), config methods.
2. Framework (medium): Test calculate_feature() with real DataFrames.
3. Integration (slow): Test full pipeline via mloda.run_all().

All Pattern Guides

Plugin Journey Guides