Scaffolding beyond devices

Until this month plesty init default was accepted by the CLI and then raised “Default project template is not yet available”, and analyzer was half-supported — the module type validated, but no scaffold offered it and no analyzer gate existed. Now all four project types scaffold, an analyzer arrives as a working schema-declared transform, and a1 holds it to the Analyzer contract.

Four project types, one template

plesty init [PROJECT_TYPE] takes default, device, analyzer or experiment — the argument now defaults to default rather than to a device. All four come out of the same Copier template; the type decides which files are rendered, which extra module is copied in, and which contract gate becomes active.

UsersScaffolding a project today

The standard workflow is two commands: make the directory, initialize inside it. The module name is inferred from the directory — the plesty- prefix is stripped and hyphens become underscores — so --name is usually unnecessary.

# A plain library module (the new default)
mkdir plesty-fit-utils && cd plesty-fit-utils
plesty init

# An analyzer — plesty.lib.analyzer.Analyzer + the a1 contract tests
mkdir plesty-peak-fit && cd plesty-peak-fit
plesty init analyzer

# A device server, explicit about author and CI standard
plesty --project-dir ~/projects/plesty-power-meter init device \
  --name power_meter --author "Jane Doe" --email jane@example.com \
  --standard nebula

Scaffolding is not an interview — every answer comes from an option or from the directory name. init then formats the generated files with the SDK’s own ruff config, makes the initial git commit (versioningit needs it to resolve a version), and installs the pre-push hook that runs plesty check before every push. The scaffold is plesty check-clean from the first commit.

What lands on disk

The type-specific module (analyzer.py, device.py, experiment.py) is copied from the template’s extras/<type>/ directory after the Copier render; the rest is one shared tree with Jinja branches. __main__.py and .env.example became device/experiment-only in this change — an analyzer has no server to run and no connection credentials to hold.

The scaffold tells you what to do next

plesty init ends with a numbered, project-type-specific Next steps list — environment setup, the files to implement, then the verify/publish loop. For an analyzer that reads:

1. Install the environment: uv sync
2. Declare your input/output schemas and implement analyze() in plesty/peak_fit/analyzer.py.
3. Keep calibration and analysis parameters as constructor arguments — they land in
   each result's provenance stamp.
4. Adapt the AnalyzerPipeline gate tests in tests/ (override synthetic inputs via
   mock_inputs if your transform needs realistic data).
5. Keep the generated tests green: uv run pytest
6. Run the compliance gates: uv run plesty check
7. Publish via CI: push to GitLab and tag a release when ready.

The step text ships in the wheel at plesty/sdk/assets/init/next-steps.yaml rather than living in the code, so the guidance is editable without touching the command. Pass the global --quiet flag to print only the result line — plesty --quiet --project-dir plesty-peak-fit init analyzer.

DevelopersWriting an analyzer against the scaffold

The generated analyzer.py is a complete working transform — it normalizes a trace to its peak — so the module is green before you have written a line. You replace the two schemas and the analyze() body.

from plesty.lib.analyzer import Analyzer as BaseAnalyzer
from plesty.lib.data import PlestyArray


class Analyzer(BaseAnalyzer):
    """Example analyzer: normalizes a signal trace to its peak value."""

    input_schema = {
        "signal": {"dtype": "array_float", "unit": "a.u.",
                     "description": "Raw signal trace to normalize."},
    }
    output_schema = {
        "normalized": {"dtype": "array_float", "unit": "a.u.",
                        "description": "Signal scaled to peak 1."},
    }

    def __init__(self, smoothing: int = 1) -> None:
        # Analysis parameters go here — they land in every result's provenance.
        super().__init__(smoothing=smoothing)

    def analyze(self, signal: PlestyArray) -> dict[str, Any]:
        data = np.asarray(signal, dtype=float)
        peak = float(np.max(np.abs(data))) if data.size else 0.0
        return {"normalized": PlestyArray(data / (peak or 1.0))}

Three rules follow from the base class, and the gates check all three:

• Declare, don’t document. input_schema and output_schema use the device-schema vocabulary — float, int, str, bool, array_<numpy dtype>, table2d. Arrays may pin a shape ([None, 2], where None is a free dimension) and an input may set required: False.
• The call validates. You implement analyze(); callers use Analyzer()(signal=data). The validating __call__ checks inputs against input_schema, fills unset name/unit/description on returned values from output_schema, and stamps every array or table result with provenance — analyzer class, package version, constructor parameters.
• Calibration is a constructor parameter, never module state. Anything passed to __init__ is recorded in that provenance stamp; a threshold read from a module global is invisible in the result and unreproducible from it.

Gate a1 — Analyzer Contract quantum

New in plesty check this month, mirroring the device gate d1 and the experiment gate e1. It activates on [tool.plesty] module_type = "analyzer" in pyproject.toml — which the scaffold writes for you — and is reported as N/A for every other module type. All five contract test functions must be present in tests/ and pass on schema-generated synthetic inputs:

The generated tests/test_<module>.py wires them in five lines — the pipeline holds the logic, the module holds the delegation:

from plesty.lib.test.analyzer_pipeline import AnalyzerPipeline
from plesty.peak_fit import Analyzer, load_config

PIPELINE = AnalyzerPipeline(Analyzer)


def test_analyze_signature() -> None:
    """Gate 3: analyze() accepts exactly the declared input names."""
    PIPELINE.test_analyze_signature()

What the scaffold already satisfies

A fresh init analyzer passes the full quantum check — including a1, at 100% coverage — before you change anything. That means REUSE licensing headers, the docs build, the packaging metadata and the CI file are all in place, and the first failure you see is one you introduced. Docs are one of the fixes that came with this work: the generated docs/index.md used to embed an automodule block that duplicated the always-on generated API reference, costing seven Sphinx warnings on every non-device scaffold; it now points at the generated reference pages instead.

DevelopersContributing to the templates

Everything the scaffold emits ships inside the SDK wheel, so extending it is editing assets, not code:

A new project type is therefore: a copier.yml choice, an extras/<type>/ module, Jinja branches in __init__.py.jinja and the test template, a next-steps.yaml block, and — if the type carries a contract — a gate in check.py that keys off module_type and stays silent for everyone else.

Where to look

• plesty-sdk — plesty/sdk/commands/init.py, plesty/sdk/commands/check.py, and the plesty/sdk/assets/ tree; docs/commands/init.md and docs/commands/check.md.
• plesty-lib — plesty.lib.analyzer for the base class, plesty.lib.test.analyzer_pipeline for the five gates.
• uv run plesty check in any module prints each gate with its tier and, on failure, the guidance for that gate.