symfonic.agent.triage

triage

Intent triage — pre-hydration routing primitives.

Provides the IntentClassifier (v7.0 T06) used by the hydration path to route turns into action / knowledge / ambiguous lanes. The default deterministic heuristic runs without any LLM call; an LLM fallback is tracked for v7.1.

IntentClassifier

IntentClassifier(*, ambiguity_confidence_floor: float = 0.55, min_action_signals: int = 2)

Deterministic verb+keyword intent classifier.

Thread-safe and stateless. Safe to reuse across turns. Callers wire this into the hydration path via FrameworkConfig.intent_filter_mode (see engine.py). Scoring lives in :mod:symfonic._intent_scoring, shared with the capabilities.triage port; this module owns the lexicon and the DomainTemplate input.

Parameters:

Name	Type	Description	Default
ambiguity_confidence_floor	float	Verdicts below this confidence value are labelled ambiguous regardless of which lane won. Default 0.55 — chosen so pure verb-lexicon hits (~0.6) stay decisive while contested turns fall through.	0.55
min_action_signals	int	Minimum number of distinct signals required before action can win outright. Default 2 implements the "2-of-3" rule from risk register item T06 so a single action verb in a question turn does not flip to action.	2

Source code in src/symfonic/agent/triage/intent.py

def __init__(
    self,
    *,
    ambiguity_confidence_floor: float = 0.55,
    min_action_signals: int = 2,
) -> None:
    self._scoring = IntentScoring(
        _LEXICON,
        ambiguity_confidence_floor=ambiguity_confidence_floor,
        min_action_signals=min_action_signals,
    )

classify

classify(query: str, domain: DomainTemplate | None = None) -> IntentVerdict

Classify query into action / knowledge / ambiguous.

Never raises. On empty input returns an ambiguous verdict with confidence 0.0.

Source code in src/symfonic/agent/triage/intent.py

def classify(
    self,
    query: str,
    domain: DomainTemplate | None = None,
) -> IntentVerdict:
    """Classify ``query`` into action / knowledge / ambiguous.

    Never raises. On empty input returns an ``ambiguous`` verdict
    with confidence ``0.0``.
    """
    verdict = IntentVerdict(**self._scoring.score(query, _tool_keywords(domain)).as_fields())
    logger.debug("intent verdict: %s", verdict)
    return verdict

IntentVerdict dataclass

IntentVerdict(label: IntentLabel, confidence: float, matched_tool_keywords: list[str] = list(), reasoning: str = '', action_score: float = 0.0, knowledge_score: float = 0.0)

Classifier verdict for a single turn.

Attributes:

Name	Type	Description
label	IntentLabel	One of action / knowledge / ambiguous.
confidence	float	0.0–1.0 heuristic confidence. Values below 0.55 are coerced to ambiguous regardless of the winning lane so downstream consumers can gate on a single axis.
matched_tool_keywords	list[str]	Tool names whose trigger keywords overlap with the current query (per DomainTemplate).
reasoning	str	Short human-readable note — which signals fired.
action_score	float	Raw action-lane score prior to normalisation.
knowledge_score	float	Raw knowledge-lane score prior to normalisation.

to_event_payload

to_event_payload() -> dict[str, object]

Return a minimal payload suitable for an ExtensionEvent.

Source code in src/symfonic/agent/triage/intent.py

def to_event_payload(self) -> dict[str, object]:
    """Return a minimal payload suitable for an ``ExtensionEvent``."""
    return {
        "label": self.label,
        "confidence": round(self.confidence, 3),
        "matched_tool_keywords": list(self.matched_tool_keywords),
        "reasoning": self.reasoning,
        "action_score": round(self.action_score, 3),
        "knowledge_score": round(self.knowledge_score, 3),
    }

estimate_dropped_tokens

estimate_dropped_tokens(dropped_tools: Sequence[Any]) -> int

Rough token estimate for the tools we chose not to bind.

Used for the tool_routing_decision telemetry event so operators can correlate classifier behaviour with token savings without instrumenting the provider payload themselves. Uses the standard chars // 4 rule of thumb against description + name. Schemas are ignored: the estimate is a floor, not a ceiling.

Source code in src/symfonic/agent/triage/tool_routing.py

def estimate_dropped_tokens(dropped_tools: Sequence[Any]) -> int:
    """Rough token estimate for the tools we chose not to bind.

    Used for the ``tool_routing_decision`` telemetry event so
    operators can correlate classifier behaviour with token savings
    without instrumenting the provider payload themselves. Uses the
    standard ``chars // 4`` rule of thumb against ``description`` +
    ``name``. Schemas are ignored: the estimate is a floor, not a
    ceiling.
    """
    total = 0
    for tool in dropped_tools:
        desc = getattr(tool, "description", "") or ""
        name = tool_name(tool) or ""
        total += (len(desc) + len(name)) // 4
    return total

narrow_tools_for_intent

narrow_tools_for_intent(verdict: IntentVerdict | None, all_tools: Sequence[Any], domain: DomainTemplate | None, *, always_include: Sequence[str] = DEFAULT_ALWAYS_INCLUDE) -> list[Any]

Return the subset of all_tools to bind for the current turn.

Decision matrix:

• verdict is None or the verdict is ambiguous — return all_tools unchanged. Conservative fallback preserves recall whenever the signal is noisy.
• verdict.label == "knowledge" — return only the always_include tools that exist in all_tools. The classifier is confident the turn is a lookup; the LLM should not need action tools.
• verdict.label == "action" — keep any tool whose name appears in verdict.matched_tool_keywords (per the domain's tool_trigger_keywords map). Tools with no keyword list declared in the domain are always kept for back-compat (v6.1.8 semantics: absent entry means "always include"). Always add the always_include tools.

Parameters:

Name	Type	Description	Default
verdict	IntentVerdict | None	Output of IntentClassifier.classify for the current query. None triggers the fallback.	required
all_tools	Sequence[Any]	The full tool manifest registered on the agent. Each element must expose a name attribute (satisfied by langchain_core.tools.BaseTool and by the demo stubs used in tests).	required
domain	DomainTemplate | None	The active DomainTemplate. Used to read tool_trigger_keywords. None collapses to the "no trigger keywords declared" case — every tool is considered for action turns.	required
always_include	Sequence[str]	Tool names that must appear in every narrowed set regardless of verdict. Defaults to ("hydrate_context",).	DEFAULT_ALWAYS_INCLUDE

Returns:

Type	Description
list[Any]	A list of tools preserving the input order. Never raises;
list[Any]	unknown tool names, missing name attributes, and empty
list[Any]	all_tools all return the same conservative fallback.

T3.1.2: the decision matrix itself now lives in :class:~symfonic.capabilities.tools.IntentRoutingStage. This function is the synchronous v7.0.1 entry point and keeps its exact contract — including returning [] for an empty input and the input list (not a stage abstention) for the fallback paths.

Source code in src/symfonic/agent/triage/tool_routing.py

def narrow_tools_for_intent(
    verdict: IntentVerdict | None,
    all_tools: Sequence[Any],
    domain: DomainTemplate | None,
    *,
    always_include: Sequence[str] = DEFAULT_ALWAYS_INCLUDE,
) -> list[Any]:
    """Return the subset of ``all_tools`` to bind for the current turn.

    Decision matrix:

    - ``verdict`` is ``None`` or the verdict is ``ambiguous`` —
      return ``all_tools`` unchanged. Conservative fallback preserves
      recall whenever the signal is noisy.
    - ``verdict.label == "knowledge"`` — return only the
      ``always_include`` tools that exist in ``all_tools``. The
      classifier is confident the turn is a lookup; the LLM should
      not need action tools.
    - ``verdict.label == "action"`` — keep any tool whose name
      appears in ``verdict.matched_tool_keywords`` (per the domain's
      ``tool_trigger_keywords`` map). Tools with no keyword list
      declared in the domain are always kept for back-compat (v6.1.8
      semantics: absent entry means "always include"). Always add
      the ``always_include`` tools.

    Args:
        verdict: Output of ``IntentClassifier.classify`` for the
            current query. ``None`` triggers the fallback.
        all_tools: The full tool manifest registered on the agent.
            Each element must expose a ``name`` attribute (satisfied
            by ``langchain_core.tools.BaseTool`` and by the demo
            stubs used in tests).
        domain: The active ``DomainTemplate``. Used to read
            ``tool_trigger_keywords``. ``None`` collapses to the
            "no trigger keywords declared" case — every tool is
            considered for action turns.
        always_include: Tool names that must appear in every
            narrowed set regardless of verdict. Defaults to
            ``("hydrate_context",)``.

    Returns:
        A list of tools preserving the input order. Never raises;
        unknown tool names, missing ``name`` attributes, and empty
        ``all_tools`` all return the same conservative fallback.

    T3.1.2: the decision matrix itself now lives in
    :class:`~symfonic.capabilities.tools.IntentRoutingStage`. This
    function is the synchronous v7.0.1 entry point and keeps its exact
    contract — including returning ``[]`` for an empty input and the
    *input list* (not a stage abstention) for the fallback paths.
    """
    if not all_tools:
        return []

    stage = IntentRoutingStage(
        verdict=verdict,
        trigger_keywords=(
            dict(getattr(domain, "tool_trigger_keywords", None) or {})
            if domain is not None
            else {}
        ),
        always_include=always_include,
    )
    outcome = stage.decide(all_tools)
    if outcome.abstained:
        return list(all_tools)
    return list(outcome.tools or ())