[FIX]: Enforce PromptTemplate construction invariants

[Spencer Schoenberg (spencrr)]

Description

Fixes construction and equality invariants for PromptTemplate introduced in #120.

The dataclass-generated initializer exposed every field, including _template. A leading underscore is only a Python naming convention, so a caller could combine declared parameter metadata with an unrelated Jinja template and bypass PromptTemplate.from_yaml() validation:

PromptTemplate(
    name="x",
    description=None,
    parameter_keys=("declared",),
    _template=Template("{{ actual }}"),
).render(declared="provided")

This renders an empty string: argument validation succeeds against parameter_keys, while the injected template references a different variable and was compiled outside RAMPART's StrictUndefined environment.

This PR:

• disables the generated dataclass initializer and explicitly rejects direct construction, including the otherwise-valid empty PromptTemplate() call left available by init=False alone;
• creates instances only from a schema-validated YAML definition;
• compiles the Jinja template inside the validated-definition factory so the declared parameters and compiled behavior cannot drift independently;
• uses object.__new__() and object.__setattr__() for the narrow initialization phase required by a frozen, slotted dataclass;
• disables generated structural equality, which previously treated templates with identical metadata but different bodies as equal because _template was excluded from comparison, while preserving identity-based hashing; and
• marks PromptTemplate as final for static type checkers and IDEs.

PromptTemplate.from_yaml(path) remains the supported construction API and retains its Self return type. Separate instances now use identity equality:

first = PromptTemplate.from_yaml(path)
second = PromptTemplate.from_yaml(path)

assert first is not second
assert first != second
assert len({first, second}) == 2

Breaking changes

Direct PromptTemplate(...) construction is now rejected. Use PromptTemplate.from_yaml(path) instead. Equality between separate instances is now identity-based rather than metadata-based. Existing RAMPART production call sites already construct templates through from_yaml().

Checklist

• pre-commit run --all-files passes
• Tests added or updated for changes: direct construction, the former generated-constructor arguments, identity equality, and hashability
• Documentation updated: factory-only construction and migration are documented above and in the API docstrings

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Nina Chikanov (nina-msft)]

Was considering your comment on whether dataclass is still necessary since we are limiting some of its core usage...what do you think about this approach?

The object.__new__ + four object.__setattr__ reconstruction here only exists to work around init=False on a frozen, slotted dataclass — the class opts into the dataclass machinery and then fights it. You can keep the dataclass (its generated __init__, __repr__, frozen guard, and slots) and just gate construction with a module-private sentinel:

_FROM_YAML: Final = object()

@final
@dataclass(frozen=True, kw_only=True, slots=True, eq=False)
class PromptTemplate:
    name: str
    description: str | None
    parameter_keys: tuple[str, ...]
    _template: Template = field(repr=False)
    _token: InitVar[object]

    def __post_init__(self, _token: object) -> None:
        if _token is not _FROM_YAML:
            raise TypeError("Use PromptTemplate.from_yaml()")

from_yaml then just calls cls(name=..., description=..., parameter_keys=tuple(definition.parameters), _template=_compile_template(definition, path=path), _token=_FROM_YAML). That deletes _from_validated_definition, both object.* calls, the custom raising __init__, and all four lint suppressions — for the same guarantees.

I checked this on 3.11: direct construction, bare PromptTemplate(), and a wrong/absent token all raise TypeError; instances stay frozen (FrozenInstanceError); equality stays identity-based; the repr still hides _template; and because _token is an InitVar it never lands in __slots__ or on the instance. If you'd rather not carry a sentinel field, the other option is dropping @dataclass for a plain @final + __slots__ class — but then you hand-roll frozen and __repr__, so this is the smaller change.

[Spencer Schoenberg (spencrr)]

Nina Chikanov (@nina-msft) Yeah I am not a big fan of the token/sentinel thing. Can you PTAL at #144 - maybe a cleaner approach?

[Nina Chikanov (nina-msft)]

If we go with #144 - can you close this out as stale?

[Spencer Schoenberg (spencrr)]

Closing both in favor of your comment! Stay tuned!

[Spencer Schoenberg (spencrr)]

See #156