kg-mcp 0.1.8__py3-none-any.whl

kg_mcp/kg/retrieval.py

@@ -0,0 +1,225 @@
+"""
+Retrieval module for building context packs from the knowledge graph.
+Navigates the graph to construct relevant context for IDE agents.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from kg_mcp.kg.repo import get_repository
+
+logger = logging.getLogger(__name__)
+
+
+class ContextBuilder:
+    """Builds context packs from the knowledge graph."""
+
+    def __init__(self):
+        self.repo = get_repository()
+
+    async def build_context_pack(
+        self,
+        project_id: str,
+        focus_goal_id: Optional[str] = None,
+        query: Optional[str] = None,
+        k_hops: int = 2,
+        user_id: str = "default_user",
+    ) -> Dict[str, Any]:
+        """
+        Build a comprehensive context pack for an IDE agent.
+
+        Args:
+            project_id: Project to build context for
+            focus_goal_id: Optional specific goal to focus on
+            query: Optional search query for additional context
+            k_hops: Number of hops for graph traversal
+            user_id: User ID for preferences
+
+        Returns:
+            Dict with 'markdown' (formatted context) and 'entities' (raw data)
+        """
+        logger.info(f"Building context pack for project {project_id}")
+
+        entities: Dict[str, Any] = {
+            "active_goals": [],
+            "preferences": [],
+            "constraints": [],
+            "pain_points": [],
+            "strategies": [],
+            "recent_decisions": [],
+            "code_artifacts": [],
+            "focus_goal_subgraph": None,
+            "search_results": [],
+        }
+
+        # Get active goals
+        entities["active_goals"] = await self.repo.get_active_goals(project_id)
+        logger.debug(f"Found {len(entities['active_goals'])} active goals")
+
+        # Get user preferences
+        entities["preferences"] = await self.repo.get_preferences(user_id)
+        logger.debug(f"Found {len(entities['preferences'])} preferences")
+
+        # Get open pain points
+        entities["pain_points"] = await self.repo.get_open_painpoints(project_id)
+        logger.debug(f"Found {len(entities['pain_points'])} open pain points")
+
+        # If focus goal specified, get its subgraph
+        if focus_goal_id:
+            entities["focus_goal_subgraph"] = await self.repo.get_goal_subgraph(
+                focus_goal_id, k_hops
+            )
+            # Get artifacts for the focused goal
+            entities["code_artifacts"] = await self.repo.get_artifacts_for_goal(focus_goal_id)
+
+        # If query specified, do fulltext search
+        if query:
+            entities["search_results"] = await self.repo.fulltext_search(
+                project_id=project_id,
+                query=query,
+                limit=10,
+            )
+
+        # Build markdown context
+        markdown = self._format_markdown(entities, project_id)
+
+        return {
+            "markdown": markdown,
+            "entities": entities,
+        }
+
+    def _format_markdown(self, entities: Dict[str, Any], project_id: str) -> str:
+        """Format entities into a structured markdown document."""
+        sections = []
+
+        # Header
+        sections.append(f"# 📋 Context Pack for Project: {project_id}")
+        sections.append(f"*Generated at: {datetime.utcnow().isoformat()}*\n")
+
+        # Active Goals
+        if entities["active_goals"]:
+            sections.append("## 🎯 Active Goals\n")
+            for i, goal in enumerate(entities["active_goals"], 1):
+                priority_emoji = self._priority_emoji(goal.get("priority", 3))
+                sections.append(
+                    f"### {i}. {priority_emoji} {goal.get('title', 'Untitled')}\n"
+                )
+                if goal.get("description"):
+                    sections.append(f"**Description:** {goal['description']}\n")
+                sections.append(f"**Status:** {goal.get('status', 'unknown')}")
+                sections.append(f"**Priority:** {goal.get('priority', '-')}\n")
+
+                # Acceptance criteria
+                if goal.get("acceptance_criteria"):
+                    sections.append("**Acceptance Criteria:**")
+                    for ac in goal["acceptance_criteria"]:
+                        sections.append(f"- [ ] {ac.get('criterion', ac)}")
+                    sections.append("")
+
+                # Constraints
+                if goal.get("constraints"):
+                    sections.append("**Constraints:**")
+                    for c in goal["constraints"]:
+                        severity = c.get("severity", "must")
+                        sections.append(f"- [{severity}] {c.get('description', c)}")
+                    sections.append("")
+
+                # Strategies
+                if goal.get("strategies"):
+                    sections.append("**Strategies:**")
+                    for s in goal["strategies"]:
+                        sections.append(f"- **{s.get('title', 'Strategy')}**: {s.get('approach', '')}")
+                    sections.append("")
+
+        # User Preferences
+        if entities["preferences"]:
+            sections.append("## ⚙️ User Preferences\n")
+            prefs_by_category: Dict[str, List[Any]] = {}
+            for pref in entities["preferences"]:
+                cat = pref.get("category", "other")
+                if cat not in prefs_by_category:
+                    prefs_by_category[cat] = []
+                prefs_by_category[cat].append(pref)
+
+            for category, prefs in prefs_by_category.items():
+                sections.append(f"**{category.replace('_', ' ').title()}:**")
+                for p in prefs:
+                    strength = p.get("strength", "prefer")
+                    prefix = "✅" if strength == "require" else ("❌" if strength == "avoid" else "💡")
+                    sections.append(f"- {prefix} {p.get('preference', p)}")
+                sections.append("")
+
+        # Pain Points
+        if entities["pain_points"]:
+            sections.append("## ⚠️ Open Pain Points\n")
+            for pp in entities["pain_points"]:
+                severity = pp.get("severity", "medium")
+                emoji = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🟢"}.get(
+                    severity, "⚪"
+                )
+                sections.append(f"- {emoji} **[{severity}]** {pp.get('description', pp)}")
+                if pp.get("blocking_goals"):
+                    sections.append(f"  - Blocking: {', '.join(pp['blocking_goals'])}")
+            sections.append("")
+
+        # Code Artifacts
+        if entities["code_artifacts"]:
+            sections.append("## 📁 Relevant Code Artifacts\n")
+            for artifact in entities["code_artifacts"]:
+                path = artifact.get("path", "unknown")
+                kind = artifact.get("kind", "file")
+                sections.append(f"- **{path}** ({kind})")
+                if artifact.get("symbols"):
+                    for sym in artifact["symbols"][:5]:
+                        sections.append(f"  - `{sym.get('fqn', sym.get('name', 'symbol'))}`")
+            sections.append("")
+
+        # Focus Goal Subgraph
+        if entities.get("focus_goal_subgraph") and entities["focus_goal_subgraph"].get("goal"):
+            fg = entities["focus_goal_subgraph"]
+            sections.append("## 🔍 Focus Goal Details\n")
+            sections.append(f"**Goal:** {fg['goal'].get('title', 'Untitled')}\n")
+            if fg.get("connected"):
+                sections.append("**Connected entities:**")
+                for node in fg["connected"][:10]:
+                    if isinstance(node, dict):
+                        node_type = list(node.keys())[0] if node else "Entity"
+                        sections.append(f"- {node}")
+            sections.append("")
+
+        # Search Results
+        if entities["search_results"]:
+            sections.append("## 🔎 Search Results\n")
+            for result in entities["search_results"]:
+                rtype = result.get("type", "Unknown")
+                data = result.get("data", {})
+                score = result.get("score", 0)
+                title = data.get("title") or data.get("description", str(data))[:50]
+                sections.append(f"- **[{rtype}]** {title} (score: {score:.2f})")
+            sections.append("")
+
+        # Footer with instructions
+        sections.append("---")
+        sections.append(
+            "*Use this context to guide your work. "
+            "Call `kg_link_code_artifact` when creating/modifying files to keep the graph updated.*"
+        )
+
+        return "\n".join(sections)
+
+    def _priority_emoji(self, priority: int) -> str:
+        """Convert priority number to emoji."""
+        return {1: "🔴", 2: "🟠", 3: "🟡", 4: "🟢", 5: "⚪"}.get(priority, "⚪")
+
+
+# Factory function
+_builder: Optional[ContextBuilder] = None
+
+
+def get_context_builder() -> ContextBuilder:
+    """Get or create the context builder singleton."""
+    global _builder
+    if _builder is None:
+        _builder = ContextBuilder()
+    return _builder

kg_mcp/kg/schema.cypher

@@ -0,0 +1,176 @@
+// =============================================================================
+// Neo4j Schema Definition for MCP-KG-Memory
+// Run this script to initialize the database schema
+// =============================================================================
+
+// -----------------------------------------------------------------------------
+// CONSTRAINTS (Unique keys)
+// -----------------------------------------------------------------------------
+
+// User constraints
+CREATE CONSTRAINT user_id_unique IF NOT EXISTS
+FOR (u:User) REQUIRE u.id IS UNIQUE;
+
+// Project constraints
+CREATE CONSTRAINT project_id_unique IF NOT EXISTS
+FOR (p:Project) REQUIRE p.id IS UNIQUE;
+
+// Interaction constraints
+CREATE CONSTRAINT interaction_id_unique IF NOT EXISTS
+FOR (i:Interaction) REQUIRE i.id IS UNIQUE;
+
+// Goal constraints
+CREATE CONSTRAINT goal_id_unique IF NOT EXISTS
+FOR (g:Goal) REQUIRE g.id IS UNIQUE;
+
+// Constraint (node) constraints
+CREATE CONSTRAINT constraint_id_unique IF NOT EXISTS
+FOR (c:Constraint) REQUIRE c.id IS UNIQUE;
+
+// Preference constraints
+CREATE CONSTRAINT preference_id_unique IF NOT EXISTS
+FOR (p:Preference) REQUIRE p.id IS UNIQUE;
+
+// PainPoint constraints
+CREATE CONSTRAINT painpoint_id_unique IF NOT EXISTS
+FOR (pp:PainPoint) REQUIRE pp.id IS UNIQUE;
+
+// Strategy constraints
+CREATE CONSTRAINT strategy_id_unique IF NOT EXISTS
+FOR (s:Strategy) REQUIRE s.id IS UNIQUE;
+
+// Decision constraints
+CREATE CONSTRAINT decision_id_unique IF NOT EXISTS
+FOR (d:Decision) REQUIRE d.id IS UNIQUE;
+
+// CodeArtifact constraints
+CREATE CONSTRAINT artifact_id_unique IF NOT EXISTS
+FOR (ca:CodeArtifact) REQUIRE ca.id IS UNIQUE;
+
+// Symbol constraints (unique by FQN within project)
+CREATE CONSTRAINT symbol_fqn_unique IF NOT EXISTS
+FOR (s:Symbol) REQUIRE s.fqn IS UNIQUE;
+
+// TestCase constraints
+CREATE CONSTRAINT testcase_id_unique IF NOT EXISTS
+FOR (tc:TestCase) REQUIRE tc.id IS UNIQUE;
+
+
+// -----------------------------------------------------------------------------
+// INDEXES (Performance)
+// -----------------------------------------------------------------------------
+
+// Project lookups
+CREATE INDEX project_name_idx IF NOT EXISTS
+FOR (p:Project) ON (p.name);
+
+// Goal lookups
+CREATE INDEX goal_status_idx IF NOT EXISTS
+FOR (g:Goal) ON (g.status);
+
+CREATE INDEX goal_project_idx IF NOT EXISTS
+FOR (g:Goal) ON (g.project_id);
+
+CREATE INDEX goal_priority_idx IF NOT EXISTS
+FOR (g:Goal) ON (g.priority);
+
+// Interaction lookups
+CREATE INDEX interaction_project_idx IF NOT EXISTS
+FOR (i:Interaction) ON (i.project_id);
+
+CREATE INDEX interaction_timestamp_idx IF NOT EXISTS
+FOR (i:Interaction) ON (i.timestamp);
+
+// CodeArtifact lookups
+CREATE INDEX artifact_path_idx IF NOT EXISTS
+FOR (ca:CodeArtifact) ON (ca.path);
+
+CREATE INDEX artifact_project_idx IF NOT EXISTS
+FOR (ca:CodeArtifact) ON (ca.project_id);
+
+// Preference lookups
+CREATE INDEX preference_user_idx IF NOT EXISTS
+FOR (p:Preference) ON (p.user_id);
+
+CREATE INDEX preference_category_idx IF NOT EXISTS
+FOR (p:Preference) ON (p.category);
+
+// PainPoint lookups
+CREATE INDEX painpoint_project_idx IF NOT EXISTS
+FOR (pp:PainPoint) ON (pp.project_id);
+
+CREATE INDEX painpoint_resolved_idx IF NOT EXISTS
+FOR (pp:PainPoint) ON (pp.resolved);
+
+// Symbol lookups
+CREATE INDEX symbol_name_idx IF NOT EXISTS
+FOR (s:Symbol) ON (s.name);
+
+CREATE INDEX symbol_artifact_idx IF NOT EXISTS
+FOR (s:Symbol) ON (s.artifact_id);
+
+CREATE INDEX symbol_kind_idx IF NOT EXISTS
+FOR (s:Symbol) ON (s.kind);
+
+// Composite index for line range queries
+CREATE INDEX symbol_lines_idx IF NOT EXISTS
+FOR (s:Symbol) ON (s.line_start, s.line_end);
+
+
+// -----------------------------------------------------------------------------
+// FULLTEXT INDEXES (Search)
+// -----------------------------------------------------------------------------
+
+// Fulltext search on Goal title and description
+CREATE FULLTEXT INDEX goal_fulltext IF NOT EXISTS
+FOR (g:Goal) ON EACH [g.title, g.description];
+
+// Fulltext search on PainPoint
+CREATE FULLTEXT INDEX painpoint_fulltext IF NOT EXISTS
+FOR (pp:PainPoint) ON EACH [pp.description];
+
+// Fulltext search on Strategy
+CREATE FULLTEXT INDEX strategy_fulltext IF NOT EXISTS
+FOR (s:Strategy) ON EACH [s.title, s.approach];
+
+// Fulltext search on Decision
+CREATE FULLTEXT INDEX decision_fulltext IF NOT EXISTS
+FOR (d:Decision) ON EACH [d.title, d.decision, d.rationale];
+
+// Fulltext search on CodeArtifact (path and symbol)
+CREATE FULLTEXT INDEX artifact_fulltext IF NOT EXISTS
+FOR (ca:CodeArtifact) ON EACH [ca.path];
+
+// Fulltext search on Interaction user text
+CREATE FULLTEXT INDEX interaction_fulltext IF NOT EXISTS
+FOR (i:Interaction) ON EACH [i.user_text];
+
+// Fulltext search on Symbol (name, fqn, signature)
+CREATE FULLTEXT INDEX symbol_fulltext IF NOT EXISTS
+FOR (s:Symbol) ON EACH [s.name, s.fqn, s.signature];
+
+
+// -----------------------------------------------------------------------------
+// SAMPLE RELATIONSHIP PATTERNS (for documentation)
+// -----------------------------------------------------------------------------
+// These are comments showing the expected relationship types:
+//
+// (User)-[:PREFERS]->(Preference)
+// (User)-[:WORKS_ON]->(Project)
+// (Project)-[:HAS_GOAL]->(Goal)
+// (Goal)-[:DECOMPOSES_INTO]->(Goal)  -- SubGoal
+// (Goal)-[:HAS_CONSTRAINT]->(Constraint)
+// (Goal)-[:HAS_STRATEGY]->(Strategy)
+// (Goal)-[:BLOCKED_BY]->(PainPoint)
+// (Goal)-[:HAS_ACCEPTANCE_CRITERIA]->(AcceptanceCriteria)
+// (PainPoint)-[:OBSERVED_IN]->(Interaction)
+// (Interaction)-[:IN_PROJECT]->(Project)
+// (Interaction)-[:PRODUCED]->(Goal|Strategy|Decision|PainPoint)
+// (Goal)-[:IMPLEMENTED_BY]->(CodeArtifact)
+// (CodeArtifact)-[:CONTAINS]->(Symbol)
+// (Symbol)-[:CALLS]->(Symbol)
+// (Symbol)-[:REFERENCES]->(Symbol)
+// (Goal)-[:VERIFIED_BY]->(TestCase)
+// (CodeArtifact)-[:COVERED_BY]->(TestCase)
+// (CodeArtifact)-[:TOUCHED_IN]->(Interaction)
+// (CodeArtifact)-[:CHANGED_IN]->(CodeChange)

kg_mcp/llm/__init__.py

@@ -0,0 +1,4 @@
+"""
+LLM submodule for MCP-KG-Memory.
+Handles communication with Gemini via LiteLLM.
+"""

kg_mcp/llm/client.py

@@ -0,0 +1,291 @@
+"""
+LLM Client wrapper for Gemini via LiteLLM.
+Provides structured extraction and linking capabilities.
+"""
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+import litellm
+from pydantic import ValidationError
+
+from kg_mcp.config import get_settings
+from kg_mcp.llm.schemas import (
+    ExtractionResult,
+    LinkingResult,
+    CodeReference,
+    GoalExtract,
+    ConstraintExtract,
+    PreferenceExtract,
+    PainPointExtract,
+    StrategyExtract,
+    AcceptanceCriteriaExtract,
+    MergeSuggestion,
+    RelationshipSuggestion,
+)
+from kg_mcp.llm.prompts.extractor import get_extractor_prompt
+from kg_mcp.llm.prompts.linker import get_linker_prompt
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """Client for LLM operations using LiteLLM."""
+
+    def __init__(self):
+        self.settings = get_settings()
+
+        # Determine active mode and primary provider
+        mode = self.settings.llm_mode
+        primary = self.settings.llm_primary
+
+        if mode == "gemini_direct" or (mode == "both" and primary == "gemini_direct"):
+            self._configure_gemini_direct()
+        elif mode == "litellm" or (mode == "both" and primary == "litellm"):
+            self._configure_litellm()
+        else:
+            # Fallback (legacy behavior)
+            if self.settings.litellm_base_url and self.settings.litellm_api_key:
+                self._configure_litellm()
+            elif self.settings.gemini_api_key:
+                self._configure_gemini_direct()
+            else:
+                self.api_base = None
+                self.api_key = None
+                self.model = self.settings.llm_model  # fallback
+                logger.warning("No LLM API credentials configured!")
+
+    def _configure_gemini_direct(self):
+        """Configure for Gemini Direct API."""
+        self.provider = "gemini"
+        self.api_base = None
+        self.api_key = self.settings.gemini_api_key
+        # For Gemini Direct via LiteLLM library, we might need to set the environment variable
+        # or pass it explicitly. LiteLLM supports 'gemini/' prefix with GEMINI_API_KEY env.
+        litellm.api_key = self.settings.gemini_api_key
+        
+        # Use specific gemini model if set, else fallback
+        self.model = self.settings.gemini_model or self.settings.llm_model
+        
+        # If model doesn't start with gemini/, prepend it for LiteLLM
+        if not self.model.startswith("gemini/") and "gemini" in self.model:
+             self.model = f"gemini/{self.model}"
+             
+        logger.info(f"Using Direct Gemini API with model {self.model}")
+
+    def _configure_litellm(self):
+        """Configure for LiteLLM Gateway."""
+        self.provider = "litellm"
+        self.api_base = self.settings.litellm_base_url.rstrip("/")
+        self.api_key = self.settings.litellm_api_key
+        
+        # Use specific litellm model if set, else fallback
+        self.model = self.settings.litellm_model or self.settings.llm_model
+        logger.info(f"Using LiteLLM Gateway at {self.api_base} with model {self.model}")
+
+    async def extract_entities(
+        self,
+        user_text: str,
+        files: Optional[List[str]] = None,
+        diff: Optional[str] = None,
+        symbols: Optional[List[str]] = None,
+        context: Optional[str] = None,
+    ) -> ExtractionResult:
+        """
+        Extract structured entities from user text using LLM.
+
+        Args:
+            user_text: The user's message/request
+            files: Optional list of file paths involved
+            diff: Optional code diff
+            symbols: Optional list of code symbols
+            context: Optional additional context
+
+        Returns:
+            ExtractionResult with extracted entities
+        """
+        logger.info(f"Extracting entities from user text: {user_text[:100]}...")
+
+        # Build the prompt
+        system_prompt, user_prompt = get_extractor_prompt(
+            user_text=user_text,
+            files=files,
+            diff=diff,
+            symbols=symbols,
+            context=context,
+        )
+
+        try:
+            # Build kwargs for litellm
+            llm_kwargs = {
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                "temperature": self.settings.llm_temperature,
+                "max_tokens": self.settings.llm_max_tokens,
+                "response_format": {"type": "json_object"},
+            }
+            
+            # Add gateway config if using LiteLLM Gateway
+            if self.api_base:
+                llm_kwargs["api_base"] = self.api_base
+                llm_kwargs["api_key"] = self.api_key
+            
+            response = await litellm.acompletion(**llm_kwargs)
+
+            content = response.choices[0].message.content
+            if not content:
+                logger.warning("Empty response from LLM")
+                return ExtractionResult()
+
+            # Parse JSON response
+            data = json.loads(content)
+            logger.debug(f"Extracted data: {json.dumps(data, indent=2)}")
+
+            # Validate and convert to pydantic models
+            return self._parse_extraction_result(data)
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse LLM response as JSON: {e}")
+            return ExtractionResult(confidence=0.0)
+        except Exception as e:
+            logger.error(f"LLM extraction failed: {e}")
+            raise
+
+    async def link_entities(
+        self,
+        extraction: ExtractionResult,
+        existing_goals: List[Dict[str, Any]],
+        existing_preferences: List[Dict[str, Any]],
+        recent_interactions: List[Dict[str, Any]],
+    ) -> LinkingResult:
+        """
+        Analyze extraction results and suggest links/merges with existing entities.
+
+        Args:
+            extraction: The extraction result to link
+            existing_goals: List of existing goals in the graph
+            existing_preferences: List of existing preferences
+            recent_interactions: Recent interactions for context
+
+        Returns:
+            LinkingResult with merge and relationship suggestions
+        """
+        logger.info("Linking extracted entities with existing graph...")
+
+        system_prompt, user_prompt = get_linker_prompt(
+            extraction=extraction,
+            existing_goals=existing_goals,
+            existing_preferences=existing_preferences,
+            recent_interactions=recent_interactions,
+        )
+
+        try:
+            # Build kwargs for litellm
+            llm_kwargs = {
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                "temperature": 0.1,  # Lower temperature for more deterministic linking
+                "max_tokens": 2048,
+                "response_format": {"type": "json_object"},
+            }
+            
+            # Add gateway config if using LiteLLM Gateway
+            if self.api_base:
+                llm_kwargs["api_base"] = self.api_base
+                llm_kwargs["api_key"] = self.api_key
+            
+            response = await litellm.acompletion(**llm_kwargs)
+
+            content = response.choices[0].message.content
+            if not content:
+                logger.warning("Empty response from LLM for linking")
+                return LinkingResult()
+
+            data = json.loads(content)
+            return self._parse_linking_result(data)
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse linking response as JSON: {e}")
+            return LinkingResult()
+        except Exception as e:
+            logger.error(f"LLM linking failed: {e}")
+            raise
+
+    def _parse_extraction_result(self, data: Dict[str, Any]) -> ExtractionResult:
+        """Parse raw JSON into ExtractionResult."""
+        try:
+            goals = [
+                GoalExtract(**g) for g in data.get("goals", [])
+            ]
+            constraints = [
+                ConstraintExtract(**c) for c in data.get("constraints", [])
+            ]
+            preferences = [
+                PreferenceExtract(**p) for p in data.get("preferences", [])
+            ]
+            pain_points = [
+                PainPointExtract(**pp) for pp in data.get("pain_points", [])
+            ]
+            strategies = [
+                StrategyExtract(**s) for s in data.get("strategies", [])
+            ]
+            acceptance_criteria = [
+                AcceptanceCriteriaExtract(**ac) for ac in data.get("acceptance_criteria", [])
+            ]
+            code_references = [
+                CodeReference(**cr) for cr in data.get("code_references", [])
+            ]
+            next_actions = data.get("next_actions", [])
+            confidence = data.get("confidence", 0.8)
+
+            return ExtractionResult(
+                goals=goals,
+                constraints=constraints,
+                preferences=preferences,
+                pain_points=pain_points,
+                strategies=strategies,
+                acceptance_criteria=acceptance_criteria,
+                code_references=code_references,
+                next_actions=next_actions,
+                confidence=confidence,
+            )
+        except ValidationError as e:
+            logger.warning(f"Validation error parsing extraction: {e}")
+            return ExtractionResult(confidence=0.5)
+
+    def _parse_linking_result(self, data: Dict[str, Any]) -> LinkingResult:
+        """Parse raw JSON into LinkingResult."""
+        try:
+            merge_suggestions = [
+                MergeSuggestion(**ms) for ms in data.get("merge_suggestions", [])
+            ]
+            relationships = [
+                RelationshipSuggestion(**r) for r in data.get("relationships", [])
+            ]
+
+            return LinkingResult(
+                merge_suggestions=merge_suggestions,
+                relationships=relationships,
+            )
+        except ValidationError as e:
+            logger.warning(f"Validation error parsing linking: {e}")
+            return LinkingResult()
+
+
+# Singleton instance
+_llm_client: Optional[LLMClient] = None
+
+
+def get_llm_client() -> LLMClient:
+    """Get or create the LLM client singleton."""
+    global _llm_client
+    if _llm_client is None:
+        _llm_client = LLMClient()
+    return _llm_client