# 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:

```text
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.

```python
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)
```

```typescript
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.