Skip to content

fix(graph): inconsistent schema for external modules using is_external boolean instead of dedicated label #498

Description

@vitali87

Problem

The graph schema uses two different patterns for distinguishing internal vs. external entities:

  • Packages: Separate node labels (Package vs ExternalPackage)
  • Modules: A boolean property is_external on the same Module label

This inconsistency was noted in the gdotv blog analysis (Part 2) as a schema design flaw.

The is_external property is defined in constants.py:191 as KEY_IS_EXTERNAL = "is_external" but is not part of the documented NODE_SCHEMAS in types_defs.py, not included in the protobuf schema, and not mentioned in the Cypher system prompts. This means LLM-generated Cypher queries cannot reliably distinguish external from internal modules.

Expected Behavior

Either:

  1. Create a dedicated ExternalModule label (matching the Package/ExternalPackage pattern), or
  2. Unify both patterns to use boolean flags consistently

Option 1 is preferred for consistency and because it makes Cypher queries more natural (MATCH (m:ExternalModule) vs MATCH (m:Module {is_external: true})).

Affected Components

  • codebase_rag/constants.py (KEY_IS_EXTERNAL)
  • codebase_rag/types_defs.py (NODE_SCHEMAS)
  • codebase_rag/parsers/definition_processor.py (module node creation)
  • codebase_rag/schema_builder.py (schema text generation for LLM prompts)
  • codec/schema.proto (protobuf schema)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions