{"_id":"@agenttool/hf-scout","name":"@agenttool/hf-scout","dist-tags":{"next":"0.2.0-dev.0","latest":"0.2.0-dev.0"},"versions":{"0.2.0-dev.0":{"name":"@agenttool/hf-scout","version":"0.2.0-dev.0","description":"Read-only Hugging Face metadata, exact-revision provenance, and release reconciliation for AgentTool and KINGDOM","license":"Apache-2.0","type":"module","sideEffects":false,"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./facilities":{"types":"./dist/facilities.d.ts","import":"./dist/facilities.js"},"./report.schema.json":{"default":"./schema/agenttool-hf-scout-report-v0.2.schema.json"},"./report-v0.2.schema.json":{"default":"./schema/agenttool-hf-scout-report-v0.2.schema.json"},"./report-v0.1.schema.json":{"default":"./schema/agenttool-hf-scout-report-v0.1.schema.json"},"./search.schema.json":{"default":"./schema/agenttool-hf-scout-search-v0.2.schema.json"},"./search-v0.2.schema.json":{"default":"./schema/agenttool-hf-scout-search-v0.2.schema.json"},"./search-v0.1.schema.json":{"default":"./schema/agenttool-hf-scout-search-v0.1.schema.json"},"./sidecar.schema.json":{"default":"./schema/kingdom-hf-sidecar-v0.2.schema.json"},"./sidecar-v0.2.schema.json":{"default":"./schema/kingdom-hf-sidecar-v0.2.schema.json"},"./sidecar-v0.1.schema.json":{"default":"./schema/kingdom-hf-sidecar-v0.1.schema.json"},"./reconciliation.schema.json":{"default":"./schema/agenttool-hf-release-reconciliation-v0.2.schema.json"},"./release-reconciliation-v0.2.schema.json":{"default":"./schema/agenttool-hf-release-reconciliation-v0.2.schema.json"},"./research-catalog.schema.json":{"default":"./schema/agenttool-hf-research-catalog-v0.1.schema.json"},"./research-binding.schema.json":{"default":"./schema/agenttool-hf-research-binding-v0.1.schema.json"},"./kingdom.extension.json":{"default":"./kingdom.extension.json"}},"bin":{"agenttool-hf-scout":"dist/cli.js","kingdom-hf":"dist/kingdom-hf.js"},"engines":{"node":">=20.19.0","bun":">=1.3.5"},"scripts":{"clean":"node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","build":"bun run clean && tsc","typecheck":"tsc --noEmit","test":"bun test tests","smoke:runtimes":"node --input-type=module --eval \"const m = await import('./dist/index.js'); if (typeof m.inspectHfRepository !== 'function') process.exit(1)\" && bun --eval \"const m = await import('./dist/index.js'); if (typeof m.inspectHfRepository !== 'function') process.exit(1)\" && node dist/cli.js help >/dev/null && bun dist/cli.js help >/dev/null && node dist/kingdom-hf.js help >/dev/null && bun dist/kingdom-hf.js help >/dev/null","check:package":"node scripts/check-package-inventory.mjs","ci":"bun run typecheck && bun run test && bun run build && bun run smoke:runtimes && bun run check:package","prepack":"bun run ci"},"devDependencies":{"@types/bun":"1.3.14","@types/node":"20.19.43","ajv":"8.17.1","ajv-formats":"3.0.1","typescript":"5.9.3"},"keywords":["agents","huggingface","kingdom","metadata","provenance","read-only"],"repository":{"type":"git","url":"git+https://github.com/cambridgetcg/agenttool.git","directory":"packages/hf-scout"},"homepage":"https://github.com/cambridgetcg/agenttool/tree/main/packages/hf-scout","publishConfig":{"access":"public","tag":"next"},"_id":"@agenttool/hf-scout@0.2.0-dev.0","bugs":{"url":"https://github.com/cambridgetcg/agenttool/issues"},"_integrity":"sha512-qbiIMuCqNyyC/M0kvOqGsY4T/jCvL79vbfPBAQCHhWkLFFCrh2ir3E7OpyMCrLh0JFKcm41xJ1hmJuamuCRNYA==","_resolved":"/home/runner/work/_temp/agenttool-npm-release/agenttool-hf-scout-0.2.0-dev.0.tgz","_from":"file:/home/runner/work/_temp/agenttool-npm-release/agenttool-hf-scout-0.2.0-dev.0.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-qbiIMuCqNyyC/M0kvOqGsY4T/jCvL79vbfPBAQCHhWkLFFCrh2ir3E7OpyMCrLh0JFKcm41xJ1hmJuamuCRNYA==","shasum":"8fdd75905dbcd4860b6ebf6ec5400da5b1044091","tarball":"https://registry.npmjs.org/@agenttool/hf-scout/-/hf-scout-0.2.0-dev.0.tgz","fileCount":83,"unpackedSize":427158,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agenttool%2fhf-scout@0.2.0-dev.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBsDfBwx5KWaWK2eHa/Zx3YDuktm/ksNB6+C/z2f4lLYAiBG5KhMx54fxim7hW0ugKELiFpms+ri1fzAr1Opu8JeMA=="}]},"_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-scout_0.2.0-dev.0_1787598852928_0.7812481623768843"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-24T19:14:12.689Z","0.2.0-dev.0":"2026-08-24T19:14:13.118Z","modified":"2026-08-24T19:14:13.553Z"},"maintainers":[{"name":"agenttool","email":"contact@cambridgetcg.com"}],"description":"Read-only Hugging Face metadata, exact-revision provenance, and release reconciliation for AgentTool and KINGDOM","homepage":"https://github.com/cambridgetcg/agenttool/tree/main/packages/hf-scout","keywords":["agents","huggingface","kingdom","metadata","provenance","read-only"],"repository":{"type":"git","url":"git+https://github.com/cambridgetcg/agenttool.git","directory":"packages/hf-scout"},"bugs":{"url":"https://github.com/cambridgetcg/agenttool/issues"},"license":"Apache-2.0","readme":"# @agenttool/hf-scout\n\nPublic developer preview for projecting bounded Hugging Face repository\nmetadata into KINGDOM and Agent Data shapes, and for reconciling a named\nrelease commit with a separately observed current Hub head. It is deliberately\na scout, not an inference provider, credential bridge, downloader, or hosted\nservice.\n\n## What it does\n\n- Reads one explicitly selected public model, dataset, or Space through fixed\n  unauthenticated Hugging Face Hub API endpoints, either at the mutable current\n  head or at an exact requested full commit SHA.\n- Accepts a caller-owned `HubReader` so an MCP host or\n  `@huggingface/hub` adapter can supply metadata without coupling OAuth to this\n  package.\n- Separates requested revision, resolved revision, mutable current-head\n  observations, publisher assertions, provider content commitments, caller\n  declarations, and local derivations.\n- Emits a structurally closed inspection report, a compact derived KINGDOM\n  reference sidecar, or a structural `@agenttool/data` text-collector request.\n  Runtime projectors enforce semantic invariants that portable JSON Schema\n  cannot express, including sorted unique paths and logical identity limits.\n- Projects an explicitly supplied\n  `love.huggingface-model-lock/v1` document into compact status metadata.\n- Reconciles one exact release-revision observation against a second,\n  independent current-head observation, with explicit provider-versus-caller\n  transport provenance and optional caller-declared source and caller-reported\n  local manifest evidence.\n- Exposes a closed, revision-pinned catalog of phase-specific research leads\n  and can bind one lead to the exact canonical bytes of a Scout report.\n\n## What it does not do\n\nIt does not read ambient HF credentials, arbitrary URLs, private repositories,\nor raw cards. It does not download files, execute model or Space code, invoke\ninference, Jobs, Sandboxes, or MCP tools, write to the Hub, upload traces,\nmodify KINGDOM-OS, publish npm packages, or verify that a declared license is\ncorrect or compatible.\n\nEach built-in read makes one bounded `GET`, follows no redirects, requests\ncredential omission, and retries zero times at the Scout layer. Exact reads use\n`/revision/{percent-encoded-full-sha}?blobs=true`; mutable reads also retain\n`?blobs=true`. Reconciliation deliberately performs two reads: exact release,\nthen current head. The reader captures the host fetch function when the module\nloads so a later global replacement is\nnot silently adopted. These are requested wrapper effects, not proof that the\nhost runtime itself is uncompromised. A structural `HubReader` cannot claim\nthat built-in identity. An injected reader—or a `PublicHubReader` given a\ncustom `fetch`—is caller-owned; the report names that boundary and does not\nmake claims about its credentials, retries, or body policy. The wrapper races\nits deadline even when a custom fetch ignores `AbortSignal`.\n\n## Local use\n\n```bash\nbun install --frozen-lockfile\nbun run ci\n\nbun src/cli.ts facilities\nbun src/cli.ts research-leads --phase pretraining_data_selection\nbun src/cli.ts search model mlx-community --limit 3\nbun src/cli.ts inspect model mlx-community/Llama-3.2-3B-Instruct-4bit --json\nbun src/cli.ts inspect dataset Yu-and-Ai/agenttool-training-garden \\\n  --revision 208eba3addddfaf8bbc8a2ba3b31926db69d4131 --agent-data\nbun src/cli.ts reconcile dataset Yu-and-Ai/agenttool-training-garden \\\n  208eba3addddfaf8bbc8a2ba3b31926db69d4131 --json\nbun src/cli.ts lock-status /explicit/path/to/model-lock.json\n```\n\nThe pinned Training Garden example was confirmed on 2026-08-24; current head\ncan move. For another repository, use an actual commit belonging to that\nrepository. A revision 404 means that the revision was not found or was not\nassociated with that repository; Scout cannot distinguish those cases.\n\n`--sidecar` emits `kingdom-hf-sidecar/v0.2`; it does not register that sidecar\nwith KINGDOM. It stores a digest-bound artifact reference rather than copying\nthe complete snapshot, and carries the public-versus-caller-owned observation\nboundary. Its effect booleans describe only the sidecar projector.\n`--agent-data` requires an exact requested-and-resolved commit match and emits\na request for the existing `text` collector. A full SHA merely returned by a\ncurrent-head read is not sufficient. Observation time stays outside snapshot\nbytes. The Agent Data external identity and version bind both the revision and\nexact snapshot SHA-256, so repository settings or bounded inventory changes at\none revision cannot collide.\n\n`reconcile` records the release revision and current head independently. Its\noptional `--source-*` values are caller declarations. Its `--local-*` values\nare caller-reported local verification and must be supplied together; Scout\ndoes not read or verify local repository bytes. When the exact file inventory\nis complete, the observed manifest digest is SHA-256 over Scout's canonical\nJSON encoding of the sorted file-commitment array. Comparisons are useful\nevidence, but do not establish license truth, consent, training authority,\nsafety, or compatibility.\n\nHub repository metadata exposes Git `blobId` commitments and, for LFS files,\nseparate `lfs.sha256` payload commitments. Scout keeps those algorithms\nseparate. It leaves Xet hashes null unless they appear in the bounded response;\nit does not issue a second tree walk to infer them.\n\nDataset Viewer is not used by the v0.2 runtime. Its revision-like query is not\nan immutable selector, and `X-Revision` represents a possibly stale cached\nprocessing revision rather than a universal current Hub head.\n\n`lock-status` validates and digests the lock metadata only. It accepts the\nLove creator's nullable `last_modified`, `task`, and `library` fields,\nstring-or-list `base_model`, and optional Git blob commitments. The Love\nPython tool remains authoritative for creating/reproducing the lock and\nverifying a downloaded snapshot. This package never claims\n`snapshot_verified: true`.\n\n## Phase-aware research treasures\n\n`research-leads` is an inert curated overlay, not a downloader. Its 15 pinned\nrecords cover pretraining data-selection experiments, quality filtering and\ndecontamination, human disagreement and preference rationales, earliest-step\nreasoning errors, judge/rhetoric bias, simulated tool traces, tool-failure\nrecovery, multilingual evaluation, gated safety labels, agent SFT/RL task\nbundles, and sparse-autoencoder sweeps. The DataDecide suite is deliberately\nsplit into three records because its evaluation results and data recipes\ndeclare ODC-By while its perplexity-results repository declares no license.\nDespite its name, the pinned `DataDecide-data-recipes` tree includes very\nlarge tokenized binary shards; Scout therefore catalogs only their metadata\nand requires separate approval for binary or bulk retrieval.\n\nThe intended ecosystem routes stay deliberately narrow:\n\n- DataDecide evaluation and perplexity trajectories become Yutabase\n  experiment/provenance graphs; the token arrays remain out of process.\n- HelpSteer2 and OffsetBias become bounded RhetorLint disagreement and\n  evaluator-bias probes, never truth or intent labels.\n- ToolACE, AgentTrove, and tool-failure recovery become inert AgentTool parser\n  and recovery fixtures. AgentTrove contains text traces and environment/tool\n  transcripts; only the separate Agent RL 5K record declares binary tasks.\n- ProcessBench and Global-MMLU remain sealed evaluation material, excluded\n  from training and retrieval indexes.\n- Gemma Scope stays a metadata matrix unless a separately reviewed single-SAE\n  pilot is approved; its base-model terms and publisher-noted quality issues\n  remain explicit boundaries.\n\nEvery record separates publisher assertions from researcher inference, names\nbounded and forbidden ecosystem uses, and derives its Hub/paper URLs from\nexact repository identity, revision, and paper IDs. `bindHfResearchLead`\nrequires the byte-equivalent built-in curated definition, an immutable\nmatching Scout report, exact license/gate/private declarations, and the\nScout's non-download/non-execution boundaries. Reusing a known key with\nrewritten research fields is rejected. Its output binds the canonical lead\ndefinition and report snapshot with separate SHA-256 digests. It records legal\nclearance and gate acceptance as `not_assessed`.\n\nThe current catalog is metadata-only. It does not read rows, download files,\naccept gated terms, extract binary task bundles, execute embedded calls, or\nmake preference, rhetoric, safety, or interpretability labels authoritative.\n\n### Companion training atlas\n\nAgentTool's `@agenttool/dark-continent-karma` package owns a separate\n`kingdom.hf-training-treasure/0.1` atlas. The atlas is the proposal-only,\npublishable research map; Scout is the transport/provenance boundary that can\nobserve a repository and bind the 15 exact definitions curated here. Their\noverlap is intentional, but neither silently imports the other. An atlas\nconsumer must validate that package's schema and hash manifest separately;\nScout does not turn an external atlas row into one of its canonical leads.\n\n## npm / HF crossover\n\nThe package demonstrates a small npm boundary:\n\n- explicit ESM `exports` for code, facilities,\n  v0.2 inspect/search/sidecar/reconciliation schemas, explicit historical v0.1\n  aliases, research schemas, and a developer-preview local extension\n  manifest;\n- two CLI bins, `agenttool-hf-scout` and `kingdom-hf`;\n- zero runtime dependencies and a strict package file allow-list;\n- an injected `HubReader` seam for an optional `@huggingface/hub` adapter;\n- no `@huggingface/inference`, MCP client, or agent loop in the default graph.\n\nThe facilities catalog records the broader HF map and official source links as\nobserved on 2026-07-30. It intentionally contains no volatile price or quota\nentitlement claim.\n\n## Authority and trust\n\nHub cards, tags, gating flags, and license fields are publisher assertions.\nRepository SHAs and file hashes are useful content commitments; a 40-hex value\nalone does not prove that a commit exists or belongs to the named repository.\nPublic-reader observations and caller-owned reader assertions therefore remain\ndistinct in durable artifacts. Neither proves safety, behaviour, consent,\nauthorship, or license truth. Search hits are leads until a separate repository\nread succeeds. Boundary codes use a closed vocabulary and describe only what\nthis Scout did; they do not claim that a caller-owned reader avoided downloads,\nexecution, compute, or writes.\n\nThis package is Apache-2.0 licensed and configured for a public prerelease on\nthe npm `next` tag. The descriptor is not a KINGDOM host registration, and no\nhosted route is installed. Publication, Hub upload, compute, and deployment\nremain separate operator decisions.\n","readmeFilename":"README.md","_rev":"1-d25f60a877cde2d2e9de01258a790eb4"}