keble-idea 0.3.0__py3-none-any.whl

keble_idea/__init__.py

@@ -0,0 +1,66 @@
+"""Public provider-neutral contracts for Keble Idea."""
+
+from .application.services import (
+    ConceptAliasService,
+    ExtractionService,
+    IdeaSearchService,
+)
+from .domain.content import ContentCreate, ContentMongoObject
+from .domain.idea import IdeaCreate, IdeaMongoObject
+from .domain.job import (
+    ActiveProviderRecoveryProfilePointer,
+    EnvelopeManualRetryCommand,
+    EnvelopeProcessResult,
+    IdeaJobStatus,
+    IdeaJobType,
+    JobFailureSnapshot,
+    JobRecoveryDecision,
+    JobRecoveryDecisionReason,
+    ProviderPaymentEvidenceSource,
+    ProviderRecoveryProfileActivationCommand,
+    ProviderRecoveryProfileCreate,
+    ProviderRecoveryProfileMongoObject,
+    ProviderRecoveryProfileSnapshot,
+    QueuedEnvelopeCreate,
+    QueuedEnvelopeMongoObject,
+    UpstreamFailureEvidence,
+    UpstreamFailureEvidenceSource,
+    default_provider_recovery_profile_snapshot,
+    recovery_decision_for_failure,
+    recovery_profile_for_manual_retry,
+    retry_at_for_failure,
+)
+from .domain.search import IdeaSearchRequest, IdeaSearchResponse
+
+__all__ = [
+    "ActiveProviderRecoveryProfilePointer",
+    "ConceptAliasService",
+    "ContentCreate",
+    "ContentMongoObject",
+    "ExtractionService",
+    "EnvelopeManualRetryCommand",
+    "EnvelopeProcessResult",
+    "IdeaCreate",
+    "IdeaMongoObject",
+    "IdeaJobStatus",
+    "IdeaJobType",
+    "IdeaSearchRequest",
+    "IdeaSearchResponse",
+    "IdeaSearchService",
+    "JobFailureSnapshot",
+    "JobRecoveryDecision",
+    "JobRecoveryDecisionReason",
+    "ProviderPaymentEvidenceSource",
+    "ProviderRecoveryProfileActivationCommand",
+    "ProviderRecoveryProfileCreate",
+    "ProviderRecoveryProfileMongoObject",
+    "ProviderRecoveryProfileSnapshot",
+    "QueuedEnvelopeCreate",
+    "QueuedEnvelopeMongoObject",
+    "UpstreamFailureEvidence",
+    "UpstreamFailureEvidenceSource",
+    "default_provider_recovery_profile_snapshot",
+    "recovery_decision_for_failure",
+    "recovery_profile_for_manual_retry",
+    "retry_at_for_failure",
+]

keble_idea/application/__init__.py

@@ -0,0 +1 @@
+"""Provider-neutral use cases and caller-owned protocols."""

keble_idea/application/lifecycle.py

@@ -0,0 +1,251 @@
+"""Canonical generation cutover and relationship lifecycle use cases."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import Field
+
+from keble_idea.application.ports import (
+    ConceptPostingCompactorProtocol,
+    GenerationRegistryProtocol,
+    RelationshipInferenceProtocol,
+    RelationshipRepositoryProtocol,
+)
+from keble_idea.domain.base import IdeaSchema
+from keble_idea.domain.concept import NeighborSummary
+from keble_idea.domain.errors import IdeaDomainError, IdeaErrorCode, ObjectNotFoundError
+from keble_idea.domain.generation import (
+    ActiveGenerationPointer,
+    GenerationCutoverCommand,
+    GenerationLifecycle,
+    GenerationRollbackCommand,
+)
+from keble_idea.domain.idea import IdeaConfidenceBand
+from keble_idea.domain.job import EnvelopeExecutionIdentity
+from keble_idea.domain.relationship import (
+    ConceptRelationshipCreate,
+    RelationshipCandidate,
+    RelationshipCoverage,
+)
+from keble_idea.processors.identity import build_record_key
+
+
+class RelationshipRunContext(IdeaSchema):
+    """Immutable policy and model identity for one bounded inference batch."""
+
+    relationship_generation: str = Field(min_length=1, max_length=128)
+    embedding_generation: str = Field(min_length=1, max_length=128)
+    neighborhood_generation: str = Field(min_length=1, max_length=128)
+    model_id: str = Field(min_length=1, max_length=256)
+    prompt_hash: str = Field(pattern=r"^[0-9a-f]{64}$")
+    policy_version: str = Field(min_length=1, max_length=128)
+    acceptance_threshold: float = Field(default=0.8, ge=0.65, le=1)
+    retirement_absence_sweeps: int = Field(default=2, ge=2, le=10)
+    execution: EnvelopeExecutionIdentity
+    processed_at: datetime
+
+
+class RelationshipInferenceService:
+    """Infer exact candidate pairs and persist accepted edges plus coverage.
+
+    Steps:
+    1. enforce unique deterministic concept pairs;
+    2. accept null/no-relation outputs as successful evaluations;
+    3. persist only outputs above the configured precision threshold;
+    4. stamp exact evaluated-neighbor coverage after every pair completes.
+
+    Side effects if changes:
+    - relationship workers and evals share this acceptance behavior;
+    - Mongo is canonical and Neo4j reconciliation consumes accepted edges.
+    """
+
+    def __init__(
+        self,
+        *,
+        inference: RelationshipInferenceProtocol,
+        relationships: RelationshipRepositoryProtocol,
+    ) -> None:
+        self._inference = inference
+        self._relationships = relationships
+
+    async def ainfer(
+        self,
+        *,
+        concept_key: str,
+        candidates: list[RelationshipCandidate],
+        context: RelationshipRunContext,
+    ) -> RelationshipCoverage:
+        """Evaluate each unique pair and persist deterministic accepted relations."""
+
+        pair_keys = [(row.left_concept_key, row.right_concept_key) for row in candidates]
+        if len(pair_keys) != len(set(pair_keys)):
+            raise ValueError("relationship candidates must contain unique concept pairs")
+        evaluated_neighbors: dict[str, NeighborSummary] = {}
+        for candidate in candidates:
+            if concept_key not in {candidate.left_concept_key, candidate.right_concept_key}:
+                raise ValueError("coverage concept_key must participate in every candidate")
+            if (
+                candidate.embedding_generation != context.embedding_generation
+                or candidate.neighborhood_generation != context.neighborhood_generation
+            ):
+                raise ValueError("candidate generations must match the relationship run context")
+            output = await self._inference.ainfer(
+                candidate=candidate,
+                execution=context.execution,
+            )
+            if (
+                output.left_concept_key != candidate.left_concept_key
+                or output.right_concept_key != candidate.right_concept_key
+            ):
+                raise ValueError("relationship inference returned an unknown concept pair")
+            neighbor_key = (
+                candidate.right_concept_key
+                if candidate.left_concept_key == concept_key
+                else candidate.left_concept_key
+            )
+            evaluated_neighbors[neighbor_key] = NeighborSummary(
+                concept_key=neighbor_key,
+                similarity=candidate.similarity,
+            )
+            if output.relation_type is None or output.confidence is None:
+                continue
+            if output.confidence < context.acceptance_threshold:
+                continue
+            relationship_key = build_record_key(
+                prefix="relationship",
+                identity={
+                    "left_concept_key": output.left_concept_key,
+                    "right_concept_key": output.right_concept_key,
+                    "relation_type": output.relation_type.value,
+                    "relationship_generation": context.relationship_generation,
+                },
+            )
+            confidence_band = (
+                IdeaConfidenceBand.HIGH
+                if output.confidence >= 0.9
+                else IdeaConfidenceBand.MEDIUM
+            )
+            relationship = ConceptRelationshipCreate(
+                record_key=relationship_key,
+                pipeline_generation=context.relationship_generation,
+                relationship_key=relationship_key,
+                left_concept_key=output.left_concept_key,
+                right_concept_key=output.right_concept_key,
+                relation_type=output.relation_type,
+                confidence_score=output.confidence,
+                confidence_band=confidence_band,
+                inference_basis=candidate.inference_basis,
+                evidence_refs=output.evidence_refs,
+                embedding_generation=candidate.embedding_generation,
+                neighborhood_generation=candidate.neighborhood_generation,
+                relationship_generation=context.relationship_generation,
+                model_id=context.model_id,
+                prompt_hash=context.prompt_hash,
+                policy_version=context.policy_version,
+                first_observed_at=context.processed_at,
+                last_observed_at=context.processed_at,
+            )
+            await self._relationships.aupsert(relationship=relationship)
+        coverage = RelationshipCoverage(
+            concept_key=concept_key,
+            embedding_generation=context.embedding_generation,
+            neighborhood_generation=context.neighborhood_generation,
+            relationship_generation=context.relationship_generation,
+            evaluated_neighbors=list(evaluated_neighbors.values()),
+            retirement_absence_sweeps=context.retirement_absence_sweeps,
+            covered_at=context.processed_at,
+        )
+        await self._relationships.aset_coverage(coverage=coverage)
+        return coverage
+
+
+class GenerationLifecycleService:
+    """Register, verify, atomically cut over, and rollback immutable generations.
+
+    Side effects if changes:
+    - active search/runtime pointers change only through this service;
+    - Qdrant alias switching and projection verification occur in outer adapters;
+    - retention preserves the pointer's active and previous generations.
+    """
+
+    def __init__(self, *, registry: GenerationRegistryProtocol) -> None:
+        self._registry = registry
+
+    async def acutover(self, *, command: GenerationCutoverCommand) -> ActiveGenerationPointer:
+        """Switch one component only after its immutable generation is verified."""
+
+        generation = await self._registry.aget_generation(
+            generation_key=command.generation_key
+        )
+        if generation is None:
+            raise ObjectNotFoundError(
+                object_name="Generation",
+                object_key=command.generation_key,
+            )
+        if generation.component is not command.component:
+            raise ValueError("generation component does not match cutover component")
+        if generation.lifecycle not in {GenerationLifecycle.VERIFIED, GenerationLifecycle.ACTIVE}:
+            raise IdeaDomainError(
+                code=IdeaErrorCode.GENERATION_NOT_VERIFIED,
+                message=f"generation is not verified: {command.generation_key}",
+            )
+        return await self._registry.acompare_and_switch(command=command)
+
+    async def arollback(
+        self,
+        *,
+        command: GenerationRollbackCommand,
+    ) -> ActiveGenerationPointer:
+        """Restore the immediately previous verified generation atomically."""
+
+        pointer = await self._registry.aget_pointer(component=command.component)
+        if pointer is None or pointer.previous_generation_key is None:
+            raise IdeaDomainError(
+                code=IdeaErrorCode.GENERATION_NOT_VERIFIED,
+                message=f"no rollback generation for {command.component.value}",
+            )
+        previous = await self._registry.aget_generation(
+            generation_key=pointer.previous_generation_key
+        )
+        if previous is None or previous.verified_at is None:
+            raise IdeaDomainError(
+                code=IdeaErrorCode.GENERATION_NOT_VERIFIED,
+                message=f"rollback generation is not verified: {pointer.previous_generation_key}",
+            )
+        return await self._registry.acompare_and_rollback(command=command)
+
+
+class PostingCompactionService:
+    """Rewrite a bounded alias posting page without blocking merge/unmerge."""
+
+    def __init__(self, *, compactor: ConceptPostingCompactorProtocol) -> None:
+        self._compactor = compactor
+
+    async def acompact(
+        self,
+        *,
+        source_concept_key: str,
+        canonical_concept_key: str,
+        after_posting_key: str | None,
+        limit: int = 250,
+    ) -> str | None:
+        """Compact one indexed page and return the next resumable cursor."""
+
+        if source_concept_key == canonical_concept_key:
+            raise ValueError("compaction source and canonical concepts must differ")
+        if limit < 1 or limit > 1_000:
+            raise ValueError("compaction limit must be between 1 and 1000")
+        return await self._compactor.acompact_page(
+            source_concept_key=source_concept_key,
+            canonical_concept_key=canonical_concept_key,
+            after_posting_key=after_posting_key,
+            limit=limit,
+        )
+
+    async def aclear(self, *, source_concept_key: str) -> int:
+        """Remove only derived alias rows after unmerge; preserve original postings."""
+
+        return await self._compactor.aclear_compacted(
+            source_concept_key=source_concept_key
+        )