java-codebase-rag 0.5.3__py3-none-any.whl → 0.6.1__py3-none-any.whl

mcp_v2.py

@@ -30,7 +30,7 @@ from sentence_transformers import SentenceTransformer
 from index_common import SBERT_MODEL
 from java_codebase_rag.config import resolved_sbert_model_for_process_env
 from java_ontology import EDGE_SCHEMA, ResolveReason
-from kuzu_queries import KuzuGraph, OVERRIDE_AXIS_COMPOSED_EDGE_TYPES
+from ladybug_queries import LadybugGraph, OVERRIDE_AXIS_COMPOSED_EDGE_TYPES
 from mcp_hints import generate_hints, MCP_HINTS_STRUCTURED_FIELD_DESCRIPTION
 from search_lancedb import TABLES, run_search
 
@@ -48,6 +48,22 @@ def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
 
+# Closed value taxonomies surfaced to MCP consumers as enums. Sources of truth:
+#   Role         — VALID_ROLES in java_ontology.py + the "OTHER" inference fallback (ast_java.infer_role)
+#   Framework    — hardcoded literals across ast_java.py / build_ast_graph.py
+#   SourceLayer  — exhaustive classifier build_ast_graph._client_source_layer / _producer_source_layer
+#   ClientKind   — VALID_CLIENT_KINDS in java_ontology.py (every producer validated at index time)
+#   ProducerKind — VALID_PRODUCER_KINDS in java_ontology.py (every producer validated at index time)
+# Keep these in sync with the indexing-side taxonomies if they change.
+Role = Literal[
+    "CONTROLLER", "SERVICE", "REPOSITORY", "COMPONENT", "CONFIG",
+    "ENTITY", "CLIENT", "MAPPER", "DTO", "OTHER",
+]
+Framework = Literal["spring_mvc", "webflux", "kafka", "rabbitmq", "jms", "stream", "feign", ""]
+SourceLayer = Literal["builtin", "layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"]
+ClientKind = Literal["feign_method", "rest_template", "web_client"]
+ProducerKind = Literal["kafka_send", "stream_bridge_send"]
+
 # Stored graph edge labels for one-hop neighbors. Composed DECLARES.* and OVERRIDDEN_BY.*
 # dot-keys are separate ComposedEdgeType literals (2-hop traversal). Stored OVERRIDES is an EdgeType.
 EdgeType = Literal[
@@ -133,21 +149,30 @@ class NodeFilter(BaseModel):
 
     microservice: str | None = None
     module: str | None = None
-    source_layer: str | None = None
-    role: str | None = None
-    exclude_roles: list[str] | None = None
+    source_layer: SourceLayer | None = None
+    role: Role | None = None
+    exclude_roles: list[Role] | None = None
     annotation: str | None = None
     capability: str | None = None
     fqn_prefix: str | None = None
     symbol_kind: DeclarationSymbolKind | None = None
     symbol_kinds: list[DeclarationSymbolKind] | None = None
-    http_method: str | None = None
+    http_method: str | None = Field(
+        default=None,
+        description="HTTP verb (commonly GET/POST/PUT/DELETE/PATCH; user route annotations may yield others).",
+    )
     path_prefix: str | None = None
-    framework: str | None = None
-    client_kind: str | None = None
+    framework: Framework | None = None
+    client_kind: ClientKind | None = Field(
+        default=None,
+        description="Outbound HTTP client kind: feign_method, rest_template, or web_client.",
+    )
     target_service: str | None = None
     target_path_prefix: str | None = None
-    producer_kind: str | None = None
+    producer_kind: ProducerKind | None = Field(
+        default=None,
+        description="Outbound async producer kind: kafka_send or stream_bridge_send.",
+    )
     topic_prefix: str | None = None
 
 
@@ -157,9 +182,9 @@ class EdgeFilter(BaseModel):
     min_confidence: float | None = None
     exclude_strategies: list[str] | None = None
     include_strategies: list[str] | None = None
-    callee_declaring_role: str | None = None
-    callee_declaring_roles: list[str] | None = None
-    exclude_callee_declaring_roles: list[str] | None = None
+    callee_declaring_role: Role | None = None
+    callee_declaring_roles: list[Role] | None = None
+    exclude_callee_declaring_roles: list[Role] | None = None
 
     @model_validator(mode="after")
     def _strategy_axes_mutually_exclusive(self) -> EdgeFilter:
@@ -604,7 +629,7 @@ def _node_kind_from_id(
 
 
 def _resolve_node_kind(
-    graph: KuzuGraph,
+    graph: LadybugGraph,
     node_id: str,
 ) -> Literal["symbol", "route", "client", "producer", "unresolved_call_site"]:
     try:
@@ -733,7 +758,7 @@ def _node_ref_from_row(kind: Literal["symbol", "route", "client", "producer"], r
 
 
 def _load_node_record(
-    graph: KuzuGraph, node_id: str, kind: Literal["symbol", "route", "client", "producer"],
+    graph: LadybugGraph, node_id: str, kind: Literal["symbol", "route", "client", "producer"],
 ) -> dict[str, Any] | None:
     if kind == "symbol":
         projection = (
@@ -807,7 +832,7 @@ def _merge_overrides_edge_summary(
 
 
 def _edge_summary_for_node(
-    graph: KuzuGraph, node_id: str, *, kind: str, row: dict[str, Any]
+    graph: LadybugGraph, node_id: str, *, kind: str, row: dict[str, Any]
 ) -> dict[str, dict[str, int]]:
     summary = dict(graph.edge_counts_for(node_id))
     sym_kind = str(row.get("kind") or "")
@@ -887,7 +912,7 @@ def search_v2(
     offset: int = 0,
     path_contains: str | None = None,
     filter: NodeFilter | dict[str, Any] | str | None = None,
-    graph: KuzuGraph | None = None,
+    graph: LadybugGraph | None = None,
 ) -> SearchOutput:
     try:
         raw_filter = _coerce_filter(filter)
@@ -967,10 +992,10 @@ def find_v2(
     filter: NodeFilter | dict[str, Any] | str,
     limit: int = 25,
     offset: int = 0,
-    graph: KuzuGraph | None = None,
+    graph: LadybugGraph | None = None,
 ) -> FindOutput:
     try:
-        g = graph or KuzuGraph.get()
+        g = graph or LadybugGraph.get()
         raw_filter = _coerce_filter(filter)
         if raw_filter is None:
             raw_filter = {}
@@ -1063,10 +1088,10 @@ _DESCRIBE_UCS_ID_MESSAGE = (
 def describe_v2(
     id: str | None = None,
     fqn: str | None = None,
-    graph: KuzuGraph | None = None,
+    graph: LadybugGraph | None = None,
 ) -> DescribeOutput:
     try:
-        g = graph or KuzuGraph.get()
+        g = graph or LadybugGraph.get()
         has_id = bool(id and str(id).strip())
         has_fqn = bool(fqn and str(fqn).strip())
         if not has_id and not has_fqn:
@@ -1171,7 +1196,7 @@ def _resolve_parse_microservice_route(identifier: str) -> tuple[str, str, str] |
 
 
 def _resolve_symbol_candidates(
-    g: KuzuGraph,
+    g: LadybugGraph,
     identifier: str,
 ) -> list[tuple[NodeRef, ResolveReason, int]]:
     out: list[tuple[NodeRef, ResolveReason, int]] = []
@@ -1213,7 +1238,7 @@ def _resolve_symbol_candidates(
 
 
 def _resolve_route_candidates(
-    g: KuzuGraph,
+    g: LadybugGraph,
     identifier: str,
 ) -> list[tuple[NodeRef, ResolveReason, int]]:
     out: list[tuple[NodeRef, ResolveReason, int]] = []
@@ -1265,7 +1290,7 @@ def _resolve_route_candidates(
 
 
 def _resolve_client_candidates(
-    g: KuzuGraph,
+    g: LadybugGraph,
     identifier: str,
 ) -> list[tuple[NodeRef, ResolveReason, int]]:
     out: list[tuple[NodeRef, ResolveReason, int]] = []
@@ -1304,7 +1329,7 @@ def _resolve_client_candidates(
 
 
 def _resolve_producer_candidates(
-    g: KuzuGraph,
+    g: LadybugGraph,
     identifier: str,
 ) -> list[tuple[NodeRef, ResolveReason, int]]:
     out: list[tuple[NodeRef, ResolveReason, int]] = []
@@ -1462,7 +1487,7 @@ def _resolve_finalize_success(
 def resolve_v2(
     identifier: str,
     hint_kind: Literal["symbol", "route", "client", "producer"] | None = None,
-    graph: KuzuGraph | None = None,
+    graph: LadybugGraph | None = None,
 ) -> ResolveOutput:
     try:
         trimmed, err = _resolve_validate_identifier(identifier)
@@ -1481,7 +1506,7 @@ def resolve_v2(
         if "*" in trimmed or "?" in trimmed:
             return _resolve_finalize_success(trimmed, hint_kind, [])
 
-        g = graph or KuzuGraph.get()
+        g = graph or LadybugGraph.get()
         raw: list[tuple[NodeRef, ResolveReason, int]] = []
         for kind in _resolve_kinds_to_search(hint_kind):
             if kind == "symbol":
@@ -1726,7 +1751,7 @@ def neighbors_v2(
         declares_composed = [k for k in composed_keys if k in _MEMBER_COMPOSED_EDGE_TYPES]
         override_composed = [k for k in composed_keys if k in _OVERRIDE_COMPOSED_EDGE_TYPES]
         ordered_composed = declares_composed + override_composed
-        g = graph or KuzuGraph.get()
+        g = graph or LadybugGraph.get()
         try:
             raw_filter = _coerce_filter(filter)
             nf = (

pr_analysis.py

@@ -12,7 +12,7 @@ from typing import Any
 from unidiff import PatchSet
 from unidiff.errors import UnidiffParseError
 
-from kuzu_queries import SymbolHit, find_symbols_in_file_range, _row_to_symbol
+from ladybug_queries import SymbolHit, find_symbols_in_file_range, _row_to_symbol
 
 
 @dataclass

search_lancedb.py

@@ -675,16 +675,16 @@ def _graph_expand_merge(
     limit: int,
     extra_predicates: list[str],
     expand_depth: int,
-    kuzu_path: str | None,
+    ladybug_path: str | None,
 ) -> list[dict]:
     """Expand vector top-k through the Kuzu graph and fuse (RRF) with the original list."""
     # Lazy import so the module works without kuzu installed when graph_expand=False.
     try:
-        from kuzu_queries import KuzuGraph
+        from ladybug_queries import LadybugGraph
     except Exception:
         return vector_rows
 
-    if not KuzuGraph.exists(kuzu_path):
+    if not LadybugGraph.exists(ladybug_path):
         return vector_rows
 
     seed_fqns = sorted({r.get("primary_type_fqn") for r in vector_rows if r.get("primary_type_fqn")})
@@ -692,7 +692,7 @@ def _graph_expand_merge(
         return vector_rows
 
     try:
-        graph = KuzuGraph.get(kuzu_path)
+        graph = LadybugGraph.get(ladybug_path)
         structural = graph.expand_fqns(seed_fqns, depth=expand_depth)
         method_pairs = graph.expand_methods(
             seed_fqns, depth=expand_depth, exclude_external=True,
@@ -804,7 +804,7 @@ def run_search(
     package_prefix: str | None = None,
     graph_expand: bool = False,
     expand_depth: int = 1,
-    kuzu_path: str | None = None,
+    ladybug_path: str | None = None,
     context_neighbors: int = 0,
     role_in: list[str] | None = None,
     exclude_roles: list[str] | None = None,
@@ -890,7 +890,7 @@ def run_search(
                 limit=need,
                 extra_predicates=extra_java,
                 expand_depth=expand_depth,
-                kuzu_path=kuzu_path,
+                ladybug_path=ladybug_path,
             )
 
         window = rows[offset : offset + limit]
@@ -966,7 +966,7 @@ def main() -> None:
     parser.add_argument("--package-prefix", default=None)
     parser.add_argument("--graph-expand", action="store_true")
     parser.add_argument("--expand-depth", type=int, default=1)
-    parser.add_argument("--kuzu-path", default=None)
+    parser.add_argument("--ladybug-path", default=None)
     parser.add_argument(
         "--context-neighbors", type=int, default=0,
         help="Attach N adjacent chunks per hit as surrounding context (Java only).",
@@ -1010,7 +1010,7 @@ def main() -> None:
             package_prefix=args.package_prefix,
             graph_expand=args.graph_expand,
             expand_depth=args.expand_depth,
-            kuzu_path=args.kuzu_path,
+            ladybug_path=args.ladybug_path,
             context_neighbors=args.context_neighbors,
         )
     except Exception as e: