@unified-product-graph/sdk · v0.7.3
Programmatic client for reading and writing .upg product knowledge graphs. UPGClient with namespaced node and edge operations, health, search, and verify, built on @unified-product-graph/core.
Not sure between MCP, SDK, and CLI? Compare access modes →
Copy four commands. See a node land in your .upg file within 60 seconds.
01 · Install
Add the SDK to your project
02 · Scaffold
Create an empty .upg file
The SDK reads and writes .upg files but doesn’t currently auto-create them. The CLI does. (A single-call UPGClient.init() factory is planned. Once it lands, this step folds into step 3.)
03 · Write
Create a node, check the graph health
// quick-start.mjs
import { UPGClient } from '@unified-product-graph/sdk'
const upg = new UPGClient({ file: './product.upg' })
const { node } = await upg.nodes.create({
type: 'feature',
title: 'Dark mode',
})
console.log('created:', node.id)
const { score, digest } = await upg.health()
console.log('health:', score, digest)
await upg.close()04 · Run
Watch it write to disk
Open ./product.upg The feature node is in there as a --- type: feature --- block.
Cookbook · 10 recipes
Task-oriented snippets: list nodes by type, traverse edges, gate CI on health, wire UPGClient into a Claude agent.
Browse cookbook →Playground · interactive
Pick a recipe, hit Run, see what it prints. No need to leave the docs. Live in-browser execution ships with the npm publish.
Open playground →Pick an entity from the FitParent graph to see its real JSON on the left and the rendered card on the right. Every entity is a node wired to others by typed edges, so select a connection to walk the graph. That is what makes it a graph, not a pile of documents.
{"type": "product","title": "FitParent","status": "validation","description": "A fitness app for busy parents. Micro-workouts under 10 minutes.","properties": {"stage": "validation","health_status": "on_track"}}
Programmatic CRUD on a .upg file
client.nodes.{create,list,get,update,delete} and client.edges.{connect,list,delete}. The everyday SDK surface.
Build an import adapter
Map Notion, Linear, GitHub, or Markdown into UPG via the SDK or drop down to the catalog/grammar resolver helpers from core.
Validate at the boundary
client.verify() runs the validator + anti-pattern catalogue before persisting any write. Single async call.
Drive an LLM with structure
client.search() and the playbook/region primitives give an agent a typed map of the graph instead of free-text prompts.
Health-score a graph
Wire client.health() into CI to keep a long-running graph from rotting. Returns a score plus a structural digest.
Migrate a legacy graph
UPG_MIGRATIONS, UPG_PROPERTY_MIGRATIONS, and UPG_EDGE_MIGRATIONS round-trip an older graph to the current spec version.
Anyone reading or writing .upg in code
Reach for UPGClient. Namespaced node and edge operations, async, persists to disk after each mutation. The default starting point for any programmatic UPG work.
Agent & MCP tool builders
Wire Claude, GPT, or local LLMs to read or mutate a graph. UPGClient.search() + the intelligence and playbook primitives give an agent a typed map of the graph, not free-text prompts.
Adapter, UI, and validator builders
Use UPGClient for everyday CRUD, then drop down to the core barrels (catalog, shapes, grammar, presentation, intelligence) when you need raw resolvers, render metadata, or the anti-pattern catalogue.
The high-level client API. Start here.
The lower-level barrels. Use these when you need raw resolvers, render metadata, or to write tooling that doesn’t need a live UPGClient instance.
GitHub
Issues, contributions, and the full source are on GitHub. The spec, types, and validator are all MIT licensed.