@human-exe/gil-sdk

Quickstart

Issue an API key from your dashboard, export it as GIL_API_KEY, install the SDK, and make a governed call through the Basic foundation. Choose a paid plan when you need expanded managed memory and workspace capacity.

# 1. Issue a key at https://human-exe.ca/dashboard/keys
# 2. Export credentials (your environment, your choice — env vars, secret manager, etc.)
export GIL_API_KEY=gil_live_<key-id>.<key-secret>
export ANTHROPIC_API_KEY=sk-ant-...

# 3. Install
npm install @human-exe/gil-sdk

import { GiLClient } from '@human-exe/gil-sdk';

const gil = new GiLClient({ apiKey: process.env.GIL_API_KEY! });

const res = await gil.analyze({
  provider:    'anthropic',
  providerKey: process.env.ANTHROPIC_API_KEY!,   // BYOK — forwarded, never persisted
  model:       'claude-opus-4-5',
  input:       { messages: [{ role: 'user', content: 'Hello.' }] },
  governance:  { attentionWave: 'tier1', coherencyCheck: true },
});

console.log(res.id, res.governance.attentionWaveScore);
console.log(res.output);  // provider-native, byte-identical to a direct call

Never paste your GIL_API_KEY into a chat prompt, into a file an AI agent reads, or into any model context. It is a service credential — not part of the conversation.

Client options

The GiLClient constructor accepts:

new GiLClient({
  apiKey:  string,           // required — gil_live_<key-id>.<key-secret>
  baseUrl?: string,          // default: https://human-exe.ca
                             //          (or process.env.GIL_API_BASE)
  fetch?:  typeof fetch,     // default: globalThis.fetch — inject your own for tests
  timeoutMs?: number,        // default: 30_000
});

baseUrl override is useful for local proxies or staging environments. The SDK works in any modern JS runtime with Web Crypto: Node 18+, Deno, Bun, Cloudflare Workers, Vercel Edge, browsers.

gil.analyze()

Submit a governed inference request. Returns the parsed response body.

const res = await gil.analyze({
  provider:    'anthropic' | 'openai' | 'google',
  providerKey: string,                      // BYOK
  model:       string,                      // e.g. 'claude-opus-4-5'
  input:       { messages: [...] },         // provider-native shape
  governance: {
    attentionWave:      'tier1' | 'tier2' | 'full',
    coherencyCheck:     boolean,
    decisionProvenance: 'minimal' | 'full',
  },
  metadata?: {
    principal?: string,                      // your customer / actor identifier
    sessionId?: string,                      // your session correlation id
  },
});

Response shape:

{
  id:        string,                         // "gil_resp_<uuid>"
  createdAt: string,                         // ISO-8601 UTC
  output:    unknown,                        // provider-native, unmodified
  governance: {
    attentionWaveScore: number,              // 0.0 — 1.0
    coherencyVerified:  boolean,
    provenance: {
      principal:     string,
      sessionId:     string,
      decisionChain: string[],
      signature:     string,                 // hmac of decision chain
    },
    advisories: string[],
  },
  usage: {
    providerTokensIn:  number,
    providerTokensOut: number,
    governanceUnits:   number,               // 1 unit = 1 governed call
  },
}

gil.usage()

Fetch per-day governance-unit totals. Provider tokens included for reference; provider billing is direct.

const u = await gil.usage({
  from: '2026-05-01',   // inclusive, YYYY-MM-DD
  to:   '2026-05-11',   // inclusive
});

// u.days: [{ date, governanceUnits, providerTokensIn, providerTokensOut }]
// u.total: aggregate over range

withMeta variants

analyzeWithMeta and usageWithMeta return the parsed body plus the wire-level metadata (governance-state header, rate-limit counters, request id) when you need to log or react to them.

const { data, meta } = await gil.analyzeWithMeta({ /* same args */ });

console.log(meta.governanceState);   // 'green' | 'amber' | 'red' | 'black'
console.log(meta.rateLimit);         // { remaining, reset }
console.log(meta.requestId);         // X-GiL-Request-Id

See Governance State for what each state means for response masking.

gil.reportIssue()

Report a problem or performance observation about GiL itself \u2014 an SDK bug, unexpected latency, a governance mismatch, or a docs gap. If you asked your human user whether a governed response looked right, forward what they said in userFeedback.

await gil.reportIssue({
  severity: 'medium',           // 'low' | 'medium' | 'high' | 'critical'
  category: 'incorrect-governance',
  message:  'attentionWaveScore stayed 0 across 5 consecutive calls with tier1.',
  context:  { requestId: 'gil_resp_...', model: 'claude-opus-4-5' },
  userFeedback: 'User confirmed the response looked ungoverned.',   // optional
});

Reports are stored against your account for triage \u2014 not rendered publicly. Use gil.reportIssue in the same try/catch pattern as analyze; it throws GiLError on non-2xx.

Error handling

Non-2xx responses throw GiLError. Network failures throw the underlying fetch error.

import { GiLClient, GiLError } from '@human-exe/gil-sdk';

try {
  const res = await gil.analyze({ /* ... */ });
} catch (err) {
  if (err instanceof GiLError) {
    console.error(`[${err.code}] ${err.message} (${err.httpStatus})`);
    // err.code: 'gil.auth.invalid' | 'gil.rate.limit' | ...
    // err.httpStatus: 401 | 429 | 502 | 503 | ...
    // err.requestId: X-GiL-Request-Id for support escalation
  } else {
    throw err;  // network / runtime
  }
}

Full error code reference at /docs/api#errors.

Environment variables

The SDK reads no environment variables on its own — you pass everything via the constructor — but these conventions are recommended for your application:

Set these via your host platform’s standard env-var mechanism. Human.Exe never ships an instruction file telling you how to configure your environment.

Manual signing (no SDK)

For environments without a TypeScript runtime — CI scripts, embedded systems, language ports under development — you can sign requests manually:

KEY_ID="..."
KEY_SECRET_B64URL="..."   # base64url, 32 bytes decoded

BODY='{"governance":{"attentionWave":"tier1","coherencyCheck":true,"decisionProvenance":"minimal"},"input":{"messages":[{"content":"hello","role":"user"}]},"model":"claude-opus-4-5","provider":"anthropic","providerKey":"sk-ant-..."}'
TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')

# base64url -> hex bytes for HMAC key
SECRET_HEX=$(printf '%s' "$KEY_SECRET_B64URL" | tr '_-' '/+' | base64 -d | xxd -p -c 256)

SIG=$(printf '%s.%s' "$TS" "$BODY_HASH" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$SECRET_HEX" -binary \
  | base64 | tr '+/' '-_' | tr -d '=')

curl -X POST https://human-exe.ca/api/gil/analyze \
  -H "Authorization: Bearer gil_live_${KEY_ID}.${KEY_SECRET_B64URL}" \
  -H "X-GiL-Timestamp: $TS" \
  -H "X-GiL-Signature: $SIG" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"

The body sent on the wire must be byte-identical to the body that was hashed. If a proxy reformats JSON, the signature breaks. The SDK guarantees this by serializing once via canonicalize() and reusing the exact string.