# `Arcana.Graph.GraphBuilder`
[🔗](https://github.com/georgeguimaraes/arcana/blob/main/lib/arcana/graph/graph_builder.ex#L1)

Builds knowledge graph data from document chunks.

GraphBuilder orchestrates entity extraction, relationship extraction, and
mention tracking to create a knowledge graph structure from text.

## Usage

GraphBuilder is designed to integrate optionally into the ingest pipeline:

    # During ingest (when graph: true option is passed)
    chunks = Chunker.chunk(text, opts)
    {:ok, graph_data} = GraphBuilder.build(chunks,
      entity_extractor: &Arcana.Graph.EntityExtractor.NER.extract/2,
      relationship_extractor: &RelationshipExtractor.extract/3
    )

    # Convert to queryable format
    graph = GraphBuilder.to_query_graph(graph_data, chunks)

## Output Structure

The builder outputs a map with:

    %{
      entities: [%{id: "...", name: "...", type: :atom}],
      relationships: [%{source: "...", target: "...", type: "..."}],
      mentions: [%{entity_name: "...", chunk_id: "..."}]
    }

This intermediate format can be persisted to a database or converted
to the in-memory format used by `GraphQuery`.

# `build`

Builds graph data from a list of chunks.

Extracts entities and relationships from each chunk, tracking which
entities appear in which chunks (mentions).

## Options

  - `:extractor` - Combined extractor `(text, opts) -> {:ok, %{entities: [...], relationships: [...]}}`.
    When provided, this takes priority over separate extractors.
  - `:entity_extractor` - Function `(text, opts) -> {:ok, entities} | {:error, reason}`.
    Used when `:extractor` is not provided.
  - `:relationship_extractor` - Function `(text, entities, opts) -> {:ok, rels} | {:error, reason}`.
    Used when `:extractor` is not provided.

## Returns

  - `{:ok, graph_data}` - Successfully built graph data
  - `{:error, reason}` - If all extractions fail

# `build_from_text`

Builds graph data from a single text string.

Convenience function for processing a single document without chunks.

# `merge`

Merges two graph data structures.

Combines entities (deduplicating by name), relationships, and mentions.
Useful for incremental graph building across multiple documents.

# `to_query_graph`

Converts builder output to the format used by GraphQuery.

Takes the graph data and original chunks to build an indexed
graph structure suitable for querying.

---

*Consult [api-reference.md](api-reference.md) for complete listing*