symfonic.capabilities.prompting.regional

regional

Regional prompt composition for deployments migrating HMS settings.

The compiler still owns the total prompt budget. This module adds the two legacy regional boundaries as explicit sources: the authored HMS section is protected before it reaches compiler admission, while a JIT tool manifest is rendered under its own cap. Neither boundary receives prompt text in its observer callback.

JitManifestSource dataclass

JitManifestSource(manifest: Sequence[str], policy: RegionalPromptPolicy, untrusted: bool = False, offline_safe: bool = True, scope_aware: bool = False)

Render a fixed tool manifest under the policy's independent JIT cap.

The caller supplies the manifest it has already authorised for the turn. This source deliberately does not discover tools or inspect providers.

RegionalBudgetSource dataclass

RegionalBudgetSource(source: _ReadableSource, policy: RegionalPromptPolicy, region: str = 'hms_system_prompt')

Apply an advisory or strict boundary to an authored prompt source.

RegionalPromptPolicy dataclass

RegionalPromptPolicy(hms_system_prompt_token_budget: int | None = None, jit_manifest_token_budget: int = 0, hms_budget_mode: Literal['warn', 'strict'] = 'warn', on_hms_budget_exceeded: BudgetObserver | None = None, domain_description_max_chars: tuple[int, int] = (2000, 400))

The explicit legacy-region limits a native composition can honour.

hms_system_prompt_token_budget guards only the authored HMS source. jit_manifest_token_budget controls only the manifest source. The compiler's own PromptBudget remains a distinct total-prompt ceiling.

bounded_domain_description

bounded_domain_description(description: str, policy: RegionalPromptPolicy, *, jit: bool) -> str

Return the model-visible domain description for the selected surface.

Source code in src/symfonic/capabilities/prompting/regional.py

def bounded_domain_description(
    description: str, policy: RegionalPromptPolicy, *, jit: bool
) -> str:
    """Return the model-visible domain description for the selected surface."""
    if not description:
        return "(none)" if jit else "(no domain-specific directives)"
    cap = policy.domain_description_max_chars[1 if jit else 0]
    return description if len(description) <= cap else description[:cap] + "... [truncated]"

hms_source_for_domain

hms_source_for_domain(state: Mapping[str, object], domain: object, policy: RegionalPromptPolicy) -> _ReadableSource

Bind the supported domain.description field into an HMS source.

The caller still supplies the template's other authored values. Domain fields that belong to tools or governance are intentionally not projected into this prompt source.

Source code in src/symfonic/capabilities/prompting/regional.py

def hms_source_for_domain(
    state: Mapping[str, object], domain: object, policy: RegionalPromptPolicy
) -> _ReadableSource:
    """Bind the supported ``domain.description`` field into an HMS source.

    The caller still supplies the template's other authored values.  Domain
    fields that belong to tools or governance are intentionally not projected
    into this prompt source.
    """
    from symfonic.capabilities.prompting.hms import HmsSystemSource

    bound = dict(state)
    bound["DOMAIN_DESCRIPTION"] = bounded_domain_description(
        str(getattr(domain, "description", "") or ""), policy, jit=False
    )
    return HmsSystemSource(state=bound)

jit_manifest_contribution

jit_manifest_contribution(source: JitManifestSource, *, order: int = 100) -> PromptContribution

Declare the manifest in L1; callers use it only in a JIT composition.

Source code in src/symfonic/capabilities/prompting/regional.py

def jit_manifest_contribution(source: JitManifestSource, *, order: int = 100) -> PromptContribution:
    """Declare the manifest in L1; callers use it only in a JIT composition."""
    return PromptContribution(
        contribution_id="jit.tool_manifest",
        source=source,
        capability="prompting",
        layer=Layer.L1,
        tier=TrustTier.PLATFORM,
        scope=ContributionScope.DEPLOYMENT,
        order=order,
    )

regional_hms_contribution

regional_hms_contribution(source: _ReadableSource, policy: RegionalPromptPolicy, *, order: int = -1000) -> PromptContribution

Declare the HMS section as a pinned authored L0 region.

Source code in src/symfonic/capabilities/prompting/regional.py

def regional_hms_contribution(
    source: _ReadableSource,
    policy: RegionalPromptPolicy,
    *,
    order: int = -1000,
) -> PromptContribution:
    """Declare the HMS section as a pinned authored L0 region."""
    return PromptContribution(
        contribution_id="hms.system",
        source=RegionalBudgetSource(source=source, policy=policy),
        capability="prompting",
        layer=Layer.L0,
        tier=TrustTier.PLATFORM,
        scope=ContributionScope.DEPLOYMENT,
        order=order,
        pinned=True,
    )

regional_prompting_capability

regional_prompting_capability(hms_source: _ReadableSource, policy: RegionalPromptPolicy, *, strategy: Literal['jit', 'stratified'] = 'stratified', manifest: Sequence[str] = ()) -> object

Build the supported regional composition with explicit JIT intent.

A non-zero manifest budget is only effective when a JIT manifest is supplied and the composition declares strategy='jit'. Refusing the other combinations prevents a deployment from carrying a configuration value that cannot affect the model request.

Source code in src/symfonic/capabilities/prompting/regional.py

def regional_prompting_capability(
    hms_source: _ReadableSource,
    policy: RegionalPromptPolicy,
    *,
    strategy: Literal["jit", "stratified"] = "stratified",
    manifest: Sequence[str] = (),
) -> object:
    """Build the supported regional composition with explicit JIT intent.

    A non-zero manifest budget is only effective when a JIT manifest is
    supplied and the composition declares ``strategy='jit'``.  Refusing the
    other combinations prevents a deployment from carrying a configuration
    value that cannot affect the model request.
    """
    if policy.jit_manifest_token_budget and not manifest:
        raise ValueError(
            "jit_manifest_token_budget needs a manifest; set it to zero when "
            "the JIT manifest is not composed"
        )
    if manifest and strategy != "jit":
        raise ValueError("a JIT manifest requires strategy='jit'")
    from symfonic.capabilities.prompting.capability import PromptingCapability
    from symfonic.capabilities.prompting.strategies import ContextStrategy

    sources: list[PromptContribution] = [regional_hms_contribution(hms_source, policy)]
    if manifest:
        sources.append(jit_manifest_contribution(JitManifestSource(manifest, policy)))
    return PromptingCapability(
        sources=sources,
        options={"strategy": ContextStrategy(strategy)},
    )