Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

clients/README.md

@@ -0,0 +1,54 @@
+# 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.