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

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/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,

kodit/infrastructure/api/v1/routers/commits.py

@@ -22,6 +22,11 @@ from kodit.infrastructure.api.v1.schemas.commit import (
     FileListResponse,
     FileResponse,
 )
+from kodit.infrastructure.api.v1.schemas.enrichment import (
+    EnrichmentAttributes,
+    EnrichmentData,
+    EnrichmentListResponse,
+)
 from kodit.infrastructure.api.v1.schemas.snippet import (
     EnrichmentSchema,
     GitFileSchema,
@@ -269,3 +274,79 @@ async def list_commit_embeddings(
             for embedding in embeddings
         ]
     )
+
+
+@router.get(
+    "/{repo_id}/commits/{commit_sha}/enrichments",
+    summary="List commit enrichments",
+    responses={404: {"description": "Repository or commit not found"}},
+)
+async def list_commit_enrichments(
+    repo_id: str,  # noqa: ARG001
+    commit_sha: str,
+    server_factory: ServerFactoryDep,
+) -> EnrichmentListResponse:
+    """List all enrichments for a specific commit."""
+    # TODO(Phil): Should use repo too, it's confusing to the user when they specify the
+    # wrong commit and another repo. It's like they are seeing results from the other
+    # repo.
+    enrichment_v2_repository = server_factory.enrichment_v2_repository()
+    enrichments = await enrichment_v2_repository.enrichments_for_entity_type(
+        entity_type="git_commit",
+        entity_ids=[commit_sha],
+    )
+
+    return EnrichmentListResponse(
+        data=[
+            EnrichmentData(
+                type="enrichment",
+                id=str(enrichment.id),
+                attributes=EnrichmentAttributes(
+                    type=enrichment.type,
+                    subtype=enrichment.subtype,
+                    content=enrichment.content,
+                    created_at=enrichment.created_at,
+                    updated_at=enrichment.updated_at,
+                ),
+            )
+            for enrichment in enrichments
+        ]
+    )
+
+
+@router.delete(
+    "/{repo_id}/commits/{commit_sha}/enrichments",
+    summary="Delete all commit enrichments",
+    responses={404: {"description": "Commit not found"}},
+    status_code=204,
+)
+async def delete_all_commit_enrichments(
+    repo_id: str,  # noqa: ARG001
+    commit_sha: str,
+    server_factory: ServerFactoryDep,
+) -> None:
+    """Delete all enrichments for a specific commit."""
+    enrichment_v2_repository = server_factory.enrichment_v2_repository()
+    await enrichment_v2_repository.bulk_delete_enrichments(
+        entity_type="git_commit",
+        entity_ids=[commit_sha],
+    )
+
+
+@router.delete(
+    "/{repo_id}/commits/{commit_sha}/enrichments/{enrichment_id}",
+    summary="Delete commit enrichment",
+    responses={404: {"description": "Enrichment not found"}},
+    status_code=204,
+)
+async def delete_commit_enrichment(
+    repo_id: str,  # noqa: ARG001
+    commit_sha: str,  # noqa: ARG001
+    enrichment_id: int,
+    server_factory: ServerFactoryDep,
+) -> None:
+    """Delete a specific enrichment for a commit."""
+    enrichment_v2_repository = server_factory.enrichment_v2_repository()
+    deleted = await enrichment_v2_repository.delete_enrichment(enrichment_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Enrichment not found")

kodit/infrastructure/api/v1/schemas/enrichment.py

@@ -0,0 +1,29 @@
+"""Enrichment JSON-API schemas."""
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class EnrichmentAttributes(BaseModel):
+    """Enrichment attributes following JSON-API spec."""
+
+    type: str
+    subtype: str | None
+    content: str
+    created_at: datetime | None
+    updated_at: datetime | None
+
+
+class EnrichmentData(BaseModel):
+    """Enrichment data following JSON-API spec."""
+
+    type: str = "enrichment"
+    id: str
+    attributes: EnrichmentAttributes
+
+
+class EnrichmentListResponse(BaseModel):
+    """Enrichment list response following JSON-API spec."""
+
+    data: list[EnrichmentData]

kodit/infrastructure/cloning/git/git_python_adaptor.py

@@ -101,8 +101,11 @@ class GitPythonAdapter(GitAdapter):
 
         await asyncio.get_event_loop().run_in_executor(self.executor, _clone)
 
-    async def checkout_commit(self, local_path: Path, commit_sha: str) -> None:
-        """Checkout a specific commit in the repository."""
+    async def _checkout_commit(self, local_path: Path, commit_sha: str) -> None:
+        """Checkout a specific commit internally.
+
+        Private method - external callers should not mutate repository state directly.
+        """
 
         def _checkout() -> None:
             try:
@@ -116,6 +119,52 @@ class GitPythonAdapter(GitAdapter):
 
         await asyncio.get_event_loop().run_in_executor(self.executor, _checkout)
 
+    async def restore_to_branch(
+        self, local_path: Path, branch_name: str = "main"
+    ) -> None:
+        """Restore repository to a specific branch, recovering from detached HEAD.
+
+        Args:
+            local_path: Path to the repository
+            branch_name: Branch to restore to (default: "main")
+
+        """
+
+        def _restore() -> None:
+            try:
+                repo = Repo(local_path)
+
+                # Try to checkout the requested branch
+                try:
+                    repo.git.checkout(branch_name)
+                except Exception:  # noqa: BLE001
+                    # If requested branch doesn't exist, try common default branches
+                    for fallback in ["master", "develop"]:
+                        try:
+                            repo.git.checkout(fallback)
+                        except Exception:  # noqa: BLE001
+                            # Branch doesn't exist, try next fallback
+                            self._log.debug(f"Branch {fallback} not found, trying next")
+                        else:
+                            self._log.debug(
+                                f"Branch {branch_name} not found, "
+                                f"restored to {fallback} instead"
+                            )
+                            return
+
+                    # If all branches fail, stay in detached state
+                    self._log.warning(
+                        f"Could not restore to any branch in {local_path}, "
+                        f"repository remains in detached HEAD state"
+                    )
+                else:
+                    self._log.debug(f"Restored repository to branch {branch_name}")
+            except Exception as e:
+                self._log.error(f"Failed to restore branch in {local_path}: {e}")
+                raise
+
+        await asyncio.get_event_loop().run_in_executor(self.executor, _restore)
+
     async def pull_repository(self, local_path: Path) -> None:
         """Pull latest changes for existing repository."""
 
@@ -139,12 +188,20 @@ class GitPythonAdapter(GitAdapter):
                 repo = Repo(local_path)
 
                 # Get local branches
+                # Check if HEAD is detached
+                try:
+                    active_branch = repo.active_branch
+                except TypeError:
+                    # HEAD is detached, no active branch
+                    active_branch = None
+
                 branches = [
                     {
                         "name": branch.name,
                         "type": "local",
                         "head_commit_sha": branch.commit.hexsha,
-                        "is_active": branch == repo.active_branch,
+                        "is_active": active_branch is not None
+                        and branch == active_branch,
                     }
                     for branch in repo.branches
                 ]
@@ -291,7 +348,7 @@ class GitPythonAdapter(GitAdapter):
     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."""
 
         def _get_files() -> list[dict[str, Any]]:
             try:
@@ -332,6 +389,16 @@ class GitPythonAdapter(GitAdapter):
 
         return await asyncio.get_event_loop().run_in_executor(self.executor, _get_files)
 
+    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."""
+        await self._checkout_commit(local_path, commit_sha)
+        try:
+            return await self.get_commit_files(local_path, commit_sha)
+        finally:
+            await self.restore_to_branch(local_path, "main")
+
     async def repository_exists(self, local_path: Path) -> bool:
         """Check if repository exists at local path."""
 

kodit/infrastructure/enricher/__init__.py

@@ -0,0 +1 @@
+"""Generic enricher infrastructure implementations."""