ModelForge-Public/clients/README.md

Lightweight ModelForge clients

These dependency-free clients are included in the installable release archive. They invoke an exact capability, never a model, node or worker. They use explicit timeouts, bounded responses and typed errors carrying the HTTP status and correlation ID. They do not automatically retry inference or follow redirects with credentials. They are server-side consumer clients, not browser session SDKs.

For Python 3.11+, copy python/modelforge_client.py into your application's import path. For Node.js 20+ JavaScript/TypeScript, copy typescript/modelforge-client.mjs and its adjacent .d.mts declaration file into your source directory. No package registry or dependency installation is required.

Configure the consumer process:

MODELFORGE_URL=https://modelforge.example.internal
MODELFORGE_TOKEN_FILE=/run/secrets/modelforge-token
MODELFORGE_CAPABILITY=rag.embedding@1

Store only the issued service key in that protected file. HTTP is rejected by default; set MODELFORGE_ALLOW_HTTP=true only for an explicitly trusted private lab. Origins cannot contain userinfo, paths, query strings or fragments. TLS certificate verification stays enabled.

from modelforge_client import ModelForgeClient, ModelForgeError

client = ModelForgeClient.from_env(timeout=60)
try:
    print(client.health())  # Verifies identity and scope; does not start inference.
    response = client.invoke({"input": ["A non-sensitive integration check"]})
except ModelForgeError as error:
    print(error.code, error.status, error.correlation_id)

import { ModelForgeClient, ModelForgeError } from "./modelforge-client.mjs";

const client = await ModelForgeClient.fromEnv({ timeoutMs: 60000 });
try {
  console.log(await client.health());
  const response = await client.invoke({ input: ["A non-sensitive integration check"] });
} catch (error) {
  if (error instanceof ModelForgeError)
    console.error(error.code, error.status, error.correlationId);
  else throw error;
}

Use the payload defined by your selected capability. health() proves connectivity, not model health or production eligibility. Do not automatically retry timed-out inference: the server may have admitted the original request. Retain correlation/request IDs for diagnosis.

Validation: backend test_project_python_client.py and node --test clients/typescript/modelforge-client.test.mjs, both included in managed full validation.