{"_id":"@derive-ltd/uht-substrate","_rev":"4-e07ede43d69d5ee59bcf74be54538dda","name":"@derive-ltd/uht-substrate","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@derive-ltd/uht-substrate","version":"1.0.0","keywords":["uht","taxonomy","semantic","hex","cli","classification","mcp","knowledge-graph","ontology"],"author":{"name":"DERIVE LTD"},"license":"MIT","_id":"@derive-ltd/uht-substrate@1.0.0","maintainers":[{"name":"hollando78","email":"steven.holland@outlook.com"}],"bin":{"uht-substrate":"dist/index.js"},"dist":{"shasum":"24565e91b7f42234587d70c6004bd3a7680a153d","tarball":"https://registry.npmjs.org/@derive-ltd/uht-substrate/-/uht-substrate-1.0.0.tgz","fileCount":44,"integrity":"sha512-V8znyyiWmlBZ6M3C3DeiSDt9OueIBNCgAZbUaWM3sWVef83s0y3FYELvOVhXVhi0dxJPH4f8fi6fkuA54TVVAg==","signatures":[{"sig":"MEQCIEXCKutzgQLMxJ56hSyoA+Yox4P3OKEvT1ToAEKm7FyvAiBGmi6tMcAERyFosIpoUfyaf7/7DydOgAVZcKdzMsM45w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120375},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"scripts":{"dev":"tsc --watch","build":"tsc"},"_npmUser":{"name":"hollando78","email":"steven.holland@outlook.com"},"_npmVersion":"10.8.2","description":"CLI for the Universal Hex Taxonomy (UHT) Substrate — classify entities into 32-bit hex codes, compare semantic similarity, manage a knowledge graph, and connect via MCP (a DERIVE LTD product).","directories":{},"_nodeVersion":"20.20.0","dependencies":{"commander":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/uht-substrate_1.0.0_1776258252137_0.18793526266056282","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@derive-ltd/uht-substrate","version":"1.0.1","keywords":["uht","taxonomy","semantic","hex","cli","classification","mcp","knowledge-graph","ontology"],"license":"MIT","_id":"@derive-ltd/uht-substrate@1.0.1","maintainers":[{"name":"hollando78","email":"steven.holland@outlook.com"}],"bin":{"uht-substrate":"dist/index.js"},"dist":{"shasum":"2172e6d5e4a459f048b590afd481a8d02b1c0b83","tarball":"https://registry.npmjs.org/@derive-ltd/uht-substrate/-/uht-substrate-1.0.1.tgz","fileCount":44,"integrity":"sha512-dZJSM5M1j0Sji7vtqUm2LY+fqJG8vKlH5F5hCP+esvaUYlMGdkMAo1SQXLnP0jHMDc/TqD5N5zZ9ZiCD3Nehfg==","signatures":[{"sig":"MEQCIERwuTgt0nTXYww5mujScCkzruQxNnm4MWSpX7FPuZsvAiBPaKW8/x6illi74LK19thHsKfPaq7hp97ncOzVLQ5gmw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120684},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"759b6fa6a3e61dba9fa7ad6ae67d052ae775a690","scripts":{"dev":"tsc --watch","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"hollando78","email":"steven.holland@outlook.com"},"_npmVersion":"10.9.4","description":"CLI for the Universal Hex Taxonomy (UHT) Substrate — classify entities into 32-bit hex codes, compare semantic similarity, manage a knowledge graph, and connect via MCP","directories":{},"_nodeVersion":"22.22.1","dependencies":{"commander":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/uht-substrate_1.0.1_1777302259518_0.44313358804771674","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@derive-ltd/uht-substrate","version":"1.0.2","keywords":["uht","taxonomy","semantic","hex","cli","classification","mcp","knowledge-graph","ontology"],"license":"MIT","_id":"@derive-ltd/uht-substrate@1.0.2","maintainers":[{"name":"hollando78","email":"steven.holland@outlook.com"}],"bin":{"uht-substrate":"dist/index.js"},"dist":{"shasum":"18712e4de47003474e27d12e305e3cb31eb380a6","tarball":"https://registry.npmjs.org/@derive-ltd/uht-substrate/-/uht-substrate-1.0.2.tgz","fileCount":45,"integrity":"sha512-Dsv7jMlwt0sTsnRvHxjcmy07Xq+iITy28oBSM6tk8UfHfSDBxHjkKWAbMzYwXN08WJYZUI/yTGRAbQixTAOOYg==","signatures":[{"sig":"MEUCICxaHSqoDDtkvrJL7fRA1Fh3O6IgnAHVXVpEEMM69e72AiEAzM6N0yOHdCEl5s5oq33IKPR9oKDwSulmxHeLOjXZmAY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120922},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"a90e0d085e2a3ce608c86dd22993f82b9ad585fd","scripts":{"dev":"tsc --watch","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"hollando78","email":"steven.holland@outlook.com"},"_npmVersion":"10.9.4","description":"CLI for the Universal Hex Taxonomy (UHT) Substrate — classify entities into 32-bit hex codes, compare semantic similarity, manage a knowledge graph, and connect via MCP","directories":{},"_nodeVersion":"22.22.1","dependencies":{"commander":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/uht-substrate_1.0.2_1777374970031_0.04101016261562318","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@derive-ltd/uht-substrate","version":"1.0.3","description":"CLI for the Universal Hex Taxonomy (UHT) Substrate — classify entities into 32-bit hex codes, compare semantic similarity, manage a knowledge graph, and connect via MCP","bin":{"uht-substrate":"dist/index.js"},"main":"./dist/index.js","type":"module","scripts":{"build":"tsc","dev":"tsc --watch","prepublishOnly":"npm run build"},"engines":{"node":">=18.0.0"},"keywords":["uht","taxonomy","semantic","hex","cli","classification","mcp","knowledge-graph","ontology"],"license":"MIT","dependencies":{"commander":"^12.0.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.4.0"},"_id":"@derive-ltd/uht-substrate@1.0.3","gitHead":"575dfc24a5b93568fbef3b5720d7383a6741e797","types":"./dist/index.d.ts","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-6FYyZYp5mkVqDl1w5WokJJxpwvqOF60hMT4cZRGHe/G0BwNCYHwQG+DtLJ1tSM3ZtbehROTGO83hfHTvfPo8bA==","shasum":"49c3114efbb10ff566ddfecc28d36c7b1656a755","tarball":"https://registry.npmjs.org/@derive-ltd/uht-substrate/-/uht-substrate-1.0.3.tgz","fileCount":45,"unpackedSize":121375,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG5AqdX91VoYFd9FodjhJ2bITTZot40KMu9IP1vQqnLhAiEAvLcMWMKWp1zbgF4Zg5usPHs0IPHvnqFnRvZCKQel4aQ="}]},"_npmUser":{"name":"hollando78","email":"steven.holland@outlook.com"},"directories":{},"maintainers":[{"name":"hollando78","email":"steven.holland@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/uht-substrate_1.0.3_1777375811874_0.6086296689019386"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-15T13:04:12.021Z","modified":"2026-04-28T11:30:12.237Z","1.0.0":"2026-04-15T13:04:12.293Z","1.0.1":"2026-04-27T15:04:19.703Z","1.0.2":"2026-04-28T11:16:10.183Z","1.0.3":"2026-04-28T11:30:12.076Z"},"license":"MIT","keywords":["uht","taxonomy","semantic","hex","cli","classification","mcp","knowledge-graph","ontology"],"description":"CLI for the Universal Hex Taxonomy (UHT) Substrate — classify entities into 32-bit hex codes, compare semantic similarity, manage a knowledge graph, and connect via MCP","maintainers":[{"name":"hollando78","email":"steven.holland@outlook.com"}],"readme":"# @derive-ltd/uht-substrate\n\nCLI and MCP client config for the [Universal Hex Taxonomy](https://universalhex.org) Substrate API — classify entities, compare concepts, manage facts, and build knowledge graphs.\n\nOperated by **DERIVE LTD** (Company 17159546, England & Wales)\n\n## Install\n\n```bash\nnpm install -g @derive-ltd/uht-substrate\n```\n\nOr run without installing:\n\n```bash\nnpx @derive-ltd/uht-substrate <command>\n```\n\n## Setup\n\n```bash\nuht-substrate config set token <your-api-token>\n```\n\nGet a token by signing in at [substrate.universalhex.org](https://substrate.universalhex.org) (Google or GitHub login).\n\nThe default API URL is `https://substrate.universalhex.org/api`. To override:\n\n```bash\nuht-substrate config set api-url https://your-server.com/api\n```\n\nOr use environment variables:\n\n```bash\nexport UHT_API_URL=https://substrate.universalhex.org/api\nexport UHT_TOKEN=your-token\n```\n\n## MCP Client Config\n\nThis package includes `mcp.json` for connecting AI agents (Claude Desktop, etc.) to the hosted MCP server. Add to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"uht-substrate\": {\n      \"url\": \"https://substrate.universalhex.org/mcp\",\n      \"transport\": \"streamable-http\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n## Quick Start\n\n```bash\n# Classify an entity — get its 8-char hex code and 32 trait bits\nuht-substrate classify hammer\nuht-substrate classify \"cognitive dissonance\" -c \"a psychology concept\" --format pretty\n\n# Reclassify in place (skip cache, update existing entity)\nuht-substrate classify \"epistemic humility\" \\\n  -c \"the intellectual virtue of recognizing the limits of one's knowledge\" \\\n  --force\n\n# Compare two entities — Jaccard similarity, shared/unique traits\nuht-substrate compare hammer screwdriver --format pretty\n\n# Batch compare — rank candidates by similarity\nuht-substrate batch-compare hammer wrench screwdriver pliers saw\n\n# Semantic search across 16k+ entities\nuht-substrate search \"hand tools\" --limit 10\n\n# Disambiguate a polysemous term\nuht-substrate disambiguate bank\n```\n\n## Commands\n\n### Classification & Reasoning\n\n| Command | Description |\n|---------|-------------|\n| `classify <entity>` | Classify an entity (`-c` context, `-f` force, `-n` namespace, `--display-name`) |\n| `infer <entity>` | Infer properties from classification |\n| `compare <a> <b>` | Compare two entities |\n| `batch-compare <entity> <candidates...>` | Compare against multiple, ranked by Jaccard |\n| `search <query>` | Semantic search across the entity corpus |\n| `disambiguate <term>` | Get word senses for polysemous terms |\n| `semantic-triangle <text>` | Ogden-Richards semantic triangle decomposition |\n| `map-properties <props...>` | Map natural language properties to UHT trait bits |\n\n### Entity Management\n\n| Command | Description |\n|---------|-------------|\n| `entities list` | List entities (`-n` name, `--namespace`, `-l` limit/`all`, `--offset`, `--count-only`) |\n| `entities get` | Get a single entity by `--name` or `--uuid` |\n| `entities update <name>` | Update metadata (`-d` description, `--display-name`) |\n| `entities reclassify <name>` | Re-run classification preserving UUID and facts (`-c`, `-n`) |\n| `entities merge <source> <target>` | Merge duplicate entities, transferring all facts and relationships |\n| `entities history <name>` | View classification history (previous hex codes) |\n| `entities delete <name>` | Delete entity (unbinds referencing facts) |\n| `entities deduplicate` | Find/remove entities that leaked from global into a namespace |\n| `entities find-similar <entity>` | Find similar entities by trait overlap |\n| `entities search-traits` | Search entities by trait pattern (`--<trait>` / `--no-<trait>`) |\n\n#### Trait search example\n\nUse `--<trait-name>` to require a trait, `--no-<trait-name>` to exclude:\n\n```bash\nuht-substrate entities search-traits --synthetic --powered --no-biological\n```\n\n### Fact Management\n\n| Command | Description |\n|---------|-------------|\n| `facts store <subject> <predicate> <object>` | Store a fact (`-n` namespace, `-u` user) |\n| `facts store-bulk -f <path>` | Store multiple facts from JSON (`-n` default namespace) |\n| `facts upsert <subject> <predicate> <object>` | Create or update a fact |\n| `facts query` | Query facts with filters (`-s`, `-o`, `-p`, `-c`, `-n`, `-l` limit/`all`) |\n| `facts update <fact-id>` | Update an existing fact |\n| `facts delete <fact-id>` | Delete a fact |\n| `facts user-context` | Get a user's stored facts |\n| `facts namespace-context <namespace>` | Get all entities and facts under a namespace |\n| `facts reconcile` | Cross-check facts against AIRGen trace links |\n\n```bash\n# Store a typed fact\nuht-substrate facts store \"spark plug\" PART_OF \"engine\" --namespace SE:automotive\n\n# Query facts (returns total count for pagination)\nuht-substrate facts query --subject \"spark plug\" --category compositional\nuht-substrate facts query --namespace SE:automotive --predicate PART_OF --limit all\n\n# Bulk store from JSON with default namespace\necho '[{\"subject\":\"bolt\",\"predicate\":\"PART_OF\",\"object_value\":\"frame\"}]' \\\n  | uht-substrate facts store-bulk -f - --namespace SE:automotive\n```\n\n### Namespace Management\n\n| Command | Description |\n|---------|-------------|\n| `namespaces create <code> <name>` | Create a namespace |\n| `namespaces list` | List namespaces |\n| `namespaces assign <entity> <namespace>` | Assign an entity to a namespace |\n\n```bash\nuht-substrate namespaces create SE:automotive \"Automotive Engineering\"\nuht-substrate namespaces assign \"spark plug\" SE:automotive\nuht-substrate namespaces list --parent SE --descendants\n```\n\n### Reference\n\n| Command | Description |\n|---------|-------------|\n| `info` | System information and overview |\n| `traits` | All 32 trait definitions (with version) |\n| `trait-prompts` | Classifier prompts sent to the LLM (edge cases, examples) |\n| `patterns` | Reasoning patterns for tool orchestration |\n\n### Configuration\n\n| Command | Description |\n|---------|-------------|\n| `config set <key> <value>` | Set a config value (`api-url`, `token`, `format`) |\n| `config show` | Show current configuration |\n\n## Pipeline Integration\n\n### Semantic Impact Analysis\n\nAnalyse the semantic impact of requirement changes from an [Airgen](https://airgen.io) diff. For each changed requirement, the command classifies the text using UHT and detects **semantic drift** — cases where a textual edit shifts the requirement into a different meaning-space.\n\n```bash\n# Generate a diff from airgen\nairgen diff --json > diff.json\n\n# Analyse impact\nuht-substrate impact --airgen-diff diff.json --format pretty\nuht-substrate impact --airgen-diff diff.json --json\n```\n\nThe input file must be the JSON output from `airgen diff --json`, structured as `{ summary, added, removed, modified }` where each requirement has `ref` and `text` fields, and modified entries have `old_text` and `new_text`.\n\n## Global Options\n\n| Option | Description |\n|--------|-------------|\n| `--api-url <url>` | API base URL |\n| `--token <token>` | Bearer token for authentication |\n| `--format <fmt>` | Output format: `json` (default) or `pretty` |\n| `--verbose` | Show request/response details |\n| `--version` | Show version |\n\n## Output Formats\n\n**JSON** (default) — machine-readable, pipe to `jq`:\n\n```bash\nuht-substrate classify hammer | jq '.hex_code'\n```\n\n**Pretty** — colored terminal output:\n\n```bash\nuht-substrate classify hammer --format pretty\n```\n\n## What is UHT?\n\nThe Universal Hex Taxonomy encodes any concept as a 32-bit classification (8-char hex code) across four layers:\n\n- **Physical** (bits 1–8): Material properties, boundaries, energy\n- **Functional** (bits 9–16): Capabilities, interfaces, state\n- **Abstract** (bits 17–24): Symbolic, temporal, rule-governed\n- **Social** (bits 25–32): Cultural, economic, institutional\n\nTwo entities with similar hex codes share similar properties. Jaccard similarity measures meaningful overlap between classifications.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}