{"_id":"@agenttool/hf-kingdom-lab","name":"@agenttool/hf-kingdom-lab","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agenttool/hf-kingdom-lab","version":"0.1.0","type":"module","description":"Bounded Hugging Face training archaeology, provenance, and situated-flow evidence for AgentTool and KINGDOM.","license":"Apache-2.0","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./hub":{"types":"./dist/hub.d.ts","import":"./dist/hub.js"},"./datadecide":{"types":"./dist/datadecide.d.ts","import":"./dist/datadecide.js"},"./dpi-provenance":{"types":"./dist/dpi-provenance.d.ts","import":"./dist/dpi-provenance.js"},"./flow":{"types":"./dist/flow-lenses.d.ts","import":"./dist/flow-lenses.js"},"./treasures":{"types":"./dist/treasures.d.ts","import":"./dist/treasures.js"},"./datadecide-ledger.json":"./data/datadecide-ledger.v1.json","./dpi-provenance-contract.json":"./data/dpi-provenance-contract.v1.json","./flow-lenses.json":"./data/flow-lenses.v1.json","./dataset-treasures.json":"./data/dataset-treasures.v1.json","./package.json":"./package.json"},"bin":{"hfkl":"dist/cli.js","hfkl-flow":"dist/flow-cli.js","hfkl-treasures":"dist/treasure-cli.js"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/cambridgetcg/hf-kingdom-lab.git"},"homepage":"https://cambridgetcg.github.io/hf-kingdom-lab/","bugs":{"url":"https://github.com/cambridgetcg/hf-kingdom-lab/issues"},"keywords":["agents","agenttool","huggingface","kingdom","provenance","training-data","artistic-expression","local-first"],"packageManager":"bun@1.3.5","scripts":{"build":"bun scripts/build-package.ts","check":"bun run typecheck && bun test","ci":"bun run check && bun run build && bun run package:verify && bun run site:build","demo":"bun src/cli.ts demo","demo:sql":"bun src/cli.ts sql-demo","demo:round2":"bun src/cli.ts round2-demo","embedding:prepare":"bun src/cli.ts embedding-prepare","flow":"bun src/flow-cli.ts","package:verify":"bun scripts/verify-package.ts","prepack":"bun run check && bun run build","site:build":"bun scripts/build-site.ts","test":"bun test","treasures":"bun src/treasure-cli.ts","typecheck":"tsc --noEmit"},"dependencies":{"@agenttool/data":"0.3.1","@huggingface/hub":"2.14.4"},"devDependencies":{"@huggingface/transformers":"4.2.0","@types/bun":"1.3.14","typescript":"7.0.2"},"overrides":{"adm-zip":"0.6.0","sharp":"0.35.3"},"engines":{"bun":">=1.3.5"},"_id":"@agenttool/hf-kingdom-lab@0.1.0","_integrity":"sha512-8GbsEbNHNYFuguwGXwWpVnM05uQBBpZQ+Sd3d4YOfyHmpLPeS9eWMFbAmYJWp14ZPd64syJybRDj4GHMQ0qRNA==","_resolved":"/private/tmp/hf-kingdom-lab-v0.1.0-0a85b13/agenttool-hf-kingdom-lab-0.1.0.tgz","_from":"file:/private/tmp/hf-kingdom-lab-v0.1.0-0a85b13/agenttool-hf-kingdom-lab-0.1.0.tgz","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-8GbsEbNHNYFuguwGXwWpVnM05uQBBpZQ+Sd3d4YOfyHmpLPeS9eWMFbAmYJWp14ZPd64syJybRDj4GHMQ0qRNA==","shasum":"044c2837d7c3c3bba9dc6609fb5243f57e3335e2","tarball":"https://registry.npmjs.org/@agenttool/hf-kingdom-lab/-/hf-kingdom-lab-0.1.0.tgz","fileCount":57,"unpackedSize":536466,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAoKKLtGxkCUc7t1yBCCNsOCdoXlv1G7Fsock+9GiAwaAiEAz0AldSVe8fT3QBB1B99lvHhzLomL1kcTxGQccW6VHoQ="}]},"_npmUser":{"name":"agenttool","email":"contact@cambridgetcg.com"},"directories":{},"maintainers":[{"name":"agenttool","email":"contact@cambridgetcg.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hf-kingdom-lab_0.1.0_1785583897634_0.684478450834221"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T11:31:37.406Z","0.1.0":"2026-08-01T11:31:37.859Z","modified":"2026-08-01T11:31:38.101Z"},"maintainers":[{"name":"agenttool","email":"contact@cambridgetcg.com"}],"description":"Bounded Hugging Face training archaeology, provenance, and situated-flow evidence for AgentTool and KINGDOM.","homepage":"https://cambridgetcg.github.io/hf-kingdom-lab/","keywords":["agents","agenttool","huggingface","kingdom","provenance","training-data","artistic-expression","local-first"],"repository":{"type":"git","url":"git+https://github.com/cambridgetcg/hf-kingdom-lab.git"},"bugs":{"url":"https://github.com/cambridgetcg/hf-kingdom-lab/issues"},"license":"Apache-2.0","readme":"# Hugging Face × AgentTool × KINGDOM Lab\n\nA local-first, public-read playground for turning selected Hugging Face\nresources into searchable AgentTool evidence and a KINGDOM-discoverable\nproject.\n\nThe working path is deliberately small:\n\n```text\nnamed public HF resource\n  -> bounded @huggingface/hub observation\n  -> canonical JSON snapshot + explicit boundary\n  -> AgentTool agent-data/v1 CAS + SQLite/FTS\n  -> immutable run receipt\n  -> KINGDOM project card\n\nfixed public Parquet export\n  -> bounded temporary download + SHA-256\n  -> fixed aggregate-only DuckDB query\n  -> closed-schema validation\n  -> AgentTool aggregate record\n\nfixed DTap tree + exact Collection/Paper roots\n  -> capped metadata-only census + provenance graph\n  -> hash-verified local MiniLM CPU/q8 embeddings\n  -> bounded semantic scan + Trackio capability mapping\n  -> separate AgentTool evidence collections\n\npinned training/data archaeology\n  -> DataDecide recipe -> scale -> seed -> checkpoint -> evaluation ledger\n  -> DPI source/licence manifest and fail-closed future-reader contract\n  -> situated artistic/conversation/music flow lenses\n  -> optional exact metadata-only AgentTool receipt\n```\n\nIt does **not** start a service, call AgentTool production, project anything\ninto memory, enumerate private repositories, invoke a Space, submit a Job, use\nInference Providers, or write to Hugging Face.\n\nThe archaeology lane also contains no training token shards, checkpoint\nweights, evaluation-instance archives, DPI text, prompts/responses, images,\naudio, participant profiles, or verbatim/full remote dataset rows. The\nDataDecide ledger intentionally retains two normalized aggregate-result\nwitnesses with exact source coordinates.\n\n## What works\n\nAs of 2026-07-30, the live demos have:\n\n- observed four explicitly named public Hub resources without supplying a\n  token: two datasets, one model, and one Space;\n- stored their normalized snapshots and a separate effects receipt in a local\n  AgentTool `DataNode`;\n- queried those records through the node's local FTS index;\n- downloaded one 1,382,608-byte public Parquet export into a bounded temporary\n  file, verified its Parquet framing and SHA-256, and ran a fixed DuckDB\n  aggregate;\n- stored only five grade-level aggregate rows, not repository identifiers or\n  raw scanner findings.\n- pinned the public DTap tree at revision\n  `836caf2fdd78b888ddd14fb62dc038e932e17898`, counted 10,000 path entries,\n  and stopped at the ten-page limit without reading a trajectory body;\n- observed one exact public MCP Security Collection and two exact Paper Pages\n  as a six-node, three-edge graph while discarding abstracts, author profiles,\n  comments, and linked-repository bodies;\n- downloaded and rehashed four fixed files for\n  `Xenova/all-MiniLM-L6-v2@751bff3…`, then ran 384-dimensional CPU/q8\n  feature extraction locally with the Transformers.js network transport\n  disabled;\n- indexed seven source-bound semantic fragments and mapped the run to\n  Trackio 0.34.0 concepts without importing Trackio, writing native Trackio\n  storage, starting hardware logging, a dashboard, MCP, or Hugging Face sync.\n\nSee [docs/ROUND2.md](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/docs/ROUND2.md) for the exact live result and\n[bounded live evidence](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/artifacts/round2/live-evidence-20260730.json) for the\nrecord IDs, hashes, effects, and limitations. DTap's 10,000-entry result is\nHub-order partial and explicitly not a representative dataset distribution.\nSemantic similarity is a derived English-language signal, not a truth or\nsafety decision.\n\nThe saved SQL evidence snapshot is\n[artifacts/hf/mcpshield-grade-aggregate-20260730-direct-python.json](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/artifacts/hf/mcpshield-grade-aggregate-20260730-direct-python.json).\nScanner grades are evidence to investigate, not established vulnerabilities.\nThe associated MCP security study reports that fewer than half of sampled\nscanner alerts survived manual validation.\n\nThe companion\n[artifacts/hf/public-resource-ingest-20260730.json](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/artifacts/hf/public-resource-ingest-20260730.json)\nis the exact effects receipt and record index for the four-resource Hub run.\n\n## Training decisions, provenance, and situated flow\n\nThe 2026-08-01 deep pass turns three promising research seams into bounded\nlocal artifacts:\n\n- the [DataDecide phase ledger](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/docs/DATADECIDE-LEDGER.md) preserves exact\n  recipe aliases, all 14 scales, five seed identities, branch-qualified\n  checkpoint witnesses, and evaluation joins without mirroring roughly 19 TB\n  of token shards or 123 GB of instance evaluations;\n- the [DPI provenance contract](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/docs/DPI-PROVENANCE.md) pins the three source\n  exports, ten Viewer Parquet shards, nested provenance schema, immutable\n  revisions, count discrepancy, column boundary, and prerequisites for a\n  future aggregate reader. No reader is implemented because the current\n  DuckDB/httpfs boundary cannot yet enforce the claimed network-byte ceiling;\n- the [flow and vibe atlas](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/docs/FLOW-AND-VIBE.md) maps ten writing, visual-art,\n  music, and conversation artifacts across pair, turn, branch, culture/language,\n  observer, region, rubric, perspective, and time-series shapes.\n\nThe flow atlas treats a vibe as a situated observation rather than an essence\nor universal score. It machine-separates human, model, and mixed evidence;\ndescriptive, normative, and control lanes; component licences; identity\nsurfaces; Viewer mismatches; and what each transformation preserves or loses.\nIts exact-allowlist `record` command stores a newly reconstructed narrow copy\nof current public Hub metadata and an effects receipt only.\n\n## Local 20B result\n\nOne public, unauthenticated MLX run of\n[`mlx-community/gpt-oss-20b-MXFP4-Q8`](https://huggingface.co/mlx-community/gpt-oss-20b-MXFP4-Q8)\ncompleted locally on the M4 Max at revision\n`773a7da77e569019bb0fd17a554b263738d669a3`:\n\n- 12,104,215,835 snapshot bytes across ten independently rehashed files;\n- 96 generated tokens at 125.657 tokens/second;\n- 12.246 GB MLX-reported peak memory;\n- 2,343.96 seconds wall time including the first public download;\n- no authenticated Hub request, Inference Provider, ZeroGPU, Job, Space call,\n  upload, daemon, port, or HF credit/quota use.\n\nThe process exited 0, but the host truncated the completed PTY page. Only a\ntrailing English fragment was recoverable. It appears to be planning text, but\nthat is an inference rather than an observed output-channel marker. The\nevidence explicitly does **not** claim a complete Cantonese answer, and the run\nwas not repeated to manufacture a cleaner result.\n\nSee the [run receipt](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/artifacts/local-model/receipt.json),\n[metrics and model file hashes](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/artifacts/local-model/metrics.json), and\n[bounded recovered output](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/artifacts/local-model/selected-output.txt).\n\n## Run it\n\nRequirements: Bun 1.3.5+, `uv`, and network access to the public Hugging Face\nresource being observed.\n\n```bash\nbun install --frozen-lockfile --ignore-scripts\nuv sync --frozen\n\nbun run check\nbun run demo\nbun src/cli.ts query agent --limit 10\nbun run demo:sql\nbun run embedding:prepare\nbun run demo:round2\nbun src/cli.ts semantic-query \\\n  \"tool side effects, policy checks, receipts, and security evidence\"\nbun src/cli.ts doctor\n\nbun run treasures -- list\nbun run flow -- list\nbun run flow -- trace amaai-lab/MERP\n```\n\n`embedding:prepare` is the only model-asset network step. It accepts no model\nor URL argument, refuses the common ambient Hugging Face token variables on a\ncold run, downloads a fixed 23,685,047-byte manifest, and verifies each\nSHA-256 before an atomic local install. A warm prepare rehashes local files and\nperforms no read. Semantic commands then set Transformers.js remote loading\noff and replace its fetch transport with a failing network trap.\n\n`uv sync --frozen` is an explicit setup step: on a fresh checkout it creates\nthe project `.venv` and may contact the configured Python package index to\ninstall the locked DuckDB wheel. `sql-demo` then executes that environment's\nPython directly; it does not run `uv`, sync dependencies, or contact a package\nindex as part of the recorded aggregate operation. An installed npm package\ncan instead use an explicitly provisioned absolute interpreter through\n`HFKL_PYTHON`; that override does not install or trust Python dependencies.\n\nObserve one additional named public repository:\n\n```bash\nbun src/cli.ts ingest dataset AI-Secure/DTap-Bench-Agent-Trajectories\n```\n\nLocal records use the platform user-data directory (`~/Library/Application\nSupport/hf-kingdom-lab` on macOS, `$XDG_DATA_HOME/hf-kingdom-lab` or\n`~/.local/share/hf-kingdom-lab` on Linux). `HFKL_DATA_ROOT` may name a bounded\nabsolute override. State therefore stays outside `node_modules` and survives a\npackage update. The demo's public metadata and source bytes can change over\ntime, so every stored document carries its observation time or source digest.\n\n## Public package and atlas\n\nThe Apache-2.0 npm package ships compiled Bun ESM, explicit subpath exports,\nthree CLIs, the four closed JSON catalogues/contracts, and documentation. It\ndoes not ship the experiment receipts, source tree, test fixtures, remote\ndataset bodies, model weights, or prepared local AgentTool node.\n\nThe npm install also deliberately omits the optional local Transformers\nruntime. As of this release, Transformers 4.2.0 still declares transitive\nranges containing two high-severity advisory families. The source checkout\nkeeps that research lane available behind audited lockfile overrides to\n`adm-zip` 0.6.0 and `sharp` 0.35.3; the published package does not silently\nimpose those root-only overrides on consumers. Its catalogue APIs and the\n`hfkl-flow`/`hfkl-treasures` CLIs do not need the semantic runtime.\n\n```bash\nbun add --exact @agenttool/hf-kingdom-lab@0.1.0\nbunx --package @agenttool/hf-kingdom-lab@0.1.0 hfkl-flow list\nbunx --package @agenttool/hf-kingdom-lab@0.1.0 hfkl-treasures list\n```\n\nThe [public atlas](https://cambridgetcg.github.io/hf-kingdom-lab/) is a static\nrendering of bounded checked-in summaries. GitHub Pages serves no AgentTool\nnode, dataset row, inference endpoint, credential, scheduler, or remote-action\nAPI.\n\n## Honest boundaries\n\n- `@huggingface/hub` is used directly for public model, dataset, and Space\n  metadata. The adapter supplies no access token and rejects a private\n  response, but that is an application boundary rather than a provider-wide\n  anonymity guarantee.\n- The DTap path performs metadata/tree reads only. Its normal cap is 10 pages,\n  10,000 entries, 6 MiB of tree response bodies, 4 MiB of normalized path\n  bytes, and 15 seconds. Cap-stopped counts are retained only with an explicit\n  truncated/non-representative marker.\n- The graph accepts one exact Collection URL and two exact Paper API URLs. A\n  Collection is mutable curation, and paper titles/membership remain untrusted\n  observations. One shared 15-second deadline covers transport and bounded\n  response-body reads.\n- The MiniLM weights are an Apache-2.0 community conversion rather than a\n  security-reviewed publisher build. The semantic lane is English-oriented,\n  capped at 256 wordpieces per text and 64 locally scanned vectors; AgentTool\n  FTS remains the general/Cantonese search path. Collection and query both\n  resolve every named source record and compare its envelope content SHA-256;\n  only one network-trapped embedder may be active in a process.\n- The Trackio document targets the public 0.34.0 run/config/numeric-metric\n  concepts only. It is not a Trackio-validated database, runtime, dashboard,\n  MCP service, or sync receipt.\n- AgentTool `DataNode` supplies local content-addressed storage, SQLite\n  metadata, FTS, and immutable record identities. It does not validate these\n  application schemas, enforce the declared `private` visibility label,\n  verify signatures, decide truth, synchronize peers, or physically erase\n  content.\n- The aggregate path validates an exact closed document schema before\n  collection. Arbitrary URLs, SQL, datasets, and row-level output are not\n  accepted.\n- The DataDecide ledger is checked-in, static evidence. It retains exact alias\n  joins and branch target SHAs, but its bounded checkpoint/evaluation rows are\n  witnesses rather than a materialized copy of all 31,404 revisions or 1.41M\n  result rows.\n- The DPI module is a static contract, not a dataset reader. Hub LFS hashes are\n  publisher/Hub assertions because the 1.23 GB source and 1.89 GB conversion\n  were not downloaded and rehashed. A future range reader must also account\n  honestly for text min/max statistics present in Parquet footers.\n- Flow-lens `list`, `show`, and `trace` are local. `drift` reads one exact public\n  dataset's metadata; `record` refuses identity drift and stores that same\n  metadata only. A future content route still needs the listed licence,\n  privacy, representation, and aggregate gates.\n- The KINGDOM card makes this lab discoverable as a local `nervous`-layer\n  project. It does not register a production runtime or grant authority over\n  AgentTool, KINGDOM, Hugging Face, or any participant.\n- `RIGHTS.md` adopts `xenia.rights/0.1`. Rights, account permissions, and\n  authorization remain distinct.\n\nSee [docs/HF-RESOURCE-MAP.md](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/docs/HF-RESOURCE-MAP.md) for the wider playground\nand [docs/INTEGRATION.md](https://github.com/cambridgetcg/hf-kingdom-lab/blob/main/docs/INTEGRATION.md) for the bridge contract.\n","readmeFilename":"README.md","_rev":"1-1a0028dc297a62d07078183309c2a50d"}