local-deep-research 0.4.4__py3-none-any.whl → 0.5.2__py3-none-any.whl

local_deep_research/advanced_search_system/constraint_checking/strict_checker.py

@@ -0,0 +1,259 @@
+"""
+Strict constraint checker - example of creating a custom variant.
+
+This implementation is very strict about constraint satisfaction,
+requiring high confidence for all constraints.
+"""
+
+from typing import Dict, List, Tuple
+
+from loguru import logger
+
+from ..candidates.base_candidate import Candidate
+from ..constraints.base_constraint import Constraint, ConstraintType
+from .base_constraint_checker import (
+    BaseConstraintChecker,
+    ConstraintCheckResult,
+)
+
+
+class StrictChecker(BaseConstraintChecker):
+    """
+    Strict constraint checker that requires high confidence for all constraints.
+
+    This is an example of how to create custom constraint checking variants
+    by inheriting from BaseConstraintChecker.
+    """
+
+    def __init__(
+        self,
+        *args,
+        strict_threshold: float = 0.9,  # Very high threshold
+        name_pattern_required: bool = True,  # NAME_PATTERN constraints are mandatory
+        **kwargs,
+    ):
+        """
+        Initialize strict checker.
+
+        Args:
+            strict_threshold: Very high threshold for all constraints
+            name_pattern_required: Whether NAME_PATTERN constraints are mandatory
+        """
+        super().__init__(*args, **kwargs)
+        self.strict_threshold = strict_threshold
+        self.name_pattern_required = name_pattern_required
+
+    def check_candidate(
+        self, candidate: Candidate, constraints: List[Constraint]
+    ) -> ConstraintCheckResult:
+        """Check candidate with strict requirements."""
+        logger.info(f"Checking candidate: {candidate.name} (strict mode)")
+
+        constraint_scores = {}
+        detailed_results = []
+        rejection_reason = None
+        should_reject = False
+
+        for constraint in constraints:
+            # Gather evidence
+            evidence_list = self._gather_evidence_for_constraint(
+                candidate, constraint
+            )
+
+            # Calculate score
+            score = self._evaluate_constraint_strictly(
+                candidate, constraint, evidence_list
+            )
+
+            # Check for rejection
+            reject, reason = self.should_reject_candidate(
+                candidate, constraint, evidence_list
+            )
+
+            if reject and not should_reject:
+                should_reject = True
+                rejection_reason = reason
+
+            # Store results
+            constraint_scores[constraint.value] = {
+                "total": score,
+                "strict_pass": score >= self.strict_threshold,
+                "weight": constraint.weight,
+            }
+
+            detailed_results.append(
+                {
+                    "constraint": constraint.value,
+                    "score": score,
+                    "strict_pass": score >= self.strict_threshold,
+                    "weight": constraint.weight,
+                    "type": constraint.type.value,
+                }
+            )
+
+            self._log_constraint_result(candidate, constraint, score, {})
+
+        # Calculate total score
+        if should_reject:
+            total_score = 0.0
+        else:
+            # All constraints must pass strict threshold
+            all_pass = all(r["strict_pass"] for r in detailed_results)
+            total_score = 1.0 if all_pass else 0.0
+
+        logger.info(
+            f"Strict evaluation for {candidate.name}: {'PASS' if total_score > 0 else 'FAIL'}"
+        )
+
+        return ConstraintCheckResult(
+            candidate=candidate,
+            total_score=total_score,
+            constraint_scores=constraint_scores,
+            should_reject=should_reject,
+            rejection_reason=rejection_reason,
+            detailed_results=detailed_results,
+        )
+
+    def should_reject_candidate(
+        self,
+        candidate: Candidate,
+        constraint: Constraint,
+        evidence_data: List[Dict],
+    ) -> Tuple[bool, str]:
+        """Strict rejection rules."""
+        if not evidence_data:
+            return True, f"No evidence for constraint '{constraint.value}'"
+
+        score = self._evaluate_constraint_strictly(
+            candidate, constraint, evidence_data
+        )
+
+        # Special handling for NAME_PATTERN constraints
+        if (
+            constraint.type == ConstraintType.NAME_PATTERN
+            and self.name_pattern_required
+        ):
+            if score < 0.95:  # Even stricter for name patterns
+                return (
+                    True,
+                    f"NAME_PATTERN constraint '{constraint.value}' failed strict evaluation",
+                )
+
+        # General strict threshold
+        if score < self.strict_threshold:
+            return (
+                True,
+                f"Constraint '{constraint.value}' below strict threshold ({score:.0%})",
+            )
+
+        return False, ""
+
+    def _evaluate_constraint_strictly(
+        self,
+        candidate: Candidate,
+        constraint: Constraint,
+        evidence_list: List[Dict],
+    ) -> float:
+        """Evaluate constraint with strict criteria."""
+        if not evidence_list:
+            return 0.0
+
+        # For NAME_PATTERN constraints, use direct name checking
+        if constraint.type == ConstraintType.NAME_PATTERN:
+            return self._check_name_pattern_strictly(
+                candidate.name, constraint.value
+            )
+
+        # For other constraints, use LLM with strict prompt
+        combined_evidence = "\n".join(
+            [e.get("text", "")[:300] for e in evidence_list[:2]]
+        )
+
+        prompt = f"""
+STRICT EVALUATION: Does "{candidate.name}" definitely and clearly satisfy: "{constraint.value}"?
+
+Evidence:
+{combined_evidence}
+
+Be very strict. Only return a high score if there is clear, unambiguous evidence.
+
+Score (0.0-1.0):
+"""
+
+        try:
+            response = self.model.invoke(prompt).content.strip()
+            import re
+
+            match = re.search(r"(\d*\.?\d+)", response)
+            if match:
+                return max(0.0, min(float(match.group(1)), 1.0))
+        except Exception as e:
+            logger.error(f"Error in strict evaluation: {e}")
+
+        return 0.0  # Default to fail on error
+
+    def _check_name_pattern_strictly(
+        self, candidate_name: str, pattern_description: str
+    ) -> float:
+        """Strict name pattern checking."""
+        # Example: Check for body parts in name
+        if "body part" in pattern_description.lower():
+            body_parts = [
+                "arm",
+                "leg",
+                "foot",
+                "feet",
+                "hand",
+                "eye",
+                "ear",
+                "nose",
+                "mouth",
+                "tooth",
+                "teeth",
+                "head",
+                "face",
+                "neck",
+                "back",
+                "chest",
+                "heart",
+                "finger",
+                "thumb",
+                "toe",
+                "knee",
+                "elbow",
+                "shoulder",
+                "spine",
+                "bone",
+            ]
+
+            name_lower = candidate_name.lower()
+            for part in body_parts:
+                if part in name_lower.split() or part in name_lower:
+                    logger.info(
+                        f"✓ Found body part '{part}' in '{candidate_name}'"
+                    )
+                    return 1.0
+
+            logger.info(f"✗ No body part found in '{candidate_name}'")
+            return 0.0
+
+        # For other name patterns, use LLM
+        prompt = f"""
+Does the name "{candidate_name}" match this pattern: "{pattern_description}"?
+
+Be very strict. Return 1.0 only if it clearly matches, 0.0 otherwise.
+
+Score:
+"""
+
+        try:
+            response = self.model.invoke(prompt).content.strip()
+            import re
+
+            match = re.search(r"(\d*\.?\d+)", response)
+            if match:
+                return max(0.0, min(float(match.group(1)), 1.0))
+        except Exception:
+            pass
+
+        return 0.0

local_deep_research/advanced_search_system/constraint_checking/threshold_checker.py

@@ -0,0 +1,213 @@
+"""
+Simple threshold-based constraint checker.
+
+This implementation uses simple yes/no threshold checking for constraints,
+making it faster but less nuanced than dual confidence checking.
+"""
+
+from typing import Dict, List, Tuple
+
+from loguru import logger
+
+from ..candidates.base_candidate import Candidate
+from ..constraints.base_constraint import Constraint
+from .base_constraint_checker import (
+    BaseConstraintChecker,
+    ConstraintCheckResult,
+)
+
+
+class ThresholdChecker(BaseConstraintChecker):
+    """
+    Simple threshold-based constraint checker.
+
+    This checker:
+    1. Uses simple LLM yes/no responses for constraint satisfaction
+    2. Makes rejection decisions based on simple thresholds
+    3. Faster than dual confidence but less detailed
+    """
+
+    def __init__(
+        self,
+        *args,
+        satisfaction_threshold: float = 0.7,  # Minimum score to consider satisfied
+        required_satisfaction_rate: float = 0.8,  # % of constraints that must be satisfied
+        **kwargs,
+    ):
+        """
+        Initialize threshold checker.
+
+        Args:
+            satisfaction_threshold: Minimum score for constraint satisfaction
+            required_satisfaction_rate: Percentage of constraints that must be satisfied
+        """
+        super().__init__(*args, **kwargs)
+        self.satisfaction_threshold = satisfaction_threshold
+        self.required_satisfaction_rate = required_satisfaction_rate
+
+    def check_candidate(
+        self, candidate: Candidate, constraints: List[Constraint]
+    ) -> ConstraintCheckResult:
+        """Check candidate using simple threshold analysis."""
+        logger.info(f"Checking candidate: {candidate.name} (threshold)")
+
+        constraint_scores = {}
+        detailed_results = []
+        satisfied_count = 0
+        total_constraints = len(constraints)
+
+        for constraint in constraints:
+            # Gather evidence
+            evidence_list = self._gather_evidence_for_constraint(
+                candidate, constraint
+            )
+
+            if evidence_list:
+                # Simple satisfaction check
+                satisfaction_score = self._check_constraint_satisfaction(
+                    candidate, constraint, evidence_list
+                )
+
+                is_satisfied = satisfaction_score >= self.satisfaction_threshold
+                if is_satisfied:
+                    satisfied_count += 1
+
+                # Store results
+                constraint_scores[constraint.value] = {
+                    "total": satisfaction_score,
+                    "satisfied": is_satisfied,
+                    "weight": constraint.weight,
+                }
+
+                detailed_results.append(
+                    {
+                        "constraint": constraint.value,
+                        "score": satisfaction_score,
+                        "satisfied": is_satisfied,
+                        "weight": constraint.weight,
+                        "type": constraint.type.value,
+                    }
+                )
+
+                self._log_constraint_result(
+                    candidate, constraint, satisfaction_score, {}
+                )
+
+            else:
+                # No evidence - consider unsatisfied
+                constraint_scores[constraint.value] = {
+                    "total": 0.0,
+                    "satisfied": False,
+                    "weight": constraint.weight,
+                }
+
+                detailed_results.append(
+                    {
+                        "constraint": constraint.value,
+                        "score": 0.0,
+                        "satisfied": False,
+                        "weight": constraint.weight,
+                        "type": constraint.type.value,
+                    }
+                )
+
+                logger.info(
+                    f"? {candidate.name} | {constraint.value}: No evidence found"
+                )
+
+        # Check rejection based on satisfaction rate
+        satisfaction_rate = (
+            satisfied_count / total_constraints if total_constraints > 0 else 0
+        )
+        should_reject = satisfaction_rate < self.required_satisfaction_rate
+
+        rejection_reason = None
+        if should_reject:
+            rejection_reason = f"Only {satisfied_count}/{total_constraints} constraints satisfied ({satisfaction_rate:.0%})"
+
+        # Calculate total score
+        if should_reject:
+            total_score = 0.0
+        else:
+            # Use satisfaction rate as score
+            total_score = satisfaction_rate
+
+        logger.info(
+            f"Final score for {candidate.name}: {total_score:.2%} ({satisfied_count}/{total_constraints} satisfied)"
+        )
+
+        return ConstraintCheckResult(
+            candidate=candidate,
+            total_score=total_score,
+            constraint_scores=constraint_scores,
+            should_reject=should_reject,
+            rejection_reason=rejection_reason,
+            detailed_results=detailed_results,
+        )
+
+    def should_reject_candidate(
+        self,
+        candidate: Candidate,
+        constraint: Constraint,
+        evidence_data: List[Dict],
+    ) -> Tuple[bool, str]:
+        """Simple rejection based on evidence availability and quality."""
+        if not evidence_data:
+            return (
+                True,
+                f"No evidence found for constraint '{constraint.value}'",
+            )
+
+        satisfaction_score = self._check_constraint_satisfaction(
+            candidate, constraint, evidence_data
+        )
+
+        if satisfaction_score < self.satisfaction_threshold:
+            return (
+                True,
+                f"Constraint '{constraint.value}' not satisfied (score: {satisfaction_score:.0%})",
+            )
+
+        return False, ""
+
+    def _check_constraint_satisfaction(
+        self,
+        candidate: Candidate,
+        constraint: Constraint,
+        evidence_list: List[Dict],
+    ) -> float:
+        """Check if constraint is satisfied using simple LLM prompt."""
+        # Combine evidence texts
+        combined_evidence = "\n".join(
+            [e.get("text", "")[:200] for e in evidence_list[:3]]
+        )
+
+        prompt = f"""
+Does the candidate "{candidate.name}" satisfy this constraint: "{constraint.value}"?
+
+Evidence:
+{combined_evidence}
+
+Consider the evidence and respond with a satisfaction score from 0.0 to 1.0 where:
+- 1.0 = Definitely satisfies the constraint
+- 0.5 = Partially satisfies or unclear
+- 0.0 = Definitely does not satisfy the constraint
+
+Score:
+"""
+
+        try:
+            response = self.model.invoke(prompt).content.strip()
+
+            # Extract score
+            import re
+
+            match = re.search(r"(\d*\.?\d+)", response)
+            if match:
+                score = float(match.group(1))
+                return max(0.0, min(score, 1.0))
+
+        except Exception as e:
+            logger.error(f"Error checking constraint satisfaction: {e}")
+
+        return 0.5  # Default to neutral if parsing fails

local_deep_research/advanced_search_system/constraints/__init__.py

@@ -0,0 +1,6 @@
+# Constraints System Package
+
+from .base_constraint import Constraint, ConstraintType
+from .constraint_analyzer import ConstraintAnalyzer
+
+__all__ = ["Constraint", "ConstraintType", "ConstraintAnalyzer"]

local_deep_research/advanced_search_system/constraints/base_constraint.py

@@ -0,0 +1,58 @@
+"""
+Base constraint classes for query decomposition.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict
+
+
+class ConstraintType(Enum):
+    """Types of constraints in queries."""
+
+    PROPERTY = "property"  # e.g., "formed during ice age"
+    NAME_PATTERN = "name_pattern"  # e.g., "contains body part"
+    EVENT = "event"  # e.g., "fall between 2000-2021"
+    STATISTIC = "statistic"  # e.g., "84.5x ratio"
+    TEMPORAL = "temporal"  # e.g., "in 2014"
+    LOCATION = "location"  # e.g., "in Colorado"
+    COMPARISON = "comparison"  # e.g., "more than X"
+    EXISTENCE = "existence"  # e.g., "has a viewpoint"
+
+
+@dataclass
+class Constraint:
+    """A single constraint extracted from a query."""
+
+    id: str
+    type: ConstraintType
+    description: str
+    value: Any
+    weight: float = 1.0  # Importance of this constraint
+    metadata: Dict[str, Any] = None
+
+    def __post_init__(self):
+        """Initialize metadata if not provided."""
+        if self.metadata is None:
+            self.metadata = {}
+
+    def to_search_terms(self) -> str:
+        """Convert constraint to search terms."""
+        if self.type == ConstraintType.PROPERTY:
+            return self.value
+        elif self.type == ConstraintType.NAME_PATTERN:
+            return f"{self.value} name trail mountain"
+        elif self.type == ConstraintType.EVENT:
+            return f"{self.value} accident incident"
+        elif self.type == ConstraintType.STATISTIC:
+            return f"{self.value} statistics data"
+        else:
+            return str(self.value)
+
+    def is_critical(self) -> bool:
+        """Determine if this is a critical constraint that must be satisfied."""
+        # Consider NAME_PATTERN constraints as critical regardless of weight
+        if self.type == ConstraintType.NAME_PATTERN:
+            return True
+        # Otherwise use weight to determine criticality
+        return self.weight > 0.8

local_deep_research/advanced_search_system/constraints/constraint_analyzer.py

@@ -0,0 +1,143 @@
+"""
+Constraint analyzer for extracting constraints from queries.
+"""
+
+import re
+from typing import List
+
+from langchain_core.language_models import BaseChatModel
+from loguru import logger
+
+from ...utilities.search_utilities import remove_think_tags
+from .base_constraint import Constraint, ConstraintType
+
+
+class ConstraintAnalyzer:
+    """Analyzes queries to extract constraints."""
+
+    def __init__(self, model: BaseChatModel):
+        """Initialize the constraint analyzer."""
+        self.model = model
+
+    def extract_constraints(self, query: str) -> List[Constraint]:
+        """Extract constraints from a query."""
+        prompt = f"""
+Generate constraints to verify if an answer candidate correctly answers this question.
+
+Question: {query}
+
+Create constraints that would help verify if a proposed answer is correct. Focus on the RELATIONSHIP between the question and answer, not just query analysis.
+
+Examples:
+- "Which university did Alice study at?" → "Alice studied at this university"
+- "What year was the company founded?" → "The company was founded in this year"
+- "Who invented the device?" → "This person invented the device"
+- "Where is the building located?" → "The building is located at this place"
+
+For each constraint, identify:
+1. Type: property, name_pattern, event, statistic, temporal, location, comparison, existence
+2. Description: What relationship must hold between question and answer
+3. Value: The specific relationship to verify
+4. Weight: How critical this constraint is (0.0-1.0)
+
+Format your response as:
+CONSTRAINT_1:
+Type: [type]
+Description: [description]
+Value: [value]
+Weight: [0.0-1.0]
+
+CONSTRAINT_2:
+Type: [type]
+Description: [description]
+Value: [value]
+Weight: [0.0-1.0]
+
+Focus on answer verification, not query parsing.
+"""
+
+        response = self.model.invoke(prompt)
+        content = remove_think_tags(response.content)
+
+        constraints = []
+        current_constraint = {}
+        constraint_id = 1
+
+        for line in content.strip().split("\n"):
+            line = line.strip()
+
+            if line.startswith("CONSTRAINT_"):
+                if current_constraint and all(
+                    k in current_constraint
+                    for k in ["type", "description", "value"]
+                ):
+                    constraint = Constraint(
+                        id=f"c{constraint_id}",
+                        type=self._parse_constraint_type(
+                            current_constraint["type"]
+                        ),
+                        description=current_constraint["description"],
+                        value=current_constraint["value"],
+                        weight=self._parse_weight(
+                            current_constraint.get("weight", 1.0)
+                        ),
+                    )
+                    constraints.append(constraint)
+                    constraint_id += 1
+                current_constraint = {}
+            elif ":" in line:
+                key, value = line.split(":", 1)
+                key = key.strip().lower()
+                value = value.strip()
+                if key in ["type", "description", "value", "weight"]:
+                    current_constraint[key] = value
+
+        # Don't forget the last constraint
+        if current_constraint and all(
+            k in current_constraint for k in ["type", "description", "value"]
+        ):
+            constraint = Constraint(
+                id=f"c{constraint_id}",
+                type=self._parse_constraint_type(current_constraint["type"]),
+                description=current_constraint["description"],
+                value=current_constraint["value"],
+                weight=self._parse_weight(
+                    current_constraint.get("weight", 1.0)
+                ),
+            )
+            constraints.append(constraint)
+
+        logger.info(f"Extracted {len(constraints)} constraints from query")
+        return constraints
+
+    def _parse_constraint_type(self, type_str: str) -> ConstraintType:
+        """Parse constraint type from string."""
+        type_map = {
+            "property": ConstraintType.PROPERTY,
+            "name_pattern": ConstraintType.NAME_PATTERN,
+            "event": ConstraintType.EVENT,
+            "statistic": ConstraintType.STATISTIC,
+            "temporal": ConstraintType.TEMPORAL,
+            "location": ConstraintType.LOCATION,
+            "comparison": ConstraintType.COMPARISON,
+            "existence": ConstraintType.EXISTENCE,
+        }
+        return type_map.get(type_str.lower(), ConstraintType.PROPERTY)
+
+    def _parse_weight(self, weight_value) -> float:
+        """Parse weight value to float, handling text annotations.
+
+        Args:
+            weight_value: String or numeric weight value, possibly with text annotations
+
+        Returns:
+            float: Parsed weight value
+        """
+        if isinstance(weight_value, (int, float)):
+            return float(weight_value)
+        if isinstance(weight_value, str):
+            # Extract the first number from the string
+            match = re.search(r"(\d+(\.\d+)?)", weight_value)
+            if match:
+                return float(match.group(1))
+        return 1.0  # Default weight

local_deep_research/advanced_search_system/evidence/__init__.py

@@ -0,0 +1,12 @@
+# Evidence System Package
+
+from .base_evidence import Evidence, EvidenceType
+from .evaluator import EvidenceEvaluator
+from .requirements import EvidenceRequirements
+
+__all__ = [
+    "Evidence",
+    "EvidenceType",
+    "EvidenceEvaluator",
+    "EvidenceRequirements",
+]