OpenAI-Compatible Proxy Integration

Audience

Developers who already use OpenAI-shaped clients and want requests to cross the HELM AI Kernel execution boundary before they reach an upstream provider.

Outcome

After this integration you should have a local OpenAI-compatible base URL at http://127.0.0.1:9090/v1, a HELM AI Kernel boundary on 127.0.0.1:7714, and a receipt inspection path that proves the application did not bypass HELM.

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Client["OpenAI-compatible client"]
        Proxy["helm-ai-kernel proxy :9090/v1"]
        Boundary["HELM execution boundary"]
        Upstream["configured upstream"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["signed receipts"]
    end

    %% Operational Flow Edges
    Client --> Proxy
    Proxy --> Boundary
    Boundary --> Upstream
    Boundary --> Receipts

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Client["OpenAI-compatible client"]
        Proxy["helm-ai-kernel proxy :9090/v1"]
        Boundary["HELM execution boundary"]
        Upstream["configured upstream"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Receipts["signed receipts"]
    end

    %% Operational Flow Edges
    Client --> Proxy
    Proxy --> Boundary
    Boundary --> Upstream
    Boundary --> Receipts

    %% Premium Styling Rules
    style Receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

Source Truth

• CLI proxy implementation: core/cmd/helm-ai-kernel/proxy_cmd.go
• Local boundary command: core/cmd/helm-ai-kernel/server_cmd.go, core/cmd/helm-ai-kernel/serve_policy.go
• Receipt routes: core/cmd/helm-ai-kernel/receipt_routes.go
• Source-backed examples: examples/python_openai_baseurl/, examples/ts_openai_baseurl/, examples/js_openai_baseurl/

The proxy is an OpenAI-compatible request boundary. It is not hosted operations and it does not certify provider SDK behavior.

The current naming is deliberate: this integration is the OpenAI-compatible proxy, not a Vercel-specific adapter. Existing framework or provider examples should describe the base URL contract they exercise and keep provider-specific claims in source-backed example pages. Do not reintroduce deleted Vercel example paths or document a framework SDK as supported unless the retained example imports that SDK and is covered by a validation command.

The proxy path has one job: preserve an OpenAI-shaped client interface while moving authorization and receipt emission into HELM. A successful upstream response is not enough evidence. The operator should be able to show that the request host was HELM, that the boundary emitted a decision, and that receipt inspection works for the same request.

Start The Boundary

make build
./bin/helm-ai-kernel serve --policy ./release.high_risk.v3.toml

helm-ai-kernel serve --policy binds the local policy boundary to http://127.0.0.1:7714 by default.

Start a mock upstream and the OpenAI-compatible proxy:

python3 scripts/launch/mock-openai-upstream.py --port 19090
./bin/helm-ai-kernel proxy \
  --upstream http://127.0.0.1:19090/v1 \
  --port 9090 \
  --receipts-dir ./helm-receipts

Applications that use OpenAI-shaped HTTP clients should point their base URL at:

http://127.0.0.1:9090/v1

Do not document 3000 as a default. Use it only when the local command explicitly binds that port.

Python Example

cd examples/python_openai_baseurl
HELM_URL=http://127.0.0.1:7714 PYTHONPATH=../../sdk/python python main.py

TypeScript Example

cd examples/ts_openai_baseurl
HELM_URL=http://127.0.0.1:7714 npx tsx main.ts

JavaScript Fetch Example

cd examples/js_openai_baseurl
HELM_URL=http://127.0.0.1:7714 node main.js

Receipt Behavior

Allowed and denied requests should produce HELM receipts. The CLI receipt tail requires an agent filter:

./bin/helm-ai-kernel receipts tail --agent <agent-id> --server http://127.0.0.1:7714

The HTTP route GET /api/v1/receipts/tail can be used directly when an unfiltered stream is appropriate.

Some OpenAI-compatible clients hide raw response headers. In that case, inspect the receipt stream or use a HELM SDK path that exposes receipt metadata.

Verification

Before publishing a new proxy example, prove both outcomes:

• an allowed request returns upstream-shaped output and a HELM receipt;
• a denied or escalated request does not silently dispatch;
• the application does not call the upstream provider directly.

make test-sdk-py
make test-sdk-ts
cd core && go test ./cmd/helm-ai-kernel -run 'Test.*Route|Test.*OpenAPI|Test.*Receipt' -count=1

Troubleshooting

When troubleshooting, prove the request host first. A successful model response is not proof that the request crossed HELM unless the receipt route or SDK response metadata shows a HELM decision.