symfonic.agent.prompts.system_prompt

system_prompt

HMSSystemPromptSection -- HMS-aware system prompt for SymfonicAgent.

Renders the bundled hms_system.txt template by substituting all {{VARIABLE}} placeholders from a context dict. Conforms to the PromptSection protocol defined in symfonic.core.prompt.

HMSSystemPromptSection dataclass

HMSSystemPromptSection(
    name: str = "HMS System Prompt",
    required: bool = False,
    priority: int = 5,
    cache_breakpoint: bool = True,
    template_path: Path | None = None,
)

PromptSection that renders the HMS-aware system prompt template.

Substitutes all {{VARIABLE}} placeholders from the PromptState context. Raises ValueError if any placeholder remains unresolved after rendering.

Attributes:

Name	Type	Description
name	str	Section display name used by PromptBuilder.
required	bool	Whether a render failure should abort the build.
priority	int	Lower numbers appear earlier in the assembled prompt.
template_path	Path | None	Optional override path (file or directory) for the hms_system.txt template. Defaults to the bundled template.

estimate_tokens staticmethod

estimate_tokens(text: str) -> int

Estimate token count using a conservative 3-chars-per-token heuristic.

The len // 4 heuristic undercounts by 20-30 % on structured / markdown text. len // 3 is closer to observed tokeniser output for prompts that contain headings, bullet lists, and JSON blocks.

Parameters:

Name	Type	Description	Default
text	str	The text to estimate token count for.	required

Returns:

Type	Description
int	Estimated number of tokens (conservative upper bound).

Source code in src/symfonic/agent/prompts/system_prompt.py

@staticmethod
def estimate_tokens(text: str) -> int:
    """Estimate token count using a conservative 3-chars-per-token heuristic.

    The ``len // 4`` heuristic undercounts by 20-30 % on structured /
    markdown text.  ``len // 3`` is closer to observed tokeniser output
    for prompts that contain headings, bullet lists, and JSON blocks.

    Args:
        text: The text to estimate token count for.

    Returns:
        Estimated number of tokens (conservative upper bound).
    """
    return len(text) // 3

render async

render(state: PromptState) -> str

Render the HMS system prompt by substituting placeholders.

Parameters:

Name	Type	Description	Default
state	PromptState	Mapping that must contain values for every {{VARIABLE}} placeholder in the template.	required

Returns:

Type	Description
str	The fully substituted prompt text.

Raises:

Type	Description
SecurityScopeError	If TENANT_ID is missing or empty.
ValueError	If any {{VARIABLE}} placeholder remains after substitution (i.e. the state is missing required keys).

Source code in src/symfonic/agent/prompts/system_prompt.py

async def render(self, state: PromptState) -> str:
    """Render the HMS system prompt by substituting placeholders.

    Args:
        state: Mapping that must contain values for every
            ``{{VARIABLE}}`` placeholder in the template.

    Returns:
        The fully substituted prompt text.

    Raises:
        SecurityScopeError: If ``TENANT_ID`` is missing or empty.
        ValueError: If any ``{{VARIABLE}}`` placeholder remains after
            substitution (i.e. the state is missing required keys).
    """
    tenant_id: Any = state.get("TENANT_ID") or state.get("tenant_id")
    if not tenant_id or not str(tenant_id).strip():
        raise SecurityScopeError(
            "tenant_id is required for HMS prompt rendering"
        )

    template = self._get_template()
    rendered = _substitute(template, state)
    remaining = _PLACEHOLDER_RE.findall(rendered)
    if remaining:
        raise ValueError(
            f"Unresolved HMS system prompt placeholders: {remaining}"
        )
    return rendered

validate_budget

validate_budget(
    rendered: str, max_tokens: int = 1000
) -> tuple[bool, int]

Check whether rendered fits within the token budget.

Does NOT raise — callers decide how to handle over-budget results.

Parameters:

Name	Type	Description	Default
rendered	str	The already-rendered prompt text.	required
max_tokens	int	Maximum allowed token count.	1000

Returns:

Type	Description
tuple[bool, int]	Tuple of (within_budget, estimated_tokens).

Source code in src/symfonic/agent/prompts/system_prompt.py

def validate_budget(
    self, rendered: str, max_tokens: int = 1000
) -> tuple[bool, int]:
    """Check whether *rendered* fits within the token budget.

    Does NOT raise — callers decide how to handle over-budget results.

    Args:
        rendered: The already-rendered prompt text.
        max_tokens: Maximum allowed token count.

    Returns:
        Tuple of ``(within_budget, estimated_tokens)``.
    """
    estimated = self.estimate_tokens(rendered)
    return estimated <= max_tokens, estimated