kodit 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

kodit/infrastructure/{enrichment/local_enrichment_provider.py → enricher/local_enricher.py}

@@ -1,4 +1,4 @@
-"""Local enrichment provider implementation."""
+"""Local enricher implementation."""
 
 import asyncio
 import os
@@ -8,28 +8,24 @@ from typing import Any
 import structlog
 import tiktoken
 
-from kodit.domain.services.enrichment_service import EnrichmentProvider
-from kodit.domain.value_objects import EnrichmentRequest, EnrichmentResponse
-from kodit.infrastructure.enrichment.utils import clean_thinking_tags
+from kodit.domain.enrichments.enricher import Enricher
+from kodit.domain.enrichments.request import EnrichmentRequest
+from kodit.domain.enrichments.response import EnrichmentResponse
+from kodit.infrastructure.enricher.utils import clean_thinking_tags
 
-ENRICHMENT_SYSTEM_PROMPT = """
-You are a professional software developer. You will be given a snippet of code.
-Please provide a concise explanation of the code.
-"""
+DEFAULT_ENRICHER_MODEL = "Qwen/Qwen3-0.6B"
+DEFAULT_CONTEXT_WINDOW_SIZE = 2048
 
-DEFAULT_ENRICHMENT_MODEL = "Qwen/Qwen3-0.6B"
-DEFAULT_CONTEXT_WINDOW_SIZE = 2048  # Small so it works even on low-powered devices
 
-
-class LocalEnrichmentProvider(EnrichmentProvider):
-    """Local enrichment provider implementation."""
+class LocalEnricher(Enricher):
+    """Local enricher implementation using local models."""
 
     def __init__(
         self,
-        model_name: str = DEFAULT_ENRICHMENT_MODEL,
+        model_name: str = DEFAULT_ENRICHER_MODEL,
         context_window: int = DEFAULT_CONTEXT_WINDOW_SIZE,
     ) -> None:
-        """Initialize the local enrichment provider.
+        """Initialize the local enricher.
 
         Args:
             model_name: The model name to use for enrichment.
@@ -49,13 +45,13 @@ class LocalEnrichmentProvider(EnrichmentProvider):
         """Enrich a list of requests using local model.
 
         Args:
-            requests: List of enrichment requests.
+            requests: List of generic enrichment requests.
 
         Yields:
-            Enrichment responses as they are processed.
+            Generic enrichment responses as they are processed.
 
         """
-        # Remove empty snippets
+        # Remove empty requests
         requests = [req for req in requests if req.text]
 
         if not requests:
@@ -73,7 +69,7 @@ class LocalEnrichmentProvider(EnrichmentProvider):
                     self.model_name, padding_side="left"
                 )
             if self.model is None:
-                os.environ["TOKENIZERS_PARALLELISM"] = "false"  # Avoid warnings
+                os.environ["TOKENIZERS_PARALLELISM"] = "false"
                 self.model = AutoModelForCausalLM.from_pretrained(
                     self.model_name,
                     torch_dtype="auto",
@@ -83,13 +79,13 @@ class LocalEnrichmentProvider(EnrichmentProvider):
 
         await asyncio.to_thread(_init_model)
 
-        # Prepare prompts
+        # Prepare prompts with custom system prompts
         prompts = [
             {
-                "id": req.snippet_id,
+                "id": req.id,
                 "text": self.tokenizer.apply_chat_template(  # type: ignore[attr-defined]
                     [
-                        {"role": "system", "content": ENRICHMENT_SYSTEM_PROMPT},
+                        {"role": "system", "content": req.system_prompt},
                         {"role": "user", "content": req.text},
                     ],
                     tokenize=False,
@@ -121,9 +117,8 @@ class LocalEnrichmentProvider(EnrichmentProvider):
                 )
 
             content = await asyncio.to_thread(process_prompt, prompt)
-            # Remove thinking tags from the response
             cleaned_content = clean_thinking_tags(content)
             yield EnrichmentResponse(
-                snippet_id=prompt["id"],
+                id=prompt["id"],
                 text=cleaned_content,
             )

kodit/infrastructure/enricher/null_enricher.py

@@ -0,0 +1,36 @@
+"""Null enricher implementation."""
+
+from collections.abc import AsyncGenerator
+
+import structlog
+
+from kodit.domain.enrichments.enricher import Enricher
+from kodit.domain.enrichments.request import EnrichmentRequest
+from kodit.domain.enrichments.response import EnrichmentResponse
+
+
+class NullEnricher(Enricher):
+    """Null enricher that returns empty responses."""
+
+    def __init__(self) -> None:
+        """Initialize the null enricher."""
+        self.log = structlog.get_logger(__name__)
+
+    async def enrich(
+        self, requests: list[EnrichmentRequest]
+    ) -> AsyncGenerator[EnrichmentResponse, None]:
+        """Return empty responses for all requests.
+
+        Args:
+            requests: List of generic enrichment requests.
+
+        Yields:
+            Empty generic enrichment responses.
+
+        """
+        self.log.info("NullEnricher: returning empty responses", count=len(requests))
+        for request in requests:
+            yield EnrichmentResponse(
+                id=request.id,
+                text="",
+            )

kodit/infrastructure/mappers/enrichment_mapper.py

@@ -0,0 +1,83 @@
+"""Enrichment mapper."""
+
+from kodit.domain.enrichments.architecture.architecture import (
+    ENRICHMENT_TYPE_ARCHITECTURE,
+)
+from kodit.domain.enrichments.architecture.physical.physical import (
+    ENRICHMENT_SUBTYPE_PHYSICAL,
+    PhysicalArchitectureEnrichment,
+)
+from kodit.domain.enrichments.development.development import ENRICHMENT_TYPE_DEVELOPMENT
+from kodit.domain.enrichments.development.snippet.snippet import (
+    ENRICHMENT_SUBTYPE_SNIPPET_SUMMARY,
+    SnippetEnrichment,
+)
+from kodit.domain.enrichments.enrichment import EnrichmentV2
+from kodit.domain.enrichments.usage.api_docs import (
+    ENRICHMENT_SUBTYPE_API_DOCS,
+    APIDocEnrichment,
+)
+from kodit.domain.enrichments.usage.usage import ENRICHMENT_TYPE_USAGE
+from kodit.infrastructure.sqlalchemy import entities as db_entities
+
+
+class EnrichmentMapper:
+    """Maps between domain enrichment entities and database entities."""
+
+    @staticmethod
+    def to_database(domain_enrichment: EnrichmentV2) -> db_entities.EnrichmentV2:
+        """Convert domain enrichment to database entity."""
+        return db_entities.EnrichmentV2(
+            id=domain_enrichment.id,
+            type=domain_enrichment.type,
+            subtype=domain_enrichment.subtype,
+            content=domain_enrichment.content,
+            created_at=domain_enrichment.created_at,
+            updated_at=domain_enrichment.updated_at,
+        )
+
+    @staticmethod
+    def to_domain(
+        db_enrichment: db_entities.EnrichmentV2,
+        entity_type: str,  # noqa: ARG004
+        entity_id: str,
+    ) -> EnrichmentV2:
+        """Convert database enrichment to domain entity."""
+        # Use the stored type and subtype to determine the correct domain class
+        if (
+            db_enrichment.type == ENRICHMENT_TYPE_DEVELOPMENT
+            and db_enrichment.subtype == ENRICHMENT_SUBTYPE_SNIPPET_SUMMARY
+        ):
+            return SnippetEnrichment(
+                id=db_enrichment.id,
+                entity_id=entity_id,
+                content=db_enrichment.content,
+                created_at=db_enrichment.created_at,
+                updated_at=db_enrichment.updated_at,
+            )
+        if (
+            db_enrichment.type == ENRICHMENT_TYPE_USAGE
+            and db_enrichment.subtype == ENRICHMENT_SUBTYPE_API_DOCS
+        ):
+            return APIDocEnrichment(
+                id=db_enrichment.id,
+                entity_id=entity_id,
+                content=db_enrichment.content,
+                created_at=db_enrichment.created_at,
+                updated_at=db_enrichment.updated_at,
+            )
+        if (
+            db_enrichment.type == ENRICHMENT_TYPE_ARCHITECTURE
+            and db_enrichment.subtype == ENRICHMENT_SUBTYPE_PHYSICAL
+        ):
+            return PhysicalArchitectureEnrichment(
+                id=db_enrichment.id,
+                entity_id=entity_id,
+                content=db_enrichment.content,
+                created_at=db_enrichment.created_at,
+                updated_at=db_enrichment.updated_at,
+            )
+
+        raise ValueError(
+            f"Unknown enrichment type: {db_enrichment.type}/{db_enrichment.subtype}"
+        )

kodit/infrastructure/mappers/snippet_mapper.py

@@ -1,6 +1,8 @@
 """Mapping between domain Git entities and SQLAlchemy entities."""
 
 import kodit.domain.entities.git as domain_git_entities
+from kodit.domain.enrichments.development.snippet.snippet import SnippetEnrichment
+from kodit.domain.enrichments.enrichment import EnrichmentV2
 from kodit.domain.value_objects import Enrichment, EnrichmentType
 from kodit.infrastructure.sqlalchemy import entities as db_entities
 
@@ -12,19 +14,17 @@ class SnippetMapper:
         self,
         db_snippet: db_entities.SnippetV2,
         db_files: list[db_entities.GitCommitFile],
-        db_enrichments: list[db_entities.Enrichment],
+        db_enrichments: list[EnrichmentV2],
     ) -> domain_git_entities.SnippetV2:
         """Convert SQLAlchemy SnippetV2 to domain SnippetV2."""
-        # Convert enrichments
-        enrichments = []
-        for db_enrichment in db_enrichments:
-            # Map from SQLAlchemy enum to domain enum
-            enrichment_type = EnrichmentType(db_enrichment.type.value)
-            enrichment = Enrichment(
-                type=enrichment_type,
-                content=db_enrichment.content,
+        # Convert enrichments from SnippetEnrichment to Enrichment value objects
+        enrichments: list[Enrichment] = [
+            Enrichment(
+                type=EnrichmentType.SUMMARIZATION,
+                content=enrichment.content,
             )
-            enrichments.append(enrichment)
+            for enrichment in db_enrichments
+        ]
 
         derives_from = [
             domain_git_entities.GitFile(
@@ -59,20 +59,18 @@ class SnippetMapper:
         )
 
     def from_domain_enrichments(
-        self, snippet_sha: str, enrichments: list[Enrichment]
-    ) -> list[db_entities.Enrichment]:
-        """Convert domain enrichments to SQLAlchemy enrichments."""
-        db_enrichments = []
-        for enrichment in enrichments:
-            # Map from domain enum to SQLAlchemy enum
-            db_enrichment_type = db_entities.EnrichmentType(enrichment.type.value)
-            db_enrichment = db_entities.Enrichment(
-                snippet_sha=snippet_sha,
-                type=db_enrichment_type,
+        self,
+        snippet_sha: str,
+        enrichments: list[Enrichment],
+    ) -> list[SnippetEnrichment]:
+        """Convert domain enrichments to SnippetEnrichment entities."""
+        return [
+            SnippetEnrichment(
+                entity_id=snippet_sha,
                 content=enrichment.content,
             )
-            db_enrichments.append(db_enrichment)
-        return db_enrichments
+            for enrichment in enrichments
+        ]
 
     def to_domain_commit_index(
         self,

kodit/infrastructure/physical_architecture/__init__.py

@@ -0,0 +1 @@
+"""Physical architecture discovery infrastructure."""

kodit/infrastructure/physical_architecture/detectors/__init__.py

@@ -0,0 +1 @@
+"""Component detectors for physical architecture discovery."""

kodit/infrastructure/physical_architecture/detectors/docker_compose_detector.py

@@ -0,0 +1,336 @@
+"""Docker Compose detector for physical architecture discovery."""
+
+import contextlib
+import re
+from pathlib import Path
+
+import yaml
+
+
+class DockerComposeDetector:
+    """Detects physical components from Docker Compose files and generates narrative observations."""  # noqa: E501
+
+    # Regex pattern to detect communication addresses in environment variables
+    # Matches complete URLs with hostnames:
+    # - Simple URLs: http://api:8080, redis://cache:6379
+    # - Connection strings with auth: postgresql://user:pass@db:5432/dbname
+    # - Connection strings with asyncpg: postgresql+asyncpg://user:pass@db:5432
+    # Note: This captures the hostname portion, avoiding false matches in
+    # passwords or other parts of the URL
+    COMMUNICATION_PATTERN = re.compile(
+        r"(?:"
+        # Protocol-based URLs with optional auth (user:pass@)
+        r"(?:https?|tcp|grpc|ws|wss|amqp|kafka|redis|memcached|"
+        r"postgres(?:ql)?(?:\+\w+)?|mysql|mongodb)://"
+        r"(?:[^@/]+@)?"  # Optional user:pass@ (non-capturing, skip it)
+        r"([\w\-\.]+(?::\d+)?)"  # Capture hostname:port after @ or ://
+        r")",
+        re.IGNORECASE,
+    )
+
+    async def analyze(self, repo_path: Path) -> tuple[list[str], list[str], list[str]]:
+        """Generate narrative observations from Docker Compose analysis."""
+        component_notes: list[str] = []
+        connection_notes: list[str] = []
+        infrastructure_notes: list[str] = []
+
+        # Find all docker-compose files
+        yml_files = list(repo_path.glob("docker-compose*.yml"))
+        yaml_files = list(repo_path.glob("docker-compose*.yaml"))
+        compose_files = yml_files + yaml_files
+
+        if not compose_files:
+            return ([], [], [])
+
+        # Analyze each compose file
+        for compose_file in compose_files:
+            try:
+                with compose_file.open(encoding="utf-8") as f:
+                    compose_data = yaml.safe_load(f)
+
+                if not compose_data or "services" not in compose_data:
+                    continue
+
+                self._analyze_compose_file(
+                    compose_file,
+                    compose_data,
+                    component_notes,
+                    connection_notes,
+                    infrastructure_notes,
+                )
+
+            except (yaml.YAMLError, OSError, KeyError):
+                infrastructure_notes.append(
+                    f"Unable to parse Docker Compose file at {compose_file}. "
+                    "File may be malformed or inaccessible."
+                )
+
+        return (component_notes, connection_notes, infrastructure_notes)
+
+    def _analyze_compose_file(
+        self,
+        compose_file: Path,
+        compose_data: dict,
+        component_notes: list[str],
+        connection_notes: list[str],
+        infrastructure_notes: list[str],
+    ) -> None:
+        """Analyze a single Docker Compose file and generate observations."""
+        services = compose_data.get("services", {})
+
+        # High-level infrastructure observation
+        infrastructure_notes.append(
+            f"Found Docker Compose configuration at {compose_file.name} defining "
+            f"{len(services)} services. This suggests a containerized application "
+            f"architecture with orchestrated service dependencies."
+        )
+
+        # Analyze each service
+        for service_name, service_config in services.items():
+            self._analyze_service(
+                service_name,
+                service_config,
+                component_notes,
+                connection_notes,
+            )
+
+        # Analyze service dependencies
+        self._analyze_service_dependencies(services, connection_notes)
+
+        # Check for additional Docker Compose features
+        self._analyze_compose_features(compose_data, infrastructure_notes)
+
+    def _analyze_service(
+        self,
+        service_name: str,
+        service_config: dict,
+        component_notes: list[str],
+        _connection_notes: list[str],
+    ) -> None:
+        """Generate narrative observations for a single service."""
+        # Extract key configuration details
+        image = service_config.get("image", "")
+        build = service_config.get("build", "")
+        ports = self._extract_ports(service_config)
+
+        component_observation = (
+            f"Found '{service_name}' service in Docker Compose configuration."
+        )
+
+        # Add deployment details
+        if image:
+            component_observation += f" Service uses '{image}' Docker image"
+            if ":" in image:
+                tag = image.split(":")[-1]
+                component_observation += f" with tag '{tag}'"
+            component_observation += "."
+        elif build:
+            component_observation += f" Service builds from local source at '{build}'."
+
+        # Add port information
+        if ports:
+            port_list = ", ".join(str(p) for p in ports)
+            component_observation += f" Exposes ports {port_list}"
+            protocol_info = self._infer_protocol_description(ports)
+            if protocol_info:
+                component_observation += f" suggesting {protocol_info}"
+            component_observation += "."
+
+        component_notes.append(component_observation)
+
+    def _analyze_service_dependencies(  # noqa: PLR0912, C901
+        self, services: dict, connection_notes: list[str]
+    ) -> None:
+        """Analyze dependencies between services."""
+        for service_name, service_config in services.items():
+            depends_on = service_config.get("depends_on", [])
+
+            if isinstance(depends_on, dict):
+                dependencies = list(depends_on.keys())
+                condition_info = []
+                for dep, condition in depends_on.items():
+                    if isinstance(condition, dict) and "condition" in condition:
+                        condition_info.append(f"{dep} ({condition['condition']})")
+
+                if condition_info:
+                    connection_notes.append(
+                        f"Service '{service_name}' has conditional dependencies on "
+                        f"{', '.join(condition_info)}, indicating sophisticated "
+                        "startup orchestration with health checks."
+                    )
+                else:
+                    dependencies = list(depends_on.keys())
+            elif isinstance(depends_on, list):
+                dependencies = depends_on
+            else:
+                continue
+
+            if dependencies:
+                dep_list = "', '".join(dependencies)
+                connection_notes.append(
+                    f"Docker Compose 'depends_on' configuration shows '{service_name}' "
+                    f"requires '{dep_list}' to start first, indicating service startup "
+                    "dependency and likely runtime communication pattern."
+                )
+
+        # Check for communication patterns in environment variables
+        # and command arguments
+        service_names = {name for name, _ in services.items()}
+        # Track which connections we've already recorded to avoid duplicates
+        recorded_connections: set[tuple[str, str]] = set()
+
+        for service_name, service_config in services.items():
+            # Check environment variables
+            env = service_config.get("environment", [])
+            if isinstance(env, list):
+                for var in env:
+                    self._check_communication_pattern(
+                        var,
+                        service_name,
+                        service_names,
+                        "environment variable",
+                        connection_notes,
+                        recorded_connections,
+                    )
+            elif isinstance(env, dict):
+                for value in env.values():
+                    if isinstance(value, str):
+                        self._check_communication_pattern(
+                            value,
+                            service_name,
+                            service_names,
+                            "environment variable",
+                            connection_notes,
+                            recorded_connections,
+                        )
+
+            # Check command arguments
+            args = service_config.get("command", [])
+            if isinstance(args, list):
+                for arg in args:
+                    if isinstance(arg, str):
+                        self._check_communication_pattern(
+                            arg,
+                            service_name,
+                            service_names,
+                            "command argument",
+                            connection_notes,
+                            recorded_connections,
+                        )
+            elif isinstance(args, str):
+                self._check_communication_pattern(
+                    args,
+                    service_name,
+                    service_names,
+                    "command argument",
+                    connection_notes,
+                    recorded_connections,
+                )
+
+    def _check_communication_pattern(  # noqa: PLR0913
+        self,
+        text: str,
+        service_name: str,
+        service_names: set[str],
+        source_type: str,
+        connection_notes: list[str],
+        recorded_connections: set[tuple[str, str]],
+    ) -> None:
+        """Check if text contains communication patterns referencing other services."""
+        # Find all matches and extract hostnames from captured groups
+        matches = self.COMMUNICATION_PATTERN.finditer(text)
+        hostnames = set()
+
+        for match in matches:
+            # Group 1 contains the hostname
+            if match.group(1):
+                # Extract just the hostname (without port)
+                hostname = match.group(1).split(":")[0]
+                hostnames.add(hostname)
+
+        if not hostnames:
+            return
+
+        # Check if any extracted hostname matches a service name
+        for target_service in service_names:
+            if target_service == service_name:
+                continue
+
+            # Check if the target service is in the extracted hostnames
+            if target_service in hostnames:
+                connection_key = (service_name, target_service)
+                if connection_key not in recorded_connections:
+                    connection_notes.append(
+                        f"'{service_name}' has a communication address referencing "
+                        f"'{target_service}' in its {source_type}, indicating a "
+                        "direct runtime dependency."
+                    )
+                    recorded_connections.add(connection_key)
+                    break
+
+    def _analyze_compose_features(
+        self, compose_data: dict, infrastructure_notes: list[str]
+    ) -> None:
+        """Analyze additional Docker Compose features."""
+        # Check for networks
+        networks = compose_data.get("networks", {})
+        if networks:
+            infrastructure_notes.append(
+                f"Docker Compose defines {len(networks)} custom networks, "
+                "indicating network segmentation and controlled service communication."
+            )
+
+    def _extract_ports(self, service_config: dict) -> list[int]:
+        """Extract port numbers from service configuration."""
+        ports = []
+
+        # Extract from 'ports' section
+        port_specs = service_config.get("ports", [])
+        for port_spec in port_specs:
+            if isinstance(port_spec, str):
+                if ":" in port_spec:
+                    external_port = port_spec.split(":")[0]
+                    with contextlib.suppress(ValueError):
+                        ports.append(int(external_port))
+                else:
+                    with contextlib.suppress(ValueError):
+                        ports.append(int(port_spec))
+            elif isinstance(port_spec, int):
+                ports.append(port_spec)
+
+        # Extract from 'expose' section
+        expose_specs = service_config.get("expose", [])
+        for expose_spec in expose_specs:
+            with contextlib.suppress(ValueError, TypeError):
+                ports.append(int(expose_spec))
+
+        return sorted(set(ports))
+
+    def _infer_protocol_description(self, ports: list[int]) -> str:
+        """Infer protocol information from ports and return descriptive text."""
+        protocols = []
+
+        # HTTP ports
+        http_ports = {80, 8080, 3000, 4200, 5000, 8000, 8443, 443}
+        if any(port in http_ports for port in ports):
+            protocols.append("HTTP/HTTPS web traffic")
+
+        # gRPC ports
+        grpc_ports = {9090, 50051}
+        if any(port in grpc_ports for port in ports):
+            protocols.append("gRPC API communication")
+
+        # Cache/Redis ports
+        if 6379 in ports:
+            protocols.append("cache service")
+
+        # Database ports (excluding Redis which is handled above)
+        db_ports = {5432, 3306, 27017}
+        if any(port in db_ports for port in ports):
+            protocols.append("database service")
+
+        if protocols:
+            return " and ".join(protocols)
+        if ports:
+            return "TCP-based service communication"
+        return ""

kodit/infrastructure/physical_architecture/formatters/__init__.py

@@ -0,0 +1 @@
+"""Formatters for converting architecture observations to LLM-optimized text."""