Human.Exe Geometric Intelligence Layer

Quickstart

Issue a key from your dashboard, export it as GIL_API_KEY, then 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 from /dashboard/keys (secret shown once at issuance)
# 2. export GIL_API_KEY=gil_live_<key-id>.<key-secret>
# 3. export ANTHROPIC_API_KEY=sk-ant-…

# Either: install the SDK (recommended)
npm install @human-exe/gil-sdk

# Or: probe the API directly. The SDK does the HMAC signing for you;
# the example below shows what the SDK puts on the wire.
curl -X POST https://human-exe.ca/api/gil/analyze \
  -H "Authorization: Bearer $GIL_API_KEY" \
  -H "X-GiL-Signature: <hmac-sha256(${ts}.${sha256(body)}, key-secret)>" \
  -H "X-GiL-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "providerKey": "'"$ANTHROPIC_API_KEY"'",
    "model": "claude-opus-4-5",
    "input": { "messages": [{"role":"user","content":"…"}] },
    "governance": { "attentionWave": "tier1", "coherencyCheck": true }
  }'

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. See Integration paths.

Integration paths

GiL integrates at the network layer. Two supported paths, both opt-in (the user explicitly installs the SDK or sets an env var):

1. SDK integration — for application developers

Your application instantiates GiLClient and calls gil.analyze(…). The SDK handles HMAC signing, body canonicalisation, and timestamp headers. The model on the other end has no awareness of governance and is not asked to comply with anything.

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: '…' }] },
  governance:  { attentionWave: 'tier1', coherencyCheck: true },
});

// res.governance carries the audit trail, coherency score, decision provenance.
// The provider response is in res.output, byte-identical to a direct call.

2. Base-URL override — for transparent agent integration

For agents that already speak a provider protocol (Claude Code, Cursor, Aider, custom agents), point the provider base URL at the GiL passthrough endpoint. The agent makes normal provider calls; GiL governs at the proxy layer. Same shape as Cloudflare AI Gateway, OpenRouter, LiteLLM.

# Anthropic-shape passthrough
export ANTHROPIC_BASE_URL=https://human-exe.ca/api/gil/v1/proxy/anthropic
export ANTHROPIC_API_KEY=sk-ant-…          # forwarded, never persisted
export GIL_API_KEY=gil_live_…              # service bearer; HMAC-signed by the proxy

# OpenAI-shape passthrough
export OPENAI_BASE_URL=https://human-exe.ca/api/gil/v1/proxy/openai
export OPENAI_API_KEY=sk-…
export GIL_API_KEY=gil_live_…

# The agent makes normal provider calls. GiL signs, scores, audits,
# attaches governance headers (governance-state, X-GiL-Request-Id),
# and forwards. No model-side instructions. No prompt-layer integration.

Both paths require: explicit user opt-in (install SDK or set env var); per-request provider-key forwarding (never persisted); HMAC-signed requests with timestamp + ±5-min replay window; governance metadata returned in-band on the response. Neither path writes instruction files to the user’s workspace.

Why not a “session-start file” pattern? An instruction file telling the model to “honour governance directives” and “announce a session ID” is structurally indistinguishable from prompt injection. Capable models will refuse it; only weaker models comply. We don’t ship that pattern. Governance is something we observe about your traffic, not something we instruct your model to do.

Authentication

The service bearer is HMAC-issued per account. GiL starts with the Basic foundation and is account-gated; the bearer authenticates you to GiL; your provider key (BYOK) is forwarded per-request in the body and is a separate credential.

Authorization: Bearer gil_live_<key-id>.<key-secret>
X-GiL-Signature: <hex hmac-sha256(`${ts}.${sha256(body)}`, key-secret)>
X-GiL-Timestamp: <unix-seconds>

Replay window: ±5 minutes. Idempotency cache: 10 minutes. Body must be canonicalized (sorted keys, no whitespace).

The key secret is shown once at issuance and never retrievable. Lost secrets require key rotation: issue a new key, deploy, then revoke the old one (7-day grace period applies on rotation).

Endpoints

Base URL: https://human-exe.ca/api/gil

POST /analyze

Submit a governed inference request. GiL applies the configured governance pipeline and forwards to the customer-named provider with the customer-supplied key.

Request body

{
  "provider":    "anthropic" | "openai" | "google",
  "providerKey": "sk-ant-...",
  "model":       "claude-opus-4-5",
  "input":       { "messages": [...] },
  "governance": {
    "attentionWave":      "tier1" | "tier2" | "full",
    "coherencyCheck":      true,
    "decisionProvenance":  "minimal" | "full"
  },
  "metadata": {
    "principal":  "<customer-defined>",
    "sessionId":  "<customer-defined>"
  }
}

Response

{
  "id":         "gil_resp_<uuid>",
  "createdAt":  "2026-04-25T18:00:00Z",
  "output":     { /* provider-native, unmodified */ },
  "governance": {
    "attentionWaveScore": 0.82,
    "coherencyVerified":  true,
    "provenance": {
      "principal":     "...",
      "sessionId":     "...",
      "decisionChain": ["governed-input","wave-weighted","coherency-checked","provider-routed"],
      "signature":     "<hmac of decision chain>"
    },
    "advisories": []
  },
  "usage": {
    "providerTokensIn":   1240,
    "providerTokensOut":  512,
    "governanceUnits": 1
  }
}

Response headers

Every response carries:

• governance-state: green | amber | red | black — see Governance State
• X-GiL-RateLimit-Remaining, X-GiL-RateLimit-Reset

GET /usage

Customer-side billing reconciliation. Returns per-day governanceUnits + provider tokens (informational; provider tokens are NOT billed by Human.Exe — BYOK).

GET https://human-exe.ca/api/gil/usage?from=2026-04-01&to=2026-04-30
Authorization: Bearer gil_live_...

Governance State

Governance states do not block the API. They modulate how much of your user-data surface a misbehaving agent can see. Your call always proceeds.

Optional doctrinal surface: GREEN/AMBER as workflow-depth modulation hint — GREEN = deepest analysis; AMBER = drafting / framing.

Error Codes

SDKs

Full SDK reference moved to /docs/sdk. Install, client options, every method, error handling, environment-variable conventions, and the manual-signing fallback live there as a first-class destination. Quick recap below for in-context reading; the dedicated page is authoritative.

The TypeScript SDK ships as @human-exe/gil-sdk (internal · publication pending) — internal-first inside the Human.Exe workspace at src/lib/gil-sdk. Edge-runtime compatible (Web Crypto only, no node:crypto). Python lands post-launch; Go / Rust by demand.

TypeScript quickstart

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

const gil = new GiLClient({
  apiKey: process.env.GIL_API_KEY!,    // gil_live_<key-id>.<key-secret>
  // baseUrl defaults to https://human-exe.ca
  // (override via GIL_API_BASE env)
});

try {
  const res = await gil.analyze({
    provider:    'anthropic',
    providerKey: process.env.ANTHROPIC_API_KEY!,   // BYOK — never persisted
    model:       'claude-opus-4-5',
    input:       { messages: [{ role: 'user', content: '…' }] },
    governance: {
      attentionWave:      'tier1',
      coherencyCheck:     true,
      decisionProvenance: 'minimal',
    },
  });
  console.log(res.id, res.governance.attentionWaveScore);
} catch (err) {
  if (err instanceof GiLError) {
    console.error(`[${err.code}] ${err.message} (${err.httpStatus})`);
  } else { throw err; }
}

The SDK handles canonicalization (sorted keys, no whitespace), HMAC-SHA256 signing, and timestamp/signature header construction. analyzeWithMeta /usageWithMeta additionally surface governance-state, rate-limit, and request-id headers.

Manual signing — bash / openssl

For environments without a TypeScript runtime:

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.