Knowledge Graph Builder

Documents (.pdf/.docx/.txt/.md) or raw text -> entities/relationships (via LLM) -> Neo4j. Architecture inspired by Graphiti: episode-based ingestion, Pydantic entity/edge models, pluggable LLM provider.

Setup

docker compose up -d neo4j          # Neo4j at bolt://localhost:7687, browser at :7474
cp .env.example .env                # fill in ANTHROPIC_API_KEY or OPENAI_API_KEY, set LLM_PROVIDER
pip install -e ".[dev]"

Usage

kg ingest path/to/document.pdf      # input option 1: CLI
kg serve-mcp                        # input option 2: MCP server (ingest_document, ingest_text,
                                     # search_entities, get_episode tools)

Logs

Every pipeline run writes one JSON line per phase to logs/pipeline.jsonl, tagged with run_id and episode_id:

tail -f logs/pipeline.jsonl | jq
grep '"run_id":"<id>"' logs/pipeline.jsonl | jq

Extending

• New entity type: subclass BaseNode in src/kg/models/entities.py, add it to ENTITY_TYPES.

• New document format: add a _load_x(path) -> str function in src/kg/ingestion/loaders.py and register its extension in LOADERS.

• New LLM provider: subclass LLMClient in src/kg/llm/, add a branch in get_llm_client() (src/kg/llm/base.py) and matching config in src/kg/config.py.

Tests

pytest                     # model/chunker/extraction-schema tests need no external services
                            # test_writer.py needs `docker compose up -d neo4j` and skips otherwise

Known v1 limitations (documented, not hidden)

• Entity resolution is exact (name, entity_type) match only — no fuzzy/embedding dedupe yet (src/kg/graph/resolver.py).

• Search is Cypher CONTAINS, not vector/hybrid search.

• Single graph backend (Neo4j) — no multi-backend abstraction since nothing else was requested.