# Knowledge Graph Builder

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

## Setup

```bash
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

```bash
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`:

```bash
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

```bash
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.