mcp-sequential-thinking 0.6.0__py3-none-any.whl

mcp_sequential_thinking/analysis.py

@@ -0,0 +1,289 @@
+from collections import Counter
+from typing import Any, Dict, List
+
+from .logging_conf import configure_logging
+from .models import ThoughtData, ThoughtStage
+
+logger = configure_logging("sequential-thinking.analysis")
+
+
+class ThoughtAnalyzer:
+    """Analyzer for thought data to extract insights and patterns."""
+
+    @staticmethod
+    def _is_mainline(thought: ThoughtData) -> bool:
+        """Whether a thought belongs to the main line of reasoning.
+
+        Revisions and branch thoughts are excluded from progress metrics:
+        counting them would report e.g. 160% for a 5-thought session with
+        3 revisions.
+        """
+        return not thought.is_revision and thought.branch_id is None
+
+    @staticmethod
+    def find_related_thoughts(
+        current_thought: ThoughtData, all_thoughts: List[ThoughtData], max_results: int = 3
+    ) -> List[ThoughtData]:
+        """Find thoughts related to the current thought.
+
+        Args:
+            current_thought: The current thought to find related thoughts for
+            all_thoughts: All available thoughts to search through
+            max_results: Maximum number of related thoughts to return
+
+        Returns:
+            List[ThoughtData]: Related thoughts, sorted by relevance
+        """
+        # First, find thoughts in the same stage
+        same_stage = [
+            t
+            for t in all_thoughts
+            if t.stage == current_thought.stage and t.id != current_thought.id
+        ]
+
+        # Then, find thoughts with similar tags
+        if current_thought.tags:
+            tag_matches = []
+            for thought in all_thoughts:
+                if thought.id == current_thought.id:
+                    continue
+
+                # Count matching tags
+                matching_tags = set(current_thought.tags) & set(thought.tags)
+                if matching_tags:
+                    tag_matches.append((thought, len(matching_tags)))
+
+            # Sort by number of matching tags (descending)
+            tag_matches.sort(key=lambda x: x[1], reverse=True)
+            tag_related = [t[0] for t in tag_matches]
+        else:
+            tag_related = []
+
+        # Combine and deduplicate results
+        combined = []
+        seen_ids = set()
+
+        # First add same stage thoughts
+        for thought in same_stage:
+            if thought.id not in seen_ids:
+                combined.append(thought)
+                seen_ids.add(thought.id)
+
+                if len(combined) >= max_results:
+                    break
+
+        # Then add tag-related thoughts
+        if len(combined) < max_results:
+            for thought in tag_related:
+                if thought.id not in seen_ids:
+                    combined.append(thought)
+                    seen_ids.add(thought.id)
+
+                    if len(combined) >= max_results:
+                        break
+
+        return combined
+
+    @staticmethod
+    def generate_summary(thoughts: List[ThoughtData]) -> Dict[str, Any]:
+        """Generate a summary of the thinking process.
+
+        Args:
+            thoughts: List of thoughts to summarize
+
+        Returns:
+            Dict[str, Any]: Summary data
+        """
+        if not thoughts:
+            return {"summary": "No thoughts recorded yet"}
+
+        # Group thoughts by stage
+        stages: Dict[str, List[ThoughtData]] = {}
+        for thought in thoughts:
+            if thought.stage.value not in stages:
+                stages[thought.stage.value] = []
+            stages[thought.stage.value].append(thought)
+
+        # Count tags - using a more readable approach with explicit steps
+        # Collect all tags from all thoughts
+        all_tags = []
+        for thought in thoughts:
+            all_tags.extend(thought.tags)
+
+        # Count occurrences of each tag
+        tag_counts = Counter(all_tags)
+
+        # Get the 5 most common tags
+        top_tags = tag_counts.most_common(5)
+
+        # Create summary
+        try:
+            # Progress is based on mainline thoughts only; revisions and
+            # branch thoughts don't advance the sequence.
+            mainline_thoughts = [t for t in thoughts if ThoughtAnalyzer._is_mainline(t)]
+
+            # Safely calculate max total thoughts to avoid division by zero
+            max_total = max((t.total_thoughts for t in mainline_thoughts), default=0)
+
+            # Calculate percent complete safely
+            percent_complete: float = 0.0
+            if max_total > 0:
+                percent_complete = (len(mainline_thoughts) / max_total) * 100
+
+            logger.debug(
+                f"Calculating completion: {len(mainline_thoughts)}/{max_total} "
+                f"= {percent_complete}%"
+            )
+
+            # Build the summary dictionary with more readable and
+            # maintainable list comprehensions
+
+            # Count thoughts by stage
+            stage_counts = {stage: len(thoughts_list) for stage, thoughts_list in stages.items()}
+
+            # Create timeline entries
+            sorted_thoughts = sorted(thoughts, key=lambda x: x.thought_number)
+            timeline_entries = []
+            for t in sorted_thoughts:
+                entry: Dict[str, Any] = {"number": t.thought_number, "stage": t.stage.value}
+                if t.is_revision:
+                    entry["isRevision"] = True
+                if t.branch_id is not None:
+                    entry["branchId"] = t.branch_id
+                timeline_entries.append(entry)
+
+            # Aggregate branches: first occurrence defines the fork point.
+            branches: Dict[str, Dict[str, Any]] = {}
+            for t in sorted_thoughts:
+                if t.branch_id is None:
+                    continue
+                if t.branch_id not in branches:
+                    branches[t.branch_id] = {
+                        "fromThought": t.branch_from_thought,
+                        "thoughtCount": 0,
+                    }
+                branches[t.branch_id]["thoughtCount"] += 1
+
+            revision_count = sum(1 for t in thoughts if t.is_revision)
+
+            # Create top tags entries
+            top_tags_entries = []
+            for tag, count in top_tags:
+                top_tags_entries.append({"tag": tag, "count": count})
+
+            # Check if all stages are represented
+            all_stages_present = all(stage.value in stages for stage in ThoughtStage)
+
+            # Assemble the final summary
+            summary = {
+                "totalThoughts": len(thoughts),
+                "stages": stage_counts,
+                "timeline": timeline_entries,
+                "branches": branches,
+                "revisionCount": revision_count,
+                "topTags": top_tags_entries,
+                "completionStatus": {
+                    "hasAllStages": all_stages_present,
+                    "percentComplete": percent_complete,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Error generating summary: {e}")
+            summary = {"totalThoughts": len(thoughts), "error": str(e)}
+
+        return {"summary": summary}
+
+    @staticmethod
+    def analyze_thought(thought: ThoughtData, all_thoughts: List[ThoughtData]) -> Dict[str, Any]:
+        """Analyze a single thought in the context of all thoughts.
+
+        Args:
+            thought: The thought to analyze
+            all_thoughts: All available thoughts for context
+
+        Returns:
+            Dict[str, Any]: Analysis results
+        """
+        # Find related thoughts
+        related_thoughts = ThoughtAnalyzer.find_related_thoughts(thought, all_thoughts)
+
+        # Check if this is the first thought in its stage (lowest thought_number)
+        same_stage_thoughts = [t for t in all_thoughts if t.stage == thought.stage]
+        is_first_in_stage = all(
+            t.thought_number >= thought.thought_number for t in same_stage_thoughts
+        )
+
+        # Calculate progress. Revisions and branch thoughts don't advance the
+        # sequence, so for them progress reflects the mainline position instead
+        # of their own number (which may exceed total_thoughts).
+        if ThoughtAnalyzer._is_mainline(thought):
+            effective_number = thought.thought_number
+        else:
+            effective_number = max(
+                (t.thought_number for t in all_thoughts if ThoughtAnalyzer._is_mainline(t)),
+                default=0,
+            )
+        progress = (effective_number / thought.total_thoughts) * 100
+
+        # For a revision, surface a snippet of the mainline thought it revises.
+        revision_of = None
+        if thought.is_revision and thought.revises_thought_number is not None:
+            revised = next(
+                (
+                    t
+                    for t in all_thoughts
+                    if ThoughtAnalyzer._is_mainline(t)
+                    and t.thought_number == thought.revises_thought_number
+                ),
+                None,
+            )
+            if revised is not None:
+                revision_of = {
+                    "thoughtNumber": revised.thought_number,
+                    "stage": revised.stage.value,
+                    "snippet": (
+                        revised.thought[:100] + "..."
+                        if len(revised.thought) > 100
+                        else revised.thought
+                    ),
+                }
+
+        # Create analysis
+        analysis_block: Dict[str, Any] = {
+            "relatedThoughtsCount": len(related_thoughts),
+            "relatedThoughtSummaries": [
+                {
+                    "thoughtNumber": t.thought_number,
+                    "stage": t.stage.value,
+                    "snippet": (
+                        t.thought[:100] + "..." if len(t.thought) > 100 else t.thought
+                    ),
+                }
+                for t in related_thoughts
+            ],
+            "progress": progress,
+            "isFirstInStage": is_first_in_stage,
+            "isRevision": thought.is_revision,
+            "revisedThought": thought.revises_thought_number,
+            "branchId": thought.branch_id,
+        }
+        if revision_of is not None:
+            analysis_block["revisionOf"] = revision_of
+
+        return {
+            "thoughtAnalysis": {
+                "currentThought": {
+                    "thoughtNumber": thought.thought_number,
+                    "totalThoughts": thought.total_thoughts,
+                    "nextThoughtNeeded": thought.next_thought_needed,
+                    "stage": thought.stage.value,
+                    "tags": thought.tags,
+                    "timestamp": thought.timestamp,
+                },
+                "analysis": analysis_block,
+                "context": {
+                    "thoughtHistoryLength": len(all_thoughts),
+                    "currentStage": thought.stage.value,
+                },
+            }
+        }

mcp_sequential_thinking/logging_conf.py

@@ -0,0 +1,24 @@
+import logging
+import sys
+
+
+def configure_logging(name: str = "sequential-thinking") -> logging.Logger:
+    """Configure and return a logger with standardized settings.
+    
+    Args:
+        name: The name for the logger
+        
+    Returns:
+        logging.Logger: Configured logger instance
+    """
+    # Configure root logger
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.StreamHandler(sys.stderr)
+        ]
+    )
+    
+    # Get and return the named logger
+    return logging.getLogger(name)

mcp_sequential_thinking/models.py

@@ -0,0 +1,226 @@
+import re
+from typing import List, Optional
+from enum import Enum
+from datetime import datetime
+from uuid import uuid4, UUID
+from pydantic import BaseModel, Field, field_validator, model_validator, ValidationInfo
+
+# branch_id ends up in files and tool output, so it is restricted to a short,
+# filesystem- and log-safe alphabet.
+BRANCH_ID_MAX_LENGTH = 64
+BRANCH_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+class ThoughtStage(Enum):
+    """Basic thinking stages for structured sequential thinking."""
+    PROBLEM_DEFINITION = "Problem Definition"
+    RESEARCH = "Research"
+    ANALYSIS = "Analysis"
+    SYNTHESIS = "Synthesis"
+    CONCLUSION = "Conclusion"
+
+    @classmethod
+    def from_string(cls, value: str) -> 'ThoughtStage':
+        """Convert a string to a thinking stage.
+
+        Args:
+            value: The string representation of the thinking stage
+
+        Returns:
+            ThoughtStage: The corresponding ThoughtStage enum value
+
+        Raises:
+            ValueError: If the string does not match any valid thinking stage
+        """
+        # Case-insensitive comparison
+        for stage in cls:
+            if stage.value.casefold() == value.casefold():
+                return stage
+
+        # If no match found
+        valid_stages = ", ".join(stage.value for stage in cls)
+        raise ValueError(f"Invalid thinking stage: '{value}'. Valid stages are: {valid_stages}")
+
+
+class ThoughtData(BaseModel):
+    """Data structure for a single thought in the sequential thinking process."""
+    thought: str
+    thought_number: int
+    total_thoughts: int
+    next_thought_needed: bool
+    stage: ThoughtStage
+    tags: List[str] = Field(default_factory=list)
+    axioms_used: List[str] = Field(default_factory=list)
+    assumptions_challenged: List[str] = Field(default_factory=list)
+    is_revision: bool = False
+    revises_thought_number: Optional[int] = None
+    branch_from_thought: Optional[int] = None
+    branch_id: Optional[str] = None
+    timestamp: str = Field(default_factory=lambda: datetime.now().isoformat())
+    id: UUID = Field(default_factory=uuid4)
+
+    def __hash__(self) -> int:
+        """Make ThoughtData hashable based on its ID."""
+        return hash(self.id)
+
+    def __eq__(self, other: object) -> bool:
+        """Compare ThoughtData objects based on their ID."""
+        if not isinstance(other, ThoughtData):
+            return False
+        return self.id == other.id
+
+    @field_validator('thought')
+    @classmethod
+    def thought_not_empty(cls, v: str) -> str:
+        """Validate that thought content is not empty."""
+        if not v or not v.strip():
+            raise ValueError("Thought content cannot be empty")
+        return v
+
+    @field_validator('thought_number')
+    @classmethod
+    def thought_number_positive(cls, v: int) -> int:
+        """Validate that thought number is positive."""
+        if v < 1:
+            raise ValueError("Thought number must be positive")
+        return v
+
+    @field_validator('total_thoughts')
+    @classmethod
+    def total_thoughts_valid(cls, v: int, info: ValidationInfo) -> int:
+        """Validate that total thoughts is valid."""
+        thought_number = info.data.get('thought_number')
+        if thought_number is not None and v < thought_number:
+            raise ValueError("Total thoughts must be greater or equal to current thought number")
+        return v
+
+    @model_validator(mode='after')
+    def validate_revision_and_branch(self) -> 'ThoughtData':
+        """Validate the cross-field rules for revisions and branches."""
+        if self.is_revision and self.revises_thought_number is None:
+            raise ValueError("is_revision=True requires revises_thought_number to be set")
+        if self.revises_thought_number is not None and not self.is_revision:
+            raise ValueError("revises_thought_number requires is_revision=True")
+        if self.is_revision and self.branch_from_thought is not None:
+            raise ValueError(
+                "A thought cannot be a revision and a branch start at the same time"
+            )
+        if self.branch_id is not None and self.branch_from_thought is None:
+            raise ValueError("branch_id requires branch_from_thought to be set")
+
+        for field_name, value in (
+            ("revises_thought_number", self.revises_thought_number),
+            ("branch_from_thought", self.branch_from_thought),
+        ):
+            if value is not None and not 1 <= value < self.thought_number:
+                raise ValueError(
+                    f"{field_name} must be >= 1 and < thought_number "
+                    f"({self.thought_number}), got {value}"
+                )
+
+        if self.branch_id is not None and (
+            len(self.branch_id) > BRANCH_ID_MAX_LENGTH
+            or not BRANCH_ID_PATTERN.match(self.branch_id)
+        ):
+            raise ValueError(
+                f"branch_id must be 1-{BRANCH_ID_MAX_LENGTH} characters from "
+                "[A-Za-z0-9_-]"
+            )
+
+        return self
+
+    def to_dict(self, include_id: bool = False) -> dict:
+        """Convert the thought data to a dictionary representation.
+
+        Args:
+            include_id: Whether to include the ID in the dictionary representation.
+                        Default is False to omit it from external representations.
+
+        Returns:
+            dict: Dictionary representation of the thought data, with camelCase
+                keys for API consistency.
+        """
+        result = {
+            "thought": self.thought,
+            "thoughtNumber": self.thought_number,
+            "totalThoughts": self.total_thoughts,
+            "nextThoughtNeeded": self.next_thought_needed,
+            "stage": self.stage.value,
+            "tags": self.tags,
+            "axiomsUsed": self.axioms_used,
+            "assumptionsChallenged": self.assumptions_challenged,
+            "timestamp": self.timestamp,
+        }
+
+        # Revision/branch fields are only emitted when set, keeping records
+        # compact and older v2 files readable without them.
+        if self.is_revision:
+            result["isRevision"] = self.is_revision
+        if self.revises_thought_number is not None:
+            result["revisesThoughtNumber"] = self.revises_thought_number
+        if self.branch_from_thought is not None:
+            result["branchFromThought"] = self.branch_from_thought
+        if self.branch_id is not None:
+            result["branchId"] = self.branch_id
+
+        if include_id:
+            result["id"] = str(self.id)
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict) -> 'ThoughtData':
+        """Create a ThoughtData instance from a dictionary.
+
+        Args:
+            data: Dictionary containing thought data
+
+        Returns:
+            ThoughtData: A new ThoughtData instance
+        """
+        # Convert any camelCase keys to snake_case
+        snake_data = {}
+        mappings = {
+            "thoughtNumber": "thought_number",
+            "totalThoughts": "total_thoughts",
+            "nextThoughtNeeded": "next_thought_needed",
+            "axiomsUsed": "axioms_used",
+            "assumptionsChallenged": "assumptions_challenged",
+            "isRevision": "is_revision",
+            "revisesThoughtNumber": "revises_thought_number",
+            "branchFromThought": "branch_from_thought",
+            "branchId": "branch_id"
+        }
+        
+        # Process known direct mappings
+        for camel_key, snake_key in mappings.items():
+            if camel_key in data:
+                snake_data[snake_key] = data[camel_key]
+        
+        # Copy fields that don't need conversion
+        for key in ["thought", "tags", "timestamp"]:
+            if key in data:
+                snake_data[key] = data[key]
+                
+        # Handle special fields
+        if "stage" in data:
+            snake_data["stage"] = ThoughtStage.from_string(data["stage"])
+            
+        # Set default values for missing fields
+        snake_data.setdefault("tags", [])
+        snake_data.setdefault("axioms_used", data.get("axiomsUsed", []))
+        snake_data.setdefault("assumptions_challenged", data.get("assumptionsChallenged", []))
+        snake_data.setdefault("timestamp", datetime.now().isoformat())
+
+        # Add ID if present, otherwise generate a new one
+        if "id" in data:
+            try:
+                snake_data["id"] = UUID(data["id"])
+            except (ValueError, TypeError):
+                snake_data["id"] = uuid4()
+
+        return cls(**snake_data)
+
+    model_config = {
+        "arbitrary_types_allowed": True
+    }