qfa.services.coding_classifier#

Helpers for one-shot hierarchical coding prompts and per-level judge prompts.

Functions

`build_coding_messages`(*, feedback_record, ...)	Build the system and user messages for the one-shot hierarchical pick.
`build_judge_messages`(*, feedback_record, ...)	Build system and user messages for a single-level judge call.
`flatten_coding_nodes`(nodes[, _prefix])	Flatten a coding tree into one option per node, at every depth.
`format_code_path`(path)	Render a `(id, name)` path as `"Service Delivery > Staff Behavior"`.

Classes

`CodePathOption`(path)	One selectable option: a path from a root code down to some node.
`CodingResponse`(*, selected)	Structured output for one-shot hierarchical code selection.
`JudgeResponse`(*, score, explanation)	Structured output returned by the LLM judge for one hierarchy level.

qfa.services.coding_classifier.format_code_path(path: Sequence[tuple[str, str]]) → str[source]#: Render a (id, name) path as "Service Delivery > Staff Behavior".

class qfa.services.coding_classifier.CodePathOption(path: tuple[tuple[str, str], ...])[source]#

Bases: object

One selectable option: a path from a root code down to some node.

path holds (id, name) per level, root first. A path may stop at any depth — every node in the framework (not just leaves) is its own option, so a level-1-only or level-1+2 code can be selected directly when nothing more specific fits.

path: tuple[tuple[str, str], ...]#

property label: str#: Human-readable path, e.g. "Service Delivery > Staff Behavior".

qfa.services.coding_classifier.flatten_coding_nodes(nodes: list[CodingNode], _prefix: tuple[tuple[str, str], ...] = ()) → list[CodePathOption][source]#

Flatten a coding tree into one option per node, at every depth.

Pre-order: a parent immediately precedes its own children, so related paths stay grouped together for the model.

class qfa.services.coding_classifier.CodingResponse(*, selected: list[int] = <factory>)[source]#

Bases: BaseModel

Structured output for one-shot hierarchical code selection.

Confidence and explanation are deliberately absent: the pick step only chooses which paths are in play. A separate per-level judge call (see build_judge_messages()) — unchanged from the previous per-level pick/judge design — scores and explains each one afterwards.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

selected: list[int]#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

qfa.services.coding_classifier.build_coding_messages(*, feedback_record: FeedbackRecordModel, options: list[CodePathOption]) → tuple[str, str][source]#: Build the system and user messages for the one-shot hierarchical pick.

class qfa.services.coding_classifier.JudgeResponse(*, score: float, explanation: str)[source]#

Bases: BaseModel

Structured output returned by the LLM judge for one hierarchy level.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

score: float#

explanation: str#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

qfa.services.coding_classifier.build_judge_messages(*, feedback_record: FeedbackRecordModel, level: str, path: list[tuple[str, str]]) → tuple[str, str][source]#

Build system and user messages for a single-level judge call.

Parameters:

feedback_record – The feedback record being coded.
level – The hierarchy level being evaluated: "Code level 1", "Code level 2", or "Code level 3".
path – Full code path up to and including the current level, as [(level_name, label), ...]. E.g. for the Code level 2 judge: [("Code level 1", "Service Delivery"), ("Code level 2", "Staff Behavior")].