biblicus 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

biblicus/analysis/topic_modeling.py

@@ -15,16 +15,17 @@ from pydantic import BaseModel
 
 from ..ai.llm import generate_completion
 from ..corpus import Corpus
-from ..models import ExtractionRunReference
+from ..models import ExtractionSnapshotReference
 from ..retrieval import hash_text
 from ..time import utc_now_iso
 from .base import CorpusAnalysisBackend
 from .models import (
-    AnalysisRecipeManifest,
+    AnalysisConfigurationManifest,
     AnalysisRunInput,
     AnalysisRunManifest,
     TopicModelingBerTopicConfig,
     TopicModelingBerTopicReport,
+    TopicModelingConfiguration,
     TopicModelingKeyword,
     TopicModelingLabelSource,
     TopicModelingLexicalProcessingConfig,
@@ -35,7 +36,6 @@ from .models import (
     TopicModelingLlmFineTuningConfig,
     TopicModelingLlmFineTuningReport,
     TopicModelingOutput,
-    TopicModelingRecipeConfig,
     TopicModelingReport,
     TopicModelingStageStatus,
     TopicModelingTextCollectionReport,
@@ -76,69 +76,74 @@ class TopicModelingBackend(CorpusAnalysisBackend):
         self,
         corpus: Corpus,
         *,
-        recipe_name: str,
-        config: Dict[str, object],
-        extraction_run: ExtractionRunReference,
+        configuration_name: str,
+        configuration: Dict[str, object],
+        extraction_snapshot: ExtractionSnapshotReference,
     ) -> BaseModel:
         """
         Run the topic modeling analysis pipeline.
 
         :param corpus: Corpus to analyze.
         :type corpus: Corpus
-        :param recipe_name: Human-readable recipe name.
-        :type recipe_name: str
-        :param config: Analysis configuration values.
-        :type config: dict[str, object]
-        :param extraction_run: Extraction run reference for text inputs.
-        :type extraction_run: biblicus.models.ExtractionRunReference
+        :param configuration_name: Human-readable configuration name.
+        :type configuration_name: str
+        :param configuration: Analysis configuration values.
+        :type configuration: dict[str, object]
+        :param extraction_snapshot: Extraction snapshot reference for text inputs.
+        :type extraction_snapshot: biblicus.models.ExtractionSnapshotReference
         :return: Topic modeling output model.
         :rtype: pydantic.BaseModel
         """
         parsed_config = (
-            config
-            if isinstance(config, TopicModelingRecipeConfig)
-            else TopicModelingRecipeConfig.model_validate(config)
+            configuration
+            if isinstance(configuration, TopicModelingConfiguration)
+            else TopicModelingConfiguration.model_validate(configuration)
         )
         return _run_topic_modeling(
             corpus=corpus,
-            recipe_name=recipe_name,
+            configuration_name=configuration_name,
             config=parsed_config,
-            extraction_run=extraction_run,
+            extraction_snapshot=extraction_snapshot,
         )
 
 
 def _run_topic_modeling(
     *,
     corpus: Corpus,
-    recipe_name: str,
-    config: TopicModelingRecipeConfig,
-    extraction_run: ExtractionRunReference,
+    configuration_name: str,
+    config: TopicModelingConfiguration,
+    extraction_snapshot: ExtractionSnapshotReference,
 ) -> TopicModelingOutput:
-    recipe = _create_recipe_manifest(name=recipe_name, config=config)
+    configuration_manifest = _create_configuration_manifest(
+        name=configuration_name,
+        config=config,
+    )
     catalog = corpus.load_catalog()
-    run_id = _analysis_run_id(
-        recipe_id=recipe.recipe_id,
-        extraction_run=extraction_run,
+    snapshot_id = _analysis_snapshot_id(
+        configuration_id=configuration_manifest.configuration_id,
+        extraction_snapshot=extraction_snapshot,
         catalog_generated_at=catalog.generated_at,
     )
     run_manifest = AnalysisRunManifest(
-        run_id=run_id,
-        recipe=recipe,
+        snapshot_id=snapshot_id,
+        configuration=configuration_manifest,
         corpus_uri=catalog.corpus_uri,
         catalog_generated_at=catalog.generated_at,
         created_at=utc_now_iso(),
-        input=AnalysisRunInput(extraction_run=extraction_run),
+        input=AnalysisRunInput(extraction_snapshot=extraction_snapshot),
         artifact_paths=[],
         stats={},
     )
-    run_dir = corpus.analysis_run_dir(analysis_id=TopicModelingBackend.analysis_id, run_id=run_id)
+    run_dir = corpus.analysis_run_dir(
+        analysis_id=TopicModelingBackend.analysis_id, snapshot_id=snapshot_id
+    )
     output_path = run_dir / "output.json"
 
     run_dir.mkdir(parents=True, exist_ok=True)
 
     documents, text_report = _collect_documents(
         corpus=corpus,
-        extraction_run=extraction_run,
+        extraction_snapshot=extraction_snapshot,
         config=config.text_source,
     )
 
@@ -194,7 +199,7 @@ def _run_topic_modeling(
     output = TopicModelingOutput(
         analysis_id=TopicModelingBackend.analysis_id,
         generated_at=utc_now_iso(),
-        run=run_manifest,
+        snapshot=run_manifest,
         report=report,
     )
     _write_topic_modeling_output(path=output_path, output=output)
@@ -204,15 +209,15 @@ def _run_topic_modeling(
 def run_topic_modeling_for_documents(
     *,
     documents: List[TopicModelingDocument],
-    config: TopicModelingRecipeConfig,
+    config: TopicModelingConfiguration,
 ) -> TopicModelingReport:
     """
     Run topic modeling using caller-provided documents.
 
     :param documents: Pre-collected documents to model.
     :type documents: list[TopicModelingDocument]
-    :param config: Topic modeling recipe configuration.
-    :type config: TopicModelingRecipeConfig
+    :param config: Topic modeling configuration.
+    :type config: TopicModelingConfiguration
     :return: Topic modeling report with topic assignments.
     :rtype: TopicModelingReport
     """
@@ -269,10 +274,10 @@ def run_topic_modeling_for_documents(
     )
 
 
-def _create_recipe_manifest(
-    *, name: str, config: TopicModelingRecipeConfig
-) -> AnalysisRecipeManifest:
-    recipe_payload = json.dumps(
+def _create_configuration_manifest(
+    *, name: str, config: TopicModelingConfiguration
+) -> AnalysisConfigurationManifest:
+    configuration_payload = json.dumps(
         {
             "analysis_id": TopicModelingBackend.analysis_id,
             "name": name,
@@ -280,9 +285,9 @@ def _create_recipe_manifest(
         },
         sort_keys=True,
     )
-    recipe_id = hash_text(recipe_payload)
-    return AnalysisRecipeManifest(
-        recipe_id=recipe_id,
+    configuration_id = hash_text(configuration_payload)
+    return AnalysisConfigurationManifest(
+        configuration_id=configuration_id,
         analysis_id=TopicModelingBackend.analysis_id,
         name=name,
         created_at=utc_now_iso(),
@@ -290,25 +295,25 @@ def _create_recipe_manifest(
     )
 
 
-def _analysis_run_id(
+def _analysis_snapshot_id(
     *,
-    recipe_id: str,
-    extraction_run: ExtractionRunReference,
+    configuration_id: str,
+    extraction_snapshot: ExtractionSnapshotReference,
     catalog_generated_at: str,
 ) -> str:
-    run_seed = f"{recipe_id}:{extraction_run.as_string()}:{catalog_generated_at}"
+    run_seed = f"{configuration_id}:{extraction_snapshot.as_string()}:{catalog_generated_at}"
     return hash_text(run_seed)
 
 
 def _collect_documents(
     *,
     corpus: Corpus,
-    extraction_run: ExtractionRunReference,
+    extraction_snapshot: ExtractionSnapshotReference,
     config: TopicModelingTextSourceConfig,
 ) -> Tuple[List[TopicModelingDocument], TopicModelingTextCollectionReport]:
-    manifest = corpus.load_extraction_run_manifest(
-        extractor_id=extraction_run.extractor_id,
-        run_id=extraction_run.run_id,
+    manifest = corpus.load_extraction_snapshot_manifest(
+        extractor_id=extraction_snapshot.extractor_id,
+        snapshot_id=extraction_snapshot.snapshot_id,
     )
     warnings: List[str] = []
     errors: List[str] = []
@@ -321,9 +326,9 @@ def _collect_documents(
             skipped_items += 1
             continue
         text_path = (
-            corpus.extraction_run_dir(
-                extractor_id=extraction_run.extractor_id,
-                run_id=extraction_run.run_id,
+            corpus.extraction_snapshot_dir(
+                extractor_id=extraction_snapshot.extractor_id,
+                snapshot_id=extraction_snapshot.snapshot_id,
             )
             / item_result.final_text_relpath
         )