docs: add missing docstrings

Author: mirkolenz

src/cbrkit/adapt/strings.py

@@ -83,6 +83,7 @@ def __init__(
     @property
     @override
     def metadata(self) -> JsonDict:
+        """Return metadata describing the regex configuration."""
         return self._metadata
 
     @override

src/cbrkit/api.py

@@ -15,6 +15,8 @@
 
 
 class Settings(BaseSettings):
+    """Environment-based configuration for the CBRKit API."""
+
     model_config = SettingsConfigDict(env_prefix="cbrkit_")
     retriever: str = ""
     reuser: str = ""
@@ -28,6 +30,7 @@ class Settings(BaseSettings):
 
 
 def load_callables(value: str) -> dict[str, Any]:
+    """Load callable objects from a comma-separated string of module paths."""
     if value == "":
         return {}
 
@@ -56,6 +59,7 @@ def load_callables(value: str) -> dict[str, Any]:
 
 
 def parse_dataset(obj: CasebaseSpec) -> Mapping[str, Any]:
+    """Parse a casebase specification into a string-keyed mapping."""
     if isinstance(obj, dict):
         return cast(dict[str, Any], obj)
 
@@ -78,6 +82,7 @@ def parse_callables[T](
     keys: list[str] | str | None,
     loaded: dict[str, T],
 ) -> list[T]:
+    """Select loaded callables by name, defaulting to all available."""
     if not keys:
         keys = list(loaded.keys())
     elif isinstance(keys, str):
@@ -87,6 +92,8 @@ def parse_callables[T](
 
 
 class RetrieveRequest(BaseModel):
+    """Request payload for the retrieval endpoint."""
+
     casebase: CasebaseSpec
     queries: CasebaseSpec
     retrievers: Annotated[list[str] | str, Field(default_factory=list)]
@@ -96,6 +103,7 @@ class RetrieveRequest(BaseModel):
 def retrieve(
     request: RetrieveRequest,
 ) -> cbrkit.retrieval.Result[str, str, Any, cbrkit.typing.Float]:
+    """Handle a retrieval request and return ranked results."""
     return cbrkit.retrieval.apply_queries(
         parse_dataset(request.casebase),
         parse_dataset(request.queries),
@@ -104,6 +112,8 @@ def retrieve(
 
 
 class ReuseRequest(BaseModel):
+    """Request payload for the reuse endpoint."""
+
     casebase: CasebaseSpec
     queries: CasebaseSpec
     reusers: Annotated[list[str] | str, Field(default_factory=list)]
@@ -113,6 +123,7 @@ class ReuseRequest(BaseModel):
 def reuse(
     request: ReuseRequest,
 ) -> cbrkit.reuse.Result[str, str, Any, cbrkit.typing.Float]:
+    """Handle a reuse request and return adapted results."""
     return cbrkit.reuse.apply_queries(
         parse_dataset(request.casebase),
         parse_dataset(request.queries),
@@ -121,6 +132,8 @@ def reuse(
 
 
 class CycleRequest(BaseModel):
+    """Request payload for the full CBR cycle endpoint."""
+
     casebase: CasebaseSpec
     queries: CasebaseSpec
     retrievers: Annotated[list[str] | str, Field(default_factory=list)]
@@ -133,6 +146,7 @@ class CycleRequest(BaseModel):
 def cycle(
     request: CycleRequest,
 ) -> cbrkit.cycle.Result[str, str, Any, cbrkit.typing.Float]:
+    """Handle a full CBR cycle request and return the combined result."""
     return cbrkit.cycle.apply_queries(
         parse_dataset(request.casebase),
         parse_dataset(request.queries),
@@ -144,6 +158,8 @@ def cycle(
 
 
 class SynthesizeRequest(BaseModel):
+    """Request payload for the synthesis endpoint."""
+
     casebase: CasebaseSpec
     queries: CasebaseSpec
     synthesizer: str
@@ -157,6 +173,7 @@ class SynthesizeRequest(BaseModel):
 def synthesize(
     request: SynthesizeRequest,
 ) -> cbrkit.synthesis.Result[str, Any]:
+    """Handle a synthesis request by running a CBR cycle and synthesizing the result."""
     cycle_result = cbrkit.cycle.apply_queries(
         parse_dataset(request.casebase),
         parse_dataset(request.queries),
@@ -173,6 +190,7 @@ def synthesize(
 
 
 def openapi_generator():
+    """Generate and cache the OpenAPI schema for the CBRKit API."""
     if not app.openapi_schema:
         app.openapi_schema = get_openapi(
             title="CBRKit",

src/cbrkit/cli.py

@@ -23,6 +23,7 @@
 
 @app.callback()
 def app_callback():
+    """Initialize the CBRKit CLI application."""
     pass
 
 
@@ -36,6 +37,7 @@ def retrieve(
     print_similarities: bool = False,
     output_path: Path | None = None,
 ) -> None:
+    """Retrieve similar cases from a casebase for the given queries."""
     sys.path.extend(str(x) for x in search_path)
     casebase = cbrkit.loaders.path(casebase_path)
     queries = cbrkit.loaders.path(queries_path)
@@ -71,6 +73,7 @@ def reuse(
     search_path: Annotated[list[Path], typer.Option(default_factory=list)],
     output_path: Path | None = None,
 ) -> None:
+    """Reuse retrieved cases by adapting them for the given queries."""
     sys.path.extend(str(x) for x in search_path)
     casebase = cbrkit.loaders.path(casebase_path)
     queries = cbrkit.loaders.path(queries_path)
@@ -95,6 +98,7 @@ def cycle(
     retainer: str | None = None,
     output_path: Path | None = None,
 ) -> None:
+    """Run a full CBR cycle with retrieval, reuse, revision, and retention."""
     sys.path.extend(str(x) for x in search_path)
     casebase = cbrkit.loaders.path(casebase_path)
     queries = cbrkit.loaders.path(queries_path)
@@ -131,6 +135,7 @@ def synthesis(
     retainer: str | None = None,
     output_path: Path | None = None,
 ) -> None:
+    """Run a CBR cycle followed by synthesis to produce a generated response."""
     sys.path.extend(str(x) for x in search_path)
     casebase = cbrkit.loaders.path(casebase_path)
     queries = cbrkit.loaders.path(queries_path)
@@ -174,6 +179,7 @@ def serve(
     reload: bool = False,
     root_path: str = "",
 ) -> None:
+    """Start the CBRKit API server with the specified components."""
     import uvicorn
 
     from cbrkit.api import app
@@ -204,6 +210,7 @@ def uvicorn(
     reload: bool = False,
     root_path: str = "",
 ) -> None:
+    """Start a custom ASGI application using the uvicorn server."""
     import uvicorn
 
     sys.path.extend(str(x) for x in search_path)
@@ -219,6 +226,7 @@ def uvicorn(
 
 @app.command()
 def openapi(file: Path | None = None):
+    """Generate the OpenAPI schema and print or write it to a file."""
     from cbrkit.api import app
 
     schema = orjson.dumps(

src/cbrkit/dumpers.py

@@ -25,6 +25,7 @@
 
 
 def default_conversion_func(obj: Any) -> Any:
+    """Convert an object to a serializable form using Pydantic or duck typing."""
     if isinstance(obj, BaseModel):
         return obj.model_dump(
             exclude_unset=True,

src/cbrkit/eval/common.py

@@ -22,6 +22,7 @@ def compute_score_metric[C, S: Float, T](
     run_scores: Mapping[C, S],
     metric_func: Callable[[list[float], list[float]], T],
 ) -> T:
+    """Compute a score metric over shared keys between qrel and run scores."""
     keys = set(qrel_scores.keys()).intersection(set(run_scores.keys()))
 
     return metric_func(
@@ -36,6 +37,7 @@ def compute_score_metrics[Q, C, S: Float, T](
     metric_funcs: dict[str, Callable[[list[float], list[float]], T]],
     aggregation_func: ConversionFunc[list[T], T] | None = None,
 ) -> dict[str, T | float]:
+    """Compute multiple score metrics across all shared queries."""
     metric_values: dict[str, T | float] = {}
     keys = set(qrel_scores.keys()).intersection(set(run_scores.keys()))
 
@@ -356,6 +358,7 @@ def compute[Q, C, S: Float](
     metrics: Sequence[str] = DEFAULT_METRICS,
     metric_funcs: Mapping[str, EvalMetricFunc] | None = None,
 ) -> dict[str, float]:
+    """Evaluate retrieval results against relevance judgments using the given metrics."""
     import ranx
 
     if metric_funcs is None:
@@ -503,6 +506,7 @@ def similarities_to_qrels[Q, C](
     round_mode: Literal["floor", "ceil", "nearest"] = "nearest",
     auto_scale: bool = True,
 ) -> QueryCaseMatrix[Q, C, int]:
+    """Convert float similarity scores to integer relevance judgments."""
     if max_qrel is None:
         return {
             query: {

src/cbrkit/eval/retrieval.py

@@ -13,6 +13,7 @@ def retrieval_step[Q, C, S: Float](
     metrics: Sequence[str] = DEFAULT_METRICS,
     metric_funcs: dict[str, EvalMetricFunc] | None = None,
 ) -> dict[str, float]:
+    """Evaluate a single retrieval step against relevance judgments."""
     return compute(
         qrels,
         {query: entry.similarities for query, entry in step.queries.items()},
@@ -27,6 +28,7 @@ def retrieval[Q, C, S: Float](
     metrics: Sequence[str] = DEFAULT_METRICS,
     metric_funcs: dict[str, EvalMetricFunc] | None = None,
 ) -> list[dict[str, float]]:
+    """Evaluate all retrieval steps against relevance judgments."""
     return [
         retrieval_step(
             qrels,
@@ -45,6 +47,7 @@ def retrieval_step_to_qrels[Q, C, S: Float](
     round_mode: Literal["floor", "ceil", "nearest"] = "nearest",
     auto_scale: bool = True,
 ) -> QueryCaseMatrix[Q, C, int]:
+    """Convert a retrieval step's similarities to integer relevance judgments."""
     unpacked_sims = {
         query: {case: unpack_float(value) for case, value in entry.similarities.items()}
         for query, entry in result.queries.items()
@@ -65,6 +68,7 @@ def retrieval_to_qrels[Q, C, S: Float](
     round_mode: Literal["floor", "ceil", "nearest"] = "nearest",
     auto_scale: bool = True,
 ) -> list[QueryCaseMatrix[Q, C, int]]:
+    """Convert all retrieval steps' similarities to integer relevance judgments."""
     return [
         retrieval_step_to_qrels(
             step,