Hiq Cortex En

HiQ Cortex — LCA Data

Carbon footprint answers must come from real inventory data. A remembered "steel is about 2 kg CO₂e/kg" is useless to an LCA practitioner: the real value depends on database, version, system model, production route, and geography, and varies several-fold across those dimensions.

About

This skill connects to HiQ Cortex — the LCA data service of HiQ (海科数据), a Chinese provider of LCA background data and carbon footprint services that maintains its own China-specific life-cycle inventory databases and aggregates major international sources.

Available:

• 18 life-cycle inventory databases, 11 of them free. Includes China-specific data (HiQLCD covering China's full industrial system, HiQLCD-AL for the aluminium value chain, CALCD for the automotive sector) alongside international sources (Ecoinvent, BAFU, ELCD, EF, worldsteel, USLCI, AusLCI, CarbonMinds, Agri-footprint …).
• 24,000+ published EPDs (EPDItaly, ECO Platform, EPD Norge) for peer distributions and outlier review.
• ISO 14040/14044 and GB/T 24040/24044 conventions; system models covering cut-off, consequential, APOS, and EN 15804.

Search runs server-side. Pass the user's own wording or raw BOM lines straight to the search endpoint — translating material names into LCA terminology, identifying production routes, and mapping categories to process direction all happen on the server. Returned candidates are already ranked and carry a match-quality marker. Do not re-derive search terms locally.

Privacy and security

• The API key is read only from the environment or the host's MCP config. The skill never writes it to a file and never echoes it in output.
• Queries go only to x.hiqlcd.com (HiQ's API), never to any third party.
• Nothing is collected or uploaded — no local files, directory structure, or conversation content.
• The bundled script uses only the Python standard library, no third-party dependencies, and the source is auditable on GitHub.

Hard rules

1. Every number must come from a tool call in this session. Never state a GWP, LCIA value, or distribution from memory. If the tools are unavailable, say so — do not fill the gap.
2. Every number needs its basis: database + version + system model + geography + reference unit. 0.0269 kg CO₂e/kWh (BAFU 2025, DEFAULT, CH, low-voltage grid) is usable; a bare 0.027 is not.
3. Restricted is not an error. Commercial databases return a restriction marker and a purchase_url when the account lacks the data package. Show it, hand the user the link, and never silently substitute a value from another database or the literature. Retrying does not help. A free database may be used instead, but say that it is a substitution.
4. Do not compare across conventions. Data with different functional units, system models, or system boundaries is not comparable — say so rather than presenting a misleading delta. Read comparability_note first; that is what it is for.

Access

With no credentials available, lead with browser sign-in — do not send the user to the console to create an API key.

Sign-in is one command plus one click, with no registration. Creating an API key means logging into a console, finding the right page, copying a secret, and setting an environment variable — an order of magnitude more friction. Putting that first is how you lose the user.

python3 scripts/cortex.py login    # ← the default when no credential is present

The command prints an authorization link. Hand the link to the user verbatim, have them click "authorize", then carry on with the original task. Credentials land in ~/.hiq/credentials.json (mode 600) and every command works from then on; the visible data scope matches that account, including any commercial databases it has access to. logout removes them.

Only reach for an API key in three cases: the user asks for one, the environment is CI / server-side with no browser, or sign-in failed.

export HIQ_API_KEY=sk_xxx          # server-side / CI; takes precedence when both exist

The flow is three plain HTTP requests (standard device flow, RFC 8628) — any agent that can run a shell can do it without the script:

curl -sX POST https://x.hiqlcd.com/api/cortex/oauth/device_authorization \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"my-agent","agent_name":"My Assistant","scope":"lca_data"}'
# hand the returned verification_uri_complete to the user → they approve
curl -sX POST https://x.hiqlcd.com/api/cortex/oauth/token \
  -H 'Content-Type: application/json' -d '{"device_code":"..."}'   # 428 = not yet approved, keep polling

Prefer MCP when the host supports it. If lookup_datasets, aggregate_datasets, epd_search are already available in this session, use them. Otherwise add this to the host's MCP config (WorkBuddy ~/.workbuddy/mcp.json, Claude Code ~/.claude.json, Cursor ~/.cursor/mcp.json) and restart the host:

{
  "mcpServers": {
    "cortex": {
      "type": "http",
      "url": "https://x.hiqlcd.com/api/cortex/mcp",
      "headers": { "X-API-Key": "sk_xxx" }
    }
  }
}

Credentials from login work too — replace that line with "Authorization": "Bearer ".

Never hard-code credentials into files generated for the user.

Tools

Add --json to any script command for the raw payload.

Search has no MCP tool — it is a REST endpoint, wrapped by the script. Direct call:

curl -sN -X POST https://x.hiqlcd.com/api/cortex/search \
  -H "X-API-Key: sk_xxx" -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=304 stainless steel&sources=BAFU,Ecoinvent"

The response is SSE — parse the WorkflowCompleted event, then JSON-decode its content field. It takes 20–40 seconds (the server searches and verifies each hit). That is normal, not a hang; do not retry in parallel.

dataset_key is an opaque handle — pass it through unchanged, never construct or edit one.

Reading the response

Scenario routing

Top to bottom, first match wins.

When to ask the user

Search first, compare second, ask last. If there is anything searchable — a material name, product, process, or BOM line — search it and give results in the same turn. Do not ask for information already stated in the conversation.

"I'm not sure which one to use" is a decision-support signal, not a question: give the candidate list, compare under one convention, explain which dimension drives the difference, and give a conditional recommendation where the evidence supports one. A complete advisory answer can end there.

Only ask when a single dataset must be finalised and the remaining ambiguity would materially change the result. Options must correspond to candidates already shown — never invent them. Use the host's interaction facility if one exists, and do not duplicate the options as a text list. After the answer, complete the match on the existing results; do not re-run the same search.

Data entitlements

Data packages and subscription plans are two separate systems — upgrading a plan does not unlock a database. When something is restricted, name the database, hand over the purchase_url, and offer a free-database path if one answers the same question, labelled as a substitution.

Voice and terminology

Write for LCA practitioners, like a knowledgeable peer.

• No pleasantries ("I hope this helps", "let me help you"), no adjective stacking, no summarising sign-off.
• Use ISO 14040/14044, ILCD, and GB/T 24040 terminology — for this audience, standard terms are clearer than plain language.
• unit process · elementary flow · reference flow · functional unit · system boundary · impact category · characterisation factor · cut-off · consequential.
• Do not invent terminology. When unsure of the standard term, use the ISO wording.

Troubleshooting