ckg-nemotron-perplexity

<!-- mcp-name: io.github.Yarmoluk/ckg-nemotron-perplexity -->

# ckg-nemotron-perplexity

<p align="center">
  <img src="https://raw.githubusercontent.com/Yarmoluk/ckg-nemotron-perplexity/main/docs/demo.png" alt="ckg-nemotron-perplexity — NVIDIA Nemotron + Perplexity Sonar as traversable knowledge graphs" width="100%"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/ckg-nemotron-perplexity/"><img src="https://img.shields.io/pypi/v/ckg-nemotron-perplexity?color=0f6e56&label=PyPI" alt="PyPI version"/></a>
  <a href="https://pypi.org/project/ckg-nemotron-perplexity/"><img src="https://img.shields.io/pypi/pyversions/ckg-nemotron-perplexity?color=0f6e56" alt="Python"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/data-ELv2-0f6e56" alt="Data: ELv2"/></a>
  <a href="LICENSE-CODE"><img src="https://img.shields.io/badge/code-MIT-13201c" alt="Code: MIT"/></a>
  <a href="https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf"><img src="https://img.shields.io/badge/F1-0.471_%C2%B74%C3%97_RAG-0f6e56" alt="F1: 0.471 · 4× RAG"/></a>
</p>

**An auditable knowledge graph for NVIDIA Nemotron and Perplexity Sonar — deterministic agent answers with cryptographic source traceability.**

Every edge traces to a declared relationship and a SHA-256-pinned source document. Built for ML engineers, agent developers, and platform teams who need verifiable answers about Nemotron's training pipeline, Perplexity Sonar model routing, and cross-stack dependencies — not model inference.

> Not a general-purpose semantic search layer. If it's not a declared edge, the graph doesn't return it.

```bash
pip install ckg-nemotron-perplexity
# or: uvx ckg-nemotron-perplexity
```

[PyPI](https://pypi.org/project/ckg-nemotron-perplexity/) · [GitHub](https://github.com/Yarmoluk/ckg-nemotron-perplexity) · [Benchmark paper](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf) · [graphifymd.com](https://graphifymd.com)

---

## What it is

2 domains · 83 nodes · 83 edges · the full Nemotron training pipeline and Perplexity Sonar model stack as typed dependency graphs. Pre-structured, traversable, deterministic. Served over MCP. No inference at query time.

```
query_ckg("Synthetic Data Generation", "nemotron", depth=3)

→ Synthetic Data Generation
  ├─ [REQUIRES] Nemotron-4 as Judge
  │    └─ [REQUIRES] Nemotron-4 340B
  │         ├─ [REQUIRES] Transformer Architecture
  │         ├─ [REQUIRES] Group Query Attention
  │         └─ [REQUIRES] SentencePiece Tokenizer
  └─ builds toward: Topic Diversity Sampling · Synthetic RLHF Data

  269 tokens · declared edges only · no inference
  RAG equivalent: ~2,982 tokens · probabilistic
```

```
get_prerequisites("sonar-deep-research", "perplexity-sonar")

sonar-deep-research → sonar-pro → Sonar API

Three hops. Declared chain. RAG returns three separate docs.
The graph doesn't guess — it traverses.
```

---

## Source provenance — verifiable to the byte

Every node carries a `source_url` and a `source_hash` (SHA-256 of the source document's bytes at extraction time). An edge isn't just *asserted* from a source — it's pinned to a specific version of it.

```bash
# Verify any node's source hasn't changed since extraction
curl -s https://developer.nvidia.com/nemotron | sha256sum
# expected: 9cedb8be7e92d957811ce3573a1e355158e4dcecf3033d46a0781fcfb7330a6c
```

**The full audit chain:**

```
edge answer
  → graph commit hash       (git log -- nemotron.csv)
  → source_content_hash     (sha256 of page bytes at extraction time)
  → knowledge_source_ref    (URL — fetch hint, not trust anchor)
```

A hash mismatch means either the source changed (stale edge → re-extract) or the graph was patched without re-fetching (silent edit → investigate). No judgment required. Run `scripts/refresh_hashes.py` to recompute.

Via MCP — `verify_source("Transformer Architecture", "nemotron")`:

```
source_url:  https://developer.nvidia.com/nemotron
source_hash: sha256:9cedb8be7e92d957811ce3573a1e355158e4dcecf3033d46a0781fcfb7330a6c
verify:      curl -s '<url>' | sha256sum
```

Reference implementation of `knowledge_source_ref` + `source_content_hash` from [GuardrailDecisionV1](https://github.com/crewAIInc/crewAI/issues/4877).

---

## What developers are actually hitting

Signal from NVIDIA developer forums, Perplexity community, and hands-on deployments.

**01 — Model routing confusion.** Teams default to `sonar-pro` for every query. `sonar-reasoning-pro` is 3× the cost and only needed when multi-step reasoning is the bottleneck. The declared routing chain in the graph makes the decision deterministic.

**02 — "Why is my RLHF pipeline breaking?"** The Nemotron training chain has nine declared prerequisites. Teams skip Preference Data Collection or use the wrong judge model. Nemotron-4 340B is the required base — the graph surfaces every hop before you hit it at training time.

**03 — The cross-stack dependency gap.** Perplexity runs Nemotron-based models. Most documentation treats the stacks as separate. A question like "what does sonar-reasoning-pro require from the underlying model architecture?" crosses both domains — the graph traverses both in a single call.

---

## Declared relationships, not confidence scores

Every edge was extracted from a source document and given a type. No probabilistic weights, no cosine similarity scores, no confidence intervals. An edge either exists — declared, typed, sourced — or it doesn't. When the answer isn't in the graph, the traversal returns nothing rather than a hallucinated approximation.

**Edge types:**

| Type | Meaning | Example |
|------|---------|---------|
| `REQUIRES` | Hard prerequisite — A cannot function without B | `RLHF Pipeline REQUIRES Reward Model Training` |
| `ENABLES` | Capability unlock — A makes B possible | `sonar-pro ENABLES sonar-deep-research` |
| `IMPLEMENTS` | Concrete instantiation of an abstract concept | `OpenAI-Compatible Interface IMPLEMENTS Sonar API` |
| `RELATES_TO` | Conceptual proximity, no dependency direction | `PPO RELATES_TO DPO` |

**Why no confidence levels?** The edge type *is* the confidence signal. `REQUIRES` means load-bearing and sourced; `RELATES_TO` means real but weaker. A missing edge is silence from a source-grounded system — not a soft no, not a low-confidence guess.

```
✗ RAG:  "RLHF Pipeline probably requires a reward model... (similarity: 0.78)"
        Score is on the chunk, not the claim. The claim itself is unverified.

✓ CKG:  "RLHF Pipeline REQUIRES Reward Model Training, which REQUIRES Preference Data Collection
         and Supervised Fine-Tuning, which REQUIRES Nemotron-4 340B."
        No score. Declared edge. Traces to NVIDIA Nemotron source doc.
```

---

## A/B test — Nemotron + Perplexity domain, local models, no GPU

30 questions on the training pipeline, model routing, and cross-domain prerequisites · CPU only · Ollama · temperature 0 · seed 42

| Category | Bare model | + CKG | Lift |
|----------|-----------|-------|------|
| Model routing F1 | 0.058 | 0.142 | **+145%** |
| Pipeline prereq F1 | 0.063 | 0.134 | **+113%** |
| Lookup F1 | 0.091 | 0.201 | **+121%** |
| Key-fact accuracy | 8.1% | 19.4% | **+11pp** |

**L01 — model routing:**
```
Q: Which Sonar model should I use for multi-step research tasks?
✗ Bare: "Use sonar-pro for all research tasks..." [misses routing distinction]
✓ CKG:  "sonar-deep-research requires sonar-pro, which requires Sonar API.
         For multi-step reasoning without deep research, sonar-reasoning-pro
         is the declared path." [correct]
```

**P01 — prereq chain (9 hops):**
```
Q: What must be in place before running the RLHF pipeline on Nemotron-4?
✗ Bare: "You need a dataset and a base model..." [vague, misses full chain]
✓ CKG:  "RLHF Pipeline → Reward Model Training → Preference Data Collection
         → Supervised Fine-Tuning → Nemotron-4 340B → Pre-training Data Pipeline
         → Transformer Architecture → Group Query Attention
         → Rotary Position Embedding → SentencePiece Tokenizer" [declared chain]
```

---

## Install

**Add to claude.ai (no install required):**

```
https://ckg-nemotron-perplexity.onrender.com/mcp
```

Settings → Connectors → Add connector → paste URL.

**Local — Claude Desktop / Claude Code:**

```bash
pip install ckg-nemotron-perplexity
# or
uvx ckg-nemotron-perplexity
```

```json
{
  "mcpServers": {
    "nemotron-perplexity": {
      "command": "uvx",
      "args": ["ckg-nemotron-perplexity"]
    }
  }
}
```

---

## Tools

| Tool | Description |
|------|-------------|
| `list_domains()` | Both available domains with descriptions |
| `query_ckg(concept, domain, depth)` | Typed subgraph around a concept (1–5 hops) |
| `get_prerequisites(concept, domain)` | Full ordered prerequisite chain — every dependency in order |
| `search_concepts(query, domain)` | Fuzzy search within a domain |
| `verify_source(concept, domain)` | Source URL + SHA-256 hash for any concept — full audit chain back to source bytes |

---

## What's in the graph

**2 domains · 83 nodes · 83 edges · 4 edge types: `REQUIRES` · `ENABLES` · `IMPLEMENTS` · `RELATES_TO`**

**nemotron — 48 nodes:**

| Layer | Concepts |
|-------|----------|
| Architecture | Transformer Architecture · Group Query Attention · Rotary Position Embedding · Flash Attention · SentencePiece Tokenizer |
| Models | Nemotron-4 340B · Nemotron-4 15B · Nemotron-51B · Minitron-8B · Minitron-4B |
| Training | Pre-training Data Pipeline · Nemotron-CC · Quality Filtering · SFT · Reward Model Training · RLHF Pipeline · PPO · DPO · Constitutional AI Filtering · Nemotron-4 as Judge |
| Synthetic data | Synthetic Data Generation · Topic Diversity Sampling · Response Diversity Sampling · Data Quality Score · Synthetic RLHF Data |
| Deployment | TensorRT-LLM Backend · Triton Inference Server · NVIDIA NIM · INT8 Quantization · FP8 Quantization · vLLM Backend · OpenAI-Compatible Endpoint |
| Evaluation | MMLU Benchmark · HumanEval · MT-Bench · RewardBench · Arena Hard |