Configuration Reference¶

class PipelineConfig(BaseModel):
    """
    Top-level pipeline configuration. Each phase receives only its sub-config.

    Serialize to JSON/YAML for reproducible research runs:
        config.model_dump_json(indent=2)
    """

    models: ModelConfig = Field(default_factory=ModelConfig)

    graph_schema: SchemaConfig = Field(default_factory=lambda: DEFAULT_SCHEMA.model_copy())
    phase1: Phase1Config = Field(default_factory=Phase1Config)
    phase2: Phase2Config = Field(default_factory=Phase2Config)
    phase3: Phase3Config = Field(default_factory=Phase3Config)
    phase3b: Phase3bConfig = Field(default_factory=Phase3bConfig)
    phase4_maturation: Phase4EntityMaturationConfig = Field(default_factory=Phase4EntityMaturationConfig)
    phase4: Phase4Config = Field(default_factory=Phase4Config)
    phase5: Phase5Config = Field(default_factory=Phase5Config)
    phase6: Phase6Config = Field(default_factory=Phase6Config)
    theoretical_enrichment: TheoreticalEnrichmentConfig = Field(default_factory=TheoreticalEnrichmentConfig)
    execution: ExecutionConfig = Field(default_factory=ExecutionConfig)

    @classmethod
    def from_env(cls, **overrides: Any) -> "PipelineConfig":
        """Build a config whose model selection is resolved from the environment.

        This is the one supported way to turn ambient environment state into a
        config. Call it once at the edge (CLI, example script, Studio) and pass
        the result down; do not read ``os.environ`` inside phases.
        """
        return cls(models=ModelConfig.from_env(), **overrides)

    @property
    def default_embedding_model(self) -> str:
        """Deprecated alias for ``config.models.embedding_model``."""
        return self.models.embedding_model

    @property
    def default_reranker_model(self) -> str:
        """Deprecated alias for ``config.models.reranker_model``."""
        return self.models.reranker_model

class ExecutionConfig(BaseModel):
    persist_run_manifests: bool = True
    persist_phase1_artifacts: bool = True
    persist_phase2_artifacts: bool = True
    persist_phase3_artifacts: bool = True
    persist_phase3b_artifacts: bool = True
    persist_phase4_maturation_artifacts: bool = True
    persist_phase4_artifacts: bool = True
    persist_phase5_artifacts: bool = True
    persist_phase6_artifacts: bool = True
    persist_theoretical_enrichment_artifacts: bool = True
    project_artifacts_to_graph: bool = False
    allow_phase_reuse: bool = Field(
        default=True,
        description=(
            "Permit phase-level reuse across runs when every fingerprint "
            "(schema, method, prompt, config, source) matches the parent run. "
            "Set False to force every phase to re-execute."
        ),
    )
    allow_artifact_hydration: bool = Field(
        default=True,
        description=(
            "Prefer reusing persisted artifacts over re-executing upstream phases. "
            "When True, the pipeline hydrates the prior phase's ArtifactCollection "
            "from the last successful run (artifact-native resume) and feeds it into "
            "the next phase instead of recomputing it. "
            "Requires persist_run_manifests=True and an artifacts_dir holding "
            "artifacts from a prior run over the same input. "
            "Trade-off: skips expensive LLM-heavy upstream work, but relies entirely "
            "on fingerprint invalidation for correctness — if a method or schema "
            "changed without changing its fingerprint, hydrated artifacts are stale."
        ),
    )
    runs_dir: str = ".pipeline_runs"
    artifacts_dir: str = ".pipeline_artifacts"

class Phase1Config(BaseModel):
    chunk_size: int = 1024
    chunk_overlap: int = 128
    provenance_enabled: bool = True

class Phase2Config(BaseModel):
    top_k_linking_candidates: int = 10
    linking_confidence_threshold: float = 0.85
    ner_confidence_threshold: float = 0.0
    local_relation_confidence_threshold: float = 0.0
    batch_size: int = 10
    ner_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=NER_DIRECT_PROMPT,
        reasoning_template=NER_REASONING_PROMPT,
        format_template=NER_FORMAT_PROMPT,
        gleaning_template=NER_GLEANING_PROMPT,
        name="ner_extraction",
    ))
    ner_decoding_strategy: StructuredDecodingStrategy = StructuredDecodingStrategy.NL_TO_FORMAT
    entity_linking_prompt_template: str = ENTITY_LINKING_PROMPT
    entity_linking_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=ENTITY_LINKING_PROMPT,
        name="entity_linking",
    ))
    max_gleanings: int = 0

class Phase3Config(BaseModel):
    batch_size: int = 50
    global_relation_confidence_threshold: float = 0.7
    max_candidates_per_entity_pair: int = 200
    subgraph_depth: int = 2
    global_relation_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=GLOBAL_RELATION_DIRECT_PROMPT,
        reasoning_template=GLOBAL_RELATION_REASONING_PROMPT,
        format_template=GLOBAL_RELATION_FORMAT_PROMPT,
        name="global_relation",
    ))
    global_relation_decoding_strategy: StructuredDecodingStrategy = StructuredDecodingStrategy.NL_TO_FORMAT
    dense_similarity_threshold: float = 0.5
    reranker_threshold: float = 0.6
    trace_dense_retrieval: bool = True

class Phase3bConfig(BaseModel):
    """Configuration for Phase 3b: Latent Graph Consolidation.

    Attributes
    ----------
    dense_similarity_threshold : float, default 0.85
        The minimum cosine similarity between L2 entity embeddings to consider
        them candidates for consolidation.
    relation_overlap_threshold : float, default 0.8
        The minimum Jaccard similarity of Phase 3 relation edges required to
        commit a SAME_AS edge between candidates. A conservative default
        ensures distinct but related entities are not incorrectly merged.
    """
    enabled: bool = True
    dense_similarity_threshold: float = 0.85
    relation_overlap_threshold: float = 0.8

class Phase4EntityMaturationConfig(BaseModel):
    """Configuration for Phase 4: Entity Maturation (epistemic synthesis).

    Attributes
    ----------
    maturation_top_k : int, default 5
        The number of representative textual envelopes to retrieve closest to the
        geometric centroid for LLM synthesis.
    batch_size : int, default 10
        The number of entities to synthesize concurrently via the LLM API.
    entity_synthesis_prompts : StructuredPromptBundle
        The prompt bundle used when calling the LLM to synthesize a mature
        entity description.
    entity_synthesis_decoding_strategy : StructuredDecodingStrategy
        Which decoding strategy the synthesis call routes through.
    """
    maturation_top_k: int = 5
    batch_size: int = 10
    entity_synthesis_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=ENTITY_SYNTHESIS_PROMPT,
        name="entity_synthesis",
    ))
    entity_synthesis_decoding_strategy: StructuredDecodingStrategy = StructuredDecodingStrategy.DIRECT

class Phase4Config(BaseModel):
    adu_segmentation_prompt_template: str = ADU_SEGMENTATION_PROMPT
    adu_segmentation_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=ADU_SEGMENTATION_PROMPT,
        name="adu_segmentation",
    ))
    adu_confidence_threshold: float = 0.0
    acc_confidence_threshold: float = 0.0
    batch_size: int = 10
    acc_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=ACC_DIRECT_PROMPT,
        reasoning_template=ACC_REASONING_PROMPT,
        format_template=ACC_FORMAT_PROMPT,
        name="acc_classification",
    ))
    acc_decoding_strategy: StructuredDecodingStrategy = StructuredDecodingStrategy.NL_TO_FORMAT
    arc_prompts: StructuredPromptBundle = Field(default_factory=lambda: StructuredPromptBundle(
        direct_template=ARC_DIRECT_PROMPT,
        reasoning_template=ARC_REASONING_PROMPT,
        format_template=ARC_FORMAT_PROMPT,
        name="arc_classification",
    ))
    arc_decoding_strategy: StructuredDecodingStrategy = StructuredDecodingStrategy.NL_TO_FORMAT
    arc_confidence_threshold: float = 0.65
    arc_subgraph_depth: int = 2
    arc_max_candidates_per_component: int = 10
    arc_use_priority_rank: bool = False
    adu_markup_open: str = "<AC"
    adu_markup_close: str = ">"

class Phase5Config(BaseModel):
    argument_clustering_enabled: bool = True
    theory_fusion_enabled: bool = False
    fusion_similarity_threshold: float = 0.85
    cluster_layer: Literal["theory_atoms", "l2_entities", "both"] = "theory_atoms"

class SchemaConfig(BaseModel):
    """
    Decoupled schema configuration — all node/edge types the pipeline uses.

    Pass a custom instance to PipelineConfig to override the defaults for a
    different domain. Prompt templates receive these lists as {entity_types}
    and {relation_types} at runtime.
    """

    version: str = "v1"
    node_types: list[str] = Field(default_factory=lambda: list(L2_NODE_TYPES))
    relation_types: list[str] = Field(default_factory=lambda: list(L2_RELATION_TYPES))
    node_definitions: dict[str, str] = Field(default_factory=lambda: dict(L2_NODE_DEFINITIONS))
    relation_definitions: dict[str, str] = Field(default_factory=lambda: dict(L2_RELATION_DEFINITIONS))
    component_types: list[str] = Field(default_factory=lambda: list(L3_COMPONENT_TYPES))
    argument_relation_types: list[str] = Field(default_factory=lambda: list(L3_RELATION_TYPES))
    component_definitions: dict[str, str] = Field(default_factory=lambda: dict(L3_COMPONENT_DEFINITIONS))
    argument_relation_definitions: dict[str, str] = Field(default_factory=lambda: dict(L3_RELATION_DEFINITIONS))
    relation_polarities: dict[str, int] = Field(default_factory=lambda: dict(RELATION_POLARITIES))
    component_partitions: dict[str, str] = Field(default_factory=lambda: dict(COMPONENT_PARTITIONS))

    def node_types_str(self) -> str:
        return ", ".join(self.node_types)

    def relation_types_str(self) -> str:
        return ", ".join(self.relation_types)

    def component_types_str(self) -> str:
        import json
        payload = {k: self.component_definitions.get(k, "No description provided.") for k in self.component_types}
        return json.dumps(payload, indent=2, ensure_ascii=False)

    def argument_relation_types_str(self) -> str:
        import json
        payload = {k: self.argument_relation_definitions.get(k, "No description provided.") for k in self.argument_relation_types}
        return json.dumps(payload, indent=2, ensure_ascii=False)