ML Endpoints Reference

This page documents the ML-facing HTTP surface that is checked into this repository today.

The key point is scope:

The Python ML service exists
The TypeScript client exists
The current checked-in endpoint surface is intentionally small

Service location

Python service: apps/ml-service
TypeScript client: packages/ml-client

Current endpoint: `GET /health`

The FastAPI app mounts a health router and exposes a dependency-aware health endpoint.


curl http://localhost:8000/health

Example response:


{
  "status": "ok",
  "python_version": "3.11.8",
  "dependencies": {
    "pandas": true,
    "scikit_learn": true,
    "scipy": true
  },
  "versions": {
    "fastapi": "0.x",
    "pandas": "2.x",
    "scikit_learn": "1.x",
    "scipy": "1.x"
  }
}

TypeScript client

@loop/ml-client wraps the service with a small HTTP client.


import { MLClient } from '@loop/ml-client';
 
const client = new MLClient({
  baseUrl: 'http://localhost:8000',
  timeoutMs: 5000,
});
 
const health = await client.healthCheck();
 
console.log(health.status);

Client behavior

The client:

trims trailing slashes from baseUrl
uses AbortSignal.timeout()
throws MLServiceUnavailableError for network failures
throws MLServiceError for non-2xx responses


const client = new MLClient({ baseUrl: 'http://localhost:8000' });
 
try {
  const health = await client.healthCheck();
  console.log(health.dependencies.scikit_learn);
} catch (error) {
  console.error(error);
}

Local startup


cd apps/ml-service
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

What this endpoint is for

Use /health to answer:

Is the ML service reachable?
Is Python running?
Are key numerical dependencies importable?
Which package versions are loaded?

That makes it the right endpoint for:

local smoke tests
deployment checks
health monitors
client boot validation

What is not documented here

The service README mentions broader ambitions such as:

pattern discovery
statistical tests
outcome prediction

Those capabilities are not exposed as checked-in FastAPI routes in this repository snapshot, so this reference does not invent request or response contracts for them.

Example health gate


import { MLClient } from '@loop/ml-client';
 
const ml = new MLClient({ baseUrl: process.env.ML_SERVICE_URL! });
const health = await ml.healthCheck();
 
if (health.status !== 'ok') {
  throw new Error('ML service is not healthy');
}