[REFACTOR]: Decouple PromptTemplate creation from YAML

[Spencer Schoenberg (spencrr)]

Description

This supersedes the constructor approaches in #132 and #144 and follows the review feedback on #144.

This PR makes prompt-template construction source-neutral while retaining PromptTemplate.from_yaml(path) as the YAML and filesystem adapter.

• Adds a public, strict, frozen PromptTemplateDefinition.
• Normalizes declared parameters to an immutable, ordered tuple.
• Prevents prompt source from appearing in definition or template representations.
• Replaces injectable dataclass construction with PromptTemplate(definition=...).
• Compiles and validates Jinja exclusively inside PromptTemplate.
• Preserves from_yaml(path) and both existing production call sites.
• Keeps YAML paths outside the definition and compiled runtime object.
• Preserves direct underlying exception causes while adding YAML path context.
• Reports Jinja line numbers explicitly as template-value lines rather than misleading physical YAML lines.
• Replaces metadata-based equality with object identity.

Jinja receives neither the YAML path nor the logical template name. This avoids incorrect YAML file/line attribution and prevents names such as summary.html from unexpectedly enabling autoescape.

Breaking changes

Direct component-wise construction is no longer accepted:

PromptTemplate(
    name="Greeting",
    description=None,
    parameter_keys=("subject",),
    _template=compiled_template,
)

Construct from a validated definition instead:

PromptTemplate(
    definition=PromptTemplateDefinition(
        name="Greeting",
        description=None,
        parameters=("subject",),
        value="Hello, {{ subject }}!",
    ),
)

PromptTemplate.from_yaml(path) is unchanged, so existing supported call sites require no migration.

Separate PromptTemplate instances now use identity equality and hashing rather than metadata-based structural equality. PromptTemplateDefinitionError.path is optional for in-memory construction.

Checklist

• pre-commit run --all-files passes
• Tests added or updated for changes
  • 34 focused prompt-template tests pass
  • 652 tracked unit tests pass
• Documentation updated
  • Module and public API docstrings describe the source-neutral construction and error contracts

[azure-pipelines]

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

[Nina Chikanov (nina-msft)]

This looks like a great implementation based off of my feedback from previous PR! I did not get a chance to run this through GHCP because it is being very slow for me today - so if you haven't done a self-review through that it may be worth to make sure we didn't miss anything.

Otherwise, small feedback re: exception handling and otherwise I think the direction looks good. Up to you if you'd also like Bashir Partovi (@bashirpartovi) to take a look before merge.