Metadata-Version: 2.4
Name: ckg-nemotron-perplexity
Version: 0.2.1
Summary: NVIDIA Nemotron + Perplexity Sonar as traversable knowledge graphs — 2 domains, 83 nodes, MCP-native agent traversal.
Project-URL: Homepage, https://graphifymd.com
Project-URL: Repository, https://github.com/Yarmoluk/ckg-nemotron-perplexity
Author-email: Daniel Yarmoluk <daniel.yarmoluk@gmail.com>
License: MIT
Keywords: ai-agents,knowledge-graph,llm,mcp,nemotron,nvidia,perplexity,sonar
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.Yarmoluk/ckg-nemotron-perplexity -->
# MCP — CKG-NEMOTRON-PERPLEXITY

[![PyPI version](https://img.shields.io/pypi/v/ckg-nemotron-perplexity?color=0f6e56&label=PyPI)](https://pypi.org/project/ckg-nemotron-perplexity/)
[![Downloads](https://img.shields.io/pypi/dm/ckg-nemotron-perplexity?color=0f6e56&label=installs%2Fmo)](https://pypi.org/project/ckg-nemotron-perplexity/)
[![Python](https://img.shields.io/pypi/pyversions/ckg-nemotron-perplexity?color=0f6e56)](https://pypi.org/project/ckg-nemotron-perplexity/)
[![License: MIT](https://img.shields.io/badge/license-MIT-0f6e56)](LICENSE)
[![Domains](https://img.shields.io/badge/domains-2-0f6e56)](https://graphifymd.com)
[![Nodes](https://img.shields.io/badge/nodes-83-0f6e56)](https://graphifymd.com)
[![Free](https://img.shields.io/badge/free-forever-13201c)](https://pypi.org/project/ckg-nemotron-perplexity/)
[![F1: 0.471 · 4× RAG](https://img.shields.io/badge/F1-0.471_%C2%B74%C3%97_RAG-0f6e56)](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf)
[![KRB v0.6.2](https://img.shields.io/badge/benchmark-KRB_v0.6.2-13201c)](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf)
[![Built by Graphify.md](https://img.shields.io/badge/built_by-Graphify.md-0f6e56)](https://graphifymd.com)

**MCP server — Compressed Knowledge Graph (CKG) for NVIDIA Nemotron and Perplexity Sonar.**

**Nemotron's full training + deployment pipeline · Perplexity Sonar model routing · 83 nodes · deterministic traversal.**

> **Read-only.** This MCP server never writes, mutates, or executes. Every response is a declared graph traversal — not inference, not retrieval, not generation.

<p align="center">
  <a href="https://yarmoluk.github.io/ckg-nemotron-perplexity/carousel.html">
    <img src="docs/demo.png" alt="CKG-NEMOTRON-PERPLEXITY carousel" width="960">
  </a>
</p>

<p align="center">
  <a href="https://graphifymd.com">
    <img src="docs/graph.png" alt="CKG-NEMOTRON-PERPLEXITY — 2 domain knowledge graph, 83 nodes" width="960">
  </a>
</p>

---

## The problem teams hit with Nemotron and Perplexity

More agents. More retrieval. More context. And accuracy drops.

Research finds 73% of enterprise tokens are redundant context. In multi-agent pipelines, context efficiency collapses from 18.2 in Q1 to 1.6 by Q4 — **91% degradation with no model change**. The model is not the bottleneck. The context is.

Building with Nemotron means navigating a deep pipeline: pre-training data → quality filtering → SFT → reward model → RLHF → deployment via NIM. Every stage has hard prerequisites. Get one wrong and the chain breaks — at training time, at serve time, or silently in production.

Building with Perplexity means choosing between five Sonar models — `sonar`, `sonar-pro`, `sonar-reasoning`, `sonar-reasoning-pro`, `sonar-deep-research` — each with different capabilities, cost structures, and prerequisites. Teams get this wrong constantly and pay for it in latency and cost.

The deeper problem: **Perplexity runs Nemotron-based models**. The dependency chain crosses both domains. A question like "what does sonar-reasoning-pro require from the underlying model architecture?" spans two stacks that most documentation treats as separate.

Your agent shouldn't re-infer these relationships on every query. They should be declared once and traversed in 269 tokens.

---

## What this package does

A CKG is a **layer** — domain knowledge structured for traversal, not retrieval. This package gives your agent both stacks as a single traversable graph: 48 Nemotron nodes covering architecture through pruning, and 35 Perplexity Sonar nodes covering API through advanced research modes.

Every prerequisite chain declared. Every dependency typed. Cross-domain traversal built in.

| Domain | Nodes | Coverage |
|---|---|---|
| `nemotron` | 48 | Architecture · Training · Synthetic Data · RLHF · Deployment · Minitron Pruning |
| `perplexity-sonar` | 35 | Sonar API · Model Routing · Web Search · Citations · Output Modes · Deep Research |

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

Prerequisites:
  - Nemotron-4 as Judge
    - Nemotron-4 340B
      - Transformer Architecture
      - Group Query Attention
      - Rotary Position Embedding
      - SentencePiece Tokenizer
Builds toward:
  - Topic Diversity Sampling
  - Response Diversity Sampling
  - Synthetic RLHF Data
```

That traversal cost **269 tokens**. A RAG call over the same question costs ~2,982. The graph doesn't guess — it traverses.

---

## Explore the graph

Once installed, paste this into Claude, Cursor, or any MCP client:

```
You have access to the ckg-nemotron-perplexity MCP server — a typed dependency graph
covering NVIDIA Nemotron's full training pipeline and Perplexity's Sonar model stack.

I want to understand what it actually takes to build a synthetic data pipeline using
Nemotron-4 as a judge model — the real dependency chain, not the blog post version.

Start here:
  query_ckg("Synthetic Data Generation", "nemotron", 3)

Then trace the full RLHF prerequisite chain:
  get_prerequisites("RLHF Pipeline", "nemotron")

Then show me what sonar-deep-research actually requires:
  get_prerequisites("sonar-deep-research", "perplexity-sonar")

Present the result as a layered architecture — foundation at the bottom, application
at the top. Flag anything that would block a cold-start build.
```

The graph traverses both domains, surfaces every hard prerequisite, and shows you exactly
what stands between an idea and a running pipeline — no hallucination, no guessing.

---

## Quickstart

```bash
pip install ckg-nemotron-perplexity
```

```bash
uvx ckg-nemotron-perplexity     # MCP server mode, no install
```

One dependency: `mcp>=1.0.0`. Brings uvicorn, FastMCP, and all traversal code. Nothing else required.

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

### Claude Code
```bash
claude mcp add ckg-nemotron-perplexity -- uvx ckg-nemotron-perplexity
```

### Cursor / Cline / Windsurf
```json
{ "mcpServers": { "ckg-nemotron-perplexity": { "command": "uvx", "args": ["ckg-nemotron-perplexity"] } } }
```

### System prompt snippet

```
You have access to the ckg-nemotron-perplexity MCP server — a typed dependency graph of
NVIDIA Nemotron (architecture, training, synthetic data, RLHF, deployment, pruning) and
Perplexity Sonar (API, model routing, web search, citations, deep research). When answering
questions about Nemotron pipelines, Sonar model selection, or cross-stack dependencies, call
query_ckg() or get_prerequisites() before responding. Do not guess dependency chains — traverse
the graph instead.
```

---

## Accuracy model

Every edge was declared by a human reviewer. The graph is in active development — corrections arrive from the community.

**Three-state confidence:**

| State | Meaning | How to use |
|---|---|---|
| `confidence: high` | Reviewed, cross-referenced with NVIDIA and Perplexity docs | Trust for planning |
| `confidence: null` | Plausible, not yet audited | Scaffold — verify before production |
| `confidence: low` | Flagged as uncertain | Treat as a hint, not a fact |

**Typed edges — semantic precision:**

| Type | Meaning | Agent use |
|---|---|---|
| `REQUIRES` | Hard prerequisite | Plan sequencing, gap detection |
| `ENABLES` | Unlocks a capability | Optimization paths |
| `RELATES_TO` | Conceptual proximity | Disambiguation, context |
| `IMPLEMENTS` | Concrete instantiation | Architecture mapping |

If an edge isn't declared, the traversal returns nothing rather than hallucinating a path. That silence is signal.

---

## Tools

<p align="center">
  <img src="docs/slide-edges.png" alt="Every edge is a decision — typed dependency edges" width="960">
</p>

All tools are read-only. No writes, no side effects.

### `list_domains()`
Returns both available domains with descriptions. **Start here.**

### `search_concepts(query, domain)`
Find concepts by keyword within a domain.

```
search_concepts("reward", "nemotron")
→ Reward Model Training [TRAIN]
   RewardBench [EVAL]
```

```
search_concepts("reasoning", "perplexity-sonar")
→ sonar-reasoning [MODEL]
   sonar-reasoning-pro [MODEL]
   Multi-step Reasoning [ADV]
```

### `query_ckg(concept, domain, depth=3)`
Traverse the graph from a concept — prerequisites upstream, dependents downstream.

```
query_ckg("Minitron Pipeline", "nemotron", 3)

Prerequisites:
  - Structured Pruning
  - Knowledge Distillation
  - Neuron Importance Scoring
    - Nemotron-4 340B
      - Transformer Architecture
      - Group Query Attention
      - Rotary Position Embedding
      - SentencePiece Tokenizer
Builds toward:
  (terminal node — Minitron-8B and Minitron-4B are downstream via Nemotron-51B)
```

```
query_ckg("sonar-pro", "perplexity-sonar", 2)

Prerequisites:
  - Sonar API
    - API Key Authentication
    - Rate Limiting
Builds toward:
  - sonar-deep-research
  - Research Assistant
  - Code with Web Context
```

### `get_prerequisites(concept, domain)`
Full ordered prerequisite chain — everything needed before this concept works.

```
get_prerequisites("RLHF Pipeline", "nemotron")

Prerequisite chain for 'RLHF Pipeline' in nemotron (9 concepts):
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
```

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

Prerequisite chain for 'sonar-deep-research' in perplexity-sonar (2 concepts):
sonar-deep-research → sonar-pro → Sonar API
```

```
get_prerequisites("Structured Research Report", "perplexity-sonar")

Prerequisite chain for 'Structured Research Report' in perplexity-sonar (4 concepts):
Structured Research Report → Deep Research Mode → sonar-deep-research
→ sonar-pro → Sonar API
```

---

## Domains

<p align="center">
  <img src="docs/slide-sonar.png" alt="5 Sonar models — model routing declared in the graph" width="960">
</p>

### `nemotron` — 48 nodes

| Taxonomy | Concepts |
|---|---|
| `ARCH` | Transformer Architecture · GQA · RoPE · Flash Attention · SentencePiece Tokenizer |
| `MODEL` | Nemotron-4 340B · Nemotron-4 15B · Nemotron-51B · Minitron-8B · Minitron-4B |
| `TRAIN` | Pre-training Data Pipeline · Nemotron-CC · Quality Filtering · SFT · Reward Model Training · RLHF Pipeline · PPO · DPO · Constitutional AI Filtering · Nemotron-4 as Judge |
| `SYNTH` | Synthetic Data Generation · Topic Diversity Sampling · Response Diversity Sampling · Data Quality Score · Synthetic RLHF Data |
| `DEPLOY` | TensorRT-LLM Backend · Triton Inference Server · NVIDIA NIM · INT8 Quantization · FP8 Quantization · vLLM Backend · OpenAI-Compatible Endpoint |
| `EVAL` | MMLU Benchmark · HumanEval · MT-Bench · RewardBench · Arena Hard |
| `CAP` | Code Generation · Math Reasoning · Tool Use · Long Context 128K · Multi-turn Conversation · Structured Output |
| `PRUNE` | Structured Pruning · Knowledge Distillation · Neuron Importance Scoring · Minitron Pipeline |

### `perplexity-sonar` — 35 nodes

| Taxonomy | Concepts |
|---|---|
| `API` | Sonar API · API Key Authentication · OpenAI-Compatible Interface · Rate Limiting · Cost Per Query |
| `MODEL` | sonar · sonar-pro · sonar-reasoning · sonar-reasoning-pro · sonar-deep-research |
| `SEARCH` | Web Search Grounding · Real-time Knowledge · Citation Object · Source URL Reference · recency_filter · search_domain_filter · Search Context Size |
| `CTX` | System Prompt · Context Window 127K · Message History · return_images · return_related_questions |
| `OUT` | Text Response · Streaming Response · JSON Mode · Citation Inline Format |
| `USE` | Research Assistant · Fact Checking · Real-time Data Access · News Summarization · Code with Web Context |
| `ADV` | Deep Research Mode · Multi-step Reasoning · Extended Thinking · Structured Research Report |

---

## How the graph is built

Each domain is a DAG stored as typed edge CSV — human-authored and human-reviewed:

```
ConceptID, ConceptLabel, Dependencies,              TaxonomyID
N006, Nemotron-4 340B,  N001:REQUIRES|N002:REQUIRES, MODEL
N014, Supervised Fine-Tuning, N006:REQUIRES|N011:REQUIRES, TRAIN
N015, Reward Model Training,  N014:REQUIRES,           TRAIN
N017, RLHF Pipeline,    N015:REQUIRES|N016:REQUIRES,  TRAIN
```

No embeddings. No vector index. No probabilistic retrieval. Built once, reviewed once, traversed forever.

**Key chains at a glance:**

```mermaid
graph LR
    TA[Transformer Architecture] --> N4[Nemotron-4 340B]
    PP[Pre-training Data] --> N4
    N4 --> SFT[Supervised Fine-Tuning]
    SFT --> RM[Reward Model Training]
    RM --> RLHF[RLHF Pipeline]
    N4 --> J[Nemotron-4 as Judge]
    J --> SDG[Synthetic Data Gen]
    SDG --> SRLHF[Synthetic RLHF Data]
```

```mermaid
graph LR
    SAPI[Sonar API] --> SP[sonar-pro]
    SP --> SDR[sonar-deep-research]
    SDR --> DRM[Deep Research Mode]
    DRM --> SR[Structured Research Report]
    SAPI --> WS[Web Search Grounding]
    WS --> CIT[Citation Object]
    CIT --> CI[Citation Inline Format]
```

**Typed edges — semantic precision:**

| Type | Meaning | Agent use |
|---|---|---|
| `REQUIRES` | Hard prerequisite — cannot function without | Plan sequencing, gap detection |
| `ENABLES` | Unlocks a capability — optimization path | Surface optional dependencies |
| `RELATES_TO` | Conceptual proximity — not a dependency | Disambiguation |
| `IMPLEMENTS` | Concrete instantiation of an abstraction | Architecture mapping |

If an edge isn't declared, the traversal returns nothing rather than hallucinating a path. That silence is signal.

---

## Why context efficiency collapses — and how CKG reverses it

Liu et al. ([arXiv:2606.30986](https://arxiv.org/abs/2606.30986)) formally quantify **Context Transaction Cost (CTC)**: the compound tax paid every time context crosses an agent boundary. In multi-agent pipelines, efficiency collapses 91% with no model change.

CKG attacks all three root causes:

| CTC component | What it is | CKG's response |
|---|---|---|
| Token Latency Burden (τ) | Compute cost of transmitting context | 269 tokens instead of 2,982 |
| Handoff Cost (H) | Serialization loss at agent boundaries | `get_prerequisites()` replaces re-retrieval |
| Compression Loss (C) | Information destroyed when context is summarized | The graph *is* the compressed form — done once, offline |

Structured context doesn't consume your context window. It opens it.

---

## The alternative to fine-tuning

When task-specific data is scarce, fine-tuning feels like the answer — and frequently isn't. Fine-tuning requires thousands of labeled examples, a training budget, and a full retraining cycle every time the domain shifts. Nemotron was built to demonstrate what's possible at scale; most teams won't run that pipeline.

CKG encodes domain knowledge once as a typed graph. When the knowledge changes — new model release, new Sonar capability, new API parameter — you update the graph. Not the model.

> *Directional intelligence, deployed today, updatable tomorrow — at 11× lower token cost.*

**The commercial case in three parts:**

| | Fine-tuning | CKG |
|---|---|---|
| **Speed** | Months of data collection and training before results | One session to deploy |
| **Adaptability** | Retrain when knowledge shifts | Update the graph, not the model |
| **Sustainability** | Expensive to run at scale | 269 tokens/query — 10× more questions per dollar |

**Enterprise risk coverage:**

| Risk | CKG response |
|---|---|
| Drift without version control | Typed, declared edges don't drift — every change is a graph update |
| Institutional knowledge lock-in | Human-readable, portable CSV — not vendor-locked |
| Provenance reconstruction failure | Every edge has a declared source and type — inherently auditable |
| New hire / auditor onboarding | CKG as runbook — traversable by anyone, not just the team that built it |

---

## Benchmark

Evaluated on [KRB Benchmark v0.6.2](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf) — open dataset, reproducible methodology, fixed baselines.

| System | Macro F1 | Tokens/query | Cost/1K queries |
|---|---|---|---|
| **CKG** | **0.471** | **269** | **$7.81** |
| RAG (text-embedding-3-small) | 0.123 | 2,982 | $76.23 |
| GraphRAG (MS global mode) | 0.120 | — | — |

4× F1 · 11× fewer tokens · 5-hop F1 **0.772** vs **0.170** · auditable by design

These numbers are from our open benchmark across 19 domains. Reproduce them yourself: [github.com/Yarmoluk/ckg-benchmark](https://github.com/Yarmoluk/ckg-benchmark).

---

## Corrections welcome

Spotted a wrong edge? A prerequisite missing from the Nemotron RLHF chain? A Sonar model that requires something not yet declared?

**Edge corrections are the highest-value contribution.** Open an issue or PR with the concept, the current edge, and what it should be. The graph gets more useful with every fix.

---

## EVAL

```
benchmark: ckg-benchmark v0.6.2
dataset: huggingface.co/datasets/danyarm/ckg-benchmark
benchmarked: false
rag_baseline_f1: 0.123
graphrag_baseline_f1: 0.120
mean_tokens: 269
paper: github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf
```

---

## Want a CKG for your domain?

A CKG is a **knowledge layer** — the context optimization component of an agent stack. Turn your company documentation, internal APIs, competitive intelligence, or regulatory requirements into a CKG layer in a single session.

**[graphifymd.com](https://graphifymd.com)** — custom domain CKGs, enterprise solutions, and Sealed Appliance: a private CKG + query server deployed in your environment.

---

## Ecosystem

| Package | What it does |
|---|---|
| **[ckg-nemotron-perplexity](https://pypi.org/project/ckg-nemotron-perplexity/)** | This repo — Nemotron + Perplexity Sonar, free |
| **[ckg-nvidia-ai](https://pypi.org/project/ckg-nvidia-ai/)** | Full NVIDIA AI stack — 20 domains, 998 nodes, free |
| **[ckg-mcp](https://pypi.org/project/ckg-mcp/)** | 97 domains: science, finance, law, healthcare, AI infrastructure |
| **[agentmem-mcp](https://github.com/Yarmoluk/agent-memory-mcp)** | Cross-session agent memory, not vendor-locked |
| **[KRB Benchmark](https://huggingface.co/datasets/danyarm/ckg-benchmark)** | Open benchmark — reproduce the F1 numbers yourself |

**[graphifymd.com/pro/](https://graphifymd.com/pro/)** — custom domain CKGs, sealed appliances, enterprise.

---

*Patent pending · Graphify.md · graphifymd.com*
