codewiki 0.1.0__py3-none-any.whl

backend/__init__.py

@@ -0,0 +1,2 @@
+"""Backend package for Code Wiki Platform."""
+

backend/app/__init__.py

@@ -0,0 +1,2 @@
+"""FastAPI application package."""
+

backend/app/api/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP API routers."""
+

backend/app/api/ask.py

@@ -0,0 +1,37 @@
+from fastapi import APIRouter, HTTPException
+
+from backend.app.config import get_settings
+from backend.app.database import get_store
+from backend.app.schemas.ask import AskRequest, AskResponse
+from backend.app.services.graphrag import GraphRAGRetriever
+from backend.app.services.llm_gateway import LLMGateway
+from backend.app.services.llm_run_recorder import LLMCallError
+from backend.app.services.question_answerer import QuestionAnswerer
+
+router = APIRouter()
+
+
+@router.post("/{repo_id}/ask")
+async def ask_repo(repo_id: str, payload: AskRequest) -> AskResponse:
+    settings = get_settings()
+    store = get_store()
+    answerer = QuestionAnswerer(
+        GraphRAGRetriever(store=store, settings=settings),
+        LLMGateway(settings),
+        store=store,
+    )
+    try:
+        return await answerer.answer(repo_id, payload)
+    except LLMCallError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail={
+                "message": str(exc),
+                "task_type": exc.task_type,
+                "run_id": exc.run_id,
+            },
+        ) from exc
+    except ValueError as exc:
+        message = str(exc)
+        status_code = 404 if message.startswith("Repository not found") else 400
+        raise HTTPException(status_code=status_code, detail=message) from exc

backend/app/api/dependencies.py

@@ -0,0 +1,63 @@
+from functools import cached_property, lru_cache
+from typing import Annotated
+
+from fastapi import Depends
+
+from backend.app.config import Settings, get_settings
+from backend.app.database import SQLiteStore, get_store
+from backend.app.services.graphrag import GraphRAGRetriever
+from backend.app.services.incremental import IncrementalUpdater
+from backend.app.services.llm_gateway import LLMGateway
+from backend.app.services.wiki import WikiGenerator
+
+
+class ServiceContainer:
+    def __init__(self, *, settings: Settings, store: SQLiteStore) -> None:
+        self.settings = settings
+        self.store = store
+
+    @cached_property
+    def llm_gateway(self) -> LLMGateway:
+        return LLMGateway(self.settings)
+
+    @cached_property
+    def graph_retriever(self) -> GraphRAGRetriever:
+        return GraphRAGRetriever(store=self.store, settings=self.settings)
+
+    @cached_property
+    def wiki_generator(self) -> WikiGenerator:
+        return WikiGenerator(
+            self.graph_retriever,
+            self.llm_gateway,
+            store=self.store,
+            settings=self.settings,
+        )
+
+    @cached_property
+    def incremental_updater(self) -> IncrementalUpdater:
+        return IncrementalUpdater(
+            store=self.store,
+            graphrag=self.graph_retriever,
+        )
+
+
+@lru_cache
+def get_service_container() -> ServiceContainer:
+    return ServiceContainer(settings=get_settings(), store=get_store())
+
+
+def get_store_dependency() -> SQLiteStore:
+    return get_service_container().store
+
+
+def get_wiki_generator() -> WikiGenerator:
+    return get_service_container().wiki_generator
+
+
+def get_incremental_updater() -> IncrementalUpdater:
+    return get_service_container().incremental_updater
+
+
+StoreDep = Annotated[SQLiteStore, Depends(get_store_dependency)]
+WikiGeneratorDep = Annotated[WikiGenerator, Depends(get_wiki_generator)]
+IncrementalUpdaterDep = Annotated[IncrementalUpdater, Depends(get_incremental_updater)]

backend/app/api/files.py

@@ -0,0 +1,101 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from backend.app.database import get_store
+from backend.app.services.repo_scanner import RepoDescriptor, RepoScanner, ScannedFile
+
+router = APIRouter()
+
+
+@router.get("/{repo_id}/files")
+async def list_repo_files(repo_id: str) -> dict[str, object]:
+    store = get_store()
+    repo = store.get_repo(repo_id)
+    if repo is None:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+
+    try:
+        scan = RepoScanner().scan(repo.path, name=repo.name, source_type=repo.source_type)
+    except (FileNotFoundError, NotADirectoryError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {
+        "repo_id": repo.id,
+        "root": _tree_payload(repo, scan.files),
+        "files": [_file_payload(scanned_file) for scanned_file in scan.files],
+        "scanned_count": scan.scanned_count,
+        "ignored_count": scan.ignored_count,
+        "skipped_count": scan.skipped_count,
+    }
+
+
+def _tree_payload(repo: RepoDescriptor, files: list[ScannedFile]) -> dict[str, Any]:
+    root = _directory_node(repo.name, "")
+    directory_by_path: dict[str, dict[str, Any]] = {"": root}
+
+    for scanned_file in files:
+        parent = root
+        parts = [part for part in scanned_file.path.split("/") if part]
+        current_path_parts: list[str] = []
+        for directory_name in parts[:-1]:
+            current_path_parts.append(directory_name)
+            directory_path = "/".join(current_path_parts)
+            directory = directory_by_path.get(directory_path)
+            if directory is None:
+                directory = _directory_node(directory_name, directory_path)
+                directory_by_path[directory_path] = directory
+                parent["children"].append(directory)
+            parent = directory
+
+        if parts:
+            parent["children"].append(
+                {
+                    "type": "file",
+                    "name": parts[-1],
+                    "path": scanned_file.path,
+                    "language": scanned_file.language,
+                    "is_source": scanned_file.is_source,
+                    "size_bytes": scanned_file.size_bytes,
+                    "sha256": scanned_file.sha256,
+                    "modified_at": scanned_file.modified_at,
+                }
+            )
+
+    _sort_tree(root)
+    return root
+
+
+def _directory_node(name: str, path: str) -> dict[str, Any]:
+    return {
+        "type": "directory",
+        "name": name,
+        "path": path,
+        "children": [],
+    }
+
+
+def _sort_tree(node: dict[str, Any]) -> None:
+    children = node.get("children")
+    if not isinstance(children, list):
+        return
+    children.sort(
+        key=lambda item: (
+            0 if item.get("type") == "directory" else 1,
+            str(item.get("name", "")).lower(),
+        )
+    )
+    for child in children:
+        if child.get("type") == "directory":
+            _sort_tree(child)
+
+
+def _file_payload(scanned_file: ScannedFile) -> dict[str, object]:
+    return {
+        "path": scanned_file.path,
+        "language": scanned_file.language,
+        "is_source": scanned_file.is_source,
+        "size_bytes": scanned_file.size_bytes,
+        "sha256": scanned_file.sha256,
+        "modified_at": scanned_file.modified_at,
+    }

backend/app/api/graph.py

@@ -0,0 +1,183 @@
+from dataclasses import asdict
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from backend.app.config import get_settings
+from backend.app.database import get_store
+from backend.app.schemas.graph import CodeEdge, CodeNode, GraphCommunity, GraphResponse
+from backend.app.services.community_namer import CommunityNamer
+from backend.app.services.graph_provenance import edge_provenance, node_confidence, node_provenance
+from backend.app.services.graphrag import GraphRAGRetriever
+from backend.app.services.llm_gateway import LLMGateway
+
+router = APIRouter()
+
+
+class BuildGraphRAGRequest(BaseModel):
+    include_embeddings: bool = False
+
+
+class RetrieveRequest(BaseModel):
+    query: str
+    max_hops: int = 2
+    include_embeddings: bool = False
+
+
+class NameCommunitiesRequest(BaseModel):
+    max_communities: int = 40
+
+
+@router.get("/{repo_id}/graph")
+async def get_graph(repo_id: str) -> GraphResponse:
+    store = get_store()
+    if store.get_repo(repo_id) is None:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+    nodes, edges = store.get_graph(repo_id)
+    communities = store.list_graph_communities(repo_id)
+    return GraphResponse(
+        repo_id=repo_id,
+        nodes=[
+            CodeNode(
+                id=node.id,
+                type=node.type,
+                name=node.name,
+                file_path=node.file_path,
+                start_line=node.start_line,
+                end_line=node.end_line,
+                language=node.language,
+                symbol_id=node.symbol_id,
+                confidence=node_confidence(node.metadata),
+                provenance=node_provenance(node.metadata),
+                metadata=node.metadata,
+            )
+            for node in nodes
+        ],
+        edges=[
+            CodeEdge(
+                id=edge.id,
+                source=edge.source_id,
+                target=edge.target_id,
+                type=edge.type,
+                confidence=edge.confidence,
+                confidence_level=(
+                    str(edge.metadata["confidence_level"])
+                    if isinstance(edge.metadata.get("confidence_level"), str)
+                    else None
+                ),
+                reason=(
+                    str(edge.metadata["reason"])
+                    if isinstance(edge.metadata.get("reason"), str)
+                    else None
+                ),
+                is_inferred=edge.is_inferred,
+                provenance=edge_provenance(edge.metadata),
+                metadata=edge.metadata,
+            )
+            for edge in edges
+        ],
+        communities=[
+            GraphCommunity(
+                id=community.id,
+                name=community.name,
+                level=community.level,
+                node_ids=community.node_ids,
+                summary=community.summary or "",
+            )
+            for community in communities
+        ],
+    )
+
+
+@router.get("/{repo_id}/graph/nodes/{node_id}")
+async def get_node(repo_id: str, node_id: str) -> dict[str, str]:
+    nodes, edges = get_store().get_graph(repo_id)
+    node = next((item for item in nodes if item.id == node_id), None)
+    if node is None:
+        raise HTTPException(status_code=404, detail=f"Node not found: {node_id}")
+    adjacent_edges = [
+        edge for edge in edges if edge.source_id == node_id or edge.target_id == node_id
+    ]
+    return {
+        "repo_id": repo_id,
+        "node_id": node_id,
+        "type": node.type,
+        "name": node.name,
+        "file_path": node.file_path,
+        "adjacent_edge_count": str(len(adjacent_edges)),
+    }
+
+
+@router.get("/{repo_id}/communities")
+async def get_communities(repo_id: str) -> list[dict[str, str]]:
+    return [
+        {
+            "id": community.id,
+            "name": community.name,
+            "level": str(community.level),
+            "summary": community.summary or "",
+        }
+        for community in get_store().list_graph_communities(repo_id)
+    ]
+
+
+@router.post("/{repo_id}/communities/name")
+async def name_communities(
+    repo_id: str,
+    payload: NameCommunitiesRequest | None = None,
+) -> dict[str, object]:
+    store = get_store()
+    if store.get_repo(repo_id) is None:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+    request = payload or NameCommunitiesRequest()
+    try:
+        result = await CommunityNamer(
+            LLMGateway(get_settings()),
+            store=store,
+        ).summarize_communities(repo_id, max_communities=request.max_communities)
+    except ValueError as exc:
+        message = str(exc)
+        status_code = 404 if message.startswith("Repository not found") else 400
+        raise HTTPException(status_code=status_code, detail=message) from exc
+    return asdict(result)
+
+
+@router.post("/{repo_id}/graphrag/build")
+async def build_graphrag(
+    repo_id: str,
+    payload: BuildGraphRAGRequest | None = None,
+) -> dict[str, object]:
+    request = payload or BuildGraphRAGRequest()
+    store = get_store()
+    settings = get_settings()
+    try:
+        result = await GraphRAGRetriever(store=store, settings=settings).build_index(
+            repo_id,
+            include_embeddings=request.include_embeddings,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    return asdict(result)
+
+
+@router.post("/{repo_id}/graphrag/retrieve")
+async def retrieve_context(repo_id: str, payload: RetrieveRequest) -> dict[str, object]:
+    store = get_store()
+    settings = get_settings()
+    try:
+        trace = await GraphRAGRetriever(store=store, settings=settings).retrieve(
+            repo_id,
+            payload.query,
+            max_hops=payload.max_hops,
+            include_embeddings=payload.include_embeddings,
+        )
+    except ValueError as exc:
+        message = str(exc)
+        status_code = 404 if message.startswith("Repository not found") else 400
+        raise HTTPException(status_code=status_code, detail=message) from exc
+    return asdict(trace)
+
+
+@router.get("/{repo_id}/graphrag/traces/{trace_id}")
+async def get_retrieval_trace(repo_id: str, trace_id: str) -> dict[str, object]:
+    return {"repo_id": repo_id, "trace_id": trace_id, "status": "not_persisted_yet"}

backend/app/api/repos.py

@@ -0,0 +1,74 @@
+from fastapi import APIRouter, HTTPException, Response
+from pydantic import BaseModel
+
+from backend.app.database import get_store
+from backend.app.services.repo_scanner import RepoDescriptor, RepoScanResult, RepoScanner
+
+router = APIRouter()
+
+
+class CreateRepoRequest(BaseModel):
+    path: str
+    name: str | None = None
+    source_type: str = "local"
+
+
+class ScanRepoRequest(CreateRepoRequest):
+    pass
+
+
+@router.post("")
+async def create_repo(payload: CreateRepoRequest) -> RepoDescriptor:
+    scanner = RepoScanner()
+    try:
+        repo = scanner.describe(payload.path, name=payload.name, source_type=payload.source_type)
+    except (FileNotFoundError, NotADirectoryError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return get_store().upsert_repo(repo)
+
+
+@router.post("/scan")
+async def scan_repo(payload: ScanRepoRequest) -> RepoScanResult:
+    scanner = RepoScanner()
+    try:
+        return scanner.scan(payload.path, name=payload.name, source_type=payload.source_type)
+    except (FileNotFoundError, NotADirectoryError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.get("")
+async def list_repos() -> list[dict[str, str]]:
+    return [
+        {
+            "id": repo.id,
+            "name": repo.name,
+            "path": repo.path,
+            "source_type": repo.source_type,
+            "git_url": repo.git_url or "",
+            "commit_hash": repo.commit_hash or "",
+        }
+        for repo in get_store().list_repos()
+    ]
+
+
+@router.get("/{repo_id}")
+async def get_repo(repo_id: str) -> dict[str, str]:
+    repo = get_store().get_repo(repo_id)
+    if repo is None:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+    return {
+        "id": repo.id,
+        "name": repo.name,
+        "path": repo.path,
+        "source_type": repo.source_type,
+        "git_url": repo.git_url or "",
+        "commit_hash": repo.commit_hash or "",
+    }
+
+
+@router.delete("/{repo_id}", status_code=204)
+async def delete_repo(repo_id: str) -> Response:
+    deleted = get_store().delete_repo(repo_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+    return Response(status_code=204)

backend/app/api/runs.py

@@ -0,0 +1,148 @@
+from dataclasses import asdict
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from backend.app.config import get_settings
+from backend.app.database import get_store
+from backend.app.services.analyzer import AnalysisService, _llm_configured
+from backend.app.services.community_namer import CommunityNamer
+from backend.app.services.community_naming import CommunityNamingResult
+from backend.app.services.incremental import IncrementalUpdater
+from backend.app.services.llm_gateway import LLMGateway
+
+router = APIRouter()
+
+
+class AnalyzeRepoRequest(BaseModel):
+    name_communities: bool = True
+
+
+class IncrementalUpdateRequest(BaseModel):
+    refresh_chunks: bool = True
+    name_communities: bool = True
+    regenerate_wiki: bool = True
+
+
+@router.post("/{repo_id}/analyze")
+async def analyze_repo(repo_id: str, payload: AnalyzeRepoRequest | None = None) -> dict[str, object]:
+    store = get_store()
+    if store.get_repo(repo_id) is None:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+    request = payload or AnalyzeRepoRequest()
+    try:
+        analysis = await AnalysisService(store=store).analyze_with_community_summaries(
+            repo_id,
+            name_communities=request.name_communities,
+        )
+        result = analysis.analysis
+        naming_result = analysis.community_naming
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    response = {
+        "run_id": result.run_id,
+        "repo_id": result.repo_id,
+        "status": result.status,
+        "scanned_count": result.scanned_count,
+        "parsed_file_count": result.parsed_file_count,
+        "node_count": result.node_count,
+        "edge_count": result.edge_count,
+        "community_count": result.community_count,
+        "errors": result.errors,
+    }
+    if naming_result is not None:
+        response["community_naming"] = asdict(naming_result)
+    return response
+
+
+@router.post("/{repo_id}/update")
+async def update_repo(
+    repo_id: str,
+    payload: IncrementalUpdateRequest | None = None,
+) -> dict[str, object]:
+    store = get_store()
+    if store.get_repo(repo_id) is None:
+        raise HTTPException(status_code=404, detail=f"Repository not found: {repo_id}")
+    request = payload or IncrementalUpdateRequest()
+    try:
+        result, wiki_regeneration = await IncrementalUpdater(store=store).update_with_wiki_regeneration(
+            repo_id,
+            refresh_chunks=request.refresh_chunks,
+            regenerate_wiki=request.regenerate_wiki,
+        )
+        naming_result = await _name_communities(repo_id) if request.name_communities else None
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    response = {
+        "run_id": result.run_id,
+        "repo_id": result.repo_id,
+        "status": result.status,
+        "plan": result.plan.as_dict(),
+        "scanned_count": result.scanned_count,
+        "parsed_file_count": result.parsed_file_count,
+        "reused_file_count": result.reused_file_count,
+        "node_count": result.node_count,
+        "edge_count": result.edge_count,
+        "community_count": result.community_count,
+        "chunk_count": result.chunk_count,
+        "stale_pages": result.stale_pages,
+        "wiki_regeneration": wiki_regeneration,
+        "errors": result.errors,
+    }
+    if naming_result is not None:
+        response["community_naming"] = asdict(naming_result)
+    return response
+
+
+async def _name_communities(repo_id: str) -> CommunityNamingResult:
+    settings = get_settings()
+    if not _llm_configured(settings):
+        return CommunityNamingResult(
+            repo_id=repo_id,
+            status="skipped",
+            renamed_count=0,
+            community_count=len(get_store().list_graph_communities(repo_id)),
+            errors=["LLM community naming skipped because no LLM endpoint or API key is configured."],
+        )
+    try:
+        return await CommunityNamer(LLMGateway(settings), store=get_store()).summarize_communities(repo_id)
+    except Exception as exc:
+        return CommunityNamingResult(
+            repo_id=repo_id,
+            status="failed",
+            renamed_count=0,
+            community_count=len(get_store().list_graph_communities(repo_id)),
+            errors=[str(exc)],
+        )
+
+
+@router.get("/{repo_id}/runs")
+async def list_runs(repo_id: str) -> list[dict[str, object]]:
+    return [
+        {
+            "id": run.id,
+            "repo_id": run.repo_id,
+            "status": run.status,
+            "started_at": run.started_at,
+            "finished_at": run.finished_at,
+            "error": run.error,
+            "stats": run.stats,
+        }
+        for run in get_store().list_analysis_runs(repo_id)
+    ]
+
+
+@router.get("/{repo_id}/runs/{run_id}")
+async def get_run(repo_id: str, run_id: str) -> dict[str, object]:
+    run = get_store().get_analysis_run(run_id)
+    if run is None or run.repo_id != repo_id:
+        raise HTTPException(status_code=404, detail=f"Run not found: {run_id}")
+    return {
+        "id": run.id,
+        "repo_id": run.repo_id,
+        "status": run.status,
+        "started_at": run.started_at,
+        "finished_at": run.finished_at,
+        "error": run.error,
+        "stats": run.stats,
+    }

backend/app/api/settings.py

@@ -0,0 +1,50 @@
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from backend.app.config import get_settings
+from backend.app.services.model_router import ModelRouter
+
+router = APIRouter()
+
+
+class TestModelRequest(BaseModel):
+    model: str | None = None
+    task_type: str = "qa"
+
+
+@router.get("/llm/models")
+async def get_llm_models() -> dict[str, object]:
+    settings = get_settings()
+    model_router = ModelRouter(settings)
+    profiles = {
+        task_type: _profile_payload(model_router.profile_for(task_type))
+        for task_type in (
+            "catalog",
+            "community_summary",
+            "page",
+            "translation",
+            "qa",
+            "embedding",
+        )
+    }
+    return {
+        "mode": settings.llm.mode,
+        "default_profile": _profile_payload(model_router.default_profile()),
+        "profiles": profiles,
+    }
+
+
+@router.post("/llm/test")
+async def test_llm_model(payload: TestModelRequest) -> dict[str, str]:
+    return {"status": "not_implemented", "task_type": payload.task_type, "model": payload.model or ""}
+
+
+def _profile_payload(profile) -> dict[str, object]:
+    return {
+        "model": profile.model,
+        "provider_type": profile.provider_type or "",
+        "endpoint": profile.endpoint or "",
+        "has_api_key": bool(profile.api_key),
+        "stream": profile.stream,
+        "max_tokens": profile.max_tokens,
+    }