{"_id":"@agentix-e/timesfm-hierarchical","_rev":"6-7937de68da08936fe45151f68a86564d","name":"@agentix-e/timesfm-hierarchical","dist-tags":{"latest":"1.0.0"},"versions":{"0.0.1":{"name":"@agentix-e/timesfm-hierarchical","version":"0.0.1","keywords":["oidc","trusted-publishing","setup"],"_id":"@agentix-e/timesfm-hierarchical@0.0.1","maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"dist":{"shasum":"6d9f745a372bf42394dcd58166748c49a05a5068","tarball":"https://registry.npmjs.org/@agentix-e/timesfm-hierarchical/-/timesfm-hierarchical-0.0.1.tgz","fileCount":2,"integrity":"sha512-F3GK5D/rKdIoJryCT0zwAjbgH+7pfdWS1p8Rr3/tNX4fGCFgyimiCKjb5qFOQArvEHnhnyjyIDaPqc+CC+MGZw==","signatures":[{"sig":"MEUCIBaqJIV+imt0O2ZQSxyxZACGZvs9lzPWXmpRIKxMEg8rAiEAxTsjXwzXq9brHsgdTX2s0El6LjUQazAz98OKAS7dR8o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2087},"_npmUser":{"name":"lambertyan","email":"853901691@qq.com"},"_npmVersion":"11.9.0","description":"OIDC trusted publishing setup package for @agentix-e/timesfm-hierarchical","directories":{},"_nodeVersion":"22.13.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/timesfm-hierarchical_0.0.1_1782656991102_0.18357466855699056","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@agentix-e/timesfm-hierarchical","version":"0.3.2","keywords":["timesfm","hierarchical","reconciliation","time-series","forecasting","mint","bottom-up"],"license":"Apache-2.0","_id":"@agentix-e/timesfm-hierarchical@0.3.2","maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"homepage":"https://github.com/AgentiX-E/timesfm-ts#readme","bugs":{"url":"https://github.com/AgentiX-E/timesfm-ts/issues"},"dist":{"shasum":"4d4a3920cdd1a0b5c05f0d6bee3dd8ffbce69784","tarball":"https://registry.npmjs.org/@agentix-e/timesfm-hierarchical/-/timesfm-hierarchical-0.3.2.tgz","fileCount":27,"integrity":"sha512-FHD7Y3EBUqw7BEpChQnp+X7HVKeJHyoNkqnj+PBpfCuY/Mc/zEKlPI9ysgRXE7yL+5tR3cIdatHRfInRgbwSEw==","signatures":[{"sig":"MEQCIQCh2dg4mbciJY/HArS4R3IkzGacyTe9khNkgcujR0r2yAIfG3UTr/pdxq/1Uoq7kk704qzKzeWZIArhldvt/g74JQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentix-e%2ftimesfm-hierarchical@0.3.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":96628},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"198227698ad8349592f0c25a8dcbcbdc2d29bae6","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"tsc"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ce1ca30a-de87-4792-8a0b-e44da70d6572"}},"repository":{"url":"git+https://github.com/AgentiX-E/timesfm-ts.git","type":"git"},"_npmVersion":"11.13.0","description":"Hierarchical time series reconciliation for TimesFM — bottom-up, OLS, WLS, and MinT strategies","directories":{},"_nodeVersion":"24.17.0","dependencies":{"ml-matrix":"^6.12.0","@agentix-e/timesfm-core":"workspace:*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/timesfm-hierarchical_0.3.2_1782883887243_0.8059640544807234","host":"s3://npm-registry-packages-npm-production"}},"0.3.3":{"name":"@agentix-e/timesfm-hierarchical","version":"0.3.3","keywords":["timesfm","hierarchical","reconciliation","time-series","forecasting","mint","bottom-up"],"license":"Apache-2.0","_id":"@agentix-e/timesfm-hierarchical@0.3.3","maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"homepage":"https://github.com/AgentiX-E/timesfm-ts#readme","bugs":{"url":"https://github.com/AgentiX-E/timesfm-ts/issues"},"dist":{"shasum":"c33afdf43e34676c23bb1cac65db90c103e7339f","tarball":"https://registry.npmjs.org/@agentix-e/timesfm-hierarchical/-/timesfm-hierarchical-0.3.3.tgz","fileCount":27,"integrity":"sha512-dikcmawR2jp2ba4mcuIh6qxDmo2aka/aKMaaSk00KG3kNpAKbQsJpQBXM8mvX8tIyIfrndi63z15xPoR7Kemqg==","signatures":[{"sig":"MEUCIQCeYacfO7ihUHTh77aXfxX5kUCEqjnFqxnNeTeIsNPz8AIgBDEF8BVLoFFIo8MnMw0dvI8I2+s/gI9llwBUOWXOL/o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentix-e%2ftimesfm-hierarchical@0.3.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":96628},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"a9c7382793ba097332eae3fad7755d893c371ad2","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"tsc"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ce1ca30a-de87-4792-8a0b-e44da70d6572"}},"repository":{"url":"git+https://github.com/AgentiX-E/timesfm-ts.git","type":"git"},"_npmVersion":"11.13.0","description":"Hierarchical time series reconciliation for TimesFM — bottom-up, OLS, WLS, and MinT strategies","directories":{},"_nodeVersion":"24.17.0","dependencies":{"ml-matrix":"^6.12.0","@agentix-e/timesfm-core":"workspace:*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/timesfm-hierarchical_0.3.3_1782891781153_0.38595929618381275","host":"s3://npm-registry-packages-npm-production"}},"0.3.4":{"name":"@agentix-e/timesfm-hierarchical","version":"0.3.4","keywords":["timesfm","hierarchical","reconciliation","time-series","forecasting","mint","bottom-up"],"license":"Apache-2.0","_id":"@agentix-e/timesfm-hierarchical@0.3.4","maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"homepage":"https://github.com/AgentiX-E/timesfm-ts#readme","bugs":{"url":"https://github.com/AgentiX-E/timesfm-ts/issues"},"dist":{"shasum":"c2c51dd656cfdfe1db48623004378646e71b20ce","tarball":"https://registry.npmjs.org/@agentix-e/timesfm-hierarchical/-/timesfm-hierarchical-0.3.4.tgz","fileCount":27,"integrity":"sha512-kOJlUd0lhhGTTrLrxPfdsvIKvJbiMTz0/FOKQTpnn3iVo4fT4lq+EIK4v47xPZHUrz+dzpfhRj6hUlJW+3vSmg==","signatures":[{"sig":"MEYCIQDylQ512WvKjt2PUpwWTI3jS26DHc4C/6Jib0f2mK24pgIhAN2NnzqtEbgCWrJf9wcotNbVlcAJfkB0eBkU21ytW8Ab","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentix-e%2ftimesfm-hierarchical@0.3.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":96628},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"5421baf0c98740ea84f41f1b523a607235631919","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"tsc"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ce1ca30a-de87-4792-8a0b-e44da70d6572"}},"repository":{"url":"git+https://github.com/AgentiX-E/timesfm-ts.git","type":"git"},"_npmVersion":"11.16.0","description":"Hierarchical time series reconciliation for TimesFM — bottom-up, OLS, WLS, and MinT strategies","directories":{},"_nodeVersion":"24.18.0","dependencies":{"ml-matrix":"^6.12.0","@agentix-e/timesfm-core":"workspace:*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/timesfm-hierarchical_0.3.4_1782893678528_0.5042838071841835","host":"s3://npm-registry-packages-npm-production"}},"0.3.5":{"name":"@agentix-e/timesfm-hierarchical","version":"0.3.5","keywords":["timesfm","hierarchical","reconciliation","time-series","forecasting","mint","bottom-up"],"license":"Apache-2.0","_id":"@agentix-e/timesfm-hierarchical@0.3.5","maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"homepage":"https://github.com/AgentiX-E/timesfm-ts#readme","bugs":{"url":"https://github.com/AgentiX-E/timesfm-ts/issues"},"dist":{"shasum":"9181e7b1c362b290d3b45f2f46d002aef2fa82ec","tarball":"https://registry.npmjs.org/@agentix-e/timesfm-hierarchical/-/timesfm-hierarchical-0.3.5.tgz","fileCount":27,"integrity":"sha512-whkSMLdLYckmyyyJUU1ui+Rl5u6Gw2ZoqQPvV0m88J8NsEgxMlc3lIGg9nUu3pm8vxchZuhmuSj99a5Fu+buNQ==","signatures":[{"sig":"MEQCIECaUtyJBq0xOr2BOSNJ3uuSFwXc+PryTN2+ZLX6YQVFAiBigcYS79yuWR95oWIA8gMvMSHrYNSeC9B3TQ2+eyKNBA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentix-e%2ftimesfm-hierarchical@0.3.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":96628},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"gitHead":"857b805364ff2c30e3700344b7fff67c8e57f913","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"tsc"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ce1ca30a-de87-4792-8a0b-e44da70d6572"}},"repository":{"url":"git+https://github.com/AgentiX-E/timesfm-ts.git","type":"git"},"_npmVersion":"11.13.0","description":"Hierarchical time series reconciliation for TimesFM — bottom-up, OLS, WLS, and MinT strategies","directories":{},"_nodeVersion":"24.17.0","dependencies":{"ml-matrix":"^6.12.0","@agentix-e/timesfm-core":"workspace:*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/timesfm-hierarchical_0.3.5_1782894018321_0.6872058602618885","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@agentix-e/timesfm-hierarchical","version":"1.0.0","description":"Hierarchical time series reconciliation for TimesFM — bottom-up, OLS, WLS, and MinT strategies","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"build":"tsc","test":"vitest run","prepublishOnly":"rm -rf dist && tsc -b"},"dependencies":{"@agentix-e/timesfm-core":"workspace:*","ml-matrix":"^6.12.0"},"devDependencies":{"typescript":"^5.7.0","vitest":"^3.0.0"},"keywords":["timesfm","hierarchical","reconciliation","time-series","forecasting","mint","bottom-up"],"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/AgentiX-E/timesfm-ts.git"},"publishConfig":{"access":"public"},"engines":{"node":">=22"},"gitHead":"60a0322602dc1555566adb704a281839ab8b5068","_id":"@agentix-e/timesfm-hierarchical@1.0.0","bugs":{"url":"https://github.com/AgentiX-E/timesfm-ts/issues"},"homepage":"https://github.com/AgentiX-E/timesfm-ts#readme","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-6fv/vLuAIoTPpR4WqvY2lnUfWSKxWaAcEs0CTYXQ0O/s+voI5XKmxRM7e0O0X0uinxrylneMSUwJCLLbgRYSDQ==","shasum":"f7782dd30589ebaebd3e707319a5e3a01a605f3d","tarball":"https://registry.npmjs.org/@agentix-e/timesfm-hierarchical/-/timesfm-hierarchical-1.0.0.tgz","fileCount":7,"unpackedSize":36411,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agentix-e%2ftimesfm-hierarchical@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC3+qAsIZyOMbEQ/CGuy/AGk1SvHKVc+o4yiWgyacmhlQIhAIgLdyLbyXrkqwvuqInukHDAoEbqhMVeMG5X6if+8SpF"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ce1ca30a-de87-4792-8a0b-e44da70d6572"}},"directories":{},"maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/timesfm-hierarchical_1.0.0_1783075669060_0.8212861933514362"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-28T14:29:50.903Z","modified":"2026-07-03T10:47:49.453Z","0.0.1":"2026-06-28T14:29:51.292Z","0.3.2":"2026-07-01T05:31:27.371Z","0.3.3":"2026-07-01T07:43:01.299Z","0.3.4":"2026-07-01T08:14:38.660Z","0.3.5":"2026-07-01T08:20:18.456Z","1.0.0":"2026-07-03T10:47:49.192Z"},"bugs":{"url":"https://github.com/AgentiX-E/timesfm-ts/issues"},"license":"Apache-2.0","homepage":"https://github.com/AgentiX-E/timesfm-ts#readme","keywords":["timesfm","hierarchical","reconciliation","time-series","forecasting","mint","bottom-up"],"repository":{"type":"git","url":"git+https://github.com/AgentiX-E/timesfm-ts.git"},"description":"Hierarchical time series reconciliation for TimesFM — bottom-up, OLS, WLS, and MinT strategies","maintainers":[{"name":"lambertyan","email":"853901691@qq.com"}],"readme":"# @agentix-e/timesfm-hierarchical\n\n> Hierarchical time series reconciliation engine — bottom-up, OLS, WLS, and MinT forecast reconciliation.\n\n[![npm](https://img.shields.io/npm/v/@agentix-e/timesfm-hierarchical?color=blue)](https://www.npmjs.com/package/@agentix-e/timesfm-hierarchical)\n[![API Docs](https://img.shields.io/badge/docs-TypeDoc-blue)](https://agentix-e.github.io/timesfm-ts/api/modules/timesfm-hierarchical.html)\n[![Benchmark](https://img.shields.io/badge/benchmark-latest-blue)](https://agentix-e.github.io/timesfm-ts/benchmark/)\n[![Coverage](https://img.shields.io/badge/coverage-report-blue)](https://agentix-e.github.io/timesfm-ts/coverage/)\n\n## Overview\n\n`@agentix-e/timesfm-hierarchical` provides forecast reconciliation for hierarchical time series structures. When forecasting at multiple levels of a hierarchy (e.g., product → category → total), base forecasts at each level are mathematically inconsistent — the sum of child forecasts doesn't equal the parent forecast. This package reconciles them via optimal combination methods.\n\n### Reconciliation Strategies\n\n| Strategy   | Description                                                     |\n| ---------- | --------------------------------------------------------------- |\n| Bottom-Up  | Forecast at bottom level, aggregate up                          |\n| OLS        | Ordinary Least Squares — minimizes $\\|\\tilde{y} - S\\beta\\|^2$   |\n| WLS        | Weighted Least Squares — weights by forecast variance           |\n| MinT (Cov) | Minimum Trace — minimizes reconciliation error using covariance |\n\n## Installation\n\n```bash\nnpm install @agentix-e/timesfm-hierarchical\n```\n\nRequires `@agentix-e/timesfm-core` (peer dependency).\n\n## Quick Start\n\n```typescript\nimport { TimesFMModel, downloadModel, createForecastConfig } from '@agentix-e/timesfm-core';\nimport { reconcileForecast, buildSummingMatrix } from '@agentix-e/timesfm-hierarchical';\n\nconst model = await TimesFMModel.fromPretrained({\n  modelPath: await downloadModel(),\n});\nmodel.compile(createForecastConfig({ maxContext: 512, maxHorizon: 128 }));\n\n// Define hierarchy: 3-level tree (Total → {West, East} → 4 stores)\nconst result = await reconcileForecast(model, {\n  hierarchy: {\n    nodes: [\n      { id: 'total', parentId: null },\n      { id: 'west', parentId: 'total' },\n      { id: 'east', parentId: 'total' },\n      { id: 's1', parentId: 'west' },\n      { id: 's2', parentId: 'west' },\n      { id: 's3', parentId: 'east' },\n      { id: 's4', parentId: 'east' },\n    ],\n  },\n  inputs: {\n    total: totalSeries,\n    west: westSeries,\n    east: eastSeries,\n    s1: store1Series,\n    s2: store2Series,\n    s3: store3Series,\n    s4: store4Series,\n  },\n  horizon: 24,\n  reconcile: { strategy: 'mint' },\n});\n\n// Coherent reconciled forecasts\nconsole.log(result.reconciled.total.pointForecast); // Aggregate\nconsole.log(result.reconciled.s1.pointForecast); // Bottom-level\nconsole.log(result.reconciled.total.quantileForecast); // Full quantile bands\n\n// Verify coherence: total ≈ west + east\nassertCoherent(result.reconciled.total, result.reconciled.west, result.reconciled.east);\n```\n\n## API Documentation\n\n📚 **Full API reference**: [agentix-e.github.io/timesfm-ts/api/modules/timesfm-hierarchical.html](https://agentix-e.github.io/timesfm-ts/api/modules/timesfm-hierarchical.html)\n\nKey exports:\n\n- `reconcileForecast` — Main entry: forecasts all nodes via TimesFM then reconciles\n- `buildSummingMatrix` — Constructs the hierarchical summing matrix S (m×n)\n- `reconcileBaseForecasts` — Low-level reconciliation given base forecasts + summing matrix\n- `computeProjectionMatrix` — Computes the optimal projection matrix P for a given strategy\n\n## License\n\nApache 2.0\n","readmeFilename":"README.md"}