llm-connect/contracts/functional/problem-classes.md

Problem Classes

llm_connect.problem_classes provides generic token estimators for recurring LLM workflow shapes.

Contract

Every problem class exposes:

• name: stable registry key.
• base_dimensions: required dimension names supplied by consumers.
• tunable_params: parameters that can be overridden or fitted.
• estimate(dimensions, params=None) -> TokenEstimate.
• fit(observations, min_observations=3) -> ProblemClass.

TokenEstimate contains prompt_tokens, completion_tokens, and a confidence score from 0 to 1.

Built-Ins

Name	Dimensions	Tunable params
chunk-summarization	chunk_words, template_words	completion_ratio
entity-extraction	chunk_words, template_words, expected_entities	tokens_per_entity
relation-extraction	chunk_words, template_words, expected_relations	tokens_per_relation
judge-eval	artifact_words, template_words, n_criteria	tokens_per_criterion
report-synthesis	n_chunks, n_entities, n_relations, template_words	base_completion_tokens

Observations

fit() accepts either Observation objects or QualityObservation rows whose tags include:

{
    "problem_class": "entity-extraction",
    "dimensions": {
        "chunk_words": 900,
        "template_words": 200,
        "expected_entities": 4,
    },
}

When fewer than min_observations usable rows are present, fitting falls back to the current parameters.