pyfcstm.llm

LLM prompt resources for FCSTM model generation.

This module exposes the official FCSTM grammar guide prompt as a small Python API. The guide is packaged with pyfcstm so downstream prompt builders can use the same grammar reference that the project tests and releases validate.

Example:

>>> from pyfcstm.llm import get_grammar_guide_prompt_for_llm
>>> guide = get_grammar_guide_prompt_for_llm()
>>> "FCSTM" in guide
True

__all__

pyfcstm.llm.__all__ = ['GrammarGuidePromptIntegrityError', 'GrammarGuidePromptPathUnavailableError', 'get_grammar_guide_prompt_for_llm', 'get_grammar_guide_prompt_path_for_llm', 'get_grammar_guide_prompt_metadata_for_llm']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

GrammarGuidePromptIntegrityError

class pyfcstm.llm.GrammarGuidePromptIntegrityError[source]

Error raised when the packaged grammar guide integrity check fails.

This indicates that the Markdown prompt and the packaged SHA-256 digest do not agree, or that the digest resource is missing or malformed. Source-tree users should run make sha256 after editing the guide and commit the guide and digest together. Installed-package users should reinstall pyfcstm from a clean wheel or source distribution.

GrammarGuidePromptPathUnavailableError

class pyfcstm.llm.GrammarGuidePromptPathUnavailableError[source]

Error raised when the grammar guide has no direct filesystem path.

This can occur when the package is loaded from zip import, frozen bundles, or another importer that does not expose packaged Markdown resources as real files. The text API remains available for normal prompt construction in those installation modes.

get_grammar_guide_prompt_for_llm

pyfcstm.llm.get_grammar_guide_prompt_for_llm(raise_on_integrity_error: bool = True) → str[source]

Return the packaged FCSTM grammar guide prompt.

Parameters:

raise_on_integrity_error (bool, optional) – Whether a missing, malformed, or mismatched fcstm_grammar_guide.md.sha256 resource should raise instead of returning the prompt with a warning, defaults to True.

Returns:

UTF-8 decoded Markdown prompt text with LF newlines.

Return type:

str

Raises:

  • FileNotFoundError – If the packaged Markdown resource is missing.

  • UnicodeDecodeError – If the resource is not valid UTF-8.

  • GrammarGuidePromptIntegrityError – If the checksum resource is missing, malformed, or does not match the normalized prompt text.

Example:

>>> guide = get_grammar_guide_prompt_for_llm()
>>> guide.startswith("# FCSTM")
True

get_grammar_guide_prompt_path_for_llm

pyfcstm.llm.get_grammar_guide_prompt_path_for_llm(raise_on_integrity_error: bool = True) → str[source]

Return the filesystem path to the packaged grammar guide prompt.

This helper is intended for source-tree and normal wheel installs where the Markdown resource exists as a real file. It intentionally does not materialize temporary files for zip import or other non-filesystem import modes; callers that only need prompt text should use get_grammar_guide_prompt_for_llm().

Parameters:

raise_on_integrity_error (bool, optional) – Whether a missing, malformed, or mismatched fcstm_grammar_guide.md.sha256 resource should raise instead of returning the path with a warning, defaults to True.

Returns:

Filesystem path to fcstm_grammar_guide.md.

Return type:

str

Raises:

Example:

>>> import os
>>> path = get_grammar_guide_prompt_path_for_llm()
>>> os.path.basename(path)
'fcstm_grammar_guide.md'

get_grammar_guide_prompt_metadata_for_llm

pyfcstm.llm.get_grammar_guide_prompt_metadata_for_llm(raise_on_integrity_error: bool = True) → Dict[str, str | int][source]

Return deterministic metadata for the packaged grammar guide prompt.

sha256, byte_size, and line_count are computed from the same LF-normalized prompt text returned by get_grammar_guide_prompt_for_llm(). chapter_count is the number of Markdown level-two heading lines, i.e. lines starting with "## ".

Parameters:

raise_on_integrity_error (bool, optional) – Whether a missing, malformed, or mismatched fcstm_grammar_guide.md.sha256 resource should raise instead of returning metadata with a warning, defaults to True.

Returns:

Resource metadata for experiment snapshots.

Return type:

Dict[str, Union[str, int]]

Raises:

  • FileNotFoundError – If the packaged Markdown resource is missing.

  • UnicodeDecodeError – If the resource is not valid UTF-8.

  • GrammarGuidePromptIntegrityError – If the checksum resource is missing, malformed, or does not match the normalized prompt text.

Example:

>>> metadata = get_grammar_guide_prompt_metadata_for_llm()
>>> metadata["resource_name"]
'fcstm_grammar_guide.md'
>>> metadata["chapter_count"] > 0
True