kodit 0.5.1__tar.gz → 0.5.3__tar.gz

{kodit-0.5.1 → kodit-0.5.3}/.github/workflows/test.yaml

@@ -39,6 +39,7 @@ jobs:
         run: make no-database-changes-check
 
       - name: API Doc check
+        if: "!startsWith(github.ref, 'refs/tags/')"
         run: make docs-check
 
       - name: Run tests

{kodit-0.5.1 → kodit-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kodit
-Version: 0.5.1
+Version: 0.5.3
 Summary: Code indexing for better AI code generation
 Project-URL: Homepage, https://docs.helixml.tech/kodit/
 Project-URL: Documentation, https://docs.helixml.tech/kodit/

{kodit-0.5.1 → kodit-0.5.3}/docs/reference/api/index.md

@@ -12,7 +12,7 @@ look at the [hosted version](https://kodit.helix.ml/docs).
 This is the REST API for the Kodit server. Please refer to the
 [Kodit documentation](https://docs.helix.ml/kodit/) for more information.
     
-Current version: 0.5.1
+Current version: 0.5.2
 
 ## Authentication
 
@@ -516,6 +516,42 @@ Get a specific tag for a repository.
 
 - 404: Repository or tag not found
 
+### GET /api/v1/repositories/{repo_id}/enrichments
+
+List the most recent enrichments for a repository.
+
+Query parameters:
+- ref_type: Type of reference (branch, tag, or commit_sha). Defaults to "branch".
+- ref_name: Name of the reference. For branches, defaults to the tracking branch.
+- enrichment_type: Optional filter for specific enrichment type.
+- limit: Maximum number of enrichments to return. Defaults to 10.
+
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| repo_id | string | True |  |
+| ref_type | string | False |  |
+| ref_name |  | False |  |
+| enrichment_type |  | False |  |
+| limit | integer | False |  |
+
+
+#### Responses
+
+- 200: Successful Response
+
+[EnrichmentListResponse](#enrichmentlistresponse)
+
+- 500: Internal server error
+
+- 401: Unauthorized
+
+- 422: Invalid request
+
+- 404: Repository not found
+
 ## Components
 
 

{kodit-0.5.1 → kodit-0.5.3}/docs/reference/api/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "kodit API",
     "description": "\nThis is the REST API for the Kodit server. Please refer to the\n[Kodit documentation](https://docs.helix.ml/kodit/) for more information.\n    ",
-    "version": "0.5.1"
+    "version": "0.5.2"
   },
   "paths": {
     "/healthz": {
@@ -1034,6 +1034,108 @@
           }
         }
       }
+    },
+    "/api/v1/repositories/{repo_id}/enrichments": {
+      "get": {
+        "tags": [
+          "repositories"
+        ],
+        "summary": "List latest repository enrichments",
+        "description": "List the most recent enrichments for a repository.\n\nQuery parameters:\n- ref_type: Type of reference (branch, tag, or commit_sha). Defaults to \"branch\".\n- ref_name: Name of the reference. For branches, defaults to the tracking branch.\n- enrichment_type: Optional filter for specific enrichment type.\n- limit: Maximum number of enrichments to return. Defaults to 10.",
+        "operationId": "list_repository_enrichments_api_v1_repositories__repo_id__enrichments_get",
+        "security": [
+          {
+            "Header (X-API-KEY)": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "repo_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Repo Id"
+            }
+          },
+          {
+            "name": "ref_type",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "default": "branch",
+              "title": "Ref Type"
+            }
+          },
+          {
+            "name": "ref_name",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Ref Name"
+            }
+          },
+          {
+            "name": "enrichment_type",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Enrichment Type"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 10,
+              "title": "Limit"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EnrichmentListResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "422": {
+            "description": "Invalid request"
+          },
+          "404": {
+            "description": "Repository not found"
+          }
+        }
+      }
     }
   },
   "components": {

{kodit-0.5.1 → kodit-0.5.3}/docs/reference/configuration/index.md

@@ -24,6 +24,9 @@ Global context for the kodit project. Provides a shared state for the app.
 | `EMBEDDING_ENDPOINT_NUM_PARALLEL_TASKS` | int | `10` | Number of parallel tasks to use for the endpoint |
 | `EMBEDDING_ENDPOINT_SOCKET_PATH` | `str | None` | `None` | Unix socket path for local communication (e.g., /tmp/openai.sock) |
 | `EMBEDDING_ENDPOINT_TIMEOUT` | float | `60` | Request timeout in seconds |
+| `EMBEDDING_ENDPOINT_MAX_RETRIES` | int | `5` | Maximum number of retries for the endpoint |
+| `EMBEDDING_ENDPOINT_INITIAL_DELAY` | float | `2.0` | Initial delay in seconds for the endpoint |
+| `EMBEDDING_ENDPOINT_BACKOFF_FACTOR` | float | `2.0` | Backoff factor for the endpoint |
 | `EMBEDDING_ENDPOINT_EXTRA_PARAMS` | `dict | None` | `None` | Extra provider-specific non-secret parameters for LiteLLM |
 | `EMBEDDING_ENDPOINT_MAX_TOKENS` | int | `8000` | Conservative token limit for the embedding model |
 | `ENRICHMENT_ENDPOINT` | `Endpoint | None` | `None` | Endpoint to use for enrichment. |
@@ -33,6 +36,9 @@ Global context for the kodit project. Provides a shared state for the app.
 | `ENRICHMENT_ENDPOINT_NUM_PARALLEL_TASKS` | int | `10` | Number of parallel tasks to use for the endpoint |
 | `ENRICHMENT_ENDPOINT_SOCKET_PATH` | `str | None` | `None` | Unix socket path for local communication (e.g., /tmp/openai.sock) |
 | `ENRICHMENT_ENDPOINT_TIMEOUT` | float | `60` | Request timeout in seconds |
+| `ENRICHMENT_ENDPOINT_MAX_RETRIES` | int | `5` | Maximum number of retries for the endpoint |
+| `ENRICHMENT_ENDPOINT_INITIAL_DELAY` | float | `2.0` | Initial delay in seconds for the endpoint |
+| `ENRICHMENT_ENDPOINT_BACKOFF_FACTOR` | float | `2.0` | Backoff factor for the endpoint |
 | `ENRICHMENT_ENDPOINT_EXTRA_PARAMS` | `dict | None` | `None` | Extra provider-specific non-secret parameters for LiteLLM |
 | `ENRICHMENT_ENDPOINT_MAX_TOKENS` | int | `8000` | Conservative token limit for the embedding model |
 | `DEFAULT_SEARCH` | Search | `provider='sqlite'` |  |

{kodit-0.5.1 → kodit-0.5.3}/src/kodit/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.5.1'
-__version_tuple__ = version_tuple = (0, 5, 1)
+__version__ = version = '0.5.3'
+__version_tuple__ = version_tuple = (0, 5, 3)
 
 __commit_id__ = commit_id = None

{kodit-0.5.1 → kodit-0.5.3}/src/kodit/application/factories/server_factory.py

@@ -1,7 +1,6 @@
 """Create a big object that contains all the application services."""
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING
 
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -12,6 +11,9 @@ from kodit.application.services.code_search_application_service import (
 from kodit.application.services.commit_indexing_application_service import (
     CommitIndexingApplicationService,
 )
+from kodit.application.services.enrichment_query_service import (
+    EnrichmentQueryService,
+)
 from kodit.application.services.queue_service import QueueService
 from kodit.application.services.reporting import ProgressTracker
 from kodit.application.services.sync_scheduler import SyncSchedulerService
@@ -39,6 +41,7 @@ from kodit.domain.services.git_repository_service import (
 from kodit.domain.services.physical_architecture_service import (
     PhysicalArchitectureService,
 )
+from kodit.domain.tracking.resolution_service import TrackableResolutionService
 from kodit.infrastructure.bm25.local_bm25_repository import LocalBM25Repository
 from kodit.infrastructure.bm25.vectorchord_bm25_repository import (
     VectorChordBM25Repository,
@@ -82,9 +85,6 @@ from kodit.infrastructure.sqlalchemy.task_status_repository import (
 )
 from kodit.infrastructure.sqlalchemy.unit_of_work import SqlAlchemyUnitOfWork
 
-if TYPE_CHECKING:
-    from kodit.domain.services.enrichment_service import EnrichmentDomainService
-
 
 class ServerFactory:
     """Factory for creating server application services."""
@@ -105,7 +105,6 @@ class ServerFactory:
         self._commit_indexing_application_service: (
             CommitIndexingApplicationService | None
         ) = None
-        self._enrichment_service: EnrichmentDomainService | None = None
         self._enricher_service: Enricher | None = None
         self._task_status_repository: TaskStatusRepository | None = None
         self._operation: ProgressTracker | None = None
@@ -127,6 +126,8 @@ class ServerFactory:
         self._architecture_service: PhysicalArchitectureService | None = None
         self._enrichment_v2_repository: EnrichmentV2Repository | None = None
         self._architecture_formatter: PhysicalArchitectureFormatter | None = None
+        self._trackable_resolution_service: TrackableResolutionService | None = None
+        self._enrichment_query_service: EnrichmentQueryService | None = None
 
     def architecture_formatter(self) -> PhysicalArchitectureFormatter:
         """Create a PhysicalArchitectureFormatter instance."""
@@ -351,3 +352,22 @@ class ServerFactory:
                 session_factory=self.session_factory
             )
         return self._git_tag_repository
+
+    def trackable_resolution_service(self) -> TrackableResolutionService:
+        """Create a TrackableResolutionService instance."""
+        if not self._trackable_resolution_service:
+            self._trackable_resolution_service = TrackableResolutionService(
+                commit_repo=self.git_commit_repository(),
+                branch_repo=self.git_branch_repository(),
+                tag_repo=self.git_tag_repository(),
+            )
+        return self._trackable_resolution_service
+
+    def enrichment_query_service(self) -> EnrichmentQueryService:
+        """Create a EnrichmentQueryService instance."""
+        if not self._enrichment_query_service:
+            self._enrichment_query_service = EnrichmentQueryService(
+                trackable_resolution=self.trackable_resolution_service(),
+                enrichment_repo=self.enrichment_v2_repository(),
+            )
+        return self._enrichment_query_service

kodit-0.5.3/src/kodit/application/services/enrichment_query_service.py

@@ -0,0 +1,95 @@
+"""Application service for querying enrichments."""
+
+import structlog
+
+from kodit.domain.enrichments.enrichment import EnrichmentV2
+from kodit.domain.tracking.resolution_service import TrackableResolutionService
+from kodit.domain.tracking.trackable import Trackable
+from kodit.infrastructure.sqlalchemy.enrichment_v2_repository import (
+    EnrichmentV2Repository,
+)
+
+
+class EnrichmentQueryService:
+    """Finds the latest commit with enrichments for a trackable.
+
+    Orchestrates domain services and repositories to fulfill the use case.
+    """
+
+    def __init__(
+        self,
+        trackable_resolution: TrackableResolutionService,
+        enrichment_repo: EnrichmentV2Repository,
+    ) -> None:
+        """Initialize the enrichment query service."""
+        self.trackable_resolution = trackable_resolution
+        self.enrichment_repo = enrichment_repo
+        self.log = structlog.get_logger(__name__)
+
+    async def find_latest_enriched_commit(
+        self,
+        trackable: Trackable,
+        enrichment_type: str | None = None,
+        max_commits_to_check: int = 100,
+    ) -> str | None:
+        """Find the most recent commit with enrichments.
+
+        Args:
+            trackable: What to track (branch, tag, or commit)
+            enrichment_type: Optional filter for specific enrichment type
+            max_commits_to_check: How far back in history to search
+
+        Returns:
+            Commit SHA of the most recent commit with enrichments, or None
+
+        """
+        # Get candidate commits from the trackable
+        candidate_commits = await self.trackable_resolution.resolve_to_commits(
+            trackable, max_commits_to_check
+        )
+
+        if not candidate_commits:
+            return None
+
+        # Check which commits have enrichments
+        enrichments = await self.enrichment_repo.enrichments_for_entity_type(
+            entity_type="git_commit",
+            entity_ids=candidate_commits,
+        )
+
+        # Filter by type if specified
+        if enrichment_type:
+            enrichments = [e for e in enrichments if e.type == enrichment_type]
+
+        # Find the first commit (newest) that has enrichments
+        for commit_sha in candidate_commits:
+            if any(e.entity_id == commit_sha for e in enrichments):
+                return commit_sha
+
+        return None
+
+    async def get_enrichments_for_commit(
+        self,
+        commit_sha: str,
+        enrichment_type: str | None = None,
+    ) -> list[EnrichmentV2]:
+        """Get all enrichments for a specific commit.
+
+        Args:
+            commit_sha: The commit SHA to get enrichments for
+            enrichment_type: Optional filter for specific enrichment type
+
+        Returns:
+            List of enrichments for the commit
+
+        """
+        enrichments = await self.enrichment_repo.enrichments_for_entity_type(
+            entity_type="git_commit",
+            entity_ids=[commit_sha],
+        )
+
+        # Filter by type if specified
+        if enrichment_type:
+            enrichments = [e for e in enrichments if e.type == enrichment_type]
+
+        return enrichments

{kodit-0.5.1 → kodit-0.5.3}/src/kodit/config.py

@@ -70,6 +70,18 @@ class Endpoint(BaseModel):
         default=60,
         description="Request timeout in seconds",
     )
+    max_retries: int = Field(
+        default=5,
+        description="Maximum number of retries for the endpoint",
+    )
+    initial_delay: float = Field(
+        default=2.0,
+        description="Initial delay in seconds for the endpoint",
+    )
+    backoff_factor: float = Field(
+        default=2.0,
+        description="Backoff factor for the endpoint",
+    )
     extra_params: dict[str, Any] | None = Field(
         default=None,
         description="Extra provider-specific non-secret parameters for LiteLLM",

kodit-0.5.3/src/kodit/domain/tracking/__init__.py

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

kodit-0.5.3/src/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-0.5.3/src/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-0.5.1 → kodit-0.5.3}/src/kodit/infrastructure/api/v1/dependencies.py

@@ -13,6 +13,9 @@ from kodit.application.services.code_search_application_service import (
 from kodit.application.services.commit_indexing_application_service import (
     CommitIndexingApplicationService,
 )
+from kodit.application.services.enrichment_query_service import (
+    EnrichmentQueryService,
+)
 from kodit.application.services.queue_service import QueueService
 from kodit.config import AppContext
 from kodit.domain.protocols import (
@@ -155,3 +158,15 @@ async def get_code_search_app_service(
 CodeSearchAppServiceDep = Annotated[
     CodeSearchApplicationService, Depends(get_code_search_app_service)
 ]
+
+
+async def get_enrichment_query_service(
+    server_factory: ServerFactoryDep,
+) -> EnrichmentQueryService:
+    """Get enrichment query service dependency."""
+    return server_factory.enrichment_query_service()
+
+
+EnrichmentQueryServiceDep = Annotated[
+    EnrichmentQueryService, Depends(get_enrichment_query_service)
+]

{kodit-0.5.1 → kodit-0.5.3}/src/kodit/infrastructure/api/v1/routers/repositories.py

@@ -2,15 +2,22 @@
 
 from fastapi import APIRouter, Depends, HTTPException
 
+from kodit.domain.tracking.trackable import Trackable, TrackableReferenceType
 from kodit.infrastructure.api.middleware.auth import api_key_auth
 from kodit.infrastructure.api.v1.dependencies import (
     CommitIndexingAppServiceDep,
+    EnrichmentQueryServiceDep,
     GitBranchRepositoryDep,
     GitCommitRepositoryDep,
     GitRepositoryDep,
     GitTagRepositoryDep,
     TaskStatusQueryServiceDep,
 )
+from kodit.infrastructure.api.v1.schemas.enrichment import (
+    EnrichmentAttributes,
+    EnrichmentData,
+    EnrichmentListResponse,
+)
 from kodit.infrastructure.api.v1.schemas.repository import (
     RepositoryBranchData,
     RepositoryCommitData,
@@ -259,6 +266,98 @@ async def get_repository_tag(
     )
 
 
+@router.get(
+    "/{repo_id}/enrichments",
+    summary="List latest repository enrichments",
+    responses={404: {"description": "Repository not found"}},
+)
+async def list_repository_enrichments(  # noqa: PLR0913
+    repo_id: str,
+    git_repository: GitRepositoryDep,
+    enrichment_query_service: EnrichmentQueryServiceDep,
+    ref_type: str = "branch",
+    ref_name: str | None = None,
+    enrichment_type: str | None = None,
+    limit: int = 10,
+) -> EnrichmentListResponse:
+    """List the most recent enrichments for a repository.
+
+    Query parameters:
+    - ref_type: Type of reference (branch, tag, or commit_sha). Defaults to "branch".
+    - ref_name: Name of the reference. For branches, defaults to the tracking branch.
+    - enrichment_type: Optional filter for specific enrichment type.
+    - limit: Maximum number of enrichments to return. Defaults to 10.
+    """
+    # Get repository
+    repo = await git_repository.get_by_id(int(repo_id))
+    if not repo:
+        raise HTTPException(status_code=404, detail="Repository not found")
+
+    # Determine the reference to track
+    if ref_name is None:
+        if ref_type == "branch":
+            # Default to tracking branch
+            if not repo.tracking_branch:
+                raise HTTPException(
+                    status_code=400, detail="No tracking branch configured"
+                )
+            ref_name = repo.tracking_branch.name
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail="ref_name is required for tag and commit_sha references",
+            )
+
+    # Parse ref_type
+    try:
+        trackable_type = TrackableReferenceType(ref_type)
+    except ValueError:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid ref_type: {ref_type}. Must be branch, tag, or commit_sha",
+        ) from None
+
+    # Create trackable
+    trackable = Trackable(
+        type=trackable_type, identifier=ref_name, repo_id=int(repo_id)
+    )
+
+    # Find the latest enriched commit
+    enriched_commit = await enrichment_query_service.find_latest_enriched_commit(
+        trackable=trackable,
+        enrichment_type=enrichment_type,
+        max_commits_to_check=limit * 10,  # Check more commits to find enriched ones
+    )
+
+    # If no enriched commit found, return empty list
+    if not enriched_commit:
+        return EnrichmentListResponse(data=[])
+
+    # Get enrichments for the commit
+    enrichments = await enrichment_query_service.get_enrichments_for_commit(
+        commit_sha=enriched_commit,
+        enrichment_type=enrichment_type,
+    )
+
+    # Map enrichments to API response format
+    enrichment_data = [
+        EnrichmentData(
+            type="enrichment",
+            id=str(enrichment.id) if enrichment.id else "0",
+            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
+    ]
+
+    return EnrichmentListResponse(data=enrichment_data)
+
+
 @router.delete(
     "/{repo_id}",
     status_code=204,