@@ -0,0 +1,24 @@
+# System One: native structured decision inference
+
+System One models make fast, structured decisions — a Choice among named
+options, a Noul (yes/no), or a Score over ordered levels — from a shared text
+snapshot, returning probabilities and a confidence value instead of generated
+text. This directory provides a model-agnostic C++ interface for embedding
+them, following
+[TypeSafe's SDK operation](https://docs.typesafe.ai/sdk/python/api/clients/sync)
+and [typed SDK](https://docs.typesafe.ai/sdk/python/api/types/questions).
+
+[api.h](api.h) defines the question and answer types (`Choice`, `Noul`,
+`Score`, `ChoiceAnswer`, `NoulAnswer`, `ScoreAnswer`) and the virtual
+`SystemOne::system_one(state, questions)` interface in the
+`executorch::systemone` namespace. It is shared across models; it has no
+dependency on any one model's tokenizer, export format, or runtime.
+
+Model-specific implementations live in their own subdirectory, each
+borrowing or embedding an ExecuTorch `Module` and providing a concrete
+`SystemOne` subclass:
+
+- [kev/](kev/) — [Kev](https://huggingface.co/jaredpalmer/kev-0.8b), a System
+  One model, using XNNPACK on CPU or MLX on Apple GPUs.
+
+See a model's subdirectory for export, build, and benchmarking instructions.
@@ -16,7 +16,8 @@
 #include <variant>
 #include <vector>
 
-namespace kev {
+namespace executorch {
+namespace systemone {
 
 struct Choice {
   std::string instructions;
@@ -70,4 +71,5 @@ class SystemOne {
       const Questions& questions) = 0;
 };
 
-} // namespace kev
+} // namespace systemone
+} // namespace executorch
@@ -24,7 +24,7 @@ project(kev LANGUAGES C CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
-get_filename_component(EXECUTORCH_ROOT "../.." ABSOLUTE)
+get_filename_component(EXECUTORCH_ROOT "../../.." ABSOLUTE)
 
 option(BUILD_SHARED_LIBS "" OFF)
 option(EXECUTORCH_BUILD_EXECUTOR_RUNNER "" OFF)
 
@@ -1,7 +1,8 @@
 # Native Kev decision inference
 
-Embed [Kev](https://huggingface.co/jaredpalmer/kev-0.8b) in a C++ application
-with ExecuTorch's `Module` API, using XNNPACK on CPU or MLX on Apple GPUs.
+Embed [Kev](https://huggingface.co/jaredpalmer/kev-0.8b), a System One model,
+in a C++ application with ExecuTorch's `Module` API, using XNNPACK on CPU or
+MLX on Apple GPUs.
 Prefill a shared text once, then ask batches of questions from that snapshot.
 Inference uses the native binary, model, and tokenizer; Python is needed for
 export.
@@ -27,10 +28,10 @@ hf download jaredpalmer/kev-0.8b \
   --revision 54f4f8777356cd5bbbb6c6919c657f26e6f2f6d8 \
   --local-dir kev-checkpoint
 
-PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/kev/export.py \
+PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/systemone/kev/export.py \
   --checkpoint kev-checkpoint --backend xnnpack --dtype fp32 --output kev-cpu
 
-PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/kev/export.py \
+PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/systemone/kev/export.py \
   --checkpoint kev-checkpoint --backend mlx --dtype bf16 --output kev-mlx
 ```
 
@@ -44,7 +45,7 @@ The default limits are 384 prefix tokens and 1,024 tokens for the prefix plus
 one question. Set larger export bounds for longer documents:
 
 ```bash
-PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/kev/export.py \
+PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/systemone/kev/export.py \
   --checkpoint kev-checkpoint --backend mlx --dtype bf16 --output kev-mlx-long \
   --max-prefix 2048 --max-context 4096
 ```
@@ -63,7 +64,7 @@ returns the fitted temperature as a float; `get_checkpoint_id` returns
 From the ExecuTorch root, with submodules initialized:
 
 ```bash
-cmake -S examples/kev -B cmake-out/kev-cpu \
+cmake -S examples/systemone/kev -B cmake-out/kev-cpu \
   -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE="$(command -v python)"
 cmake --build cmake-out/kev-cpu --target kev_runner --parallel 8
 
@@ -73,7 +74,7 @@ cmake-out/kev-cpu/kev_runner kev-cpu/model.pte kev-cpu/tokenizer.json
 For MLX, use macOS 14+ with Xcode's Metal compiler installed:
 
 ```bash
-cmake -S examples/kev -B cmake-out/kev-mlx \
+cmake -S examples/systemone/kev -B cmake-out/kev-mlx \
   -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE="$(command -v python)" \
   -DEXECUTORCH_BUILD_MLX=ON
 cmake --build cmake-out/kev-mlx --target kev_runner --parallel 8
@@ -134,19 +135,22 @@ of the other medians. FP32 is faster on this CPU; all exports are unquantized.
 To reproduce the XNNPACK BF16 column with the CPU benchmark:
 
 ```bash
-PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/kev/export.py \
+PYTHONPATH="$HOME/kev:$PYTHONPATH" python examples/systemone/kev/export.py \
   --checkpoint kev-checkpoint --backend xnnpack --dtype bf16 --output kev-cpu-bf16
 
 cmake-out/kev-cpu/kev_benchmark kev-cpu-bf16/model.pte kev-cpu-bf16/tokenizer.json
 ```
 
 ## C++ API
 
-[api.h](api.h) defines the question and answer types and the virtual
-`SystemOne::system_one(state, questions)` interface, following
-[TypeSafe's SDK operation](https://docs.typesafe.ai/sdk/python/api/clients/sync).
-It returns ExecuTorch's `Result<Answers>`. [kev.h](kev.h) provides `Kev`,
-which implements this interface and borrows a `Module` and tokenizer.
+[../api.h](../api.h) is generic across System One models. It defines the
+question and answer types and the virtual `SystemOne::system_one(state,
+questions)` interface, following
+[TypeSafe's SDK operation](https://docs.typesafe.ai/sdk/python/api/clients/sync),
+in the `executorch::systemone` namespace. It returns ExecuTorch's
+`Result<Answers>`. [kev.h](kev.h) provides `Kev` in `executorch::systemone::kev`,
+which implements this interface for the Kev model and borrows a `Module` and
+tokenizer.
 
 For explicit prefix reuse, `Kev` also provides `prefill(state)` and
 `evaluate(prefix, questions)`. `Prefix` owns its snapshot and must be used with
@@ -164,21 +168,22 @@ The question and answer types follow [TypeSafe's typed SDK](https://docs.typesaf
 and are not sent to the model.
 
 ```cpp
-kev::Questions questions{
-    {"department", kev::Choice{"Which team should handle this?",
+using namespace executorch::systemone;
+Questions questions{
+    {"department", Choice{"Which team should handle this?",
         {{"billing", "Invoices and refunds"}, {"technical", "Bugs and outages"}}}},
-    {"refund", kev::Noul{"Is a refund requested?",
-        {{kev::NoulOutcome::False, "No refund requested"},
-         {kev::NoulOutcome::True, "Explicitly asks for a refund"}}}},
-    {"urgency", kev::Score{"How urgent is this?",
+    {"refund", Noul{"Is a refund requested?",
+        {{NoulOutcome::False, "No refund requested"},
+         {NoulOutcome::True, "Explicitly asks for a refund"}}}},
+    {"urgency", Score{"How urgent is this?",
         {"Can wait", "This week", "Today"}}}};
 ```
 
 With a loaded module and tokenizer, call through the interface:
 
 ```cpp
-kev::Kev model(module, tokenizer);
-kev::SystemOne& api = model;
+executorch::systemone::kev::Kev model(module, tokenizer);
+executorch::systemone::SystemOne& api = model;
 auto answers = api.system_one(state, questions);
 ```
 
@@ -195,7 +200,7 @@ if (!answers.ok()) {
   return 1;
 }
 auto followup = model.evaluate(*prefix, {
-    {"duplicate", kev::Noul{"Was the customer charged more than once?", {}}}});
+    {"duplicate", Noul{"Was the customer charged more than once?", {}}}});
 if (!followup.ok()) {
   return 1;
 }
 
@@ -16,9 +16,10 @@
 #include "kev.h"
 
 using executorch::extension::Module;
-using kev::Choice;
-using kev::Noul;
-using kev::Questions;
+using executorch::systemone::Choice;
+using executorch::systemone::Noul;
+using executorch::systemone::Questions;
+using executorch::systemone::kev::Kev;
 
 int main(int argc, char** argv) {
   if (argc < 3 || argc > 4) {
@@ -31,7 +32,7 @@ int main(int argc, char** argv) {
     std::cerr << "Cannot load tokenizer.json\n";
     return 1;
   }
-  kev::Kev model(module, tokenizer);
+  Kev model(module, tokenizer);
   const std::string state = argc == 4
       ? argv[3]
       : "I was charged twice for invoice 4411. Please refund the duplicate charge.";
 
@@ -18,6 +18,8 @@
 #include <executorch/extension/tensor/tensor.h>
 #include <pytorch/tokenizers/tokenizer.h>
 
+namespace executorch {
+namespace systemone {
 namespace kev {
 
 using executorch::aten::ScalarType;
@@ -356,3 +358,5 @@ Result<Answers> Kev::evaluate(
 }
 
 } // namespace kev
+} // namespace systemone
+} // namespace executorch
@@ -15,12 +15,14 @@
 #include <cstdint>
 #include <string>
 
-#include "api.h"
+#include "executorch/examples/systemone/api.h"
 
 namespace tokenizers {
 class Tokenizer;
 }
 
+namespace executorch {
+namespace systemone {
 namespace kev {
 
 class Kev;
@@ -70,3 +72,5 @@ class Kev final : public SystemOne {
 };
 
 } // namespace kev
+} // namespace systemone
+} // namespace executorch
@@ -12,9 +12,10 @@
 #include "kev.h"
 
 using executorch::extension::Module;
-using kev::Choice;
-using kev::Noul;
-using kev::Questions;
+using executorch::systemone::Choice;
+using executorch::systemone::Noul;
+using executorch::systemone::Questions;
+using executorch::systemone::kev::Kev;
 
 int main(int argc, char** argv) {
   if (argc < 3 || argc > 4) {
@@ -41,24 +42,27 @@ int main(int argc, char** argv) {
        Noul{"Does the customer explicitly ask for a refund?", {}}},
       {"duplicate_charge",
        Noul{"Was the customer charged more than once?", {}}}};
-  kev::Kev model(module, tokenizer);
+  Kev model(module, tokenizer);
   auto answers = model.system_one(state, questions);
   if (!answers.ok()) {
     std::cerr << executorch::runtime::to_string(answers.error()) << '\n';
     return 1;
   }
   for (const auto& [id, answer] : *answers) {
     std::cout << id << ": ";
-    if (const auto* choice = std::get_if<kev::ChoiceAnswer>(&answer)) {
+    if (const auto* choice =
+            std::get_if<executorch::systemone::ChoiceAnswer>(&answer)) {
       std::cout << choice->choice << " (confidence " << choice->confidence
                 << ")\n";
       for (const auto& [name, probability] : choice->probabilities) {
         std::cout << "  " << name << ": " << probability << '\n';
       }
-    } else if (const auto* noul = std::get_if<kev::NoulAnswer>(&answer)) {
+    } else if (
+        const auto* noul =
+            std::get_if<executorch::systemone::NoulAnswer>(&answer)) {
       std::cout << noul->noul << '\n';
     } else {
-      const auto& score = std::get<kev::ScoreAnswer>(answer);
+      const auto& score = std::get<executorch::systemone::ScoreAnswer>(answer);
       std::cout << score.score << " (confidence " << score.confidence << ")\n";
       for (size_t level = 0; level < score.probabilities.size(); ++level) {
         std::cout << "  " << level << " (" << score.legend.at(level)