@callback delete_by_chunks(chunk_ids :: [binary()], opts :: keyword()) ::
  :ok | {:error, term()}

Deletes all graph data for the given chunk IDs.

Removes mentions referencing these chunks, and cleans up orphaned entities (entities with no remaining mentions).

@callback delete_by_collection(binary(), opts :: keyword()) :: :ok | {:error, term()}

Deletes all graph data for a collection.

Removes all entities, relationships, mentions, and communities associated with the collection.

@callback find_entities(binary(), opts :: keyword()) :: [map()]

Finds all entities in a collection.

@callback find_related_entities(binary(), depth :: pos_integer(), opts :: keyword()) :: [
  map()
]

Finds entities related to the given entity within the specified depth.

Enables graph-native traversal operations.

@callback get_community(community_id :: binary(), opts :: keyword()) ::
  {:ok, map()} | {:error, :not_found}

Retrieves a single community by ID.

@callback get_community_summaries(binary(), opts :: keyword()) :: [map()]

Retrieves community summaries for a collection.

@callback get_entity(binary(), opts :: keyword()) :: {:ok, map()} | {:error, :not_found}

Retrieves a single entity by ID.

@callback get_mentions(binary(), opts :: keyword()) :: [map()]

Retrieves mentions for an entity with chunk context.

Returns mentions with associated chunk text for display.

@callback get_relationship(relationship_id :: binary(), opts :: keyword()) ::
  {:ok, map()} | {:error, :not_found}

Retrieves a single relationship by ID.

@callback get_relationships(binary(), opts :: keyword()) :: [map()]

Retrieves all relationships for an entity.

Returns relationships where the entity is either source or target.

@callback list_communities(opts :: keyword()) :: [map()]

Lists communities with optional filtering and pagination.

Options

• :collection_id - Filter by collection (nil for all)
• :level - Filter by hierarchy level
• :search - Search in summary
• :limit - Maximum results (default: 50)
• :offset - Pagination offset (default: 0)

Returns communities with entity counts.

@callback list_entities(opts :: keyword()) :: [map()]

Lists entities with optional filtering and pagination.

Options

• :collection_id - Filter by collection (nil for all)
• :type - Filter by entity type
• :search - Search in entity name
• :limit - Maximum results (default: 50)
• :offset - Pagination offset (default: 0)

Returns entities with aggregated counts (mention_count, relationship_count).

@callback list_relationships(opts :: keyword()) :: [map()]

Lists relationships with optional filtering and pagination.

Options

• :collection_id - Filter by collection (nil for all)
• :type - Filter by relationship type
• :search - Search in entity names or type
• :strength - Filter by strength (:strong, :medium, :weak)
• :limit - Maximum results (default: 50)
• :offset - Pagination offset (default: 0)

Returns relationships with source/target entity names.

@callback persist_communities(binary(), [map()], opts :: keyword()) ::
  :ok | {:error, term()}

Persists community data for a collection.

@callback persist_entities(binary(), [map()], opts :: keyword()) ::
  {:ok, map()} | {:error, term()}

Persists entities to the graph store.

Returns a map of entity names to their assigned IDs.

@callback persist_mentions([map()], map(), opts :: keyword()) :: :ok | {:error, term()}

Persists entity mentions (links between entities and chunks).

@callback persist_relationships([map()], map(), opts :: keyword()) ::
  :ok | {:error, term()}

Persists relationships between entities.

@callback search([String.t()], [binary()] | nil, opts :: keyword()) :: [map()]

Searches for chunks related to the given entity names.

Returns scored chunk results.

@callback search_by_embedding([float()], [binary()] | nil, opts :: keyword()) :: [map()]

Searches for entities by embedding similarity.

Returns entities whose description embeddings are most similar to the query embedding, sorted by similarity descending.