You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
InferenceX already publishes a public API and a measured-power contract, but users must still teach their agents how to discover the right operations, select comparable observations, interpret PowerX metrics, and preserve provenance in an export. A machine-readable schema describes the interface; it does not by itself install reusable task guidance in Codex or Claude Code.
Users want to install one skill, ask for benchmark or PowerX data in plain language, and receive a traceable CSV or JSON result using public HTTP access. They should not need the InferenceX repository, database credentials, or familiarity with dashboard implementation details. Incorrect workload selection, mixed model releases, missing validity fields, and confusion between measured and provisioned power can otherwise produce plausible but misleading results.
Solution
Publish one public inferencex-api Agent Skill in the npm package @semianalysisai/inferencex-skills. Reuse the package and installer foundation proposed in #901, adapting the skill to currently deployed public operations. Use #938's shipped measured-power contract as the API foundation.
The first release includes a concise skill entrypoint, one PowerX cookbook, a Node 24 export example, and a predictable installer for Codex and Claude Code. Add bilingual agent onboarding to the existing API reference. A user can install the package, ask for validated PowerX observations for a chosen workload, and receive an export with correct units, validity, source identities, request metadata, and an honest explanation of unavailable data.
User Stories
As an agent user, I want to install one published npm package, so that I can use InferenceX without assembling instructions myself.
As a Codex user, I want the installer to place the skill where Codex discovers project skills, so that it is available in my working project.
As a Claude Code user, I want the same skill installed in Claude Code's supported location, so that I can use the same workflow in my chosen agent.
As a user with a custom project setup, I want to choose an explicit installation destination, so that the skill fits my existing organization.
As an existing skill user, I want repeated installation to preserve my current files by default, so that installation does not silently overwrite my work.
As an existing skill user, I want an explicit upgrade option with documented overwrite behavior, so that I can intentionally adopt a newer version.
As a prospective user, I want help and a list of bundled skills without filesystem changes, so that I can understand the package before installing it.
As an external API consumer, I want the installed package to work outside the InferenceX repository and without private credentials, so that public access is sufficient.
As an agent user, I want the skill to consult the current OpenAPI document, so that it uses deployed operations and supported parameters.
As a benchmark analyst, I want a basic benchmark lookup example, so that I can retrieve source observations before performing more specialized analysis.
As a benchmark analyst, I want requested display models and returned model keys kept distinct, so that a display bucket containing multiple releases is not mistaken for one exact release.
As a benchmark analyst, I want to select an as-of date while retaining actual measurement dates, so that historical observations are not presented as newly measured results.
As a PowerX analyst, I want strict validated schema-v2 selection, so that my primary export uses the supported measurement semantics.
As a PowerX analyst, I want exact workload selection, so that single-turn observations with my input/output lengths are not mixed with other workloads.
As an analyst studying an exact model release, I want to further select a returned raw model key, so that related releases in the same display bucket remain separate.
As a PowerX analyst, I want measured per-GPU watts, whole-deployment GPU energy, and provisioned estimates clearly distinguished, so that I compare quantities with the same meaning.
As an analyst, I want missing measurements and genuine zero values to remain different, so that absence is not interpreted as perfect efficiency.
As an analyst, I want original run provenance and logical snapshot provenance preserved separately, so that I can trace each observation to its actual source.
As a spreadsheet user, I want a correctly escaped CSV with workload, configuration, measurements, and provenance, so that I can analyze the result in my existing tools.
As a programmatic consumer, I want JSON containing selected observations and request metadata, so that structured optional audit information can remain intact.
As an analyst, I want an empty strict selection reported precisely, so that I do not confuse missing eligible power data with missing benchmark data altogether.
As an analyst investigating unavailable measurements, I want a bounded diagnostic recipe for the same scope, so that I can distinguish invalid, legacy, missing, and unsupported-schema data when the API permits it.
As an API consumer, I want HTTP and malformed-response failures reported as failures, so that a failed download cannot masquerade as a successful empty export.
As an analyst, I want identifiers preserved exactly, including large numeric-looking strings, so that exported provenance remains reliable.
As a user returning to an analysis, I want the request URL, retrieval time, selected scope, and package version recorded, so that I can repeat the procedure and identify live-data changes.
As an English- or Chinese-speaking visitor, I want equivalent installation instructions and sample prompts in the API reference, so that I can start in my preferred language.
As a new user, I want advertised installation commands to refer to an available package version, so that onboarding works when I follow it.
As a maintainer, I want the packed artifact tested outside the monorepo, so that release contents and executable wiring are verified before publication.
As a maintainer, I want skill-only changes to trigger meaningful CI checks, so that later edits do not silently break installation or extraction.
As a maintainer, I want realistic acceptance runs in both supported agents, so that skill quality is judged by completed user tasks rather than instruction text alone.
As a release owner, I want the exact reviewed archive published and checked by version, so that the public package matches the tested candidate.
As a maintainer of the broader views effort, I want this focused package work to remain compatible with that effort, so that later integration does not restore guidance for unavailable operations or duplicate the package.
Implementation Decisions
One package and one skill. Retain the proposed npm identity from Add read-only views API (/api/v1/views/*) and inferencex-skills package / 新增只读视图 API 与 inferencex-skills 技能包 #901 and initially bundle only inferencex-api. Selectively reuse its installer and package metadata; adapt its API guidance to the shipped contract. Keep the common workflow in the skill and PowerX interpretation in one cookbook. Consult live OpenAPI for endpoint details instead of carrying an exhaustive copied schema catalogue.
Runtime. Use Node 24 and its standard library for the installer and exporter. Declare and test that requirement truthfully. The public package has no runtime dependency on the monorepo, a private SDK, or a second language environment.
Installer interface. Keep help, list, install, target selection, explicit destination, and explicit force-overwrite behavior. Both Codex and generic Agent Skills targets use Codex's supported project discovery location; Claude Code uses its supported project location. Default installation skips an existing skill. Force performs documented merging and overwriting, preserves neighboring skills, and does not promise deletion of obsolete files. Invalid commands/options return useful errors without unintended writes.
Exporter interface. Accept a display model, input/output lengths, optional as-of date, optional returned raw-model selection, output format, and output destination. Default to CSV and support JSON. Record that an omitted date means latest available data. Use standard URL construction and compressed-response handling.
Strict selection. Request powerValid=strictV2, then defensively require numeric validity 1 and numeric schema version 2. Strings, booleans, absent fields, an invalid verdict, and unsupported versions do not satisfy the rule. Locally select single-turn observations with the exact requested input/output lengths. The ordinary benchmark endpoint ignores its sequence parameter outside the calculator projection; that projection cannot be combined with the strict filter. The history operation has no equivalent server-side power filter, so historical guidance must validate locally when needed.
Model and date identity. Discover supported display names through the current contract, retain returned raw model keys, and expose mixed-release buckets explicitly. Do not maintain a duplicated static alias table. An as-of cutoff, original measurement date, and logical snapshot date remain distinct.
Measurement interpretation. Describe average per-GPU watts, schema-v2 whole-deployment GPU energy over its stated denominator, and provisioned-power estimates separately. Measured GPU energy is not measured facility energy. Preserve missing versus zero values and exclude non-finite measurements. Eligibility alone does not establish a representative performance or energy win.
Export contents. Include query URL, retrieval time, requested model/date, raw model, exact benchmark identity, hardware/framework/image, precision, speculative method, workload/concurrency, original topology/configuration, relevant watts/joules fields, validity/schema, original date/run URL, and separate snapshot metadata where supplied. Preserve IDs as supplied, including strings beyond safe integer precision. Never substitute a curve identity for an absent producer identity. JSON can retain optional nested workers/audit data; CSV leaves missing values blank.
Unavailable data and failures. An empty strict selection means no strictV2 observations matched the scope. The diagnostic recipe may make one corresponding unfiltered request to classify the underlying availability. Fail on non-success HTTP responses, malformed JSON, or unexpected response shape with an actionable message and nonzero status; do not emit a misleading successful empty result.
Onboarding. Add a small bilingual agent-skill section to the existing API reference using its shared rendering, localized copy, and copyable-command interaction. Keep real API-operation quickstarts separate from package installation guidance. Maintain consistent package identity, tested version, sample prompts, and terminology across the website and package documentation.
CI and packaging. Reuse the existing workspace test runner, Node's built-in tests for package behavior, and the existing API-reference browser coverage. Ensure changes limited to the skills package trigger the relevant checks. The release archive contains only intended installer, metadata, documentation, and the one skill with its required resources.
Release sequencing. Prepare and test the exact archive from reviewed source, verify publication ownership and an unused version, publish that archive when authorized, and verify installation of the pinned public version before activating website onboarding. If release policy requires source merge before publication, activate the prepared onboarding afterward. Avoid a runtime release flag for this sequencing.
Testing Decisions
Principal acceptance seam: the installed package's public interface. From a clean project outside the monorepo, install the reviewed archive through npm's real executable resolution, confirm skill discovery, and use the installed skill/exporter to retrieve and export PowerX observations. Check actual files, exit statuses, scope, units, measurements, and provenance against the HTTP response used for that run. Exercise this flow in Codex and Claude Code. Record request URLs and retrieval time rather than asserting fixed production row counts.
Installer behavior through the same seam. Check the single bundled skill, complete references/resources, help/list without writes, supported targets, explicit destinations containing spaces, repeat installation, deliberate force-overwrite, and preservation of neighboring skills. Assertions concern resulting behavior, not internal parser functions or implementation shape.
Exceptional extraction cases through controlled HTTP responses. Use representative deterministic fixtures for invalid or nonnumeric validity, unsupported schemas, mixed workload/model rows, missing versus zero/non-finite measurements, oversized string IDs, absent producer identity with present snapshot identity, CSV quoting/Unicode, empty results, HTTP errors, and malformed bodies. Keep any focused lower-level checks limited to cases that cannot be reliably exercised through the public interface. Do not introduce public testing switches or a generic transport framework solely for tests.
Existing website seam. Extend the current API-reference browser tests to cover both languages, consistent commands and release status, sample-prompt/cookbook navigation, and the existing copy interaction. Reuse the current browser suite and shared page.
Prior art and CI. The proposed package installer in Add read-only views API (/api/v1/views/*) and inferencex-skills package / 新增只读视图 API 与 inferencex-skills 技能包 #901 provides the existing CLI interface; the repository's workspace runner already discovers package test scripts; its API-reference browser tests already exercise localized content and copyable code. Add skills-package trigger coverage and run the repository's required type, lint, formatting, typography, unit, and E2E smoke checks. Keep the API synchronization guard passing without gratuitously changing handler digests for onboarding-only work.
Release acceptance. Inspect the candidate archive, test installation through npm from that local archive before publishing, publish exactly the reviewed archive, and verify the pinned public artifact and one real extraction afterward. Preserve evidence for benchmark lookup, valid PowerX export, and unavailable/error requests. Review Chinese semantic fidelity and naturalness using the repository's established advisory workflow.
Package/installer work to reuse selectively: #901. Its wider views scope remains separate; coordinate later integration so it preserves this shipped skill's contract.
Optional detailed provenance work: #939. Current documentation can describe fields before every dataset supplies values.
Authoritative consumer documentation: API reference and OpenAPI document. Recheck these and related PR heads when implementation starts.
Completion means a clean-project user can install the published version, ask for PowerX data in plain language, and receive a correct, source-qualified export using public HTTP access. Package, agent, and website acceptance must all pass; a written skill alone is insufficient.
中文说明
问题陈述
InferenceX 已提供公开 API 和实测功耗契约,但用户仍需自行指导智能体发现合适的接口、筛选可比的数据、理解 PowerX 指标,并在导出时保留溯源信息。机器可读的 schema 描述了接口,却不会自动把可复用的操作指南安装到 Codex 或 Claude Code 中。
Problem Statement
InferenceX already publishes a public API and a measured-power contract, but users must still teach their agents how to discover the right operations, select comparable observations, interpret PowerX metrics, and preserve provenance in an export. A machine-readable schema describes the interface; it does not by itself install reusable task guidance in Codex or Claude Code.
Users want to install one skill, ask for benchmark or PowerX data in plain language, and receive a traceable CSV or JSON result using public HTTP access. They should not need the InferenceX repository, database credentials, or familiarity with dashboard implementation details. Incorrect workload selection, mixed model releases, missing validity fields, and confusion between measured and provisioned power can otherwise produce plausible but misleading results.
Solution
Publish one public
inferencex-apiAgent Skill in the npm package@semianalysisai/inferencex-skills. Reuse the package and installer foundation proposed in #901, adapting the skill to currently deployed public operations. Use #938's shipped measured-power contract as the API foundation.The first release includes a concise skill entrypoint, one PowerX cookbook, a Node 24 export example, and a predictable installer for Codex and Claude Code. Add bilingual agent onboarding to the existing API reference. A user can install the package, ask for validated PowerX observations for a chosen workload, and receive an export with correct units, validity, source identities, request metadata, and an honest explanation of unavailable data.
User Stories
Implementation Decisions
inferencex-api. Selectively reuse its installer and package metadata; adapt its API guidance to the shipped contract. Keep the common workflow in the skill and PowerX interpretation in one cookbook. Consult live OpenAPI for endpoint details instead of carrying an exhaustive copied schema catalogue.powerValid=strictV2, then defensively require numeric validity1and numeric schema version2. Strings, booleans, absent fields, an invalid verdict, and unsupported versions do not satisfy the rule. Locally select single-turn observations with the exact requested input/output lengths. The ordinary benchmark endpoint ignores its sequence parameter outside the calculator projection; that projection cannot be combined with the strict filter. The history operation has no equivalent server-side power filter, so historical guidance must validate locally when needed.Testing Decisions
Out of Scope
Further Notes
中文说明
问题陈述
InferenceX 已提供公开 API 和实测功耗契约,但用户仍需自行指导智能体发现合适的接口、筛选可比的数据、理解 PowerX 指标,并在导出时保留溯源信息。机器可读的 schema 描述了接口,却不会自动把可复用的操作指南安装到 Codex 或 Claude Code 中。
用户希望安装一个技能后,直接用自然语言请求基准测试或 PowerX 数据,获得可追溯的 CSV 或 JSON,无需检出 InferenceX 仓库、获取数据库凭据或了解仪表板内部实现。工作负载筛选错误、混入不同模型版本、误读验证字段,以及混淆实测功耗和预留功率估算,都可能造成看似合理却具有误导性的结果。
解决方案
通过 npm 包
@semianalysisai/inferencex-skills发布一个公开的inferencex-apiAgent Skill。复用 #901 中的包结构和安装器基础,将技能指南改为使用已部署的公开接口,并以 #938 已上线的实测功耗契约为基础。首版包含简洁的技能入口、一份 PowerX 使用指南、一个基于 Node 24 的导出示例,以及行为明确的 Codex/Claude Code 安装器。现有 API 文档增加双语智能体入门说明。用户安装后即可请求指定工作负载下通过验证的 PowerX 观测值,获得包含单位、验证状态、来源标识和请求元数据的导出结果;数据不可用时,应准确解释缺失情况。
用户故事
实现决策
inferencex-api。选择性复用安装器和包元数据,将指南调整为当前已上线的契约。通用流程保留在技能入口中,PowerX 的解释性内容集中在一份指南中。接口细节以实时 OpenAPI 为准,不复制维护一份完整 schema 目录。powerValid=strictV2,并再次检查验证值为数字1、schema 版本为数字2。字符串、布尔值、缺失字段、无效判定和不受支持的版本均不满足条件。在本地筛选单轮请求及精确的输入/输出长度。普通基准测试接口在计算器投影之外会忽略 sequence 参数,而计算器投影不能与严格功耗筛选组合使用。历史接口没有对应的服务端功耗筛选参数,需要时由历史查询指南在本地验证。测试决策
不在范围内
补充说明