@spec add_edge(term(), term(), atom(), keyword()) :: :ok

Adds an edge between two nodes.

Edge types: :calls, :imports, :defines, :inherits, :implements

Options

• :weight - Edge weight (default: 1.0) for weighted graph algorithms
• :metadata - Additional metadata map

@spec add_edges([tuple()]) :: :ok

Adds multiple edges to the graph in bulk.

@spec add_node(atom(), term(), map()) :: :ok

Adds a node to the graph.

Node types: :module, :function, :type, :variable, :file

@spec add_nodes([map()]) :: :ok

Adds multiple nodes to the graph in bulk.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec clear() :: :ok

Clears all data from the graph.

@spec compact() :: :ok | {:error, term()}

Triggers database compaction on the underlying store to reclaim free space.

@spec count_embeddings() :: non_neg_integer()

Returns the number of stored embeddings (vectors) in the active backend.

@spec count_nodes_by_type(atom()) :: non_neg_integer()

Counts nodes of a specific type.

@spec embeddings_table() :: atom()

Returns the ETS table reference for embeddings.

Useful for direct access or persistence operations.

@spec find_function(term(), atom()) :: map() | nil

Finds a function node by module and name (any arity).

@spec find_node(atom(), term()) :: map() | nil

Finds a node by type and id.

@spec get_edge_weight(term(), term(), atom()) :: float() | nil

Gets the weight of an edge between two nodes.

Returns the weight (default: 1.0) if edge exists, nil otherwise.

@spec get_embedding(atom(), term()) :: {[float()], String.t()} | nil

Retrieves the embedding for a node.

Returns {embedding, text} tuple or nil if not found.

@spec get_function(term(), atom(), non_neg_integer()) :: map() | nil

Retrieves a function node by module, name, and arity.

Returns the function data or nil if not found.

Parameters

• module - The module containing the function
• name - The function name (atom)
• arity - The function arity (non-negative integer)

Examples

iex> Store.add_node(:function, {MyModule, :test, 2}, %{name: :test, arity: 2})
iex> Store.get_function(MyModule, :test, 2)
%{name: :test, arity: 2}

iex> Store.get_function(MyModule, :nonexistent, 1)
nil

@spec get_incoming_edges(term(), atom()) :: [map()]

Gets all incoming edges to a node of a specific type.

@spec get_module(term()) :: map() | nil

Retrieves a module node by name.

Returns the module data or nil if not found.

Examples

iex> Store.add_node(:module, MyModule, %{name: MyModule, file: "lib/my_module.ex"})
iex> Store.get_module(MyModule)
%{name: MyModule, file: "lib/my_module.ex"}

iex> Store.get_module(NonExistentModule)
nil

@spec get_node({atom(), term()}) :: map() | nil

Retrieves a node by its composite key.

Parameters

• node_key - Tuple of {node_type, node_id}

Returns

• Node data map if found
• nil if not found

Examples

iex> Store.add_node(:module, MyModule, %{name: MyModule})
iex> Store.get_node({:module, MyModule})
%{name: MyModule}

iex> Store.get_node({:module, NonExistent})
nil

@spec get_outgoing_edges(term(), atom()) :: [map()]

Gets all outgoing edges from a node of a specific type.

@spec list_edges(keyword()) :: [map()]

Lists all edges with optional filtering by type and limit.

Parameters

• opts - Keyword list with options:
  • :edge_type - Filter by edge type (optional)
  • :limit - Maximum number of edges to return (default: 1000)

Returns

List of edge maps with keys:

• :from - Source node
• :to - Target node
• :type - Edge type
• :metadata - Edge metadata including weight

Examples

iex> Store.list_edges(limit: 100)
[%{from: node1, to: node2, type: :calls, metadata: %{weight: 1.0}}, ...]

iex> Store.list_edges(edge_type: :imports)
[%{from: mod1, to: mod2, type: :imports, metadata: %{weight: 1.0}}, ...]

@spec list_embeddings(atom() | nil, non_neg_integer() | :infinity) :: [tuple()]

Lists all embeddings with optional type filter.

Returns list of {node_type, node_id, embedding, text} tuples.

@spec list_functions(keyword()) :: [%{id: term(), data: map()}]

Lists function nodes with optional filtering by module.

Parameters

• opts - Keyword list with options:
  • :module - Filter by module (optional)
  • :limit - Maximum number of functions to return (default: 1000)

Returns

List of function maps with keys:

• :id - Function identifier tuple {module, name, arity}
• :data - Function data

Examples

iex> Store.add_node(:function, {MyModule, :test, 2}, %{name: :test, arity: 2})
iex> Store.list_functions()
[%{id: {MyModule, :test, 2}, data: %{name: :test, arity: 2}}]

iex> Store.list_functions(module: MyModule, limit: 50)
[%{id: {MyModule, :test, 2}, data: ...}, ...]

@spec list_modules() :: [%{id: term(), data: map()}]

Lists all module nodes.

Returns

List of module maps with keys:

• :id - Module identifier (atom)
• :data - Module data

Examples

iex> Store.add_node(:module, ModuleA, %{name: ModuleA, file: "lib/a.ex"})
iex> Store.add_node(:module, ModuleB, %{name: ModuleB, file: "lib/b.ex"})
iex> Store.list_modules()
[%{id: ModuleA, data: %{name: ModuleA, file: "lib/a.ex"}}, ...]

@spec list_nodes(atom() | nil, non_neg_integer() | :infinity) :: [map()]

Lists nodes with optional filtering by type.

@spec load_project(String.t()) :: :ok

Switches the store to a specific project path.

Clears all current graph data (nodes, edges, embeddings, file tracker), then loads the cached graph and embeddings for the given project path. This ensures the store contains only data for the target project.

Parameters

• project_path - Absolute path to the project directory

Returns

• :ok

@spec remove_node(atom(), term()) :: :ok

Removes a node from the graph.

Also removes all edges connected to this node (both incoming and outgoing) and any embedding associated with the node.

Returns :ok if successful, {:error, :timeout} on timeout.

@spec save_cache(String.t() | nil) :: :ok

Saves current graph, embeddings, and analysis cache to disk for the given project path.

@spec stats() :: map()

Returns statistics about the graph.

@spec store_embedding(atom(), term(), [float()], String.t()) :: :ok

Stores an embedding vector for a node.

@spec store_embeddings([tuple()]) :: :ok

Stores a batch of embedding vectors.

@spec sync() :: :ok

Synchronous barrier: blocks until all pending casts have been processed.

Useful in tests to ensure async operations (add_node, add_edge, etc.) have been applied to ETS before querying.

@spec update_node_metadata(atom(), term(), map()) :: :ok

Merges additional metadata into an existing node.

If the node exists, its metadata map is deep-merged with new_metadata. If the node does not exist, this is a no-op.

Parameters

• node_type -- :module, :function, etc.
• node_id -- the node identifier
• new_metadata -- map of metadata to merge