Skip to content

symfonic.agent.prompts.ports

ports

The declared port of the prompt-assembly capability.

This module exists because the matrix is silent here, not because it is permissive. symfonic.agent.prompts is ruled capability (T1.2.4 archcheck.toml) and so is symfonic.capabilities.prompting, and check_boundaries returns nothing for a same-layer edge — "same-layer structure is governed by package-level rules, not the matrix" (:mod:symfonic.devtools.archcheck.boundaries). So the one cross-package import, symfonic.capabilities.prompting.hms reaching :class:~symfonic.agent.prompts.system_prompt.HMSSystemPromptSection, is not licensed by a cell; it is out of the checker's reach entirely.

T1.2.1's dependency-matrix.md says what the self cell does not mean: "capability → capability cross-talk is not an import edge at all: collaboration goes through ports declared to the compiler and wired via the plan (LAY-ADR §3.4). The self cell does not license importing another capability package's internals." system_prompt is an internal module of a different capability package, so that note excludes exactly the edge above.

The package-level rule the matrix defers to is therefore written here and enforced by test_the_prompting_capability_reaches_agent_prompts_only_through_a_port: importers outside symfonic.agent name this module and nothing else under symfonic.agent.prompts. Nothing is defined locally; the single name is re-exported from its owning module, so there is still one implementation.

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 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
@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 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
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).
    """
    return self.render_sync(state)

render_sync 

render_sync(state: PromptState) -> str

The whole of :meth:render, without the coroutine.

Extracted for #21: a prompting source's read is synchronous by contract, and rendering never awaited anything -- render is a coroutine only because PromptSection is. Splitting it keeps one implementation of the placeholder rules, which is the point of porting rather than rewriting: the upper/lower key fallback is invisible until an adopter's state happens to use the other case.

Source code in src/symfonic/agent/prompts/system_prompt.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def render_sync(self, state: PromptState) -> str:
    """The whole of :meth:`render`, without the coroutine.

    Extracted for #21: a prompting source's ``read`` is synchronous by
    contract, and rendering never awaited anything -- ``render`` is a
    coroutine only because ``PromptSection`` is. Splitting it keeps *one*
    implementation of the placeholder rules, which is the point of porting
    rather than rewriting: the upper/lower key fallback is invisible until
    an adopter's state happens to use the other case.
    """
    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 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
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