Implement-LLM-WP-0005-cost-model-estimators

contracts/functional/problem-classes.md

@@ -0,0 +1,46 @@
+# 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:
+
+```python
+{
+    "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.