Overview

NEURL Cortex is the serving layer for a trained machine-learning model. It wraps the model behind a Python REST API — entered through run_api.py — so that inference becomes an ordinary HTTP call rather than a notebook exercise. It serves the applications and internal tools that need the model's predictions as structured data they can act on.

Problem

A trained model, on its own, is inert. It lives as a serialised artefact on disk, loadable only by a process that already knows how to find it, how to initialise it, and how to shape input into the tensors it expects. Every downstream consumer that wants a prediction has to reimplement that setup, absorb the model's dependency tree, and pay the cold-start cost of loading weights on every invocation. The result is duplicated glue code, inconsistent preprocessing between callers, and a hard ceiling on how many systems can realistically use the model at all. What was needed was a boundary: one process that owns the model, holds it warm in memory, and publishes a stable contract — request in, structured output out — so that consumers depend on the interface rather than the artefact. That boundary is NEURL Cortex.

System Design

The service is Python-first and deliberately small in surface area. run_api.py at the repository root is the single entry point: it starts the HTTP process, brings the model up, and mounts the routes. Route handlers live under /APIS, keeping transport concerns — request parsing, validation, response shaping — separate from the model code they call into. The model itself ships alongside the service as a packaged artefact (Neurl Model.zip), unpacked at startup rather than fetched at request time, so the weights are resident in the process for the life of the service. The Python dependency set is pinned in requirements.txt; the package.json at the root is a vestigial npm scaffold and carries no build responsibility.

The design point is that the model loads once and serves many. Loading is a startup cost paid on process boot, not a per-request cost paid by every caller, which is what makes on-demand inference viable over HTTP. Around that core, the service treats its outputs as first-class artefacts rather than transient response bodies: an /outputs directory captures generated results on disk, so a prediction can be inspected, re-served, or handed to a downstream job after the originating HTTP request has closed. Structured output is the contract — consumers parse a defined shape, not free-form text, which is what allows other applications to build on the model programmatically.

The repository also carries a Google Cloud service-account key at the root, indicating that the service authenticates outward to a Google Cloud API as part of its work — credentials the process loads on startup and holds for the duration. Operationally, the service is built to run detached and long-lived rather than as an interactive script: service_output.log and service_error.log sit alongside the entry point, splitting normal execution telemetry from failure telemetry into separate streams. That separation is the practical basis for running Cortex as a background service — errors are readable without being buried in inference chatter. A small amount of HTML and CSS accompanies the Python, providing a lightweight rendered surface over the API rather than a full frontend application.