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

kodit/domain/enrichments/architecture/physical/discovery_notes.py

@@ -0,0 +1,14 @@
+"""Physical architecture domain value objects."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ArchitectureDiscoveryNotes:
+    """Rich, narrative observations about repository architecture for LLM consumption."""  # noqa: E501
+
+    repository_context: str  # High-level overview and discovery scope
+    component_observations: list[str]  # Detailed findings about each component
+    connection_observations: list[str]  # How components interact and communicate
+    infrastructure_observations: list[str]  # Deployment, config, operational patterns
+    discovery_metadata: str  # Methodology, confidence, limitations, timestamp

kodit/domain/enrichments/architecture/physical/formatter.py

@@ -0,0 +1,11 @@
+"""Physical architecture formatter protocol."""
+
+from typing import Any, Protocol
+
+
+class PhysicalArchitectureFormatter(Protocol):
+    """Formatter for converting architecture discovery notes to LLM-optimized text."""
+
+    def format_for_llm(self, notes: Any) -> str:
+        """Format architecture discovery notes for LLM consumption."""
+        ...

kodit/domain/enrichments/architecture/physical/physical.py

@@ -0,0 +1,17 @@
+"""Physical architecture enrichment domain entity."""
+
+from dataclasses import dataclass
+
+from kodit.domain.enrichments.architecture.architecture import ArchitectureEnrichment
+
+ENRICHMENT_SUBTYPE_PHYSICAL = "physical"
+
+
+@dataclass
+class PhysicalArchitectureEnrichment(ArchitectureEnrichment):
+    """Enrichment containing physical architecture discovery for a commit."""
+
+    @property
+    def subtype(self) -> str | None:
+        """Return the enrichment subtype."""
+        return ENRICHMENT_SUBTYPE_PHYSICAL

kodit/domain/enrichments/development/__init__.py

@@ -0,0 +1 @@
+"""Development enrichment package."""

kodit/domain/enrichments/development/development.py

@@ -0,0 +1,18 @@
+"""Development enrichment domain entity."""
+
+from abc import ABC
+from dataclasses import dataclass
+
+from kodit.domain.enrichments.enrichment import CommitEnrichment
+
+ENRICHMENT_TYPE_DEVELOPMENT = "development"
+
+
+@dataclass
+class DevelopmentEnrichment(CommitEnrichment, ABC):
+    """Enrichment containing development discovery for a commit."""
+
+    @property
+    def type(self) -> str:
+        """Return the enrichment type."""
+        return ENRICHMENT_TYPE_DEVELOPMENT

kodit/domain/enrichments/development/snippet/__init__.py

@@ -0,0 +1 @@
+"""Snippet enrichment package."""

kodit/domain/enrichments/development/snippet/snippet.py

@@ -0,0 +1,21 @@
+"""Snippet enrichment domain entity."""
+
+from dataclasses import dataclass
+
+from kodit.domain.enrichments.development.development import DevelopmentEnrichment
+
+ENRICHMENT_SUBTYPE_SNIPPET_SUMMARY = "snippet_summary"
+
+
+@dataclass
+class SnippetEnrichment(DevelopmentEnrichment):
+    """Enrichment specific to code snippets."""
+
+    @property
+    def subtype(self) -> str | None:
+        """Return the enrichment subtype."""
+        return ENRICHMENT_SUBTYPE_SNIPPET_SUMMARY
+
+    def entity_type_key(self) -> str:
+        """Return the entity type key this enrichment is for."""
+        return "snippet_v2"

kodit/domain/enrichments/enricher.py

@@ -0,0 +1,17 @@
+"""Enricher interface."""
+
+from collections.abc import AsyncGenerator
+from typing import Protocol
+
+from kodit.domain.enrichments.request import EnrichmentRequest
+from kodit.domain.enrichments.response import EnrichmentResponse
+
+
+class Enricher(Protocol):
+    """Interface for text enrichment with custom prompts."""
+
+    def enrich(
+        self, requests: list[EnrichmentRequest]
+    ) -> AsyncGenerator[EnrichmentResponse, None]:
+        """Enrich a list of requests with custom system prompts."""
+        ...

kodit/domain/enrichments/enrichment.py

@@ -0,0 +1,39 @@
+"""Enrichment domain entities."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class EnrichmentV2(ABC):
+    """Generic enrichment that can be attached to any entity."""
+
+    entity_id: str
+    content: str = ""
+    id: int | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    @property
+    @abstractmethod
+    def type(self) -> str:
+        """Return the enrichment type."""
+
+    @property
+    @abstractmethod
+    def subtype(self) -> str | None:
+        """Return the enrichment subtype (optional for hierarchical types)."""
+
+    @abstractmethod
+    def entity_type_key(self) -> str:
+        """Return the entity type key this enrichment is for."""
+
+
+@dataclass
+class CommitEnrichment(EnrichmentV2, ABC):
+    """Enrichment specific to commits."""
+
+    def entity_type_key(self) -> str:
+        """Return the entity type key this enrichment is for."""
+        return "git_commit"

kodit/domain/enrichments/request.py

@@ -0,0 +1,12 @@
+"""Generic enrichment request value object."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class EnrichmentRequest:
+    """Domain model for generic enrichment request with custom prompt."""
+
+    id: str
+    text: str
+    system_prompt: str

kodit/domain/enrichments/response.py

@@ -0,0 +1,11 @@
+"""Generic enrichment response value object."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class EnrichmentResponse:
+    """Domain model for generic enrichment response."""
+
+    id: str
+    text: str

kodit/domain/enrichments/usage/__init__.py

@@ -0,0 +1 @@
+"""Usage enrichment domain entities."""

kodit/domain/enrichments/usage/api_docs.py

@@ -0,0 +1,19 @@
+"""API documentation enrichment entity."""
+
+from dataclasses import dataclass
+
+from kodit.domain.enrichments.usage.usage import UsageEnrichment
+
+ENRICHMENT_SUBTYPE_API_DOCS = "api_docs"
+
+
+@dataclass
+class APIDocEnrichment(UsageEnrichment):
+    """API documentation enrichment for a module."""
+
+    language: str = ""
+
+    @property
+    def subtype(self) -> str | None:
+        """Return the enrichment subtype."""
+        return ENRICHMENT_SUBTYPE_API_DOCS

kodit/domain/enrichments/usage/usage.py

@@ -0,0 +1,18 @@
+"""Usage enrichment domain entity."""
+
+from abc import ABC
+from dataclasses import dataclass
+
+from kodit.domain.enrichments.enrichment import CommitEnrichment
+
+ENRICHMENT_TYPE_USAGE = "usage"
+
+
+@dataclass
+class UsageEnrichment(CommitEnrichment, ABC):
+    """Enrichment containing development discovery for a commit."""
+
+    @property
+    def type(self) -> str:
+        """Return the enrichment type."""
+        return ENRICHMENT_TYPE_USAGE

kodit/domain/protocols.py

@@ -217,7 +217,6 @@ class GitRepoRepository(ABC):
         """Delete a repository."""
 
 
-
 class GitAdapter(ABC):
     """Abstract interface for Git operations."""
 
@@ -225,10 +224,6 @@ class GitAdapter(ABC):
     async def clone_repository(self, remote_uri: str, local_path: Path) -> None:
         """Clone a repository to local path."""
 
-    @abstractmethod
-    async def checkout_commit(self, local_path: Path, commit_sha: str) -> None:
-        """Checkout a specific commit in the repository."""
-
     @abstractmethod
     async def pull_repository(self, local_path: Path) -> None:
         """Pull latest changes for existing repository."""
@@ -247,7 +242,13 @@ class GitAdapter(ABC):
     async def get_commit_files(
         self, local_path: Path, commit_sha: str
     ) -> list[dict[str, Any]]:
-        """Get all files in a specific commit."""
+        """Get all files in a specific commit from the git tree."""
+
+    @abstractmethod
+    async def get_commit_file_data(
+        self, local_path: Path, commit_sha: str
+    ) -> list[dict[str, Any]]:
+        """Get file metadata for a commit, with files checked out to disk."""
 
     @abstractmethod
     async def repository_exists(self, local_path: Path) -> bool:

kodit/domain/services/enrichment_service.py

@@ -1,48 +1,27 @@
 """Domain service for enrichment operations."""
 
-from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator
 
-from kodit.domain.value_objects import (
-    EnrichmentIndexRequest,
-    EnrichmentRequest,
-    EnrichmentResponse,
-)
-
-
-class EnrichmentProvider(ABC):
-    """Abstract enrichment provider interface."""
-
-    @abstractmethod
-    def enrich(
-        self, requests: list[EnrichmentRequest]
-    ) -> AsyncGenerator[EnrichmentResponse, None]:
-        """Enrich a list of requests."""
+from kodit.domain.enrichments.enricher import Enricher
+from kodit.domain.enrichments.request import EnrichmentRequest
+from kodit.domain.enrichments.response import EnrichmentResponse
 
 
 class EnrichmentDomainService:
     """Domain service for enrichment operations."""
 
-    def __init__(self, enrichment_provider: EnrichmentProvider) -> None:
-        """Initialize the enrichment domain service.
-
-        Args:
-            enrichment_provider: The enrichment provider to use.
-
-        """
-        self.enrichment_provider = enrichment_provider
+    def __init__(self, enricher: Enricher) -> None:
+        """Initialize the enrichment domain service."""
+        self.enricher = enricher
 
     async def enrich_documents(
-        self, request: EnrichmentIndexRequest
+        self, requests: list[EnrichmentRequest]
     ) -> AsyncGenerator[EnrichmentResponse, None]:
-        """Enrich documents using the enrichment provider.
-
-        Args:
-            request: The enrichment index request.
+        """Enrich documents using the enricher.
 
         Yields:
             Enrichment responses as they are processed.
 
         """
-        async for response in self.enrichment_provider.enrich(request.requests):
+        async for response in self.enricher.enrich(requests):
             yield response

kodit/domain/services/physical_architecture_service.py

@@ -0,0 +1,182 @@
+"""Core service for discovering physical architecture and generating narrative observations."""  # noqa: E501
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from kodit.domain.enrichments.architecture.physical.discovery_notes import (
+    ArchitectureDiscoveryNotes,
+)
+from kodit.domain.enrichments.architecture.physical.formatter import (
+    PhysicalArchitectureFormatter,
+)
+from kodit.infrastructure.physical_architecture.detectors import docker_compose_detector
+
+ARCHITECTURE_ENRICHMENT_SYSTEM_PROMPT = """You are an expert software architect.
+Deliver the user's request succinctly.
+"""
+
+ARCHITECTURE_ENRICHMENT_TASK_PROMPT = """Convert the raw architecture discovery logs
+into a clean, structured summary written in markdown.
+
+<architecture_narrative>
+{architecture_narrative}
+</architecture_narrative>
+
+**Return the following information**
+
+## Services List
+
+For each service, write one line:
+- **[Service Name]**: [what it does] | Tech: [technology] | Ports: [ports]
+
+## Service Dependencies
+
+List the important connections:
+- [Service A] → [Service B]: [why they connect]
+
+## Mermaid Diagram
+
+Output a Mermaid diagram depicting the architecture using the names of the services and
+the ports that they expose.
+
+## Key Information
+
+Answer these questions in 1-2 sentences each:
+1. What databases are used and for what?
+2. What are the critical services that everything else depends on?
+3. Are there any unusual communication patterns between services that people should be
+aware of? (e.g. a different direction to what you'd expect)
+
+## Rules:
+- Skip duplicate services (keep only one instance)
+- Don't list environment variables
+- Don't describe Docker volumes in detail
+- Focus on WHAT each service does, not HOW it's configured
+- If a service name is unclear, make your best guess based on the information
+- Keep descriptions to 10 words or less per service
+"""
+
+
+class PhysicalArchitectureService:
+    """Core service for discovering physical architecture and generating narrative observations."""  # noqa: E501
+
+    def __init__(self, formatter: PhysicalArchitectureFormatter) -> None:
+        """Initialize the service with detectors and formatter."""
+        self.docker_detector = docker_compose_detector.DockerComposeDetector()
+        self.formatter = formatter
+
+    async def discover_architecture(self, repo_path: Path) -> str:
+        """Discover physical architecture and generate rich narrative observations."""
+        # Generate repository context overview
+        repo_context = await self._analyze_repository_context(repo_path)
+
+        # Collect observations from all detectors
+        component_notes = []
+        connection_notes = []
+        infrastructure_notes = []
+
+        # Run detectors and collect narrative observations
+        (
+            docker_component_notes,
+            docker_connection_notes,
+            docker_infrastructure_notes,
+        ) = await self.docker_detector.analyze(repo_path)
+        component_notes.extend(docker_component_notes)
+        connection_notes.extend(docker_connection_notes)
+        infrastructure_notes.extend(docker_infrastructure_notes)
+
+        # Future: Add Kubernetes and code structure detectors when available
+
+        # Generate discovery metadata
+        discovery_metadata = self._generate_discovery_metadata(repo_path)
+
+        # Create comprehensive notes
+        notes = ArchitectureDiscoveryNotes(
+            repository_context=repo_context,
+            component_observations=component_notes,
+            connection_observations=connection_notes,
+            infrastructure_observations=infrastructure_notes,
+            discovery_metadata=discovery_metadata,
+        )
+
+        return self.formatter.format_for_llm(notes)
+
+    async def _analyze_repository_context(self, repo_path: Path) -> str:
+        """Generate high-level repository context and scope."""
+        context_observations = []
+
+        # Check for basic repository structure
+        context_observations.append(f"Analyzing repository at {repo_path}")
+
+        # Check for common project indicators
+        has_docker_compose = bool(
+            list(repo_path.glob("docker-compose*.yml"))
+            + list(repo_path.glob("docker-compose*.yaml"))
+        )
+        has_dockerfile = bool(list(repo_path.glob("Dockerfile*")))
+        has_k8s = bool(
+            list(repo_path.glob("**/k8s/**/*.yaml"))
+            + list(repo_path.glob("**/kubernetes/**/*.yaml"))
+        )
+        has_package_json = (repo_path / "package.json").exists()
+        has_requirements_txt = (repo_path / "requirements.txt").exists()
+        has_go_mod = (repo_path / "go.mod").exists()
+
+        # Determine likely project type
+        project_indicators = []
+        if has_docker_compose:
+            project_indicators.append("Docker Compose orchestration")
+        if has_dockerfile:
+            project_indicators.append("containerized deployment")
+        if has_k8s:
+            project_indicators.append("Kubernetes deployment")
+        if has_package_json:
+            project_indicators.append("Node.js/JavaScript components")
+        if has_requirements_txt:
+            project_indicators.append("Python components")
+        if has_go_mod:
+            project_indicators.append("Go components")
+
+        if project_indicators:
+            context_observations.append(
+                f"Repository shows evidence of {', '.join(project_indicators)}, "
+                "suggesting a modern containerized application architecture."
+            )
+        else:
+            context_observations.append(
+                "Repository structure analysis shows limited infrastructure configuration. "  # noqa: E501
+                "This may be a simple application or library without complex deployment requirements."  # noqa: E501
+            )
+
+        return " ".join(context_observations)
+
+    def _generate_discovery_metadata(self, _repo_path: Path) -> str:
+        """Document discovery methodology, confidence, and limitations."""
+        timestamp = datetime.now(UTC).isoformat()
+
+        metadata_parts = [
+            f"Analysis completed on {timestamp} using physical architecture discovery system version 1.0.",  # noqa: E501
+            "Discovery methodology: Docker Compose parsing and infrastructure configuration analysis.",  # noqa: E501
+        ]
+
+        # Document detection sources used
+        sources_used = ["Docker Compose file analysis"]
+        # Future: Add Kubernetes manifest and code analysis sources
+
+        metadata_parts.append(f"Detection sources: {', '.join(sources_used)}.")
+
+        # Document confidence levels
+        metadata_parts.append(
+            "Confidence levels: High confidence for infrastructure-defined components, "
+            "medium confidence for inferred roles based on naming and configuration patterns."  # noqa: E501
+        )
+
+        # Document limitations
+        limitations = [
+            "analysis limited to Docker Compose configurations",
+            "code-level analysis not yet implemented",
+            "runtime behavior patterns not captured",
+        ]
+        metadata_parts.append(f"Current limitations: {', '.join(limitations)}.")
+
+        return " ".join(metadata_parts)

kodit/domain/tracking/__init__.py

@@ -0,0 +1 @@
+"""Tracking domain module."""

kodit/domain/tracking/resolution_service.py

@@ -0,0 +1,81 @@
+"""Domain service for resolving trackables to commits."""
+
+import structlog
+
+from kodit.domain.protocols import (
+    GitBranchRepository,
+    GitCommitRepository,
+    GitTagRepository,
+)
+from kodit.domain.tracking.trackable import Trackable, TrackableReferenceType
+
+
+class TrackableResolutionService:
+    """Resolves trackables to ordered lists of commits.
+
+    This is a domain service because it orchestrates multiple aggregates
+    (branches, tags, commits) without belonging to any single entity.
+    """
+
+    def __init__(
+        self,
+        commit_repo: GitCommitRepository,
+        branch_repo: GitBranchRepository,
+        tag_repo: GitTagRepository,
+    ) -> None:
+        """Initialize the trackable resolution service."""
+        self.commit_repo = commit_repo
+        self.branch_repo = branch_repo
+        self.tag_repo = tag_repo
+        self.log = structlog.get_logger(__name__)
+
+    async def resolve_to_commits(
+        self, trackable: Trackable, limit: int = 100
+    ) -> list[str]:
+        """Resolve a trackable to an ordered list of commit SHAs.
+
+        Returns commits from newest to oldest based on git history.
+        """
+        if trackable.type == TrackableReferenceType.BRANCH:
+            return await self._resolve_branch(trackable, limit)
+        if trackable.type == TrackableReferenceType.TAG:
+            return await self._resolve_tag(trackable, limit)
+        # COMMIT_SHA
+        return [trackable.identifier]
+
+    async def _resolve_branch(
+        self, trackable: Trackable, limit: int
+    ) -> list[str]:
+        """Get commits from branch HEAD backwards through history."""
+        branch = await self.branch_repo.get_by_name(
+            trackable.identifier, trackable.repo_id
+        )
+        # Walk commit history from head_commit backwards
+        return await self._walk_commit_history(
+            branch.head_commit.commit_sha, limit
+        )
+
+    async def _resolve_tag(self, trackable: Trackable, limit: int) -> list[str]:
+        """Get commits from tag target backwards through history."""
+        tag = await self.tag_repo.get_by_name(
+            trackable.identifier, trackable.repo_id
+        )
+        return await self._walk_commit_history(
+            tag.target_commit.commit_sha, limit
+        )
+
+    async def _walk_commit_history(
+        self, start_sha: str, limit: int
+    ) -> list[str]:
+        """Walk commit history backwards from start_sha."""
+        result = []
+        current_sha: str | None = start_sha
+
+        for _ in range(limit):
+            if not current_sha:
+                break
+            result.append(current_sha)
+            commit = await self.commit_repo.get_by_sha(current_sha)
+            current_sha = commit.parent_commit_sha or None
+
+        return result

kodit/domain/tracking/trackable.py

@@ -0,0 +1,21 @@
+"""Trackable value objects."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class TrackableReferenceType(StrEnum):
+    """Types of git references that can be tracked."""
+
+    BRANCH = "branch"
+    TAG = "tag"
+    COMMIT_SHA = "commit_sha"
+
+
+@dataclass(frozen=True)
+class Trackable:
+    """Represents a trackable reference point in a git repository."""
+
+    type: TrackableReferenceType
+    identifier: str  # e.g., "main", "v1.0.0", "abc123..."
+    repo_id: int

kodit/domain/value_objects.py

@@ -346,29 +346,6 @@ class EmbeddingResponse:
     embedding: list[float]
 
 
-@dataclass
-class EnrichmentRequest:
-    """Domain model for enrichment request."""
-
-    snippet_id: str
-    text: str
-
-
-@dataclass
-class EnrichmentResponse:
-    """Domain model for enrichment response."""
-
-    snippet_id: str
-    text: str
-
-
-@dataclass
-class EnrichmentIndexRequest:
-    """Domain model for enrichment index request."""
-
-    requests: list[EnrichmentRequest]
-
-
 @dataclass
 class IndexView:
     """Domain model for index information."""
@@ -640,6 +617,10 @@ class TaskOperation(StrEnum):
     CREATE_CODE_EMBEDDINGS_FOR_COMMIT = "kodit.commit.create_code_embeddings"
     CREATE_SUMMARY_ENRICHMENT_FOR_COMMIT = "kodit.commit.create_summary_enrichment"
     CREATE_SUMMARY_EMBEDDINGS_FOR_COMMIT = "kodit.commit.create_summary_embeddings"
+    CREATE_ARCHITECTURE_ENRICHMENT_FOR_COMMIT = (
+        "kodit.commit.create_architecture_enrichment"
+    )
+    CREATE_PUBLIC_API_DOCS_FOR_COMMIT = "kodit.commit.create_public_api_docs"
 
     def is_repository_operation(self) -> bool:
         """Check if the task operation is a repository operation."""
@@ -663,6 +644,8 @@ class PrescribedOperations:
         TaskOperation.CREATE_CODE_EMBEDDINGS_FOR_COMMIT,
         TaskOperation.CREATE_SUMMARY_ENRICHMENT_FOR_COMMIT,
         TaskOperation.CREATE_SUMMARY_EMBEDDINGS_FOR_COMMIT,
+        TaskOperation.CREATE_ARCHITECTURE_ENRICHMENT_FOR_COMMIT,
+        TaskOperation.CREATE_PUBLIC_API_DOCS_FOR_COMMIT,
     ]
     SYNC_REPOSITORY: ClassVar[list[TaskOperation]] = [
         TaskOperation.SCAN_REPOSITORY,