infosave commited on
Commit
922a168
·
verified ·
1 Parent(s): 03aa1b3

docs: add Cortiq 0.8.5 System One adapter

Browse files

Document the opt-in Jev-compatible System One request adapter.

Files changed (2) hide show
  1. API.md +84 -8
  2. README.md +17 -1
API.md CHANGED
@@ -1,12 +1,15 @@
1
  # Cortiq Decision — API
2
 
3
- `cortiq serve cortiq-decision.cmf` starts one HTTP server that speaks two
4
- protocols at the same time:
5
 
6
- * the **decisions protocol** of Jev / OpenRouter (`POST /api/alpha/decisions`),
7
- with an optional `cmf` extension;
8
  * the **cortiq-router API**, schema `1.1` (`POST /v1/route` and the rest), so
9
- that existing router clients switch by changing the backend address only.
 
 
 
10
 
11
  Both run the same local model and the same oracle cascade ([ORACLE.md](ORACLE.md)).
12
  There is no web interface and no CORS layer. Request bodies are never logged:
@@ -28,6 +31,7 @@ examples use `curl` and `jq`.
28
  1. [Start a server](#1-start-a-server)
29
  2. [Keys, plans and limits](#2-keys-plans-and-limits)
30
  3. [Decisions API (Jev / OpenRouter protocol)](#3-decisions-api-jev--openrouter-protocol)
 
31
  4. [cortiq-router API (schema 1.1)](#4-cortiq-router-api-schema-11)
32
  5. [Administration](#5-administration)
33
  6. [Configuration reference](#6-configuration-reference)
@@ -96,7 +100,8 @@ stale `LOCK` of a dead process), `--shadow-of URL` and
96
  `--oracle-max-price`, `--oracle-key-env`, `--oracle-base-url` and
97
  `--no-oracle-learning`: the oracle in two steps, the OpenRouter key in
98
  `OPENROUTER_API_KEY` and then this flag
99
- ([ORACLE.md](ORACLE.md#connect-openrouter)).
 
100
  Language-model flags (`--task`, `--gpus`, …) are refused for a decision file.
101
 
102
  ```bash
@@ -530,8 +535,10 @@ curl -s "$CORTIQ/v1/feedback" -H "Authorization: Bearer $KEY" \
530
  | `GET /v1/usage` | key | the caller's account (router format; `x-cmf-extensions: 1` adds token and cost totals) |
531
  | `GET /healthz` | open | status, model, generation, skills, `oracle` (on/off) and `oracle_status` (`ready`, `no_key`, `bad_key`, `disabled`, `budget_exhausted`, `budget_too_small`, `stopped: <reason>`; section 5) |
532
 
533
- `/v1/models` only has the listing's shape; Cortiq Decision is not listed on
534
- OpenRouter.
 
 
535
 
536
  ```bash
537
  curl -s "$CORTIQ/v1/models" \
@@ -542,6 +549,75 @@ curl -s "$CORTIQ/v1/usage" -H "Authorization: Bearer $KEY" -H 'x-cmf-extensions:
542
  | jq '{account, totals: .cmf.totals}' # → 200
543
  ```
544
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
545
  ## 4. cortiq-router API (schema 1.1)
546
 
547
  The same server answers the router's API with exactly its keys, JSON types and
 
1
  # Cortiq Decision — API
2
 
3
+ `cortiq serve cortiq-decision.cmf` starts one HTTP server with two native
4
+ protocols and, when explicitly enabled, a third request adapter:
5
 
6
+ * the **Cortiq decisions protocol** in the Jev / OpenRouter-shaped form
7
+ (`POST /api/alpha/decisions`), with an optional `cmf` extension;
8
  * the **cortiq-router API**, schema `1.1` (`POST /v1/route` and the rest), so
9
+ that existing router clients switch by changing the backend address only;
10
+ * `POST /v1/systemone`, the opt-in TypeSafe System One / Jev-compatible
11
+ request format (`--jev-compatible`). It always identifies its result as a
12
+ local CMF model, not as Jev.
13
 
14
  Both run the same local model and the same oracle cascade ([ORACLE.md](ORACLE.md)).
15
  There is no web interface and no CORS layer. Request bodies are never logged:
 
31
  1. [Start a server](#1-start-a-server)
32
  2. [Keys, plans and limits](#2-keys-plans-and-limits)
33
  3. [Decisions API (Jev / OpenRouter protocol)](#3-decisions-api-jev--openrouter-protocol)
34
+ 3a. [System One request adapter (Jev-compatible)](#3a-system-one-request-adapter-jev-compatible)
35
  4. [cortiq-router API (schema 1.1)](#4-cortiq-router-api-schema-11)
36
  5. [Administration](#5-administration)
37
  6. [Configuration reference](#6-configuration-reference)
 
100
  `--oracle-max-price`, `--oracle-key-env`, `--oracle-base-url` and
101
  `--no-oracle-learning`: the oracle in two steps, the OpenRouter key in
102
  `OPENROUTER_API_KEY` and then this flag
103
+ ([ORACLE.md](ORACLE.md#connect-openrouter)). Add `--jev-compatible` to expose
104
+ the separate System One adapter described in [section 3a](#3a-system-one-request-adapter-jev-compatible).
105
  Language-model flags (`--task`, `--gpus`, …) are refused for a decision file.
106
 
107
  ```bash
 
535
  | `GET /v1/usage` | key | the caller's account (router format; `x-cmf-extensions: 1` adds token and cost totals) |
536
  | `GET /healthz` | open | status, model, generation, skills, `oracle` (on/off) and `oracle_status` (`ready`, `no_key`, `bad_key`, `disabled`, `budget_exhausted`, `budget_too_small`, `stopped: <reason>`; section 5) |
537
 
538
+ Without `--jev-compatible`, `/v1/models` has only the native OpenRouter-style
539
+ listing shape; Cortiq Decision is not listed on OpenRouter. With the adapter
540
+ enabled it instead returns the System One discovery `models` array described in
541
+ [section 3a](#3a-system-one-request-adapter-jev-compatible).
542
 
543
  ```bash
544
  curl -s "$CORTIQ/v1/models" \
 
549
  | jq '{account, totals: .cmf.totals}' # → 200
550
  ```
551
 
552
+ ## 3a. System One request adapter (Jev-compatible)
553
+
554
+ Enable this endpoint explicitly; it is off by default so native clients retain
555
+ their existing contracts:
556
+
557
+ ```bash
558
+ cortiq serve cortiq-decision.cmf --state ./decision.state \
559
+ --jev-compatible --port 8080
560
+ ```
561
+
562
+ `POST /v1/systemone` accepts the TypeSafe System One request shape. It uses the
563
+ same local CMF skills, gate, key policy, limits and optional oracle as the
564
+ native server. It does **not** load Jev weights or present itself as Jev.
565
+
566
+ | Field | Adapter rule |
567
+ |---|---|
568
+ | `model` | optional. Omitted, `jev-latest`, `jev-preview`, `jev-1.13.0`, the `typesafe/jev-1.13` selector series, and `cmf-decision-0.8.5` select the current local CMF decision model at this endpoint only. |
569
+ | `state` | a string, object, array or `null`. |
570
+ | `questions` | an object of `choice`, `score` or `noul` questions. `instructions` may be omitted or `null`, matching System One clients. |
571
+
572
+ For example, a client that omits `model` can send a small local choice:
573
+
574
+ ```bash
575
+ curl -s "$CORTIQ/v1/systemone" \
576
+ -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
577
+ -d '{
578
+ "state": "I still have not received my new card",
579
+ "questions": {
580
+ "intent": {
581
+ "type": "choice",
582
+ "criteria": {
583
+ "card_arrival": null,
584
+ "card_delivery_estimate": null
585
+ }
586
+ }
587
+ }
588
+ }' | jq
589
+ ```
590
+
591
+ A successful response is intentionally small and identifies the local model:
592
+
593
+ ```json
594
+ {
595
+ "model": "cmf-decision-0.8.5",
596
+ "answers": {
597
+ "intent": {
598
+ "type": "choice",
599
+ "choice": "card_arrival",
600
+ "confidence": 0.99,
601
+ "probabilities": {"card_arrival": 0.99, "card_delivery_estimate": 0.01}
602
+ }
603
+ },
604
+ "usage": {"input_tokens": 42, "output_tokens": 2}
605
+ }
606
+ ```
607
+
608
+ The token figures use the same request metering as the native endpoint; their
609
+ values vary with the request. `GET /v1/models` changes to System One discovery
610
+ format in adapter mode. Its `models` array contains the canonical
611
+ `cmf-decision-0.8.5` entry and transport aliases such as `jev-latest`; each
612
+ alias describes itself as a route to the local CMF model. Requests use the same
613
+ Cortiq key policy as the rest of the server. System One errors use
614
+ `{"error":{"type", "message", "code", "request_id"}}`.
615
+
616
+ The adapter is deliberately isolated: `/api/alpha/decisions` and
617
+ `/v1/decisions` keep their stricter native model rules and continue to reject
618
+ Jev model identifiers. Compatibility means the request/response wire format,
619
+ not a claim of Jev identity, weights, affiliation or benchmark equivalence.
620
+
621
  ## 4. cortiq-router API (schema 1.1)
622
 
623
  The same server answers the router's API with exactly its keys, JSON types and
README.md CHANGED
@@ -35,7 +35,7 @@ oracle for unfamiliar cases, then use its answers to grow your local skills.
35
  enter a request and inspect the decision, confidence and reconstruction errors.
36
  No installation or API key needed.
37
 
38
- [Quick start](#quick-start) · [Your own skill](#add-your-own-skill) · [Oracle](ORACLE.md#connect-openrouter) · [API](API.md) · [Benchmarks](BENCHMARKS.md) · [На русском](README_RU.md)
39
 
40
  ## Quick start
41
 
@@ -84,6 +84,22 @@ CORTIQ_DECISION_DEVICE=vulkan cortiq decide cortiq-decision.cmf \
84
  On multi-GPU hosts, also set `CORTIQ_DECISION_VULKAN_ADAPTER` to a unique part
85
  of the GPU name. The same variables work with `cortiq serve`. [GPU guide →](GPU.md)
86
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
87
  ## Measured results
88
 
89
  ### Quality: the model alone vs Jev 1.13
 
35
  enter a request and inspect the decision, confidence and reconstruction errors.
36
  No installation or API key needed.
37
 
38
+ [Quick start](#quick-start) · [Jev-compatible requests](#jev-compatible-request-format) · [Your own skill](#add-your-own-skill) · [Oracle](ORACLE.md#connect-openrouter) · [API](API.md) · [Benchmarks](BENCHMARKS.md) · [На русском](README_RU.md)
39
 
40
  ## Quick start
41
 
 
84
  On multi-GPU hosts, also set `CORTIQ_DECISION_VULKAN_ADAPTER` to a unique part
85
  of the GPU name. The same variables work with `cortiq serve`. [GPU guide →](GPU.md)
86
 
87
+ ### Jev-compatible request format
88
+
89
+ Cortiq 0.8.5 adds an **opt-in** adapter for the TypeSafe System One request
90
+ format. Start it alongside the normal Cortiq APIs:
91
+
92
+ ```bash
93
+ cortiq serve cortiq-decision.cmf --jev-compatible --port 8080
94
+ ```
95
+
96
+ Point a System One client at `http://127.0.0.1:8080/v1/systemone`. Its default
97
+ `jev-latest` (and the historical `typesafe/jev-1.13`) is accepted **only as a
98
+ request alias**; an omitted model works too. Every response identifies the
99
+ local CMF model as `cmf-decision-0.8.5` — this adapter does not serve or claim
100
+ to be Jev. `GET /v1/models` supplies the matching System One discovery shape
101
+ when the flag is enabled. [Request and response details →](API.md#3a-system-one-request-adapter-jev-compatible)
102
+
103
  ## Measured results
104
 
105
  ### Quality: the model alone vs Jev 1.13