@nesso-how/mcp 0.1.0-alpha.39 → 0.1.0-alpha.41
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/lib/graph-tools.d.ts +0 -5
- package/dist/lib/graph-tools.js +0 -5
- package/dist/starlight-docs.pages.json +9 -9
- package/dist/tools/get-relation-types.d.ts +17 -0
- package/dist/tools/get-relation-types.js +21 -18
- package/package.json +2 -2
- package/dist/lib/graph-tools.test.d.ts +0 -1
- package/dist/lib/graph-tools.test.js +0 -154
|
@@ -70,11 +70,6 @@ export declare const buildGraphInputSchema: z.ZodObject<{
|
|
|
70
70
|
text: z.ZodString;
|
|
71
71
|
elaboration: z.ZodOptional<z.ZodObject<{
|
|
72
72
|
definition: z.ZodString;
|
|
73
|
-
examples: z.ZodString;
|
|
74
|
-
notes: z.ZodString;
|
|
75
|
-
imageUrl: z.ZodOptional<z.ZodString>;
|
|
76
|
-
imageTitle: z.ZodOptional<z.ZodString>;
|
|
77
|
-
imageDescriptionUrl: z.ZodOptional<z.ZodString>;
|
|
78
73
|
}, z.core.$strip>>;
|
|
79
74
|
}, z.core.$strip>]>>;
|
|
80
75
|
relations: z.ZodArray<z.ZodObject<{
|
package/dist/lib/graph-tools.js
CHANGED
|
@@ -4,11 +4,6 @@ import * as z from 'zod/v4';
|
|
|
4
4
|
import { deserialize, serialize, VOCABULARY, RELATION_TYPE_VALUES, } from '@nesso-how/vocab-learning';
|
|
5
5
|
const elaborationSchema = z.object({
|
|
6
6
|
definition: z.string(),
|
|
7
|
-
examples: z.string(),
|
|
8
|
-
notes: z.string(),
|
|
9
|
-
imageUrl: z.string().optional(),
|
|
10
|
-
imageTitle: z.string().optional(),
|
|
11
|
-
imageDescriptionUrl: z.string().optional(),
|
|
12
7
|
});
|
|
13
8
|
export const relationTypeEnum = z.enum(RELATION_TYPE_VALUES);
|
|
14
9
|
const conceptInputSchema = z.union([
|
|
@@ -4,19 +4,19 @@
|
|
|
4
4
|
"slug": "faq",
|
|
5
5
|
"title": "FAQ",
|
|
6
6
|
"description": "Common conceptual questions about privacy, the web/desktop split, and the AI mentor.",
|
|
7
|
-
"markdown": "## Is my data private?\n\nGraph content (concepts, definitions,
|
|
7
|
+
"markdown": "## Is my data private?\n\nGraph content (concepts, definitions, relation structure) and review progress (FSRS stability, ratings, due dates) are stored locally, in IndexedDB on the web app or as plain JSON files on disk for the desktop app, and never leave your device. Mentor chat history lives only in memory for the current panel session, and AI endpoint API keys are stored locally and sent only to the endpoint you configured.\n\nThe only things that can leave your device:\n\n- **AI mentor prompts and chat history**, if you enable the mentor with a remote endpoint. A local Ollama endpoint sends nothing off your machine.\n- **Opt-in telemetry**, off by default.\n- **The desktop app's version check** against GitHub Releases, a plain request that carries no graph or usage data.\n\n## What changes between the web app and the desktop app?\n\n| Area | Web | Desktop |\n| --------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Graph storage | IndexedDB only | Plain JSON files on disk (authoritative); IndexedDB mirrors the active project |\n| Projects | Single implicit workspace, no switching | Multiple named project folders: create, open, switch, remove |\n| File import/export | File System Access API or browser download | Native save/open dialogs |\n| Native app menu | None | A real File/Edit/View/Window/Help menu bar |\n| Auto-update | Not applicable | Checks GitHub Releases on launch, can install and relaunch |\n| External file changes | Not applicable | A file watcher detects edits made outside the app (see [Troubleshooting](../troubleshooting/#this-graph-was-changed-on-disk-while-you-were-editing)) |\n\nEverything else, the canvas, the Inspector, Review, and the AI mentor, works the same on both.\n\n## Why does the AI mentor need an API key?\n\nIt doesn't, if you run a model locally. The default setup points at [Ollama](https://ollama.com/) on `http://localhost:11434/v1`, which needs no key. An API key is only required when you point the mentor at a hosted provider that authenticates requests (most OpenAI-compatible APIs); Nesso sends it as a bearer token to that endpoint only, never anywhere else. See [AI mentor](../guides/ai-mentor/#connecting-a-model).\n\n## Where do I report a bug or request a feature?\n\nOpen an issue on [GitHub](https://github.com/nesso-how/nesso/issues). The code is MIT-licensed and contributions are welcome."
|
|
8
8
|
},
|
|
9
9
|
{
|
|
10
10
|
"slug": "guides/ai-mentor",
|
|
11
11
|
"title": "AI mentor (Socrates)",
|
|
12
12
|
"description": "How the Socratic mentor works, connecting a model, persona, and graph-aware context.",
|
|
13
|
-
"markdown": "The Socratic mentor is **experimental** and **off by default**. Enable it under **Settings → AI** with the **Mentor** toggle. While off, **Socrates** is hidden from the status bar.\n\nWhen enabled, click **Socrates** in the **status bar** (bottom-left) to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n:::note\nFor good results, use at least a 7–8B model. `qwen3:14b` is a strong default; `llama3.3:70b` for higher quality if your hardware allows. For hosted endpoints, model names change fast, so pick any capable instruction-following model from your preferred provider.\n:::\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/nesso-how/nesso/blob/main/src/llm/context.ts)): **FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n## Connecting a model\n\nConfigure any OpenAI-compatible `chat/completions` endpoint under **Settings → AI**: base URL, model, and an optional API key. Endpoint fields appear only while the mentor toggle is on.\n\nThe default targets a local [Ollama](https://ollama.com/) instance (`http://localhost:11434/v1`, model `gemma3:4b`). Install Ollama, pull a model, and the mentor works with nothing leaving your machine.
|
|
13
|
+
"markdown": "The Socratic mentor is **experimental** and **off by default**. Enable it under **Settings → AI** with the **Mentor** toggle. While off, **Socrates** is hidden from the status bar.\n\nWhen enabled, click **Socrates** in the **status bar** (bottom-left) to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n:::note\nFor good results, use at least a 7–8B model. `qwen3:14b` is a strong default; `llama3.3:70b` for higher quality if your hardware allows. For hosted endpoints, model names change fast, so pick any capable instruction-following model from your preferred provider.\n:::\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/nesso-how/nesso/blob/main/src/llm/context.ts)): **FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n## Connecting a model\n\nConfigure any OpenAI-compatible `chat/completions` endpoint under **Settings → AI**: base URL, model, and an optional API key. Endpoint fields appear only while the mentor toggle is on.\n\nThe desktop app uses Tauri's native HTTP client for mentor requests. It supports any `https://` endpoint, including hosted providers such as OpenCode Zen at `https://opencode.ai/zen/v1` with model `big-pickle`. It also supports loopback HTTP endpoints at `localhost`, `127.0.0.1`, and `::1` for local Ollama. Arbitrary non-loopback `http://` endpoints are not permitted by the desktop capability.\n\nThe browser app keeps using the browser's normal `fetch`. Hosted endpoints must allow the app's origin, and browser requests to local Ollama still need the Ollama CORS setting described below. Nesso sends an optional API key as `Authorization: Bearer …` only to the configured endpoint and does not log it.\n\nThe default targets a local [Ollama](https://ollama.com/) instance (`http://localhost:11434/v1`, model `gemma3:4b`). Install Ollama, pull a model, and the mentor works with nothing leaving your machine. Set the API key expected by a hosted endpoint when one is required.\n\nUntil a reachable endpoint is configured, the chat input stays disabled and the mentor shows a short setup hint. If the mentor stops responding once a turn fails, see [Troubleshooting](../../troubleshooting/#mentor-not-responding).\n\n### Endpoint status\n\nWhile the AI tab is open in **Settings**, Nesso calls the `/models` endpoint of your configured base URL and shows the result inline:\n\n| Status | Meaning |\n| --------------------- | -------------------------------------------------------------------------------------------------- |\n| **Checking…** | Nesso is querying `/models` — shows a spinner until the first response arrives. |\n| **Available** | The model is present in the endpoint's model list. The mentor can start. |\n| **Not found locally** | The endpoint is reachable but the model is not installed. On localhost, a **Pull** button appears. |\n| **Pulling `NN`%** | A native Ollama pull is in progress for the current model (local endpoints only). |\n| **Unauthorized** | The endpoint returned HTTP `401` or `403` — wrong or missing API key. |\n| **API unreachable** | The endpoint did not respond (wrong URL, server down, or network failure). |\n\nThe status resets to idle when the dialog closes or the mentor toggle is turned off. Changing the base URL, model, or API key triggers a fresh check and cancels any in-flight pull.\n\n### Pulling a model from Ollama\n\nWhen the endpoint is a `localhost`-based Ollama instance and the model is **Not found locally**, click **Pull** to download it. Progress is streamed in real time, and the status switches to **Available** on success. If the pull fails mid-way, the status shows **API unreachable**.\n\nPulls are local-only: the pull button appears only for loopback URLs (`localhost`, `127.0.0.1`, `::1`) because it calls the Ollama-native `/api/pull` endpoint. For hosted providers, pull models through their own tools or dashboard.\n\nClosing the **Settings** dialog, disabling the **Mentor** toggle, or changing the model while a pull is running aborts it immediately.\n\n### Reaching local Ollama from the hosted app\n\nIf you use the hosted web app over HTTPS, requests to `http://localhost:11434` are allowed by the browser, but Ollama still rejects the cross-origin request unless you allow the app's origin. Start it with `OLLAMA_ORIGINS=https://app.nesso.how` or use the desktop build, whose native transport does not require this browser CORS setting.\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx)) shapes Socrates:\n\n- One short question per turn by default, explaining only enough to frame it.\n- Replies are soft-capped at ~200 words (hard cap via output tokens).\n- No graph edits proposed in dialogue. Socrates probes; the user edits.\n- No emojis, flattery, JSON, or pseudo-graph markup. Sparse `*asterisks*` on key terms.\n- Replies in the active UI language (English or Italian). Snapshot tokens stay **English-shaped** (`s=…d`, `…d since review`, etc.), with the same spelling in the legend for every locale.\n\nIf you want a more permissive coach, fork the persona. It is plain text in the component and easy to swap.\n\n## Opening message\n\nWhen the panel opens, the mentor sends itself a short synthetic **user** turn so its first message reflects what's selected:\n\n- **A concept node selected:** opens on that concept and one of its relations.\n- **An edge selected (no node):** opens on the typed relation between its endpoints.\n- **Nothing selected:** opens on a weak spot in the graph (low stability plus weak **last reviews** (Again/Hard or a long gap); **DUE** is extra scheduler context).\n\nClick **New chat** in the header to reset history and request a fresh opener.\n\n## Context size\n\nLarge graphs are summarised, not truncated abruptly. The weakest-reviewed nodes appear first (`nodeStrength`), so the verbatim slice emphasises instability and risky last ratings; tail nodes are omitted with a short count only. Edges have a ~2x allowance over node count. These limits live in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`."
|
|
14
14
|
},
|
|
15
15
|
{
|
|
16
16
|
"slug": "guides/building-a-graph",
|
|
17
17
|
"title": "Building a graph",
|
|
18
|
-
"description": "How to add concepts, draw typed relations, and use the Inspector to enrich nodes with definitions
|
|
19
|
-
"markdown": "The canvas is the centre of Nesso. **Concepts** are nodes and **typed relations** are edges. The **Inspector** is the right-hand panel where you enrich whatever you've got selected.\n\n## Adding concepts\n\n- **Double-click** empty canvas to add a concept at the pointer.\n- **`N`** adds a concept at the viewport centre.\n- **Right-click** empty canvas and choose **Add concept here** to add one at the cursor.\n- New concepts open in edit mode
|
|
18
|
+
"description": "How to add concepts, draw typed relations, and use the Inspector to enrich nodes with definitions.",
|
|
19
|
+
"markdown": "The canvas is the centre of Nesso. **Concepts** are nodes and **typed relations** are edges. The **Inspector** is the right-hand panel where you enrich whatever you've got selected.\n\n## Adding concepts\n\n- **Double-click** empty canvas to add a concept at the pointer.\n- **`N`** adds a concept at the viewport centre.\n- **Right-click** empty canvas and choose **Add concept here** to add one at the cursor.\n- New concepts open in edit mode with the text input focused. Start typing immediately. Press `Enter` to commit, `Esc` to cancel.\n- **Double-click** a concept to rename it inline.\n\nAn empty graph shows a centered **\"Your first concept\"** hint, but the double-click still works through it.\n\n## Drawing relations\n\nDrag from either visible connection dot on a node to another node. The node where you start is the source and the node where you release is the target, so the relation picker follows the direction of your gesture. The usual path is the right edge (`out`) to the other node's left edge (`in`). On release, a **relation picker** opens, grouped by category. Pick the relation type and the edge is created.\n\n- The connection line previews with the same quadratic geometry the final edge uses.\n- Edge type can be changed any time from the Inspector when an edge is selected.\n\nSee the [relation types reference](../../reference/relation-types/) for the full list, semantic meaning, and type properties. Each type has a category colour and an SVG glyph, both defined in `@nesso-how/vocab-learning`. Edge encoding density is under [Display options](#display-options-sidebar) below.\n\n## Selecting and editing\n\n- **Click** a node or edge to select it. The Inspector reflects the selection.\n- **Hold `⌘` / `Ctrl` and click** to toggle additional items into the selection.\n- **Drag on empty canvas** to marquee-select multiple items.\n- **`⌘A` / `Ctrl+A`** selects every concept and relation in the graph.\n- **Right-click** a concept, relation, or empty canvas for a context menu of the relevant actions (copy/cut/duplicate/delete a concept; flip / delete a relation; paste / add concept / center·fit on the canvas). To change a relation's type, select the edge and pick a new type in the Inspector.\n- **`Del`** or **`Backspace`** deletes the selection (one relation, one concept, or every concept in a marquee). Edges attached to a deleted concept go with it. Delete is also on the right-click menu and the Inspector's action toolbar.\n- **`⌘C` / `Ctrl+C`** copies the selection. Copying concepts also copies relations between them; copying a relation includes its two endpoints. **`⌘X` / `Ctrl+X`** cuts: it copies the selection and removes it in one step. **`⌘V` / `Ctrl+V`** pastes the clipboard with a small offset (right-click **Paste** drops it at the cursor instead). **`⌘D` / `Ctrl+D`** duplicates the selection in place without touching the clipboard. These also live on the right-click menu and the Inspector toolbar.\n- **Arrow keys** nudge a selected concept, and **Shift + arrows** move it in larger steps.\n- **`⌘Z` / `Ctrl+Z`** undoes structural edits; **`⌘⇧Z` / `Ctrl+Shift+Z`** redoes. History has 50 steps and resets when you switch or import a graph.\n\n## The Inspector\n\nThe Inspector docks on the **right**, full height between the top bar and the status bar. Its header has a **collapse** control that shrinks it to a slim **rail** (keeping the selection plus a vertical action toolbar) and a **close** control. A docked bottom **action toolbar** offers copy / cut / duplicate / delete for a concept, or flip / delete for a relation.\n\nWhen a concept is selected it shows, top to bottom:\n\n- **Memory** _(collapsible):_ the FSRS schedule, read-only: when due, stability (in days), last self-rating, review count (with lapses), and time since the last review.\n- **Definition**: see below.\n- **Relations** _(collapsible):_ outgoing and incoming edges, each connected concept shown with the relation glyph in a chip and the type on the right (incoming dimmed). Click a row to jump to that concept. Change a relation's type by selecting the edge.\n\nWhen an edge is selected, the Inspector shows the relation as a chip with its category colour and a dropdown of every relation type. Picking a new type updates the edge in place. The graph keeps its endpoints and identity.\n\n### Definition field\n\nA single free-text field that travels with the concept and feeds both the AI mentor and [Review](../../guides/review-mode/):\n\n- **Definition:** a one-sentence-ish explanation in your own words.\n\nIn Review, the definition appears when you **Reveal** a card so you can check your recall. The AI mentor uses the definition in its graph snapshot and focal-neighbour context when a concept is selected.\n\n## Display options (sidebar)\n\n**Sidebar → Display** controls how the **active graph** is rendered: heatmap overlay, edge encoding density, curve style, and auto flip. Choices are saved **with the graph** in IndexedDB (and included in JSON export). New graphs start from the app defaults until you change them.\n\nWhen **Display → Curve** is set to **Arc**, **Auto flip** (on by default) bends relations toward the side that avoids overlapping nodes, flipping when the target is above the source on the right, or below on the left, and updates live while you drag concepts. **Flip curve** in the Inspector is **Off | Auto | On** while auto flip is on: **Auto** follows layout, **Off** / **On** pin a manual bend on that edge. With auto flip off for that graph, the control is **Off | On** only."
|
|
20
20
|
},
|
|
21
21
|
{
|
|
22
22
|
"slug": "guides/embedding-graphs",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"slug": "guides/graph-management",
|
|
35
35
|
"title": "Graph management",
|
|
36
36
|
"description": "Working with multiple graphs, exporting and importing JSON, and desktop project folders.",
|
|
37
|
-
"markdown": "A **graph** is one map: its concepts, relations, and display settings. You can keep several graphs and switch between them, export or import any of them as JSON, and, on desktop, group graphs into project folders.\n\n## Multiple graphs\n\nThe **Sidebar** lists every graph in the current project. Click a graph to switch to it: the canvas, Inspector, and Review queue all follow.\n\n- **Rename**: double-click a graph's row in the list, type the new name, `Enter` to commit.\n- **Delete**: hover a row and click the trash icon. You're asked to confirm. Deleting also removes its file from the project folder on desktop. The last remaining graph can't be deleted, so the delete action is hidden when only one graph is left.\n- **New graph**: the **New** button above the list creates an empty graph and switches to it immediately.\n\nSwitching graphs flushes any pending autosave on the one you're leaving, so edits made just before a switch aren't lost.\n\n## Export and import (JSON)\n\nOpen the **⋯** menu in the top bar (tooltip: \"Export · Import · Shortcuts\") for:\n\n- **Export graph**: saves the active graph as a `.json` file named after the graph.\n- **Export graph (.png)**: renders the canvas at 1920×1200 and saves it as an image, with React Flow's selection handles excluded from the render.\n- **Import graph**: opens a file picker for a `.json` file and adds it as a new graph.\n\nExport behaves differently depending on platform:\n\n- **Desktop**: a native save dialog lets you pick the destination.\n- **Web**: if your browser supports the File System Access API, you get a save dialog and can overwrite the same file on repeat exports. Otherwise it falls back to a normal browser download.\n\nImporting a file that isn't a valid Nesso graph shows an error toast and imports nothing. A successful import creates a new graph (de-duplicating its name against your existing graphs) and switches to it.\n\nExported JSON carries graph **content** only: concepts, relations, and display settings. Personal review progress (FSRS data) is never included, so sharing or re-importing a file never carries someone else's recall history.\n\n## Desktop projects\n\nOn the desktop app, graphs live inside **project folders**: plain directories on disk holding one JSON file per graph plus a small manifest. The **Projects** section in the sidebar (desktop only) lists every folder you've opened and lets you switch between them.\n\n- **
|
|
37
|
+
"markdown": "A **graph** is one map: its concepts, relations, and display settings. You can keep several graphs and switch between them, export or import any of them as JSON, and, on desktop, group graphs into project folders.\n\n## Multiple graphs\n\nThe **Sidebar** lists every graph in the current project. Click a graph to switch to it: the canvas, Inspector, and Review queue all follow.\n\n- **Rename**: double-click a graph's row in the list, type the new name, `Enter` to commit.\n- **Delete**: hover a row and click the trash icon. You're asked to confirm. Deleting also removes its file from the project folder on desktop. The last remaining graph can't be deleted, so the delete action is hidden when only one graph is left.\n- **New graph**: the **New** button above the list creates an empty graph and switches to it immediately.\n\nSwitching graphs flushes any pending autosave on the one you're leaving, so edits made just before a switch aren't lost.\n\n## Export and import (JSON)\n\nOpen the **⋯** menu in the top bar (tooltip: \"Export · Import · Shortcuts\") for:\n\n- **Export graph**: saves the active graph as a `.json` file named after the graph.\n- **Export graph (.png)**: renders the canvas at 1920×1200 and saves it as an image, with React Flow's selection handles excluded from the render.\n- **Import graph**: opens a file picker for a `.json` file and adds it as a new graph.\n\nExport behaves differently depending on platform:\n\n- **Desktop**: a native save dialog lets you pick the destination.\n- **Web**: if your browser supports the File System Access API, you get a save dialog and can overwrite the same file on repeat exports. Otherwise it falls back to a normal browser download.\n\nImporting a file that isn't a valid Nesso graph shows an error toast and imports nothing. A successful import creates a new graph (de-duplicating its name against your existing graphs) and switches to it.\n\nExported JSON carries graph **content** only: concepts, relations, and display settings. Personal review progress (FSRS data) is never included, so sharing or re-importing a file never carries someone else's recall history.\n\n## Desktop projects\n\nOn the desktop app, graphs live inside **project folders**: plain directories on disk holding one JSON file per graph plus a small manifest. The **Projects** section in the sidebar (desktop only) lists every folder you've opened and lets you switch between them.\n\n- **Add project**: the **+** button opens a native folder picker. Pick an existing project folder, or create a new one from the dialog's \"New Folder\" button (macOS). The selected folder becomes the active project.\n- **Switch project**: click any project in the list. The current graph is saved first, then the target folder's graphs load.\n- **Remove project**: hover a project and click the trash icon, then confirm. This only removes it from Nesso's list. Its files stay on disk untouched. You can't remove the last project in the list.\n- **Reveal in Finder**: hover a project and click the folder icon to reveal it in the system file manager.\n\nIf a project folder is moved, renamed, or deleted outside the app, it stays in the list marked as missing (greyed out, with a \"not found\" label) rather than disappearing. Switching away from a missing project happens automatically. Switching back works again once the folder reappears at the same path. Only the trash icon removes it from the list for good.\n\n:::caution\nNative folder pickers and the system menu bar are desktop-only Tauri APIs. None of this section applies to the web app, which has a single implicit workspace backed by IndexedDB. See [FAQ](../../faq/#what-changes-between-the-web-app-and-the-desktop-app) for the full web/desktop comparison.\n:::"
|
|
38
38
|
},
|
|
39
39
|
{
|
|
40
40
|
"slug": "guides/mcp",
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
"slug": "guides/review-mode",
|
|
47
47
|
"title": "Review mode",
|
|
48
48
|
"description": "Spaced-repetition review of your concepts with FSRS, how it queues cards and reschedules them from your self-ratings.",
|
|
49
|
-
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts that are due, prompts you to recall what you know, and reschedules them based on how you self-rate.\n\nNesso uses [FSRS](https://github.com/open-spaced-repetition/ts-fsrs), a modern open-source successor to the SM-2 / Anki algorithm.\n\n## What gets reviewed\n\nEach concept node carries its own FSRS state: `stability`, `difficulty`, `due`, `lastReview`, `lastRating`, and friends. A node is **due** when `due <= now`. New, unrated concepts default to `due = 0`, which means they show up immediately the first time you open Review.\n\nThe session queue is built fresh every time you open the overlay: all due nodes, sorted by urgency, in random order within the same due bucket.\n\n## Flow\n\nFor each due concept, Review:\n\n1. **Shows the concept title** and a short recall prompt. Try to remember its definition
|
|
49
|
+
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts that are due, prompts you to recall what you know, and reschedules them based on how you self-rate.\n\nNesso uses [FSRS](https://github.com/open-spaced-repetition/ts-fsrs), a modern open-source successor to the SM-2 / Anki algorithm.\n\n## What gets reviewed\n\nEach concept node carries its own FSRS state: `stability`, `difficulty`, `due`, `lastReview`, `lastRating`, and friends. A node is **due** when `due <= now`. New, unrated concepts default to `due = 0`, which means they show up immediately the first time you open Review.\n\nThe session queue is built fresh every time you open the overlay: all due nodes, sorted by urgency, in random order within the same due bucket.\n\n## Flow\n\nFor each due concept, Review:\n\n1. **Shows the concept title** and a short recall prompt. Try to remember its definition and typed relations before revealing.\n2. **Waits for you to think**, then click **Reveal** (or press `Space`).\n3. **Reveals** the concept's definition and typed relations.\n4. **You rate** how it felt: `Again`, `Hard`, `Good`, `Easy`. Each button shows the **predicted next interval** under it (e.g. `< 1d`, `4d`, `2mo`).\n\nFSRS then updates `stability` and `difficulty`, schedules the next `due` date, and Review advances to the next card. Done with the queue, the overlay closes. You're caught up.\n\n## Tuning FSRS\n\nUnder **Settings -> Learning -> Review**:\n\n| Setting | What it does | Range |\n| -------------------- | ---------------------------------------------------------------------------------------------------- | ----------- |\n| **Target retention** | Probability of correctly recalling a concept at its next review. Higher means more frequent reviews. | 70% to 97% |\n| **Max interval** | Longest interval FSRS can schedule, in days. Caps how far into the future a card can be pushed. | 1 to 36,500 |\n\nThe defaults (90% retention, 100-year cap) match the FSRS reference defaults. Lower the retention if you're comfortable forgetting more in exchange for fewer reviews. Raise the max interval if you want long-term cards to keep stretching out.\n\nReview is on by default. The **Review mode** toggle at the top of **Settings -> Learning** turns it off entirely: the **Review** pill and the `R` shortcut disappear, and the FSRS settings above hide while it is off.\n\n## Tips\n\n- Add a **definition** in the Inspector. It appears on reveal and gives you something concrete to check your recall against.\n- Pair concepts with **at least one typed edge** before reviewing them. Relations are part of what you reveal and what makes the graph worth remembering.\n- The session count in the top bar reflects the original queue size. Cards rated `Again` that come back later increase the count past 100%. That is expected."
|
|
50
50
|
},
|
|
51
51
|
{
|
|
52
52
|
"slug": "introduction",
|
|
@@ -58,19 +58,19 @@
|
|
|
58
58
|
"slug": "reference/mcp-tools",
|
|
59
59
|
"title": "MCP tools",
|
|
60
60
|
"description": "Reference for the four tools exposed by the @nesso-how/mcp server.",
|
|
61
|
-
"markdown": "The `@nesso-how/mcp` server exposes four tools. See [MCP](../../guides/mcp/) for setup and workflow.\n\n### `get_nesso_docs`\n\nFetches documentation pages from this site. Call it without a `slug` to get a table of contents, or with a slug (e.g. `\"guides/getting-started\"`) to get the full page content.\n\n### `get_relation_types`\n\nReturns the complete list of relation types grouped by category id (`taxonomic`, `structural`, and so on from `RELATION_CATEGORIES` in `@nesso-how/vocab-learning`), with
|
|
61
|
+
"markdown": "The `@nesso-how/mcp` server exposes four tools. See [MCP](../../guides/mcp/) for setup and workflow.\n\n### `get_nesso_docs`\n\nFetches documentation pages from this site. Call it without a `slug` to get a table of contents, or with a slug (e.g. `\"guides/getting-started\"`) to get the full page content.\n\n### `get_relation_types`\n\nReturns the complete list of relation types grouped by category id (`taxonomic`, `structural`, and so on from `RELATION_CATEGORIES` in `@nesso-how/vocab-learning`), with glyph, symmetry, and type properties (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner.\n\n### `validate_graph`\n\n**Input:** `{ \"graph\": \"<json string>\" }`: a Nesso graph document (`concepts[]`, `relations[]`), not runtime React Flow `nodes`/`edges`.\n\n**Output:** `{ \"valid\": boolean, \"errors\": [{ \"path\", \"message\" }], \"warnings\": [{ \"path\", \"message\" }] }`\n\nRuns envelope and vocabulary validation plus structural checks the deserializer does not cover today: duplicate ids, dangling relation endpoints, unknown relation types. Warnings flag missing `vocabulary` or relation `type` (the app falls back to `causes` at render time).\n\n`valid` is `true` only when `errors` is empty.\n\n### `build_graph`\n\n**Input:**\n\n```json\n{\n \"name\": \"Photosynthesis\",\n \"concepts\": [\n \"Sunlight\",\n {\n \"text\": \"Chloroplast\",\n \"elaboration\": { \"definition\": \"...\" }\n }\n ],\n \"relations\": [{ \"from\": \"Sunlight\", \"to\": \"Chloroplast\", \"relation\": \"enables\" }]\n}\n```\n\n- `concepts`: label strings or objects with optional `id`, `text`, and `elaboration`.\n- `relations`: `from` / `to` match concept `id` or label (must be unambiguous); `relation` must be a valid type id from `get_relation_types`.\n\n**Output:** Pretty-printed graph document JSON ready to write to disk (includes `vocabulary`, generated ids, and dagre layout positions). FSRS review fields and React Flow edge shape (`type: \"nesso\"`, handles) are applied by the app on import, not stored in the file."
|
|
62
62
|
},
|
|
63
63
|
{
|
|
64
64
|
"slug": "reference/relation-types",
|
|
65
65
|
"title": "Relation types",
|
|
66
66
|
"description": "The 52 semantic relation types across 8 categories in Nesso.",
|
|
67
|
-
"markdown": "In Nesso, every edge carries a **semantic type**: a named relation describing how two concepts are connected, with type properties reserved for graph-analysis algorithms (future work, no algorithm currently consumes them). The vocabulary is fixed at 52 types across 8 categories, drawn from prior work in knowledge representation, lexical semantics, temporal logic, and signed-network theory.\n\n:::note[About this vocabulary]\nThese 52 relation types are one slice of `@nesso-how/vocab-learning`, which also defines node parameters (FSRS), display settings, and category palettes. Graph JSON files declare their vocabulary via `vocabulary.id` and `vocabulary.version`; the envelope schema (`@nesso-how/schema`) is vocabulary-agnostic. The types and their property values are a considered first cut, and both will evolve as real graphs accumulate and the analysis algorithms that consume them get built out.\n:::\n\n## Properties\n\nEach relation type declares the properties below. They define the contract that graph-analysis algorithms will consume; closing the enum guarantees every type comes with them, where a user-defined type would arrive without and stay analytically opaque.\n\n- **Transitive (T)**: `Y` (strict), `N` (none), or `weak` (transitivity with decay; algorithms may discount per step).\n- **Inverse (I)**: the canonical inverse type in the set; `self` for symmetric relations. Asymmetric relations declare it explicitly so traversal is first-class in both directions. The explicit-inverse design follows knowledge-graph embedding work <a id=\"cite-1\" href=\"#ref-1\">[1]</a>, which lists symmetry, antisymmetry, inversion, and composition as the four properties a good relation set should support.\n- **Strength (S)**: per-type semantic weight in `0..1`. Encodes how \"tight\" the relation is in general (e.g. `defines` 0.90 vs `similar-to` 0.40), not how sure the user is about a specific edge. The idea that different relation types carry different semantic distance comes from lexical-taxonomy weighting schemes <a id=\"cite-2\" href=\"#ref-2\">[2]</a>, <a id=\"cite-3\" href=\"#ref-3\">[3]</a>.\n- **Polarity (P)**: `+1` positive effect, `-1` antagonistic, `0` neutral/structural. From signed-network theory <a id=\"cite-4\" href=\"#ref-4\">[4]</a>: with polarity, the graph becomes a signed network where balance and cycle-sign analyses can apply.\n- **Cardinality (C)**: expected mapping pattern, always declared. One of `1-1`, `1-N`, `N-1`, `N-N` (no a-priori constraint). Setting this consistently lets algorithms flag structural anomalies (e.g. two competing `defines` edges into the same term).\n\n## Categories\n\nEach category answers a specific question about the relation. Grouping the types by question makes the vocabulary easier to navigate when authoring a graph, and lets graph-analysis algorithms compare and aggregate at category level instead of only per individual type.\n\n### Taxonomic\n\n_What kind of thing is it?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | -------------- | --- | ---- | --- | --- |\n| `subtype-of` | subtype of | `has-subtype` | Y | 0.90 | 0 | N-1 |\n| `has-subtype` | has subtype | `subtype-of` | Y | 0.90 | 0 | 1-N |\n| `instance-of` | instance of | `has-instance` | N | 0.95 | 0 | N-1 |\n| `has-instance` | has instance | `instance-of` | N | 0.95 | 0 | 1-N |\n\nTaxonomic relations answer the simplest question you can ask about a concept: what kind of thing is it? Nesso splits the answer into two layers that look alike at a glance but behave very differently under reasoning. The class-vs-instance distinction mirrors OWL/RDFS <a id=\"cite-5\" href=\"#ref-5\">[5]</a>: `subtype-of` corresponds to `rdfs:subClassOf` (one class refines another, as a sparrow refines bird), while `instance-of` corresponds to `rdf:type` (an individual belongs to a class, as Tweety belongs to sparrow). Inheritance flows freely through the subtype chain, but instances are leaves: Tweety is a sparrow and through that a bird, yet Tweety is not itself \"a kind of\" anything.\n\n### Structural\n\n_What is it made of or composed from?_\n\n| Type | Label | I | T | S | P | C |\n| ---------- | -------- | ---------- | ---- | ---- | --- | --- |\n| `part-of` | part of | `contains` | Y | 0.85 | 0 | N-1 |\n| `contains` | contains | `part-of` | Y | 0.85 | 0 | 1-N |\n| `made-of` | made of | `composes` | weak | 0.75 | 0 | N-N |\n| `composes` | composes | `made-of` | weak | 0.75 | 0 | N-N |\n\nStructural relations describe how a thing decomposes into its parts. The category covers two patterns. `part-of` and its inverse `contains` capture discrete structural decomposition: an engine is part of a car, a paragraph is part of a chapter, and transitivity flows cleanly through the chain. `made-of` and `composes` capture material or substantive composition instead: water is made of hydrogen and oxygen, a chair is made of wood. Transitivity there is only weak, because what something is made of doesn't always propagate in a meaningful way (a chair made of wood, made of cellulose, made of carbon, made of atoms dilutes the relationship as the chain grows).\n\n### Causal\n\n_What does it do or prevent?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | -------------- | ---- | ---- | --- | --- |\n| `causes` | causes | `caused-by` | N | 0.85 | +1 | N-N |\n| `caused-by` | caused by | `causes` | N | 0.85 | +1 | N-N |\n| `produces` | produces | `produced-by` | N | 0.70 | +1 | N-N |\n| `produced-by` | produced by | `produces` | N | 0.70 | +1 | N-N |\n| `enables` | enables | `enabled-by` | weak | 0.60 | +1 | N-N |\n| `enabled-by` | enabled by | `enables` | weak | 0.60 | +1 | N-N |\n| `prevents` | prevents | `prevented-by` | N | 0.85 | −1 | N-N |\n| `prevented-by` | prevented by | `prevents` | N | 0.85 | −1 | N-N |\n| `triggers` | triggers | `triggered-by` | N | 0.70 | +1 | N-N |\n| `triggered-by` | triggered by | `triggers` | N | 0.70 | +1 | N-N |\n| `inhibits` | inhibits | `inhibited-by` | N | 0.55 | −1 | N-N |\n| `inhibited-by` | inhibited by | `inhibits` | N | 0.55 | −1 | N-N |\n| `disables` | disables | `disabled-by` | weak | 0.60 | −1 | N-N |\n| `disabled-by` | disabled by | `disables` | weak | 0.60 | −1 | N-N |\n| `consumes` | consumes | `consumed-by` | N | 0.65 | −1 | N-N |\n| `consumed-by` | consumed by | `consumes` | N | 0.65 | −1 | N-N |\n| `delays` | delays | `delayed-by` | weak | 0.55 | −1 | N-N |\n| `delayed-by` | delayed by | `delays` | weak | 0.55 | −1 | N-N |\n\nCausal is the largest category in Nesso, because causation in the real world doesn't come in a single flavor. On the positive side, `causes` describes direct generation of an outcome, `triggers` describes the initiation of something that then plays out on its own (a spark triggers an explosion), and `enables` describes making something possible without forcing it. The negative side mirrors this: `prevents` is total blockage, `inhibits` is partial reduction, and `disables` is switching off a capacity or function. Intensity and mechanism live at the type level rather than as per-edge weights, so choosing between `inhibits` and `prevents` is a semantic decision about what is actually happening, not about how confident the author is.\n\n`consumes` and `delays` round out the category. `consumes` captures resource destruction, which is causal rather than dependency-flavored: it is distinct from `uses`, where the resource survives the interaction. `delays` carries negative polarity because slowing or postponing an outcome hinders it, even though nothing is destroyed.\n\n### Dependency\n\n_What does it need or serve?_\n\n| Type | Label | I | T | S | P | C |\n| ------------- | ----------- | ------------- | ---- | ---- | --- | --- |\n| `requires` | requires | `required-by` | Y | 0.85 | 0 | N-N |\n| `required-by` | required by | `requires` | Y | 0.85 | 0 | N-N |\n| `uses` | uses | `used-by` | weak | 0.50 | 0 | N-N |\n| `used-by` | used by | `uses` | weak | 0.50 | 0 | N-N |\n| `used-for` | used for | `purpose-of` | N | 0.55 | +1 | N-N |\n| `purpose-of` | purpose of | `used-for` | N | 0.55 | +1 | N-N |\n\nDependency relations capture what a concept _needs_ rather than what causes it. A car requires an engine to function, but the engine doesn't cause the car, and that difference shows up in how the graph traverses these edges. `requires` and `required-by` are the hard form, where the dependency is essential and transitivity is strict: if A requires B and B requires C, A also requires C. `uses` and `used-by` are softer, capturing a working relationship that doesn't necessarily imply the user can't survive without it, so transitivity decays through the chain. `used-for` and `purpose-of` are teleological: they point at the goal or function a thing serves (a hammer is used for driving nails). Cardinality there stays open at N-N, since one tool can serve many purposes and many tools can share a single purpose.\n\n### Temporal\n\n_When or where does it happen?_\n\n| Type | Label | I | T | S | P | C |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | --- |\n| `precedes` | precedes | `follows` | Y | 0.50 | 0 | N-N |\n| `follows` | follows | `precedes` | Y | 0.50 | 0 | N-N |\n| `occurs-in` | occurs in | `has-occurrence` | Y | 0.40 | 0 | N-1 |\n| `has-occurrence` | has occurrence | `occurs-in` | Y | 0.40 | 0 | 1-N |\n| `during` | during | `spans` | Y | 0.55 | 0 | N-1 |\n| `spans` | spans | `during` | Y | 0.55 | 0 | 1-N |\n| `overlaps-with` | overlaps with | self (symmetric) | N | 0.45 | 0 | N-N |\n| `derives-from` | derives from | `gives-rise-to` | Y | 0.70 | 0 | N-1 |\n| `gives-rise-to` | gives rise to | `derives-from` | Y | 0.70 | 0 | 1-N |\n\nTemporal relations describe when things happen relative to each other and how an event sits inside a larger period. Allen's interval algebra <a id=\"cite-6\" href=\"#ref-6\">[6]</a> inspires the containment pair: `during` and `spans` model intervals nested inside other intervals (the medieval period spans roughly a thousand years, and Charlemagne's reign was during it). `occurs-in` and its inverse work at a different scale, pinning a quasi-point event to the period it falls inside (the moon landing occurs in 1969). `precedes` and `follows` cover plain sequence without nesting, and `overlaps-with` is the symmetric case for two intervals that share a stretch of time without one containing the other.\n\n`derives-from` and `gives-rise-to` are not just about chronology, they capture genealogical descent: a transformative continuity where something becomes something else over time. Languages, species, and ideas all have lineages of this kind. The relation is close to `caused-by` but distinct, because causation is direct influence without requiring the cause to _become_ the effect. It is also distinct from taxonomic `subtype-of`, which is a snapshot of class membership rather than a historical claim. Italian derives from Latin, but Italian is not a subtype of Latin in the modern sense.\n\n### Opposition\n\n_What does it contrast with?_\n\n| Type | Label | I | T | S | P | C |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | --- |\n| `contrasts-with` | contrasts with | self (symmetric) | N | 0.50 | −1 | N-N |\n| `opposite-of` | opposite of | self (symmetric) | N | 0.80 | −1 | 1-1 |\n\nOpposition is the category for concepts that stand against each other. The two types differ in strength. `contrasts-with` is the weaker form, where two concepts highlight each other by sitting at different points on some dimension (warm contrasts with cool, North contrasts with South). `opposite-of` is the canonical, often binary opposite (alive is the opposite of dead, true is the opposite of false), and its cardinality is 1-1 because a canonical opposite is unique. Both are symmetric: if A is the opposite of B, then B is the opposite of A by definition.\n\n### Similarity\n\n_What is it like?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | --- |\n| `similar-to` | similar to | self (symmetric) | weak | 0.40 | +1 | N-N |\n| `analogous-to` | analogous to | self (symmetric) | N | 0.30 | +1 | N-N |\n\nThe similarity category includes two related but distinct relations. `similar-to` is the looser one, where two concepts share enough properties to be grouped together (lions are similar to tigers). `analogous-to` is more structural: the two concepts aren't necessarily alike in their properties, but their roles or relationships mirror each other (an electron orbiting an atom is analogous to a planet orbiting the sun). Both are symmetric, and both carry positive polarity because finding similarity or analogy is usually a constructive move in reasoning.\n\n### Epistemic\n\n_How do we know?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | --- |\n| `supports` | supports | `supported-by` | weak | 0.70 | +1 | N-N |\n| `supported-by` | supported by | `supports` | weak | 0.70 | +1 | N-N |\n| `contradicts` | contradicts | self (symmetric) | N | 0.75 | −1 | N-N |\n| `explains` | explains | `explained-by` | weak | 0.80 | 0 | N-N |\n| `explained-by` | explained by | `explains` | weak | 0.80 | 0 | N-N |\n| `defines` | defines | `defined-by` | N | 0.90 | 0 | 1-1 |\n| `defined-by` | defined by | `defines` | N | 0.90 | 0 | 1-1 |\n\nThe epistemic category is where Nesso models reasoning about claims rather than facts about the world. `supports` and `supported-by` connect a piece of evidence to the claim it bolsters; `explains` and `explained-by` connect an explanans (the explanatory account) to its explanandum (what is being explained). Both pairs are asymmetric, because evidence points to a claim and an explanation is not equivalent to what it explains.\n\n`defines` is the most rigid relation in this category. It goes from the defining expression (the _definiens_) to the term being defined (the _definiendum_): in \"F = ma defines force\", the equation is the definiens and `force` is the definiendum. Cardinality 1-1 enforces a single canonical definition per term, so two competing `defines` edges into the same concept signal a real ambiguity worth resolving.\n\n`contradicts` is the only symmetric relation in the category, because logical incompatibility goes both ways: if A contradicts B, then B equally contradicts A. This distinguishes it from `supports` and `explains`, which always point in a particular direction.\n\n## References\n\n1. <a id=\"ref-1\"></a>Sun, Z., Deng, Z.-H., Nie, J.-Y., and Tang, J. [_RotatE: Knowledge Graph Embedding by Relational Rotation in Complex Space_](https://arxiv.org/abs/1902.10197). ICLR, 2019. [↑](#cite-1)\n2. <a id=\"ref-2\"></a>Sussna, M. [_Word sense disambiguation for free-text indexing using a massive semantic network_](https://doi.org/10.1145/170088.170106). CIKM '93, 1993. [↑](#cite-2)\n3. <a id=\"ref-3\"></a>Jiang, J. J. and Conrath, D. W. [_Semantic similarity based on corpus statistics and lexical taxonomy_](https://arxiv.org/abs/cmp-lg/9709008). ROCLING X, 1997. [↑](#cite-3)\n4. <a id=\"ref-4\"></a>Cartwright, D. and Harary, F. [_Structural balance: A generalization of Heider's theory_](https://doi.org/10.1037/h0046049). Psychological Review, 63(5):277–293, 1956. [↑](#cite-4)\n5. <a id=\"ref-5\"></a>W3C. [_OWL 2 Web Ontology Language Primer (Second Edition)_](https://www.w3.org/TR/owl2-primer/). 2012. [↑](#cite-5)\n6. <a id=\"ref-6\"></a>Allen, J. F. [_Maintaining knowledge about temporal intervals_](https://doi.org/10.1145/182.358434). Communications of the ACM, 26(11):832–843, 1983. [↑](#cite-6)"
|
|
67
|
+
"markdown": "In Nesso, every edge carries a **semantic type**: a named relation describing how two concepts are connected, with type properties reserved for graph-analysis algorithms (future work, no algorithm currently consumes them). The vocabulary is fixed at 52 types across 8 categories, drawn from prior work in knowledge representation, lexical semantics, temporal logic, and signed-network theory.\n\n:::note[About this vocabulary]\nThese 52 relation types are one slice of `@nesso-how/vocab-learning`, which also defines node parameters (FSRS), display settings, and category palettes. Graph JSON files declare their vocabulary via `vocabulary.id` and `vocabulary.version`; the envelope schema (`@nesso-how/schema`) is vocabulary-agnostic. The types and their property values are a considered first cut, and both will evolve as real graphs accumulate and the analysis algorithms that consume them get built out.\n:::\n\n## Properties\n\nEach relation type declares the properties below. They define the contract that graph-analysis algorithms will consume; closing the enum guarantees every type comes with them, where a user-defined type would arrive without and stay analytically opaque.\n\n- **Transitive (T)**: `Y` (strict), `N` (none), or `weak` (transitivity with decay; algorithms may discount per step).\n- **Inverse (I)**: the canonical inverse type in the set; `self` for symmetric relations. Asymmetric relations declare it explicitly so traversal is first-class in both directions. The explicit-inverse design follows knowledge-graph embedding work <a id=\"cite-1\" href=\"#ref-1\">[1]</a>, which lists symmetry, antisymmetry, inversion, and composition as the four properties a good relation set should support.\n- **Strength (S)**: per-type semantic weight in `0..1`. Encodes how \"tight\" the relation is in general (e.g. `defines` 0.90 vs `similar-to` 0.40), not how sure the user is about a specific edge. The idea that different relation types carry different semantic distance comes from lexical-taxonomy weighting schemes <a id=\"cite-2\" href=\"#ref-2\">[2]</a>, <a id=\"cite-3\" href=\"#ref-3\">[3]</a>.\n- **Polarity (P)**: `+1` positive effect, `-1` antagonistic, `0` neutral/structural. From signed-network theory <a id=\"cite-4\" href=\"#ref-4\">[4]</a>: with polarity, the graph becomes a signed network where balance and cycle-sign analyses can apply.\n- **Cardinality (C)**: expected mapping pattern, always declared. One of `1-1`, `1-N`, `N-1`, `N-N` (no a-priori constraint). Setting this consistently lets algorithms flag structural anomalies (e.g. two competing `defines` edges into the same term).\n\n## Visual encoding\n\n- **Visual encoding**: category colour gives a coarse signal across the 8 categories; each type also has a glyph for a finer, near-type-level signal. Edge strokes are solid in every encoding mode.\n\n## Categories\n\nEach category answers a specific question about the relation. Grouping the types by question makes the vocabulary easier to navigate when authoring a graph, and lets graph-analysis algorithms compare and aggregate at category level instead of only per individual type.\n\n### Taxonomic\n\n_What kind of thing is it?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | -------------- | --- | ---- | --- | --- |\n| `subtype-of` | subtype of | `has-subtype` | Y | 0.90 | 0 | N-1 |\n| `has-subtype` | has subtype | `subtype-of` | Y | 0.90 | 0 | 1-N |\n| `instance-of` | instance of | `has-instance` | N | 0.95 | 0 | N-1 |\n| `has-instance` | has instance | `instance-of` | N | 0.95 | 0 | 1-N |\n\nTaxonomic relations answer the simplest question you can ask about a concept: what kind of thing is it? Nesso splits the answer into two layers that look alike at a glance but behave very differently under reasoning. The class-vs-instance distinction mirrors OWL/RDFS <a id=\"cite-5\" href=\"#ref-5\">[5]</a>: `subtype-of` corresponds to `rdfs:subClassOf` (one class refines another, as a sparrow refines bird), while `instance-of` corresponds to `rdf:type` (an individual belongs to a class, as Tweety belongs to sparrow). Inheritance flows freely through the subtype chain, but instances are leaves: Tweety is a sparrow and through that a bird, yet Tweety is not itself \"a kind of\" anything.\n\n### Structural\n\n_What is it made of or composed from?_\n\n| Type | Label | I | T | S | P | C |\n| ---------- | -------- | ---------- | ---- | ---- | --- | --- |\n| `part-of` | part of | `contains` | Y | 0.85 | 0 | N-1 |\n| `contains` | contains | `part-of` | Y | 0.85 | 0 | 1-N |\n| `made-of` | made of | `composes` | weak | 0.75 | 0 | N-N |\n| `composes` | composes | `made-of` | weak | 0.75 | 0 | N-N |\n\nStructural relations describe how a thing decomposes into its parts. The category covers two patterns. `part-of` and its inverse `contains` capture discrete structural decomposition: an engine is part of a car, a paragraph is part of a chapter, and transitivity flows cleanly through the chain. `made-of` and `composes` capture material or substantive composition instead: water is made of hydrogen and oxygen, a chair is made of wood. Transitivity there is only weak, because what something is made of doesn't always propagate in a meaningful way (a chair made of wood, made of cellulose, made of carbon, made of atoms dilutes the relationship as the chain grows).\n\n### Causal\n\n_What does it do or prevent?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | -------------- | ---- | ---- | --- | --- |\n| `causes` | causes | `caused-by` | N | 0.85 | +1 | N-N |\n| `caused-by` | caused by | `causes` | N | 0.85 | +1 | N-N |\n| `produces` | produces | `produced-by` | N | 0.70 | +1 | N-N |\n| `produced-by` | produced by | `produces` | N | 0.70 | +1 | N-N |\n| `enables` | enables | `enabled-by` | weak | 0.60 | +1 | N-N |\n| `enabled-by` | enabled by | `enables` | weak | 0.60 | +1 | N-N |\n| `prevents` | prevents | `prevented-by` | N | 0.85 | −1 | N-N |\n| `prevented-by` | prevented by | `prevents` | N | 0.85 | −1 | N-N |\n| `triggers` | triggers | `triggered-by` | N | 0.70 | +1 | N-N |\n| `triggered-by` | triggered by | `triggers` | N | 0.70 | +1 | N-N |\n| `inhibits` | inhibits | `inhibited-by` | N | 0.55 | −1 | N-N |\n| `inhibited-by` | inhibited by | `inhibits` | N | 0.55 | −1 | N-N |\n| `disables` | disables | `disabled-by` | weak | 0.60 | −1 | N-N |\n| `disabled-by` | disabled by | `disables` | weak | 0.60 | −1 | N-N |\n| `consumes` | consumes | `consumed-by` | N | 0.65 | −1 | N-N |\n| `consumed-by` | consumed by | `consumes` | N | 0.65 | −1 | N-N |\n| `delays` | delays | `delayed-by` | weak | 0.55 | −1 | N-N |\n| `delayed-by` | delayed by | `delays` | weak | 0.55 | −1 | N-N |\n\nCausal is the largest category in Nesso, because causation in the real world doesn't come in a single flavor. On the positive side, `causes` describes direct generation of an outcome, `triggers` describes the initiation of something that then plays out on its own (a spark triggers an explosion), and `enables` describes making something possible without forcing it. The negative side mirrors this: `prevents` is total blockage, `inhibits` is partial reduction, and `disables` is switching off a capacity or function. Intensity and mechanism live at the type level rather than as per-edge weights, so choosing between `inhibits` and `prevents` is a semantic decision about what is actually happening, not about how confident the author is.\n\n`consumes` and `delays` round out the category. `consumes` captures resource destruction, which is causal rather than dependency-flavored: it is distinct from `uses`, where the resource survives the interaction. `delays` carries negative polarity because slowing or postponing an outcome hinders it, even though nothing is destroyed.\n\n### Dependency\n\n_What does it need or serve?_\n\n| Type | Label | I | T | S | P | C |\n| ------------- | ----------- | ------------- | ---- | ---- | --- | --- |\n| `requires` | requires | `required-by` | Y | 0.85 | 0 | N-N |\n| `required-by` | required by | `requires` | Y | 0.85 | 0 | N-N |\n| `uses` | uses | `used-by` | weak | 0.50 | 0 | N-N |\n| `used-by` | used by | `uses` | weak | 0.50 | 0 | N-N |\n| `used-for` | used for | `purpose-of` | N | 0.55 | +1 | N-N |\n| `purpose-of` | purpose of | `used-for` | N | 0.55 | +1 | N-N |\n\nDependency relations capture what a concept _needs_ rather than what causes it. A car requires an engine to function, but the engine doesn't cause the car, and that difference shows up in how the graph traverses these edges. `requires` and `required-by` are the hard form, where the dependency is essential and transitivity is strict: if A requires B and B requires C, A also requires C. `uses` and `used-by` are softer, capturing a working relationship that doesn't necessarily imply the user can't survive without it, so transitivity decays through the chain. `used-for` and `purpose-of` are teleological: they point at the goal or function a thing serves (a hammer is used for driving nails). Cardinality there stays open at N-N, since one tool can serve many purposes and many tools can share a single purpose.\n\n### Temporal\n\n_When or where does it happen?_\n\n| Type | Label | I | T | S | P | C |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | --- |\n| `precedes` | precedes | `follows` | Y | 0.50 | 0 | N-N |\n| `follows` | follows | `precedes` | Y | 0.50 | 0 | N-N |\n| `occurs-in` | occurs in | `has-occurrence` | Y | 0.40 | 0 | N-1 |\n| `has-occurrence` | has occurrence | `occurs-in` | Y | 0.40 | 0 | 1-N |\n| `during` | during | `spans` | Y | 0.55 | 0 | N-1 |\n| `spans` | spans | `during` | Y | 0.55 | 0 | 1-N |\n| `overlaps-with` | overlaps with | self (symmetric) | N | 0.45 | 0 | N-N |\n| `derives-from` | derives from | `gives-rise-to` | Y | 0.70 | 0 | N-1 |\n| `gives-rise-to` | gives rise to | `derives-from` | Y | 0.70 | 0 | 1-N |\n\nTemporal relations describe when things happen relative to each other and how an event sits inside a larger period. Allen's interval algebra <a id=\"cite-6\" href=\"#ref-6\">[6]</a> inspires the containment pair: `during` and `spans` model intervals nested inside other intervals (the medieval period spans roughly a thousand years, and Charlemagne's reign was during it). `occurs-in` and its inverse work at a different scale, pinning a quasi-point event to the period it falls inside (the moon landing occurs in 1969). `precedes` and `follows` cover plain sequence without nesting, and `overlaps-with` is the symmetric case for two intervals that share a stretch of time without one containing the other.\n\n`derives-from` and `gives-rise-to` are not just about chronology, they capture genealogical descent: a transformative continuity where something becomes something else over time. Languages, species, and ideas all have lineages of this kind. The relation is close to `caused-by` but distinct, because causation is direct influence without requiring the cause to _become_ the effect. It is also distinct from taxonomic `subtype-of`, which is a snapshot of class membership rather than a historical claim. Italian derives from Latin, but Italian is not a subtype of Latin in the modern sense.\n\n### Opposition\n\n_What does it contrast with?_\n\n| Type | Label | I | T | S | P | C |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | --- |\n| `contrasts-with` | contrasts with | self (symmetric) | N | 0.50 | −1 | N-N |\n| `opposite-of` | opposite of | self (symmetric) | N | 0.80 | −1 | 1-1 |\n\nOpposition is the category for concepts that stand against each other. The two types differ in strength. `contrasts-with` is the weaker form, where two concepts highlight each other by sitting at different points on some dimension (warm contrasts with cool, North contrasts with South). `opposite-of` is the canonical, often binary opposite (alive is the opposite of dead, true is the opposite of false), and its cardinality is 1-1 because a canonical opposite is unique. Both are symmetric: if A is the opposite of B, then B is the opposite of A by definition.\n\n### Similarity\n\n_What is it like?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | --- |\n| `similar-to` | similar to | self (symmetric) | weak | 0.40 | +1 | N-N |\n| `analogous-to` | analogous to | self (symmetric) | N | 0.30 | +1 | N-N |\n\nThe similarity category includes two related but distinct relations. `similar-to` is the looser one, where two concepts share enough properties to be grouped together (lions are similar to tigers). `analogous-to` is more structural: the two concepts aren't necessarily alike in their properties, but their roles or relationships mirror each other (an electron orbiting an atom is analogous to a planet orbiting the sun). Both are symmetric, and both carry positive polarity because finding similarity or analogy is usually a constructive move in reasoning.\n\n### Epistemic\n\n_How do we know?_\n\n| Type | Label | I | T | S | P | C |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | --- |\n| `supports` | supports | `supported-by` | weak | 0.70 | +1 | N-N |\n| `supported-by` | supported by | `supports` | weak | 0.70 | +1 | N-N |\n| `contradicts` | contradicts | self (symmetric) | N | 0.75 | −1 | N-N |\n| `explains` | explains | `explained-by` | weak | 0.80 | 0 | N-N |\n| `explained-by` | explained by | `explains` | weak | 0.80 | 0 | N-N |\n| `defines` | defines | `defined-by` | N | 0.90 | 0 | 1-1 |\n| `defined-by` | defined by | `defines` | N | 0.90 | 0 | 1-1 |\n\nThe epistemic category is where Nesso models reasoning about claims rather than facts about the world. `supports` and `supported-by` connect a piece of evidence to the claim it bolsters; `explains` and `explained-by` connect an explanans (the explanatory account) to its explanandum (what is being explained). Both pairs are asymmetric, because evidence points to a claim and an explanation is not equivalent to what it explains.\n\n`defines` is the most rigid relation in this category. It goes from the defining expression (the _definiens_) to the term being defined (the _definiendum_): in \"F = ma defines force\", the equation is the definiens and `force` is the definiendum. Cardinality 1-1 enforces a single canonical definition per term, so two competing `defines` edges into the same concept signal a real ambiguity worth resolving.\n\n`contradicts` is the only symmetric relation in the category, because logical incompatibility goes both ways: if A contradicts B, then B equally contradicts A. This distinguishes it from `supports` and `explains`, which always point in a particular direction.\n\n## References\n\n1. <a id=\"ref-1\"></a>Sun, Z., Deng, Z.-H., Nie, J.-Y., and Tang, J. [_RotatE: Knowledge Graph Embedding by Relational Rotation in Complex Space_](https://arxiv.org/abs/1902.10197). ICLR, 2019. [↑](#cite-1)\n2. <a id=\"ref-2\"></a>Sussna, M. [_Word sense disambiguation for free-text indexing using a massive semantic network_](https://doi.org/10.1145/170088.170106). CIKM '93, 1993. [↑](#cite-2)\n3. <a id=\"ref-3\"></a>Jiang, J. J. and Conrath, D. W. [_Semantic similarity based on corpus statistics and lexical taxonomy_](https://arxiv.org/abs/cmp-lg/9709008). ROCLING X, 1997. [↑](#cite-3)\n4. <a id=\"ref-4\"></a>Cartwright, D. and Harary, F. [_Structural balance: A generalization of Heider's theory_](https://doi.org/10.1037/h0046049). Psychological Review, 63(5):277–293, 1956. [↑](#cite-4)\n5. <a id=\"ref-5\"></a>W3C. [_OWL 2 Web Ontology Language Primer (Second Edition)_](https://www.w3.org/TR/owl2-primer/). 2012. [↑](#cite-5)\n6. <a id=\"ref-6\"></a>Allen, J. F. [_Maintaining knowledge about temporal intervals_](https://doi.org/10.1145/182.358434). Communications of the ACM, 26(11):832–843, 1983. [↑](#cite-6)"
|
|
68
68
|
},
|
|
69
69
|
{
|
|
70
70
|
"slug": "troubleshooting",
|
|
71
71
|
"title": "Troubleshooting",
|
|
72
72
|
"description": "What to do when a banner, the mentor, or an update check doesn't behave as expected.",
|
|
73
|
-
"markdown": "## \"This graph was changed on disk while you were editing\"\n\n**When it appears**: desktop only. The file watcher noticed the active graph's JSON file changed outside the app (an external editor, a sync tool, another Nesso window) while you had unsaved edits in memory.\n\nThe banner offers two actions:\n\n- **Keep my changes**: writes your in-memory version to disk, overwriting the external change.\n- **Reload from disk**: discards your in-memory edits and loads the file as it now is on disk. Undo/redo history is cleared in the process.\n\nThere's no automatic merge: pick whichever side of the conflict you want to keep.\n\n## Auto-update problems (desktop)\n\nThe desktop app checks GitHub Releases once on launch. If checking fails (offline, GitHub unreachable), it stays silent: no banner, no error, just no update for now.\n\nOnce an update is found, the banner can show:\n\n- **Version `X` is available**: click **Install & restart** to download and apply it.\n- **Installing…**: download/install in progress; the button is disabled and there is no way to cancel.\n- **Update failed. Try again?**: the download or install step failed (e.g. lost connectivity mid-download). Click **Retry**.\n- **Update installed. Restart Nesso to finish**: the update was applied to disk, but the app couldn't relaunch itself automatically. Quit and reopen Nesso manually.\n\nYou can dismiss the available/error states for the rest of the session with the banner's close button; the install-in-progress state has no dismiss, since the install can't be cancelled once started.\n\n## Mentor not responding\n\nIf a mentor message fails, the reply bubble shows one of two messages, depending on what went wrong:\n\n- **Can't reach the AI endpoint. Check Settings (`⌘,`) → AI. For local Ollama, run `ollama serve`.** A network-level failure: the endpoint is unreachable, the wrong port, or
|
|
73
|
+
"markdown": "## \"This graph was changed on disk while you were editing\"\n\n**When it appears**: desktop only. The file watcher noticed the active graph's JSON file changed outside the app (an external editor, a sync tool, another Nesso window) while you had unsaved edits in memory.\n\nThe banner offers two actions:\n\n- **Keep my changes**: writes your in-memory version to disk, overwriting the external change.\n- **Reload from disk**: discards your in-memory edits and loads the file as it now is on disk. Undo/redo history is cleared in the process.\n\nThere's no automatic merge: pick whichever side of the conflict you want to keep.\n\n## Auto-update problems (desktop)\n\nThe desktop app checks GitHub Releases once on launch. If checking fails (offline, GitHub unreachable), it stays silent: no banner, no error, just no update for now.\n\nOnce an update is found, the banner can show:\n\n- **Version `X` is available**: click **Install & restart** to download and apply it.\n- **Installing…**: download/install in progress; the button is disabled and there is no way to cancel.\n- **Update failed. Try again?**: the download or install step failed (e.g. lost connectivity mid-download). Click **Retry**.\n- **Update installed. Restart Nesso to finish**: the update was applied to disk, but the app couldn't relaunch itself automatically. Quit and reopen Nesso manually.\n\nYou can dismiss the available/error states for the rest of the session with the banner's close button; the install-in-progress state has no dismiss, since the install can't be cancelled once started.\n\n## Mentor not responding\n\nIf a mentor message fails, the reply bubble shows one of two messages, depending on what went wrong:\n\n- **Can't reach the AI endpoint. Check Settings (`⌘,`) → AI. For local Ollama, run `ollama serve`.** A network-level failure: the endpoint is unreachable, the wrong port, or, on the hosted web app, a CORS rejection from a local Ollama instance. Confirm the base URL in **Settings → AI**, that Ollama or your server is actually running, and, if you're on the hosted web app talking to local Ollama, that you started it with `OLLAMA_ORIGINS` set to the app's origin (see [AI mentor](../guides/ai-mentor/#reaching-local-ollama-from-the-hosted-app)).\n- **_Hmm._ My voice failed me. Try again, slowly.** The endpoint was reachable but returned an error or a response Nesso couldn't parse. Check the model name and that the endpoint speaks the OpenAI-compatible `chat/completions` format.\n\nDesktop mentor requests use the native HTTP client. The desktop capability allows HTTPS and loopback HTTP only. If a desktop endpoint uses non-loopback `http://`, switch it to `https://` or configure a local service on `localhost`, `127.0.0.1`, or `::1`. Browser requests continue to follow normal browser CORS rules.\n\nClosing the mentor panel, switching graphs, or clicking **New chat** aborts any in-flight request without showing an error.\n\n## \"No AI endpoint configured\"\n\nThis isn't a failure: it's the mentor's resting state until you've set up an endpoint. It appears whenever **Mentor** is enabled in **Settings → AI** but the base URL or model field is empty. The input stays disabled until both are filled in. See [AI mentor](../guides/ai-mentor/#connecting-a-model) for setup.\n\n## Model pull stalls or shows stale results\n\nModel pulling is available only for local Ollama endpoints. When you click **Pull** in **Settings → AI**, Nesso streams the download progress from Ollama's `/api/pull` endpoint.\n\nIf a pull appears stuck:\n\n- **Changing settings cancels the pull.** Switching the model, base URL, or API key, disabling the mentor toggle, or closing the **Settings** dialog all abort the in-flight pull so stale progress cannot interfere with a new model selection.\n- **Ollama must be reachable on the native port.** Nesso strips the `/v1` suffix from your base URL to reach Ollama's native `/api/pull` endpoint. If you configured a non-standard port, make sure Ollama's native API is running on that same port.\n- **Progress is purely cosmetic.** The pull runs to completion regardless of whether the progress bar is visible. If the pull completes while you are on a different settings tab, the status badge updates when you return to the AI tab.\n\nIf the status shows **Unauthorized**, check your API key. The endpoint rejected the request with HTTP `401` or `403`. For hosted providers, make sure the key is valid and has not expired. Local Ollama instances do not require an API key — leave the field empty."
|
|
74
74
|
}
|
|
75
75
|
]
|
|
76
76
|
}
|
|
@@ -1,2 +1,19 @@
|
|
|
1
1
|
import type { McpServer } from '@modelcontextprotocol/server';
|
|
2
|
+
import { type GlyphKind, type RelationCategory, type RelationTypeName, type Transitivity, type Polarity, type Cardinality } from '@nesso-how/vocab-learning';
|
|
3
|
+
export type RelationTypePayload = {
|
|
4
|
+
type: RelationTypeName;
|
|
5
|
+
label: string;
|
|
6
|
+
glyph: GlyphKind;
|
|
7
|
+
symmetric: boolean;
|
|
8
|
+
transitive: Transitivity;
|
|
9
|
+
inverse: RelationTypeName | 'self';
|
|
10
|
+
strength: number;
|
|
11
|
+
polarity: Polarity;
|
|
12
|
+
cardinality: Cardinality;
|
|
13
|
+
};
|
|
14
|
+
export type RelationTypesPayload = Array<{
|
|
15
|
+
category: RelationCategory;
|
|
16
|
+
types: RelationTypePayload[];
|
|
17
|
+
}>;
|
|
18
|
+
export declare function getRelationTypesPayload(): RelationTypesPayload;
|
|
2
19
|
export declare function registerGetRelationTypes(server: McpServer): void;
|
|
@@ -1,29 +1,32 @@
|
|
|
1
1
|
import * as z from 'zod/v4';
|
|
2
|
-
import { RELATION_TYPES, RELATION_CATEGORIES } from '@nesso-how/vocab-learning';
|
|
2
|
+
import { RELATION_TYPES, RELATION_CATEGORIES, } from '@nesso-how/vocab-learning';
|
|
3
|
+
export function getRelationTypesPayload() {
|
|
4
|
+
return RELATION_CATEGORIES.map((cat) => ({
|
|
5
|
+
category: cat,
|
|
6
|
+
types: Object.entries(RELATION_TYPES)
|
|
7
|
+
.filter(([, def]) => def.cat === cat)
|
|
8
|
+
.map(([name, def]) => ({
|
|
9
|
+
type: name,
|
|
10
|
+
label: def.label,
|
|
11
|
+
glyph: def.glyph,
|
|
12
|
+
symmetric: def.inverse === 'self',
|
|
13
|
+
transitive: def.transitive,
|
|
14
|
+
inverse: def.inverse,
|
|
15
|
+
strength: def.strength,
|
|
16
|
+
polarity: def.polarity,
|
|
17
|
+
cardinality: def.cardinality,
|
|
18
|
+
})),
|
|
19
|
+
}));
|
|
20
|
+
}
|
|
3
21
|
export function registerGetRelationTypes(server) {
|
|
4
22
|
server.registerTool('get_relation_types', {
|
|
5
23
|
description: 'Returns all 52 semantic relation types supported by Nesso, grouped by 8 categories. ' +
|
|
6
24
|
'Each type carries type properties (transitive, inverse, strength, polarity, cardinality) ' +
|
|
7
|
-
'in addition to its
|
|
25
|
+
'in addition to its glyph. ' +
|
|
8
26
|
'Use this when you need valid relation type names for graph JSON or explanations for the user.',
|
|
9
27
|
inputSchema: z.object({}),
|
|
10
28
|
}, async () => {
|
|
11
|
-
const result =
|
|
12
|
-
category: cat,
|
|
13
|
-
types: Object.entries(RELATION_TYPES)
|
|
14
|
-
.filter(([, def]) => def.cat === cat)
|
|
15
|
-
.map(([name, def]) => ({
|
|
16
|
-
type: name,
|
|
17
|
-
label: def.label,
|
|
18
|
-
line: def.line,
|
|
19
|
-
symmetric: def.inverse === 'self',
|
|
20
|
-
transitive: def.transitive,
|
|
21
|
-
inverse: def.inverse,
|
|
22
|
-
strength: def.strength,
|
|
23
|
-
polarity: def.polarity,
|
|
24
|
-
cardinality: def.cardinality,
|
|
25
|
-
})),
|
|
26
|
-
}));
|
|
29
|
+
const result = getRelationTypesPayload();
|
|
27
30
|
return {
|
|
28
31
|
content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
|
|
29
32
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nesso-how/mcp",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.41",
|
|
4
4
|
"description": "MCP server exposing Nesso knowledge graph tools to LLM clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"dagre": "^0.8.5",
|
|
24
24
|
"zod": "^4.4.3",
|
|
25
25
|
"@modelcontextprotocol/server": "^2.0.0-alpha.2",
|
|
26
|
-
"@nesso-how/vocab-learning": "0.1.0-alpha.
|
|
26
|
+
"@nesso-how/vocab-learning": "0.1.0-alpha.41"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@types/dagre": "^0.7.53",
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|
|
@@ -1,154 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: MIT
|
|
2
|
-
import { describe, expect, it } from 'vitest';
|
|
3
|
-
import { serialize } from '@nesso-how/vocab-learning';
|
|
4
|
-
import { buildGraphDocument, buildGraphJson, newElementId, validateGraphJson, } from './graph-tools.js';
|
|
5
|
-
const validDoc = {
|
|
6
|
-
vocabulary: { id: '@nesso-how/vocab-learning', version: '0.1.0' },
|
|
7
|
-
name: 'Demo',
|
|
8
|
-
concepts: [
|
|
9
|
-
{ id: 'n1', label: 'Cause', x: 0, y: 0 },
|
|
10
|
-
{ id: 'n2', label: 'Effect', x: 250, y: 0 },
|
|
11
|
-
],
|
|
12
|
-
relations: [{ id: 'e1', source: 'n1', target: 'n2', type: 'causes' }],
|
|
13
|
-
};
|
|
14
|
-
describe('validateGraphJson', () => {
|
|
15
|
-
it('accepts a valid graph document', () => {
|
|
16
|
-
const result = validateGraphJson(serialize(validDoc));
|
|
17
|
-
expect(result.valid).toBe(true);
|
|
18
|
-
expect(result.errors).toEqual([]);
|
|
19
|
-
});
|
|
20
|
-
it('rejects invalid JSON', () => {
|
|
21
|
-
const result = validateGraphJson('{not json');
|
|
22
|
-
expect(result.valid).toBe(false);
|
|
23
|
-
expect(result.errors[0]?.message).toMatch(/Invalid JSON/);
|
|
24
|
-
});
|
|
25
|
-
it('rejects runtime nodes/edges shape', () => {
|
|
26
|
-
const result = validateGraphJson(JSON.stringify({
|
|
27
|
-
nodes: [{ id: 'n1' }],
|
|
28
|
-
edges: [{ id: 'e1', source: 'n1', target: 'n2' }],
|
|
29
|
-
}));
|
|
30
|
-
expect(result.valid).toBe(false);
|
|
31
|
-
expect(result.errors[0]?.message).toMatch(/concepts\[\] and relations\[\]/);
|
|
32
|
-
});
|
|
33
|
-
it('rejects unknown relation types', () => {
|
|
34
|
-
const result = validateGraphJson(JSON.stringify({
|
|
35
|
-
name: 'X',
|
|
36
|
-
concepts: [{ id: 'n1', label: 'A', x: 0, y: 0 }],
|
|
37
|
-
relations: [{ id: 'e1', source: 'n1', target: 'n1', type: 'not-real' }],
|
|
38
|
-
}));
|
|
39
|
-
expect(result.valid).toBe(false);
|
|
40
|
-
expect(result.errors[0]?.message).toMatch(/unknown relation type/);
|
|
41
|
-
});
|
|
42
|
-
it('rejects duplicate concept ids', () => {
|
|
43
|
-
const result = validateGraphJson(JSON.stringify({
|
|
44
|
-
name: 'X',
|
|
45
|
-
concepts: [
|
|
46
|
-
{ id: 'n1', label: 'A', x: 0, y: 0 },
|
|
47
|
-
{ id: 'n1', label: 'B', x: 100, y: 0 },
|
|
48
|
-
],
|
|
49
|
-
relations: [],
|
|
50
|
-
}));
|
|
51
|
-
expect(result.valid).toBe(false);
|
|
52
|
-
expect(result.errors.some((e) => e.message.includes('Duplicate concept id'))).toBe(true);
|
|
53
|
-
});
|
|
54
|
-
it('rejects dangling relation endpoints', () => {
|
|
55
|
-
const result = validateGraphJson(JSON.stringify({
|
|
56
|
-
name: 'X',
|
|
57
|
-
concepts: [{ id: 'n1', label: 'A', x: 0, y: 0 }],
|
|
58
|
-
relations: [{ id: 'e1', source: 'n1', target: 'missing', type: 'causes' }],
|
|
59
|
-
}));
|
|
60
|
-
expect(result.valid).toBe(false);
|
|
61
|
-
expect(result.errors.some((e) => e.path.includes('target'))).toBe(true);
|
|
62
|
-
});
|
|
63
|
-
it('warns when relation type is omitted', () => {
|
|
64
|
-
const result = validateGraphJson(JSON.stringify({
|
|
65
|
-
name: 'X',
|
|
66
|
-
concepts: [
|
|
67
|
-
{ id: 'n1', label: 'A', x: 0, y: 0 },
|
|
68
|
-
{ id: 'n2', label: 'B', x: 100, y: 0 },
|
|
69
|
-
],
|
|
70
|
-
relations: [{ id: 'e1', source: 'n1', target: 'n2' }],
|
|
71
|
-
}));
|
|
72
|
-
expect(result.valid).toBe(true);
|
|
73
|
-
expect(result.warnings.some((w) => w.path.includes('type'))).toBe(true);
|
|
74
|
-
});
|
|
75
|
-
it('warns when vocabulary is missing', () => {
|
|
76
|
-
const result = validateGraphJson(JSON.stringify({
|
|
77
|
-
name: 'X',
|
|
78
|
-
concepts: [{ id: 'n1', label: 'A', x: 0, y: 0 }],
|
|
79
|
-
relations: [],
|
|
80
|
-
}));
|
|
81
|
-
expect(result.valid).toBe(true);
|
|
82
|
-
expect(result.warnings.some((w) => w.path === 'vocabulary')).toBe(true);
|
|
83
|
-
});
|
|
84
|
-
});
|
|
85
|
-
describe('buildGraphDocument', () => {
|
|
86
|
-
it('builds a document that passes validation', () => {
|
|
87
|
-
const json = buildGraphJson({
|
|
88
|
-
name: 'Built',
|
|
89
|
-
concepts: ['Cause', 'Effect'],
|
|
90
|
-
relations: [{ from: 'Cause', to: 'Effect', relation: 'causes' }],
|
|
91
|
-
});
|
|
92
|
-
const result = validateGraphJson(json);
|
|
93
|
-
expect(result.valid).toBe(true);
|
|
94
|
-
});
|
|
95
|
-
it('resolves from/to by concept id', () => {
|
|
96
|
-
const doc = buildGraphDocument({
|
|
97
|
-
name: 'Refs',
|
|
98
|
-
concepts: [{ id: 'n_alpha', text: 'Alpha' }, 'Beta'],
|
|
99
|
-
relations: [{ from: 'n_alpha', to: 'Beta', relation: 'enables' }],
|
|
100
|
-
});
|
|
101
|
-
expect(doc.relations[0]?.source).toBe('n_alpha');
|
|
102
|
-
expect(doc.relations[0]?.type).toBe('enables');
|
|
103
|
-
});
|
|
104
|
-
it('assigns finite layout coordinates', () => {
|
|
105
|
-
const doc = buildGraphDocument({
|
|
106
|
-
name: 'Layout',
|
|
107
|
-
concepts: ['A', 'B', 'C', 'D'],
|
|
108
|
-
relations: [
|
|
109
|
-
{ from: 'A', to: 'B', relation: 'causes' },
|
|
110
|
-
{ from: 'B', to: 'C', relation: 'causes' },
|
|
111
|
-
{ from: 'C', to: 'D', relation: 'causes' },
|
|
112
|
-
],
|
|
113
|
-
});
|
|
114
|
-
for (const concept of doc.concepts) {
|
|
115
|
-
expect(Number.isFinite(concept.x)).toBe(true);
|
|
116
|
-
expect(Number.isFinite(concept.y)).toBe(true);
|
|
117
|
-
}
|
|
118
|
-
const xs = doc.concepts.map((c) => c.x);
|
|
119
|
-
expect(new Set(xs).size).toBeGreaterThan(1);
|
|
120
|
-
});
|
|
121
|
-
it('includes vocabulary metadata', () => {
|
|
122
|
-
const doc = buildGraphDocument({
|
|
123
|
-
name: 'Meta',
|
|
124
|
-
concepts: ['Only'],
|
|
125
|
-
relations: [],
|
|
126
|
-
});
|
|
127
|
-
expect(doc.vocabulary).toEqual({ id: '@nesso-how/vocab-learning', version: '0.1.0' });
|
|
128
|
-
});
|
|
129
|
-
it('rejects ambiguous label references', () => {
|
|
130
|
-
expect(() => buildGraphDocument({
|
|
131
|
-
name: 'Ambiguous',
|
|
132
|
-
concepts: ['Same', 'Same'],
|
|
133
|
-
relations: [{ from: 'Same', to: 'Same', relation: 'causes' }],
|
|
134
|
-
})).toThrow(/Ambiguous concept reference/);
|
|
135
|
-
});
|
|
136
|
-
it('rejects unknown references', () => {
|
|
137
|
-
expect(() => buildGraphDocument({
|
|
138
|
-
name: 'Missing',
|
|
139
|
-
concepts: ['A'],
|
|
140
|
-
relations: [{ from: 'A', to: 'Z', relation: 'causes' }],
|
|
141
|
-
})).toThrow(/Unknown concept reference/);
|
|
142
|
-
});
|
|
143
|
-
});
|
|
144
|
-
describe('newElementId', () => {
|
|
145
|
-
it('generates unique ids with the expected prefix', () => {
|
|
146
|
-
const used = new Set();
|
|
147
|
-
const id = newElementId('n', used);
|
|
148
|
-
expect(id.startsWith('n')).toBe(true);
|
|
149
|
-
expect(id.length).toBe(6);
|
|
150
|
-
used.add(id);
|
|
151
|
-
const next = newElementId('n', used);
|
|
152
|
-
expect(next).not.toBe(id);
|
|
153
|
-
});
|
|
154
|
-
});
|