ai-learning-dashboard / app /knowledge /graph /graph_builder.py
simhaa-hat's picture
Deploy backend to Hugging Face Spaces
4fb906a verified
Raw History Blame Contribute Delete
13.2 kB
"""Graph Builder Service — parses and ingests code structures into the Neo4j Knowledge Graph."""
from __future__ import annotations
from typing import Any
from pathlib import Path
from app.core.logging import get_logger
from app.knowledge.graph.neo4j_service import Neo4jService
logger = get_logger(__name__)
class GraphBuilder:
"""Methods to construct nodes and relationships representing a code project in Neo4j."""
@classmethod
async def create_project(cls, project_id: str, name: str) -> None:
"""Create a Project root node."""
query = """
MERGE (p:Project {id: $project_id})
ON CREATE SET p.name = $name, p.created_at = timestamp()
ON MATCH SET p.name = $name, p.updated_at = timestamp()
"""
await Neo4jService.execute_query(query, {"project_id": project_id, "name": name})
@classmethod
async def create_directory(cls, project_id: str, path: str) -> str | None:
"""Create a Directory node and link to its parent (Project or Directory)."""
path_parts = Path(path).parts
current_dir_id = None
parent_id = None
for i, part in enumerate(path_parts):
current_path = str(Path(*path_parts[:i+1]))
dir_id = f"{project_id}:dir:{current_path}"
if i == 0:
# Root directory links to Project
query = """
MERGE (d:Directory {id: $dir_id})
SET d.name = $name, d.path = $path
WITH d
MATCH (p:Project {id: $project_id})
MERGE (p)-[:CONTAINS]->(d)
"""
await Neo4jService.execute_query(
query,
{
"project_id": project_id,
"dir_id": dir_id,
"name": part,
"path": current_path
}
)
else:
# Subdirectory links to parent Directory
query = """
MERGE (d:Directory {id: $dir_id})
SET d.name = $name, d.path = $path
WITH d
MATCH (parent:Directory {id: $parent_id})
MERGE (parent)-[:CONTAINS]->(d)
"""
await Neo4jService.execute_query(
query,
{
"project_id": project_id,
"dir_id": dir_id,
"name": part,
"path": current_path,
"parent_id": parent_id
}
)
parent_id = dir_id
current_dir_id = dir_id
return current_dir_id
@classmethod
async def create_file(cls, project_id: str, path: str, language: str = "", content_hash: str = "") -> str:
"""Create a File node and link to its parent Directory."""
file_path = Path(path)
parent_dir_path = str(file_path.parent) if file_path.parent != Path(".") else ""
parent_dir_id = None
if parent_dir_path:
parent_dir_id = await cls.create_directory(project_id, parent_dir_path)
file_id = f"{project_id}:file:{path}"
if parent_dir_id:
query = """
MERGE (f:File {id: $file_id})
SET f.name = $name, f.path = $path, f.language = $language, f.content_hash = $content_hash
WITH f
MATCH (d:Directory {id: $parent_dir_id})
MERGE (d)-[:CONTAINS]->(f)
"""
await Neo4jService.execute_query(
query,
{
"file_id": file_id,
"name": file_path.name,
"path": path,
"language": language,
"content_hash": content_hash,
"parent_dir_id": parent_dir_id
}
)
else:
# File is directly in project root
query = """
MERGE (f:File {id: $file_id})
SET f.name = $name, f.path = $path, f.language = $language, f.content_hash = $content_hash
WITH f
MATCH (p:Project {id: $project_id})
MERGE (p)-[:CONTAINS]->(f)
"""
await Neo4jService.execute_query(
query,
{
"project_id": project_id,
"file_id": file_id,
"name": file_path.name,
"path": path,
"language": language,
"content_hash": content_hash
}
)
return file_id
@classmethod
async def create_module(cls, project_id: str, name: str, file_path: str) -> None:
"""Create a Module node and link to File."""
file_id = await cls.create_file(project_id, file_path)
query = """
MERGE (m:Module {id: $id})
SET m.name = $name, m.file_path = $file_path
WITH m
MATCH (f:File {id: $file_id})
MERGE (f)-[:DEFINES]->(m)
"""
await Neo4jService.execute_query(
query,
{
"project_id": project_id,
"id": f"{project_id}:{name}",
"name": name,
"file_path": file_path,
"file_id": file_id
}
)
@classmethod
async def create_class(cls, project_id: str, file_path: str, name: str, docstring: str = "") -> None:
"""Create a Class node and link to its parent File."""
file_id = await cls.create_file(project_id, file_path)
query = """
MERGE (c:Class {id: $id})
SET c.name = $name, c.docstring = $docstring
WITH c
MATCH (f:File {id: $file_id})
MERGE (f)-[:DEFINES]->(c)
"""
await Neo4jService.execute_query(
query,
{
"id": f"{project_id}:{file_path}:{name}",
"file_id": file_id,
"name": name,
"docstring": docstring
}
)
@classmethod
async def create_function(
cls,
project_id: str,
file_path: str,
parent_name: str,
parent_type: str,
name: str,
signature: str = "",
docstring: str = "",
) -> None:
"""Create a Function node and link to its parent File or Class."""
assert parent_type in ("File", "Class")
if parent_type == "Class":
func_id = f"{project_id}:{file_path}:{parent_name}:{name}"
parent_id = f"{project_id}:{file_path}:{parent_name}"
else:
func_id = f"{project_id}:{file_path}::{name}"
parent_id = await cls.create_file(project_id, file_path)
query = f"""
MERGE (f:Function {{id: $id}})
SET f.name = $name, f.signature = $signature, f.docstring = $docstring
WITH f
MATCH (p:{parent_type} {{id: $parent_id}})
MERGE (p)-[:DEFINES]->(f)
"""
await Neo4jService.execute_query(
query,
{
"id": func_id,
"parent_id": parent_id,
"name": name,
"signature": signature,
"docstring": docstring,
},
)
@classmethod
async def create_dependency(cls, project_id: str, from_module: str, to_module: str) -> None:
"""Create a DEPENDS_ON relationship between modules."""
query = """
MATCH (m1:Module {id: $from_id})
MATCH (m2:Module {id: $to_id})
MERGE (m1)-[:DEPENDS_ON]->(m2)
"""
await Neo4jService.execute_query(
query,
{
"from_id": f"{project_id}:{from_module}",
"to_id": f"{project_id}:{to_module}"
}
)
@classmethod
async def create_call_relationship(cls, project_id: str, from_func: str, to_func: str) -> None:
"""Create a CALLS relationship between functions."""
query = """
MATCH (f1:Function) WHERE f1.name = $from_func AND f1.id STARTS WITH $prefix
MATCH (f2:Function) WHERE f2.name = $to_func AND f2.id STARTS WITH $prefix
MERGE (f1)-[:CALLS]->(f2)
"""
await Neo4jService.execute_query(
query,
{
"from_func": from_func,
"to_func": to_func,
"prefix": f"{project_id}:"
}
)
@classmethod
async def clear_project_structure(cls, project_id: str) -> None:
"""Clear all nodes and relationships for a project before re-ingesting."""
query = """
MATCH (p:Project {id: $project_id})
OPTIONAL MATCH (p)-[:CONTAINS*]->(n)
DETACH DELETE p, n
"""
await Neo4jService.execute_query(query, {"project_id": project_id})
@classmethod
async def ingest_project_structure(
cls,
project_id: str,
analysis: dict[str, Any],
files: list[dict[str, Any]]
) -> None:
"""Orchestrates ingestion of structural analysis results from architectural parsing.
Args:
project_id: Target project identifier.
analysis: Dict structure containing modules, classes, and call maps.
files: List of file dicts with path, language, etc.
"""
logger.info("neo4j_ingest_started", project_id=project_id)
# 1. Clear existing structure first
await cls.clear_project_structure(project_id)
# 2. Root project
await cls.create_project(project_id, analysis.get("name", "Project"))
# 3. Ingest all files and directories first
for f in files:
await cls.create_file(
project_id,
f.get("path", ""),
f.get("language", ""),
f.get("content_hash", "")
)
# 4. Ingest modules
for mod in analysis.get("modules", []):
mod_name = mod.get("name")
file_path = mod.get("file_path", "")
await cls.create_module(project_id, mod_name, file_path)
# Ingest classes
for cls_data in mod.get("classes", []):
class_name = cls_data.get("name")
await cls.create_class(
project_id,
file_path,
class_name,
cls_data.get("docstring", "")
)
# Ingest class methods
for method in cls_data.get("methods", []):
await cls.create_function(
project_id=project_id,
file_path=file_path,
parent_name=class_name,
parent_type="Class",
name=method.get("name"),
signature=method.get("signature", ""),
docstring=method.get("docstring", ""),
)
# Ingest module functions (non-methods)
for func in mod.get("functions", []):
await cls.create_function(
project_id=project_id,
file_path=file_path,
parent_name=file_path,
parent_type="File",
name=func.get("name"),
signature=func.get("signature", ""),
docstring=func.get("docstring", ""),
)
# 5. Ingest module-level dependencies
for dep in analysis.get("dependencies", []):
await cls.create_dependency(project_id, dep.get("from"), dep.get("to"))
# 6. Ingest call graphs
for call in analysis.get("calls", []):
await cls.create_call_relationship(project_id, call.get("from"), call.get("to"))
logger.info("neo4j_ingest_completed", project_id=project_id)
@classmethod
async def validate_structure(cls, project_id: str, expected_files: list[str]) -> dict[str, Any]:
"""Validate that the knowledge graph exactly matches the expected file list."""
query = """
MATCH (p:Project {id: $project_id})-[:CONTAINS*]->(f:File)
RETURN f.path AS path
"""
results = await Neo4jService.execute_query(query, {"project_id": project_id})
graph_files = {r["path"] for r in results}
expected_set = set(expected_files)
return {
"valid": graph_files == expected_set,
"missing_in_graph": list(expected_set - graph_files),
"extra_in_graph": list(graph_files - expected_set)
}