initial commit: full implemntation of git explorer project

.gitignore

@@ -0,0 +1,52 @@
+# Virtual Environment
+venv/
+.venv/
+env/
+
+# Environment variables
+.env
+.env.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# MyPy
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Local database files
+*.db
+*.sqlite3
+
+# Jupyter
+.ipynb_checkpoints/
+
+
+# cloned repositories
+storage/repos/

app/controllers/chat_controller.py

@@ -0,0 +1,40 @@
+from app.services.context_formatter import (
+    ContextFormatter,
+)
+from app.services.llm_service import (
+    LLMService,
+)
+from app.services.retrieval_service import (
+    RetrievalService,
+)
+
+
+class ChatController:
+
+    def __init__(self):
+
+        self.retrieval = RetrievalService()
+
+        self.formatter = ContextFormatter()
+
+        self.llm = LLMService()
+
+    def ask(
+        self,
+        repository_id: str,
+        question: str,
+    ):
+
+        context = self.retrieval.search(
+            repository_id=repository_id,
+            query=question,
+        )
+
+        formatted_context = self.formatter.format(
+            context,
+        )
+
+        return self.llm.chat(
+            question=question,
+            context=formatted_context,
+        )

app/controllers/repository_controller.py

@@ -0,0 +1,111 @@
+from app.core.config import REPOSITORIES_DIR
+
+from app.services.github_service import GithubService
+from app.services.metadata_service import MetadataService
+from app.services.parser_service import ParserService
+from app.services.index_service import IndexService
+from app.services.graph_service import GraphService
+from app.services.resolver_service import ResolverService
+from app.services.embedding_service import EmbeddingService
+
+from app.utils.file_utils import get_python_files
+
+from app.core.constants import (
+    METADATA_FILE,
+    CODE_INDEX_FILE,
+    RESOLVED_CODE_FILE,
+)
+
+
+class RepositoryController:
+
+    def __init__(self):
+
+        self.github = GithubService()
+
+        self.metadata = MetadataService()
+
+        self.parser = ParserService()
+
+        self.index = IndexService()
+
+        self.resolver = ResolverService()
+
+        self.graph_service = GraphService()
+
+        self.embedding_service = EmbeddingService()
+
+    def clone(
+        self,
+        url: str,
+    ):
+
+        clone_result = self.github.clone(
+            url,
+            REPOSITORIES_DIR,
+        )
+
+        repository_id = clone_result["repository_id"]
+
+        repo_path = clone_result["repo_path"]
+
+        metadata = self.metadata.extract(
+            repo_path,
+        )
+
+        self.index.save(
+            repo_path,
+            METADATA_FILE,
+            metadata,
+        )
+
+        parsed_files = []
+
+        for file in get_python_files(repo_path):
+
+            parsed_files.append(
+                self.parser.parse_file(
+                    file,
+                )
+            )
+
+        self.index.save(
+            repo_path,
+            CODE_INDEX_FILE,
+            parsed_files,
+        )
+
+        code_index = [
+            item.model_dump()
+            for item in parsed_files
+        ]
+
+        resolved = self.resolver.resolve(
+            code_index,
+        )
+
+        self.index.save(
+            repo_path,
+            RESOLVED_CODE_FILE,
+            resolved,
+        )
+
+        print("Building graph...")
+
+        self.graph_service.build(
+            repository_id=repository_id,
+            resolved=resolved,
+        )
+
+        print("Building embeddings...")
+
+        self.embedding_service.build(
+            repository_id=repository_id,
+            resolved=resolved,
+        )
+
+        print("Repository indexed successfully.")
+
+        metadata.repository_id = repository_id
+
+        return metadata

app/core/config.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+import os
+from app.core.settings import settings
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+
+REPOSITORIES_DIR = BASE_DIR / "storage" / "repos"
+
+REPOSITORIES_DIR.mkdir(parents=True, exist_ok=True)
+

app/core/constants.py

@@ -0,0 +1,15 @@
+METADATA_FILE = "metadata.json"
+
+CODE_INDEX_FILE = "code.json"
+
+GRAPH_FILE = "graph.json"
+
+CHUNKS_FILE = "chunks.json"
+
+EMBEDDINGS_FILE = "embeddings.json"
+
+ENTITIES_FILE = "entities.json"
+
+RESOLVED_CODE_FILE = "resolved_code.json"
+
+GRAPH_FILE = "graph.json"

app/core/settings.py

@@ -0,0 +1,21 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+
+    neo4j_uri: str
+    neo4j_username: str
+    neo4j_password: str
+
+    qdrant_url: str
+    qdrant_api_key: str = ""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+    )
+    openrouter_api_key: str
+
+    llm_model: str
+
+
+settings = Settings()

app/main.py

@@ -0,0 +1,13 @@
+from fastapi import FastAPI
+from app.routes.repository_routes import router
+from app.routes.chat_routes import router as chat_router
+
+
+app = FastAPI(
+    title="Repository GraphRAG",
+)
+
+app.include_router(router)
+app.include_router(
+    chat_router,
+)

app/models/chat.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class ChatRequest(BaseModel):
+
+    repository_id: str
+
+    question: str

app/models/code.py

@@ -0,0 +1,55 @@
+from pydantic import BaseModel, Field
+
+
+class ImportInfo(BaseModel):
+    module: str | None
+    name: str
+    alias: str | None = None
+
+
+class CallInfo(BaseModel):
+    name: str
+    line: int
+    qualified_name: str | None = None
+
+
+class FunctionInfo(BaseModel):
+    name: str
+
+    qualified_name: str
+
+    line: int
+
+    end_line: int
+
+    docstring: str | None
+
+    source_code: str
+
+    calls: list[CallInfo] = Field(default_factory=list)
+
+
+class ClassInfo(BaseModel):
+
+    name: str
+
+    qualified_name: str
+
+    line: int
+    
+    end_line: int
+
+    source_code: str
+
+    methods: list[FunctionInfo] = Field(default_factory=list)
+
+
+class PythonFileInfo(BaseModel):
+    path: str
+
+    imports: list[ImportInfo] = Field(default_factory=list)
+
+    classes: list[ClassInfo] = Field(default_factory=list)
+
+    functions: list[FunctionInfo] = Field(default_factory=list)
+

app/models/graph_context.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+
+
+class GraphNode(BaseModel):
+
+    qualified_name: str | None = None
+
+    labels: list[str]
+
+    properties: dict
+
+
+class GraphEdge(BaseModel):
+
+    source: str
+
+    target: str
+
+    type: str
+
+
+class GraphContext(BaseModel):
+
+    nodes: list[GraphNode]
+
+    edges: list[GraphEdge]

app/models/metadata.py

@@ -0,0 +1,34 @@
+from pydantic import BaseModel
+
+
+class RepositoryInfo(BaseModel):
+    name: str
+    path: str
+    branch: str
+    latest_commit: str
+    size_mb: float
+
+
+class StructureInfo(BaseModel):
+    total_files: int
+    python_files: int
+    directories: int
+
+
+class ConfigurationInfo(BaseModel):
+    has_readme: bool
+    has_license: bool
+    has_dockerfile: bool
+    has_docker_compose: bool
+    requirements: list[str]
+
+
+class RepositoryMetadata(BaseModel):
+
+    repository_id: str | None = None
+
+    repository: RepositoryInfo
+
+    structure: StructureInfo
+
+    configuration: ConfigurationInfo

app/models/requests.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, HttpUrl
+
+
+class CloneRepositoryRequest(BaseModel):
+    url: HttpUrl

app/models/responses.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+from app.models.metadata import RepositoryMetadata
+
+
+class CloneRepositoryResponse(BaseModel):
+    metadata: RepositoryMetadata

app/models/symbols.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class Symbol(BaseModel):
+
+    name: str
+
+    qualified_name: str

app/repositories/neo4j_repository.py

@@ -0,0 +1,556 @@
+from neo4j import GraphDatabase
+
+from app.core.settings import settings
+from app.models.graph_context import (
+    GraphContext,
+    GraphNode,
+    GraphEdge,
+)
+
+
+class Neo4jRepository:
+
+    _instance = None
+
+    def __new__(cls):
+
+        if cls._instance is None:
+
+            cls._instance = super().__new__(cls)
+
+        return cls._instance
+
+    def __init__(self):
+
+        if hasattr(self, "_initialized"):
+            return
+
+        self.driver = GraphDatabase.driver(
+            settings.neo4j_uri,
+            auth=(
+                settings.neo4j_username,
+                settings.neo4j_password,
+            ),
+        )
+
+        self._initialized = True
+
+    def close(self):
+
+        if hasattr(self, "driver"):
+
+            self.driver.close()
+
+            self._initialized = False
+
+            Neo4jRepository._instance = None
+
+    def execute(
+        self,
+        query,
+        **params,
+    ):
+
+        with self.driver.session() as session:
+
+            session.run(
+                query,
+                **params,
+            )
+
+    def merge_function(
+        self,
+        repository_id: str,
+        qualified_name: str,
+        name: str,
+        embedding: list[float] | None = None,
+        source_code: str | None = None,
+    ):
+
+        module = ".".join(
+            qualified_name.split(".")[:-1]
+        )
+
+        self.execute(
+            """
+            MERGE (f:Function {
+                repository_id: $repository_id,
+                qualified_name: $qualified_name
+            })
+
+            SET
+                f.name = $name,
+                f.module = $module,
+                f.embedding = $embedding,
+                f.source_code = $source_code
+            """,
+            repository_id=repository_id,
+            qualified_name=qualified_name,
+            name=name,
+            module=module,
+            embedding=embedding,
+            source_code=source_code,
+        )
+
+    def merge_class(
+        self,
+        repository_id: str,
+        qualified_name: str,
+        name: str,
+        embedding: list[float] | None = None,
+        source_code: str | None = None,
+    ):
+
+        module = ".".join(
+            qualified_name.split(".")[:-1]
+        )
+
+        self.execute(
+            """
+            MERGE (c:Class {
+                repository_id: $repository_id,
+                qualified_name: $qualified_name
+            })
+
+            SET
+                c.name = $name,
+                c.module = $module,
+                c.embedding = $embedding,
+                c.source_code = $source_code
+            """,
+            repository_id=repository_id,
+            qualified_name=qualified_name,
+            name=name,
+            module=module,
+            embedding=embedding,
+            source_code=source_code,
+        )
+
+    def merge_external_function(
+        self,
+        repository_id: str,
+        qualified_name: str,
+        embedding: list[float] | None = None,
+    ):
+
+        name = qualified_name.split(".")[-1]
+
+        module = ".".join(
+            qualified_name.split(".")[:-1]
+        )
+
+        package = qualified_name.split(".")[0]
+
+        self.execute(
+            """
+            MERGE (e:ExternalFunction {
+                repository_id: $repository_id,
+                qualified_name: $qualified_name
+            })
+
+            SET
+                e.name = $name,
+                e.module = $module,
+                e.package = $package,
+                e.embedding = $embedding
+            """,
+            repository_id=repository_id,
+            qualified_name=qualified_name,
+            name=name,
+            module=module,
+            package=package,
+            embedding=embedding,
+        )
+
+    def merge_call(
+        self,
+        repository_id: str,
+        source: str,
+        target: str,
+    ):
+
+        self.execute(
+            """
+            MATCH (s {
+                repository_id: $repository_id,
+                qualified_name: $source
+            })
+
+            MATCH (t {
+                repository_id: $repository_id,
+                qualified_name: $target
+            })
+
+            MERGE (s)-[:CALLS]->(t)
+            """,
+            repository_id=repository_id,
+            source=source,
+            target=target,
+        )
+    def merge_file(
+        self,
+        repository_id: str,
+        path: str,
+    ):
+
+        self.execute(
+            """
+            MERGE (f:File {
+                repository_id: $repository_id,
+                path: $path
+            })
+            """,
+            repository_id=repository_id,
+            path=path,
+        )
+    def create_declares(
+        self,
+        repository_id: str,
+        file_path: str,
+        qualified_name: str,
+    ):
+
+        self.execute(
+            """
+            MATCH (f:File {
+                repository_id: $repository_id,
+                path: $file_path
+            })
+
+            MATCH (n {
+                repository_id: $repository_id,
+                qualified_name: $qualified_name
+            })
+
+            MERGE (f)-[:DECLARES]->(n)
+            """,
+            repository_id=repository_id,
+            file_path=file_path,
+            qualified_name=qualified_name,
+        )
+
+    def create_has_method(
+        self,
+        repository_id: str,
+        class_name: str,
+        method_name: str,
+    ):
+
+        self.execute(
+            """
+            MATCH (c:Class {
+                repository_id: $repository_id,
+                qualified_name: $class_name
+            })
+
+            MATCH (m:Function {
+                repository_id: $repository_id,
+                qualified_name: $method_name
+            })
+
+            MERGE (c)-[:HAS_METHOD]->(m)
+            """,
+            repository_id=repository_id,
+            class_name=class_name,
+            method_name=method_name,
+        )
+    def merge_module(
+        self,
+        repository_id: str,
+        module: str,
+    ):
+
+        package = module.split(".")[0]
+
+        is_internal = module.startswith("app")
+
+        self.execute(
+            """
+            MERGE (m:Module {
+                repository_id: $repository_id,
+                name: $module
+            })
+
+            SET
+                m.package = $package,
+                m.is_internal = $is_internal
+            """,
+            repository_id=repository_id,
+            module=module,
+            package=package,
+            is_internal=is_internal,
+        )
+
+
+
+
+
+
+
+
+    def create_import(
+        self,
+        repository_id: str,
+        file_path: str,
+        module: str,
+        symbol: str | None,
+        alias: str | None,
+    ):
+
+        self.execute(
+            """
+            MATCH (f:File {
+                repository_id:$repository_id,
+                path:$file_path
+            })
+
+            MATCH (m:Module {
+                repository_id:$repository_id,
+                name:$module
+            })
+
+            CREATE (f)-[r:IMPORTS]->(m)
+
+            SET
+                r.symbol=$symbol,
+                r.alias=$alias
+            """,
+            repository_id=repository_id,
+            file_path=file_path,
+            module=module,
+            symbol=symbol,
+            alias=alias,
+        )
+    def create_belongs_to(
+        self,
+        repository_id: str,
+        qualified_name: str,
+    ):
+
+        module = ".".join(
+            qualified_name.split(".")[:-1]
+        )
+
+        if not module:
+            return
+
+        self.merge_module(
+            repository_id,
+            module,
+        )
+
+        self.execute(
+            """
+            MATCH (f:ExternalFunction {
+                repository_id:$repository_id,
+                qualified_name:$qualified_name
+            })
+
+            MATCH (m:Module {
+                repository_id:$repository_id,
+                name:$module
+            })
+
+            MERGE (f)-[:BELONGS_TO]->(m)
+            """,
+            repository_id=repository_id,
+            qualified_name=qualified_name,
+            module=module,
+        )
+
+    def clear_database(self):
+
+        self.execute(
+            """
+            MATCH (n)
+
+            DETACH DELETE n
+            """
+        )
+    def create_vector_indexes(self):
+
+        self.execute(
+            """
+            CREATE VECTOR INDEX function_embeddings
+            IF NOT EXISTS
+
+            FOR (f:Function)
+
+            ON (f.embedding)
+
+            OPTIONS {
+
+                indexConfig: {
+
+                    `vector.dimensions`: 384,
+
+                    `vector.similarity_function`: 'cosine'
+
+                }
+
+            }
+            """
+        )
+
+        self.execute(
+            """
+            CREATE VECTOR INDEX class_embeddings
+            IF NOT EXISTS
+
+            FOR (c:Class)
+
+            ON (c.embedding)
+
+            OPTIONS {
+
+                indexConfig: {
+
+                    `vector.dimensions`: 384,
+
+                    `vector.similarity_function`: 'cosine'
+
+                }
+
+            }
+            """
+        )
+    def update_embedding(
+        self,
+        repository_id: str,
+        qualified_name: str,
+        embedding: list[float],
+    ):
+
+        self.execute(
+            """
+            MATCH (n {
+                repository_id:$repository_id,
+                qualified_name:$qualified_name
+            })
+
+            SET
+                n.embedding=$embedding
+            """,
+            repository_id=repository_id,
+            qualified_name=qualified_name,
+            embedding=embedding,
+        )
+
+
+    def retrieve_context(
+        self,
+        repository_id: str,
+        embedding: list[float],
+        limit: int = 5,
+        hops: int = 1,
+    ):
+
+        query = f"""
+        CALL {{
+            CALL db.index.vector.queryNodes(
+                'function_embeddings',
+                $limit,
+                $embedding
+            )
+            YIELD node, score
+
+            WHERE node.repository_id = $repository_id
+
+            RETURN node, score
+
+            UNION
+
+            CALL db.index.vector.queryNodes(
+                'class_embeddings',
+                $limit,
+                $embedding
+            )
+            YIELD node, score
+
+            WHERE node.repository_id = $repository_id
+
+            RETURN node, score
+        }}
+
+        WITH collect(DISTINCT node) AS seeds
+
+        UNWIND seeds AS seed
+
+        WITH seed
+        WHERE seed.repository_id = $repository_id
+
+        MATCH path=(seed)-[*0..{hops}]-(neighbor)
+
+        WHERE neighbor.repository_id = $repository_id
+
+        WITH
+            collect(DISTINCT neighbor) AS nodes,
+            collect(DISTINCT relationships(path)) AS rel_lists
+
+        UNWIND rel_lists AS rel_list
+        UNWIND rel_list AS rel
+
+        RETURN
+            nodes,
+            collect(
+                DISTINCT {{
+                    source: coalesce(
+                        startNode(rel).qualified_name,
+                        startNode(rel).name,
+                        startNode(rel).path
+                    ),
+                    target: coalesce(
+                        endNode(rel).qualified_name,
+                        endNode(rel).name,
+                        endNode(rel).path
+                    ),
+                    type: type(rel)
+                }}
+            ) AS edges
+        """
+
+        with self.driver.session() as session:
+
+            record = session.run(
+                query,
+                repository_id=repository_id,
+                embedding=embedding,
+                limit=limit,
+            ).single()
+
+            if record is None:
+                return GraphContext(
+                    nodes=[],
+                    edges=[],
+                )
+
+            nodes = []
+
+            for node in record["nodes"]:
+                nodes.append(
+                    GraphNode(
+                        qualified_name=node.get("qualified_name"),
+                        labels=list(node.labels),
+                        properties=dict(node),
+                    )
+                )
+
+            edges = []
+
+            for edge in record["edges"]:
+
+                if edge["source"] is None or edge["target"] is None:
+                    continue
+
+                edges.append(
+                    GraphEdge(
+                        source=edge["source"],
+                        target=edge["target"],
+                        type=edge["type"],
+                    )
+                )
+
+            return GraphContext(
+                nodes=nodes,
+                edges=edges,
+            )

app/routes/chat_routes.py

@@ -0,0 +1,20 @@
+from fastapi import APIRouter
+
+from app.controllers.chat_controller import ChatController
+from app.models.chat import ChatRequest
+
+
+router = APIRouter()
+
+controller = ChatController()
+
+
+@router.post("/chat")
+def chat(
+    request: ChatRequest,
+):
+
+    return controller.ask(
+        repository_id=request.repository_id,
+        question=request.question,
+    )

app/routes/repository_routes.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+
+from app.controllers.repository_controller import RepositoryController
+from app.models.requests import CloneRepositoryRequest
+from app.models.responses import CloneRepositoryResponse
+
+router = APIRouter(prefix="/repositories", tags=["Repositories"])
+
+controller = RepositoryController()
+
+
+@router.post("", response_model=CloneRepositoryResponse)
+def clone_repository(request: CloneRepositoryRequest):
+
+    metadata = controller.clone(str(request.url))
+
+    return CloneRepositoryResponse(
+        metadata=metadata,
+    )

app/services/context_formatter.py

@@ -0,0 +1,80 @@
+from app.models.graph_context import GraphContext
+
+
+class ContextFormatter:
+
+    def format(
+        self,
+        context: GraphContext,
+    ) -> str:
+
+        seed_names = {
+            node.qualified_name
+            for node in context.nodes
+            if node.properties.get("source_code")
+        }
+
+        lines = []
+
+        lines.append("# Relevant Code")
+        lines.append("")
+
+        for node in context.nodes:
+
+            source = node.properties.get(
+                "source_code"
+            )
+
+            if not source:
+                continue
+
+            lines.append(
+                f"## {node.qualified_name}"
+            )
+
+            lines.append("")
+
+            lines.append("```python")
+            lines.append(source)
+            lines.append("```")
+            lines.append("")
+
+        lines.append("# Related Graph Nodes")
+        lines.append("")
+
+        for node in context.nodes:
+
+            if node.qualified_name in seed_names:
+                continue
+
+            props = []
+
+            if node.properties.get("name"):
+
+                props.append(
+                    f"name={node.properties['name']}"
+                )
+
+            if node.properties.get("module"):
+
+                props.append(
+                    f"module={node.properties['module']}"
+                )
+
+            label = ",".join(node.labels)
+
+            lines.append(
+                f"- {node.qualified_name} [{label}] ({', '.join(props)})"
+            )
+
+        lines.append("")
+        lines.append("# Relationships")
+        lines.append("")
+
+        for edge in context.edges:
+
+            lines.append(
+                f"- {edge.source} --{edge.type}--> {edge.target}"
+            )
+
+        return "\n".join(lines)

app/services/embedding_model_service.py

@@ -0,0 +1,20 @@
+from sentence_transformers import SentenceTransformer
+
+
+class EmbeddingModelService:
+
+    def __init__(self):
+
+        self.model = SentenceTransformer(
+            "BAAI/bge-small-en-v1.5"
+        )
+
+    def encode(
+        self,
+        text: str,
+    ) -> list[float]:
+
+        return self.model.encode(
+            text,
+            normalize_embeddings=True,
+        ).tolist()

app/services/embedding_service.py

@@ -0,0 +1,98 @@
+from app.repositories.neo4j_repository import (
+    Neo4jRepository,
+)
+
+from app.services.embedding_model_service import (
+    EmbeddingModelService,
+)
+
+
+class EmbeddingService:
+
+    def __init__(self):
+
+        self.embedding_model = (
+            EmbeddingModelService()
+        )
+
+        self.neo = Neo4jRepository()
+
+    def build(
+        self,
+        repository_id: str,
+        resolved,
+    ):
+
+        for file in resolved:
+
+            self._embed_functions(
+                repository_id,
+                file["functions"],
+            )
+
+            self._embed_classes(
+                repository_id,
+                file["classes"],
+            )
+
+    def _embed_functions(
+        self,
+        repository_id: str,
+        functions,
+    ):
+
+        for function in functions:
+
+            source = function.get(
+                "source_code"
+            )
+
+            if not source:
+                continue
+
+            embedding = (
+                self.embedding_model.encode(
+                    source
+                )
+            )
+
+            self.neo.update_embedding(
+                repository_id=repository_id,
+                qualified_name=function[
+                    "qualified_name"
+                ],
+                embedding=embedding,
+            )
+
+    def _embed_classes(
+        self,
+        repository_id: str,
+        classes,
+    ):
+
+        for cls in classes:
+
+            source = cls.get(
+                "source_code"
+            )
+
+            if source:
+
+                embedding = (
+                    self.embedding_model.encode(
+                        source
+                    )
+                )
+
+                self.neo.update_embedding(
+                    repository_id=repository_id,
+                    qualified_name=cls[
+                        "qualified_name"
+                    ],
+                    embedding=embedding,
+                )
+
+            self._embed_functions(
+                repository_id,
+                cls["methods"],
+            )

app/services/github_service.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+from uuid import uuid4
+
+from git import Repo
+
+
+class GithubService:
+
+    def clone(
+        self,
+        url: str,
+        destination_root: Path,
+    ):
+
+        repo_name = url.rstrip("/").split("/")[-1]
+
+        repository_id = uuid4().hex[:8]
+
+        folder_name = f"{repo_name}_{repository_id}"
+
+        destination = destination_root / folder_name
+
+        Repo.clone_from(
+            url,
+            destination,
+        )
+
+        return {
+            "repository_id": repository_id,
+            "repo_path": destination,
+        }
+
+    def get_repo(
+        self,
+        repo_path,
+    ):
+        return Repo(repo_path)

app/services/graph_service.py

@@ -0,0 +1,217 @@
+from app.repositories.neo4j_repository import Neo4jRepository
+
+
+class GraphService:
+
+    def __init__(self):
+
+        self.neo = Neo4jRepository()
+
+    def build(
+        self,
+        repository_id: str,
+        resolved,
+    ):
+
+        for file in resolved:
+
+            self.neo.merge_file(
+                repository_id=repository_id,
+                path=file["path"],
+            )
+
+            self._create_imports(
+                repository_id,
+                file,
+            )
+
+            self._create_functions(
+                repository_id,
+                file,
+            )
+
+            self._create_classes(
+                repository_id,
+                file,
+            )
+
+            self._create_declares(
+                repository_id,
+                file,
+            )
+
+            self._create_has_methods(
+                repository_id,
+                file,
+            )
+
+            self._create_edges(
+                repository_id,
+                file,
+            )
+
+        self.neo.create_vector_indexes()
+
+    def _create_functions(
+        self,
+        repository_id: str,
+        file,
+    ):
+
+        for function in file["functions"]:
+
+            self.neo.merge_function(
+                repository_id=repository_id,
+                qualified_name=function["qualified_name"],
+                name=function["name"],
+                source_code=function["source_code"],
+            )
+
+    def _create_classes(
+        self,
+        repository_id: str,
+        file,
+    ):
+
+        for cls in file["classes"]:
+
+            self.neo.merge_class(
+                repository_id=repository_id,
+                qualified_name=cls["qualified_name"],
+                name=cls["name"],
+                source_code=cls["source_code"],
+            )
+
+            for method in cls["methods"]:
+
+                self.neo.merge_function(
+                    repository_id=repository_id,
+                    qualified_name=method["qualified_name"],
+                    name=method["name"],
+                    source_code=method["source_code"],
+                )
+
+    def _create_declares(
+        self,
+        repository_id: str,
+        file,
+    ):
+
+        for function in file["functions"]:
+
+            self.neo.create_declares(
+                repository_id=repository_id,
+                file_path=file["path"],
+                qualified_name=function["qualified_name"],
+            )
+
+        for cls in file["classes"]:
+
+            self.neo.create_declares(
+                repository_id=repository_id,
+                file_path=file["path"],
+                qualified_name=cls["qualified_name"],
+            )
+
+    def _create_has_methods(
+        self,
+        repository_id: str,
+        file,
+    ):
+
+        for cls in file["classes"]:
+
+            for method in cls["methods"]:
+
+                self.neo.create_has_method(
+                    repository_id=repository_id,
+                    class_name=cls["qualified_name"],
+                    method_name=method["qualified_name"],
+                )
+
+    def _create_imports(
+        self,
+        repository_id: str,
+        file,
+    ):
+
+        for imp in file["imports"]:
+
+            module = imp["module"]
+
+            if not module:
+                continue
+
+            self.neo.merge_module(
+                repository_id=repository_id,
+                module=module,
+            )
+
+            self.neo.create_import(
+                repository_id=repository_id,
+                file_path=file["path"],
+                module=module,
+                symbol=imp["name"],
+                alias=imp["alias"],
+            )
+
+    def _create_edges(
+        self,
+        repository_id: str,
+        file,
+    ):
+
+        self._create_function_edges(
+            repository_id,
+            file["functions"],
+        )
+
+        for cls in file["classes"]:
+
+            self._create_function_edges(
+                repository_id,
+                cls["methods"],
+            )
+
+    def _create_function_edges(
+        self,
+        repository_id: str,
+        functions,
+    ):
+
+        for function in functions:
+
+            source = function["qualified_name"]
+
+            for call in function["calls"]:
+
+                target = call["qualified_name"]
+
+                if target is None:
+                    continue
+
+                if target.startswith("app."):
+
+                    self.neo.merge_call(
+                        repository_id=repository_id,
+                        source=source,
+                        target=target,
+                    )
+
+                else:
+
+                    self.neo.merge_external_function(
+                        repository_id=repository_id,
+                        qualified_name=target,
+                    )
+
+                    self.neo.create_belongs_to(
+                        repository_id=repository_id,
+                        qualified_name=target,
+                    )
+
+                    self.neo.merge_call(
+                        repository_id=repository_id,
+                        source=source,
+                        target=target,
+                    )

app/services/index_service.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+import json
+from pydantic import BaseModel
+
+
+class IndexService:
+
+    INDEX_FOLDER = "index"
+
+    def _get_index_path(self, repo_path: Path) -> Path:
+
+        index_path = repo_path / self.INDEX_FOLDER
+        index_path.mkdir(exist_ok=True)
+
+        return index_path
+
+    def save(self, repo_path: Path, filename: str, data):
+
+        index_path = self._get_index_path(repo_path)
+
+        output = index_path / filename
+
+        if isinstance(data, BaseModel):
+            payload = data.model_dump()
+
+        elif isinstance(data, list):
+            payload = [
+                item.model_dump() if isinstance(item, BaseModel) else item
+                for item in data
+            ]
+
+        else:
+            payload = data
+
+        with open(output, "w", encoding="utf-8") as f:
+            json.dump(
+                payload,
+                f,
+                indent=4,
+                ensure_ascii=False,
+            )
+
+    def load(self, repo_path: Path, filename: str):
+
+        index_path = self._get_index_path(repo_path)
+
+        with open(index_path / filename, encoding="utf-8") as f:
+            return json.load(f)

app/services/llm_service.py

@@ -0,0 +1,69 @@
+from openai import OpenAI
+
+from app.core.settings import settings
+
+
+class LLMService:
+
+    def __init__(self):
+
+        self.client = OpenAI(
+            api_key=settings.openrouter_api_key,
+            base_url="https://openrouter.ai/api/v1",
+        )
+
+    def chat(
+        self,
+        question: str,
+        context: str,
+    ) -> str:
+
+        prompt = self._build_prompt(
+            question,
+            context,
+        )
+
+        response = self.client.chat.completions.create(
+            model=settings.llm_model,
+            temperature=0.2,
+            messages=[
+                {
+                    "role": "system",
+                    "content": (
+                        "You are an expert software engineer. "
+                        "Answer only using the provided repository context."
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": prompt,
+                },
+            ],
+        )
+
+        return response.choices[0].message.content
+
+    def _build_prompt(
+        self,
+        question: str,
+        context: str,
+    ) -> str:
+
+        return f"""
+Repository Context
+==================
+
+{context}
+
+==================
+
+Question:
+{question}
+
+Instructions:
+
+- Answer only using the repository context.
+- If the answer cannot be inferred from the context, say so.
+- Be concise.
+- Mention function and class names using their qualified names.
+"""

app/services/metadata_service.py

@@ -0,0 +1,114 @@
+from pathlib import Path
+
+from git import Repo
+
+from app.models.metadata import (
+    RepositoryMetadata,
+    RepositoryInfo,
+    StructureInfo,
+    ConfigurationInfo,
+)
+
+
+class MetadataService:
+
+    def extract(self, repo_path: Path):
+
+        repo = Repo(repo_path)
+
+        branch = repo.active_branch.name
+
+        latest_commit = repo.head.commit.hexsha
+
+        total_files = 0
+        python_files = 0
+        directories = 0
+
+        size = 0
+
+        has_readme = False
+        has_license = False
+        has_dockerfile = False
+        has_docker_compose = False
+
+        requirements = []
+
+        for path in repo_path.rglob("*"):
+
+            if path.is_dir():
+                directories += 1
+                continue
+
+            total_files += 1
+
+            size += path.stat().st_size
+
+            if path.suffix == ".py":
+                python_files += 1
+
+            filename = path.name.lower()
+
+            if filename.startswith("readme"):
+                has_readme = True
+
+            elif filename.startswith("license"):
+                has_license = True
+
+            elif filename == "dockerfile":
+                has_dockerfile = True
+
+            elif filename == "docker-compose.yml":
+                has_docker_compose = True
+
+            elif filename == "requirements.txt":
+
+                with open(path) as f:
+
+                    for line in f:
+
+                        line = line.strip()
+
+                        if line and not line.startswith("#"):
+
+                            requirements.append(line)
+
+        return RepositoryMetadata(
+
+            repository=RepositoryInfo(
+
+                name=repo_path.name,
+
+                path=str(repo_path),
+
+                branch=branch,
+
+                latest_commit=latest_commit,
+
+                size_mb=round(size / 1024 / 1024, 2),
+
+            ),
+
+            structure=StructureInfo(
+
+                total_files=total_files,
+
+                python_files=python_files,
+
+                directories=directories,
+
+            ),
+
+            configuration=ConfigurationInfo(
+
+                has_readme=has_readme,
+
+                has_license=has_license,
+
+                has_dockerfile=has_dockerfile,
+
+                has_docker_compose=has_docker_compose,
+
+                requirements=requirements,
+
+            ),
+        )

app/services/parser_service.py

@@ -0,0 +1,221 @@
+import ast
+from pathlib import Path
+
+from app.models.code import (
+    ImportInfo,
+    FunctionInfo,
+    ClassInfo,
+    PythonFileInfo,
+    CallInfo,
+)
+
+
+class FunctionCallVisitor(ast.NodeVisitor):
+
+    def __init__(self):
+        self.calls = []
+
+    def visit_Call(self, node: ast.Call):
+
+        name = self._get_call_name(node.func)
+
+        if name is not None:
+
+            self.calls.append(
+                CallInfo(
+                    name=name,
+                    line=node.lineno,
+                )
+            )
+
+        self.generic_visit(node)
+
+    def _get_call_name(self, node):
+
+        if isinstance(node, ast.Name):
+            return node.id
+
+        if isinstance(node, ast.Attribute):
+
+            parts = []
+
+            while isinstance(node, ast.Attribute):
+                parts.append(node.attr)
+                node = node.value
+
+            if isinstance(node, ast.Name):
+                parts.append(node.id)
+
+            return ".".join(reversed(parts))
+
+        return None
+
+
+class ParserService:
+    def _module_name(self, file_path: Path):
+
+        parts = list(file_path.parts)
+
+        if "app" in parts:
+
+            index = parts.index("app")
+
+            parts = parts[index:]
+
+        parts[-1] = parts[-1].replace(".py", "")
+
+        return ".".join(parts)
+
+    def parse_file(self, file_path: Path) -> PythonFileInfo:
+
+        module_name = self._module_name(file_path)
+
+        source = file_path.read_text(
+            encoding="utf-8",
+            errors="ignore",
+        )
+
+        lines = source.splitlines()
+
+        tree = ast.parse(source)
+
+        imports = []
+        classes = []
+        functions = []
+
+        for node in tree.body:
+
+            if isinstance(node, ast.Import):
+
+                for alias in node.names:
+
+                    imports.append(
+                        ImportInfo(
+                            module=alias.name,
+                            name=alias.name,
+                            alias=alias.asname,
+                        )
+                    )
+
+            elif isinstance(node, ast.ImportFrom):
+
+                for alias in node.names:
+
+                    imports.append(
+                        ImportInfo(
+                            module=node.module,
+                            name=alias.name,
+                            alias=alias.asname,
+                        )
+                    )
+
+            elif isinstance(node, ast.FunctionDef):
+
+                functions.append(
+                    self._parse_function(
+                        node,
+                        module_name,
+                        lines=lines,
+                    )
+                )
+
+            elif isinstance(node, ast.ClassDef):
+
+                methods = []
+
+                for child in node.body:
+
+                    if isinstance(child, ast.FunctionDef):
+
+                        methods.append(
+                            self._parse_function(
+                                node=child,
+                                module_name=module_name,
+                                lines=lines,
+                                class_name=node.name,
+                            )
+                        )
+                class_source = self._get_source_code(
+                    node,
+                    lines,
+                )
+
+                classes.append(
+
+                    ClassInfo(
+
+                        name=node.name,
+
+                        qualified_name=f"{module_name}.{node.name}",
+
+                        line=node.lineno,
+
+                        end_line=node.end_lineno,
+
+                        source_code=class_source,
+
+                        methods=methods,
+                    )
+                )
+
+        return PythonFileInfo(
+            path=str(file_path),
+            imports=imports,
+            classes=classes,
+            functions=functions,
+        )
+    def _get_source_code(
+        self,
+        node,
+        lines,
+    ) -> str:
+
+        return "\n".join(
+            lines[node.lineno - 1 : node.end_lineno]
+        )
+
+    def _parse_function(
+        self,
+        node,
+        module_name,
+        lines,
+        class_name=None,
+    ):
+
+        visitor = FunctionCallVisitor()
+
+        visitor.visit(node)
+
+        if class_name:
+
+            qualified = f"{module_name}.{class_name}.{node.name}"
+
+        else:
+
+            qualified = f"{module_name}.{node.name}"
+
+        print("module_name:", repr(module_name))
+        print("class_name:", repr(class_name))
+        print("node.name:", repr(node.name))
+        print("qualified:", repr(qualified))        
+        source_code = self._get_source_code(
+            node,
+            lines,
+        )
+
+        return FunctionInfo(
+
+            name=node.name,
+
+            qualified_name=qualified,
+
+            line=node.lineno,
+
+            end_line=node.end_lineno,
+
+            docstring=ast.get_docstring(node),
+
+            source_code=source_code,
+
+            calls=visitor.calls,
+        )

app/services/resolver_service.py

@@ -0,0 +1,115 @@
+from copy import deepcopy
+
+# TODO:
+# If multiple symbols have the same name,
+# keep all of them instead of overwriting.
+class ResolverService:
+
+    def resolve(self, code_index: list[dict]) -> list[dict]:
+
+        resolved = deepcopy(code_index)
+
+        symbols = self._build_symbol_table(resolved)
+
+        for file in resolved:
+
+            import_table = self._build_import_table(file)
+
+            self._resolve_functions(
+                file["functions"],
+                symbols,
+                import_table,
+            )
+
+            for cls in file["classes"]:
+
+                self._resolve_functions(
+                    cls["methods"],
+                    symbols,
+                    import_table,
+                )
+
+        return resolved
+
+    def _build_symbol_table(self, code_index):
+
+        table = {}
+
+        for file in code_index:
+
+            for function in file["functions"]:
+
+                table[
+                    function["qualified_name"]
+                    .split(".")[-1]
+                ] = function["qualified_name"]
+
+            for cls in file["classes"]:
+
+                table[
+                    cls["qualified_name"]
+                    .split(".")[-1]
+                ] = cls["qualified_name"]
+
+                for method in cls["methods"]:
+
+                    table[
+                        method["qualified_name"]
+                        .split(".")[-1]
+                    ] = method["qualified_name"]
+
+        return table
+
+    def _resolve_functions(
+        self,
+        functions,
+        symbols,
+        imports,
+    ):
+
+        for function in functions:
+
+            for call in function["calls"]:
+
+                raw = call["name"]
+
+                parts = raw.split(".")
+
+                first = parts[0]
+
+                # اول importهای فایل
+                if first in imports:
+
+                    resolved = imports[first]
+
+                    if len(parts) > 1:
+                        resolved += "." + ".".join(parts[1:])
+
+                    call["qualified_name"] = resolved
+
+                # بعد symbolهای پروژه
+                elif first in symbols:
+
+                    resolved = symbols[first]
+
+                    if len(parts) > 1:
+                        resolved += "." + ".".join(parts[1:])
+
+                    call["qualified_name"] = resolved
+
+    def _build_import_table(self, file):
+
+        table = {}
+
+        for imp in file["imports"]:
+
+            key = imp["alias"] or imp["name"]
+
+            if imp["module"]:
+
+                if imp["module"] == imp["name"]:
+                    table[key] = imp["module"]
+                else:
+                    table[key] = f'{imp["module"]}.{imp["name"]}'
+
+        return table

app/services/retrieval_service.py

@@ -0,0 +1,35 @@
+from app.repositories.neo4j_repository import (
+    Neo4jRepository,
+)
+
+from app.services.embedding_model_service import (
+    EmbeddingModelService,
+)
+
+
+class RetrievalService:
+
+    def __init__(self):
+
+        self.embedding = EmbeddingModelService()
+
+        self.neo = Neo4jRepository()
+
+    def search(
+        self,
+        repository_id: str,
+        query: str,
+        limit: int = 5,
+        hops: int = 1,
+    ):
+
+        vector = self.embedding.encode(
+            query
+        )
+
+        return self.neo.retrieve_context(
+            repository_id=repository_id,
+            embedding=vector,
+            limit=limit,
+            hops=hops,
+        )

app/tests/retrieval.py

@@ -0,0 +1,39 @@
+from app.services.retrieval_service import (
+    RetrievalService,
+)
+
+service = RetrievalService()
+
+context = service.search(
+    "graph creation",
+)
+
+print()
+
+print("========== NODES ==========")
+
+for node in context.nodes:
+
+    print(node.labels)
+
+    print(node.qualified_name)
+
+    print(node.properties)
+
+    print("-" * 50)
+
+print()
+
+print("========== EDGES ==========")
+
+for edge in context.edges:
+
+    print(
+        edge.source,
+        "--",
+        edge.type,
+        "-->",
+        edge.target,
+    )
+print(len(context.nodes))
+print(len(context.edges))

app/utils/file_utils.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+
+def get_python_files(root: Path):
+
+    return sorted(root.rglob("*.py"))