Skip to content

symfonic.capabilities.prompting.values

values

The values a prompt compile produces.

:class:CompiledPrompt is the whole output: the regions a provider caches, the contributions that survived, the budget arithmetic, and a diagnostic record of everything that was dropped and why. It is frozen and self-describing on purpose — an adopter debugging "why is my block missing" reads the diagnostics instead of re-running the compile with print statements.

BudgetReport dataclass 

BudgetReport(limit: int | None = None, total_tokens: int = 0, admitted: tuple[str, ...] = (), dropped: tuple[str, ...] = ())

The budget arithmetic, kept alongside the prompt it explains.

CompiledPrompt dataclass 

CompiledPrompt(strategy: str, regions: tuple[CacheRegion, ...] = (), contributions: tuple[RenderedContribution, ...] = (), budget: BudgetReport = BudgetReport(), diagnostics: tuple[PromptDiagnostic, ...] = (), digest: str = '')

One compiled prompt: regions, survivors, budget, diagnostics, digest.

text property 

text: str

The whole prompt as one string, regions joined in ladder order.

cache_annotations 

cache_annotations() -> list[dict[str, object]]

The prompt as provider content blocks, cache markers included.

Source code in src/symfonic/capabilities/prompting/values.py 
85
86
87
def cache_annotations(self) -> list[dict[str, object]]:
    """The prompt as provider content blocks, cache markers included."""
    return [region.annotation() for region in self.regions]

region_of 

region_of(contribution_id: str) -> CacheRegion | None

The region carrying contribution_id, or None when it was dropped.

Source code in src/symfonic/capabilities/prompting/values.py 
89
90
91
92
93
94
def region_of(self, contribution_id: str) -> CacheRegion | None:
    """The region carrying ``contribution_id``, or ``None`` when it was dropped."""
    for region in self.regions:
        if contribution_id in region.contribution_ids:
            return region
    return None

PromptDiagnostic dataclass 

PromptDiagnostic(kind: str, subject: str, detail: str)

One recorded compile decision.

kind is the stage that made it (input, strategy, source, gate, budget, cache), subject the contribution it concerns. Diagnostics are data rather than log lines because the caller that needs them most — a test asserting a block was dropped for the right reason — has no access to a log handler.

RenderedContribution dataclass 

RenderedContribution(contribution_id: str, layer: Layer, tier: TrustTier, text: str, revision: str, tokens: int, directive: CacheDirective, pinned: bool, degraded: bool = False)

One contribution after gating, with its cost and cache annotation fixed.

prompt_digest 

prompt_digest(regions: Sequence[CacheRegion]) -> str

A stable identity for a compiled prompt.

Computed over the region digests and their annotations, not over the joined text: two prompts with identical bytes but different breakpoints are different cache plans, and a digest that could not tell them apart would be useless as a cache key.

Source code in src/symfonic/capabilities/prompting/values.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def prompt_digest(regions: Sequence[CacheRegion]) -> str:
    """A stable identity for a compiled prompt.

    Computed over the region digests *and* their annotations, not over the
    joined text: two prompts with identical bytes but different breakpoints are
    different cache plans, and a digest that could not tell them apart would be
    useless as a cache key.
    """
    material = "|".join(
        f"{region.index}:{region.layer.value}:{region.directive.cacheable}:"
        f"{region.directive.ttl or ''}:{region.digest}"
        for region in regions
    )
    return hashlib.sha256(material.encode("utf-8")).hexdigest()[:32]