# GPC-1 API

The NVIDIA server exposes `GET /v1/models` and `POST /v1/chat/completions`. Requests use OpenAI-style `messages` and `response_format`; responses contain `choices` and a `gpc1` result object. This is a structured-prediction interface, not a complete Chat Completions implementation.

## Requests and responses

Use `model: "gpc-1"` and a strict JSON schema:

```json
{"type":"json_schema","json_schema":{"name":"result","strict":true,"schema":{}}}
```

Replace `schema` with an explicit object schema. Require every property and set `additionalProperties: false`. Supported types are `object`, `array`, `string`, `number`, `integer`, `boolean`, and `null`. References, unions, recursion, and patterns are unsupported.

Put mode-specific options in `gpc1`. OpenAI Python clients can pass them through `extra_body={"gpc1": ...}`.

- `choices[0].message.content`: JSON-encoded selected values.
- `gpc1`: probability distributions, numeric summaries, and execution accounting.
- `usage`: `null`; token usage is not reported.
- Errors: `{"error":{"message": "...", "type": "...", "param": null, "code": "..."}}`.

## Interpreting scores

Probabilities describe the model's distribution over the choices, numeric grid, or complete records supplied in the request. Changing that output space can change the scores. A probability of 0.9 is not a measured 90% accuracy rate; choose decision thresholds using representative examples from your application.

## Atomic categorical

Set `mode: "atomic"`, `field_key`, and an ordered `choices` array of 2–255 unique JSON values. The schema must contain exactly that field with a matching `enum`.

The response includes `value`, `selected_index`, and `probabilities` in choice order.

[Complete categorical request](examples/atomic_request.json)

## Numeric101

Set `mode: "numeric101"` and `numeric_fields`. Each field requires `key`, `description`, `minimum`, `maximum`, and `unit`. Optional `aliases` and `reference` clarify meaning. Schema properties must use `type: "number"` with matching bounds.

Each field uses `value(i) = minimum + (maximum - minimum) × i / 100`, for `i = 0…100`.

| Response field | Meaning |
| --- | --- |
| `choices[0].message.content` | Most likely grid value for each key |
| `gpc1.fields[key].map_value` | Most likely grid value |
| `gpc1.fields[key].expected_value` | Probability-weighted mean in the declared units |
| `gpc1.fields[key].probabilities` | Probabilities in ascending grid order |
| `gpc1.fields[key].normalized_grid` | Grid positions from 0 to 1 |

The mean may fall between grid positions. Numeric fields are separate marginals, not a full joint distribution.

[Complete numeric request](examples/numeric_request.json)

## Finite joint

Set `mode: "finite_joint"` and `allowed_records` containing unique complete JSON records that satisfy the schema. The response includes the selected `value`, candidate `probabilities`, and `log_scores`.

The schema accepts 2–255 records, subject to stricter runtime memory and row limits. The default runtime limit is 32 records. Probabilities are conditional on the supplied records; this mode does not generate arbitrary JSON.

## Images

Include one `image_url` content part containing a base64 PNG, JPEG, or WebP data URI:

```json
{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,..."}}
```

Images are supported only in `numeric101`. HTTP(S) and file URLs are rejected. Describe the target, coordinate origin, axes, and units explicitly. For boxes, request `x_min`, `y_min`, `x_max`, and `y_max`; multiply normalized horizontal values by image width and vertical values by image height. Check coordinate ordering before drawing.

The visual README examples use `expected_value`, not the MAP values in message content.

## Deployment

Set `GPC1_MODEL_PATH` to the packaged `model/` directory and `GPC1_API_KEY` to a secret. Send `Authorization: Bearer YOUR_KEY` to the model endpoints. Startup verifies the packaged base and adapter; serving does not fetch models or images from URLs.

Run one server worker per model on a GPU. Model requests execute one at a time; additional requests wait in a bounded queue. Use separate replicas to serve parallel traffic. `GET /healthz` returns `{"status":"ok"}`. `GET /readyz` returns `{"status":"ready"}` after the model backend is selected, or HTTP 503 with `{"status":"not_ready"}` before then. These two health endpoints do not require the bearer key and do not return model metadata.

Build the container from the downloaded package, then mount its model weights read-only. Set `GPC1_API_KEY` in your environment before launching:

```bash
docker build -t gpc-1 .
docker run --gpus all --rm -p 127.0.0.1:8000:8000 \
  -e GPC1_API_KEY -e GPC1_MODEL_PATH=/models/gpc-1 \
  -v "$PWD/model:/models/gpc-1:ro" gpc-1
```

For internet-facing deployment, put an HTTPS proxy in front of the server. Keep the bearer key server-side and configure request-size limits at the proxy too.

### Context window

The release server admits up to **256K tokens (262,144)** per compiled input, matching the backbone's configured context capacity. This includes prompt formatting, schema, choices, numeric field definitions, and image tokens, not just the supplied text. Inputs are never silently truncated.

This is the configured ceiling, not a completed 256K GPU validation or a guarantee that every request fits on one GPU. Memory and latency depend on input length, images, and candidate count. Set `GPC1_MAX_INPUT_TOKENS` lower for your hardware. The hosted ZeroGPU demo uses a separate 8,192-token limit.

Finite-joint requests also have an aggregate padded-token budget, defaulting to twice the input ceiling (524,288 tokens). Larger candidate sets may reach that budget before the per-input ceiling. Request-body and output-memory limits remain independent.

| Setting | Default |
| --- | --- |
| `GPC1_MAX_INPUT_TOKENS` | 262,144; configurable from 1 to 262,144 |
| `GPC1_MAX_CONCURRENCY` | 1, required; use replicas for parallel traffic |
| `GPC1_MAX_PENDING_REQUESTS` | 4 waiting requests; one additional request may be active |
| `GPC1_MAX_QUEUE_WAIT_SECONDS` | 2 |
| `GPC1_MAX_BODY_BYTES` | 16 MiB |
| `GPC1_MAX_IMAGE_BYTES` | 3 MiB |
| `GPC1_MAX_IMAGE_PIXELS` | 16,777,216 |
| `GPC1_IMAGE_CACHE_MB` | 64; one image's vision features, or 0 to disable |
| `GPC1_MAX_JOINT_ROWS` | 32 |
| `GPC1_MAX_PADDED_TOKENS` | `max(131072, 2 × GPC1_MAX_INPUT_TOKENS)`; 524,288 by default |
| `GPC1_MAX_LOGIT_VECTORS` | 512 |
| `GPC1_MAX_LOGITS_BYTES` | 512 MiB |

Over-limit inputs are rejected, never truncated. POST requests require `Content-Length`. A full queue or an expired queue wait returns HTTP 429 with code `server_busy`; body and image size limits return 413. Set `GPC1_ADMIT_VISION_NUMERIC=disabled` or `GPC1_ADMIT_FINITE_JOINT=disabled` to disable those modes.

Repeated requests for the same processed image can reuse its vision features without changing the prediction math. A new image still requires encoding. The cache stays in memory, holds at most one image's features, and can be disabled with `GPC1_IMAGE_CACHE_MB=0`.

## Unsupported

Streaming, tools, audio, remote image fetching, atomic image classification, image-conditioned finite-joint output, and unrestricted JSON generation. Omit `temperature` and `max_completion_tokens`; they are rejected rather than ignored.

[Setup](README.md#get-started) · [Downloads and CI](docs/DOWNLOADS.md) · [Architecture](docs/ARCHITECTURE.md) · [Model card](MODEL_CARD.md)