The Problem

This repository provides a modular system for extracting knowledge graphs from text using multiple LLM backends (Gemini API, Ollama, LM Studio). The codebase has grown to 91 files with 40 Python modules, but lacks the infrastructure needed for reliable production use: no CI/CD pipeline, no dependency lockfile, and no automated test gate. A consultant would find the code functional but the surrounding SDLC practices insufficient for anything beyond local prototyping.

What This Does

KGB extracts structured triples (head‑relation‑tail) from text using langextract, then offers augmentation, conversion, and visualization workflows. The repository organizes around a domain system—each knowledge domain can have custom prompts, examples, and schema constraints—and a client abstraction layer supporting three LLM backends. Core capabilities include:

  • Triple extraction from JSONL input using domain‑specific prompts (files: kgb/domains/legal/extraction/prompt_open.md, kgb/domains/legal/extraction/prompt_constrained.md)
  • Connectivity augmentation to bridge disconnected graph components via iterative strategies (file: kgb/builder/augmentation.py)
  • GraphML conversion for Cytoscape.js visualization (file: kgb/io/writers/graphml.py)
  • Text and network visualizations (files: kgb/visualization/text_viz.py, kgb/visualization/graph_viz.py)

The CLI entry point kgb/__main__.py orchestrates a pipeline of steps defined in YAML configs under kgb/pipeline/configs/. Input/output formats span JSONL, JSON, CSV to GraphML.

How It Is Wired

Execution begins at kgb/__main__.py:173 (run_pipeline), which is called from the CLI script kgb and reaches 25 function(s). The pipeline flows through kgb/pipeline/runner.py and kgb/pipeline/step.py, where steps (extraction, augmentation, conversion, visualization) are registered and executed sequentially. Client configuration is built by _build_client_config (kgb/pipeline/config.py) and resolved through kgb/clients/factory.py, which instantiates the selected backend (kgb/clients/providers/ollama.py, kgb/clients/providers/gemini.py, or kgb/clients/providers/lmstudio.py).

The most connected module is kgb/domains/__init__ (Ca 11, Ce 3, instability 0.21), followed by kgb/clients/__init__ (Ca 7, Ce 4, instability 0.36). The call graph shows build_pipeline_from_config -> _resolve executes 16 times, and augment -> LLMClientError fires 8 times, indicating that configuration resolution and error handling are frequent touch points. Representative edges include run_pipeline -> get_step (6 calls) and extract_triples -> extract (3 calls).

Paths that leave the process: augment_connectivity -> augment_triples -> extract_triples -> extract touches the filesystem via json_dir.mkdir; visualize_extraction -> batch_render and visualize_network -> batch_render_graphs both write output directories; convert -> convert_json_directory writes GraphML. Three functions call a model for inference, and one (kgb/clients/base.py BaseLLMClient) makes an outbound network call.

File responsibility (routes through, not size):

  • kgb/__init__.py – 12 functions, defines extract_triples, augment_triples, ClientConfig, ClientFactory, TextVisualizer
  • kgb/__main__.py – 18 functions, defines _available_client_types, _validate_client_type, _build_client_config, list_domains, list_clients
  • kgb/clients/base.py – defines extract, augment, LLMClientError, BaseLLMClient; calls a model and makes a network call
  • kgb/builder/augmentation.py – defines _build_graph_from_triples, strategies for connectivity augmentation
  • kgb/visualization/graph_viz.py – 1261 code lines; handles rendering and file I/O

How To Use It

Setup

# Using Makefile (recommended)
make install

# Or manually
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Requires Python 3.11+. The Makefile target auto-detects the first available Python 3.11+ interpreter.

Configuration Environment variables and keys are read from .env (not committed). The config files under kgb/pipeline/configs/ (legal_ollama.yaml, legal_gemini.yaml, legal_lmstudio.yaml) define pipeline steps, client settings, and domain references. Backend-specific requirements:

  • Gemini: GOOGLE_API_KEY in .env
  • Ollama: ollama serve running locally
  • LM Studio: server enabled with a model loaded

Running it

# Interactive REPL
kgb

# One-shot extraction
kgb extract --input data.jsonl --domain legal --client gemini

# Full pipeline via YAML config
kgb run-pipeline --config kgb/pipeline/configs/legal_ollama.yaml

# Augment connectivity
kgb augment connectivity \
  --input data/legal/legal_background.jsonl \
  --domain legal \
  --client gemini \
  --output-dir outputs/run \
  --max-disconnected 1 \
  --max-iterations 5

Real-World Use

A legal tech team could ingest a JSONL file of case descriptions, extract explicit triples (parties, dates, rulings), then run the augmentation step to generate contextual triples that connect isolated nodes—producing a fully connected graph for downstream query or visualization. The domain system lets them swap kgb/domains/legal/ prompts and schema constraints without touching the pipeline code. Output GraphML feeds Cytoscape.js for interactive exploration, or GraphML can be persisted for API consumption.

Code Health & Issues

The static analysis (MEASURED ANALYSIS block) identified the following findings:

  • [HIGH/cognitive_load] Deep nesting x8 – files kgb/builder/extraction.py, kgb/clients/providers/lmstudio.py, kgb/clients/providers/ollama.py; max indentation depth 8 makes control flow hard to follow. Fix: flatten with early returns/guard clauses.
  • [HIGH/cognitive_load] Oversized file x2 – kgb/visualization/graph_viz.py (1261 lines) and kgb/__main__.py; hard to hold in one head; changes ripple widely. Fix: split into cohesive units by responsibility.
  • [MEDIUM/resource_safety] File opened without context manager – kgb/visualization/graph_viz.py; open(...) not wrapped in with may leak handles on error. Fix: use with open(...) as f:.
  • [MEDIUM/resilience] Broad exception handling x6 – kgb/io/writers/graphml.py, kgb/visualization/graph_viz.py, kgb/visualization/text_viz.py; bare/Exception-wide except swallows errors indiscriminately. Fix: catch specific exceptions; re-raise or log the rest.
  • [HIGH/clarity] Duplicated code blocks – 246 repeated 6-line blocks across 12 files including kgb/__main__.py, kgb/pipeline/config.py, kgb/clients/base.py, kgb/clients/providers/gemini.py. Fix: extract shared helpers; DRY the repeated logic.

Code Health Audit (8 findings, 0 critical, 4 high, 4 medium, 0 low):

  • [HIGH] Add a test suite; this repository has none. Any change ships with no signal that existing behaviour still holds.
  • [HIGH] Commit a lockfile beside the manifest – pyproject.toml has no lockfile; unlocked ranges mean the artifact tested can differ from the artifact shipped.
  • [HIGH] Add a workflow that builds and tests this repository; no CI configuration exists.
  • [HIGH] Add a build gate for the deployable artifacts – Dockerfile present but no workflow validates the image.
  • [MEDIUM] Enable Dependabot or Renovate; no update bot configured.
  • [MEDIUM] Pin the container base image by digest – Dockerfile uses python:3.11-slim without a digest.
  • [MEDIUM] Add a non-root USER to the image – no USER directive; process runs as root.
  • [MEDIUM] Pin the resolution so a vulnerable version cannot install – no lockfile; declared ranges include pydantic@2.0.0 CVE-2024-3772 and requests@2.31.0 CVE-2024-47081.

The Bottom Line

This is a functional, well-structured prototype for LLM‑driven knowledge graph extraction that cleanly separates domains, clients, and pipeline steps. The domain prompt system and multi‑backend client abstraction are the strongest design choices. However, the absence of a lockfile, CI/CD, and tests means it is unsuitable for production without those additions. A team comfortable with local LLM experimentation and willing to add a test suite, lockfile, and CI workflow can ship this relatively quickly; others should look for a more fully engineered solution.