{
  "product": "NanoChat Web",
  "title": "NanoChat Web Runtime",
  "summary": "The browser runtime of nanochat, graded against the same Python reference.",
  "category": "ports",
  "version": 1,
  "source": "D:\\Dev\\Lab\\NanoChat",
  "commit": "c95059295dbd",
  "extractionMethod": "source-review-and-headless-tests",
  "evidenceGrade": "source",
  "entries": [
    {
      "key": "catalog:F01",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Tokenizer encoding contracts",
        "Ordered ordinary batch encoding"
      ],
      "value": "",
      "status": "yes",
      "note": "Encode an ordered batch into independent token arrays without changing input order.",
      "sourceRef": "tiktoken_importer.py; conversation.py; focused tests"
    },
    {
      "key": "catalog:F02",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Tokenizer encoding contracts",
        "Named prepend and append encoding"
      ],
      "value": "",
      "status": "yes",
      "note": "Resolve named special tokens and add them at text boundaries.",
      "sourceRef": "conversation.py; tokenizer_manifest.py"
    },
    {
      "key": "catalog:F03",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Tokenizer encoding contracts",
        "Raw integer prepend and append IDs"
      ],
      "value": "",
      "status": "yes",
      "note": "Accept already-resolved token IDs at text boundaries.",
      "sourceRef": "conversation.py; resident_session.py"
    },
    {
      "key": "catalog:F04",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Tokenizer encoding contracts",
        "Named and raw boundaries on batch input"
      ],
      "value": "",
      "status": "yes",
      "note": "Apply named or integer boundary tokens to every item in a batch.",
      "sourceRef": "resident_session.py; test_resident_session.py"
    },
    {
      "key": "catalog:F05",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Tokenizer encoding contracts",
        "Raw single-token bytes"
      ],
      "value": "",
      "status": "yes",
      "note": "Return the exact byte sequence represented by one token ID.",
      "sourceRef": "tokenizer_manifest.py; tokenizer_metrics.py"
    },
    {
      "key": "catalog:F06",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Tokenizer encoding contracts",
        "Supplementary-plane Unicode encoding"
      ],
      "value": "",
      "status": "yes",
      "note": "Round-trip Unicode text whose code points require surrogate pairs in UTF-16 runtimes.",
      "sourceRef": "tiktoken_importer.py; tokenizer_metrics.py; tests"
    },
    {
      "key": "catalog:F07",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Training data pipeline",
        "Tokenizer training and official data acquisition"
      ],
      "value": "",
      "status": "yes",
      "note": "Train the tokenizer from streamed ClimbMix text and acquire official parquet shards safely.",
      "sourceRef": "bpe_tokenizer_trainer.py; parquet_document_reader.py; tests"
    },
    {
      "key": "catalog:F08",
      "path": [
        "Runtime",
        "Tokenizer and data",
        "Training data pipeline",
        "Best-fit packing and resumable distributed loader"
      ],
      "value": "",
      "status": "yes",
      "note": "Create BOS-aligned packed rows with rank slicing and resumable parquet position state.",
      "sourceRef": "distributed_bestfit.py; partitioned_bestfit_iterator.py; tests"
    },
    {
      "key": "catalog:F09",
      "path": [
        "Runtime",
        "Pretraining",
        "Model architecture and optimization",
        "Model architecture and CPU optimization"
      ],
      "value": "",
      "status": "yes",
      "note": "Build the NanoChat GPT and train it with AdamW and Muon-compatible optimization.",
      "sourceRef": "nanochat_model.py; language_model_training.py; optimizer.py; tests"
    },
    {
      "key": "catalog:F10",
      "path": [
        "Runtime",
        "Pretraining",
        "Training policy",
        "Compute-optimal depth scaling and schedules"
      ],
      "value": "",
      "status": "yes",
      "note": "Scale width, heads, tokens, batches, learning rates, decay, and accumulation from depth.",
      "sourceRef": "training_scale.py; training_schedule.py; tests"
    },
    {
      "key": "catalog:F11",
      "path": [
        "Runtime",
        "Pretraining",
        "Accelerated execution",
        "CUDA, dtype, compilation, and FP8"
      ],
      "value": "",
      "status": "yes",
      "note": "Run base training with CUDA-aware dtype selection, compilation, scaling, and optional FP8.",
      "sourceRef": "gpu_diagnostics.py; language_model_training.py"
    },
    {
      "key": "catalog:F12",
      "path": [
        "Runtime",
        "Supervised fine-tuning",
        "Conversation training",
        "Conversation render, shifted loss mask, and masked scoring"
      ],
      "value": "",
      "status": "yes",
      "note": "Render conversations and optimize only the intended assistant tokens with shifted masks.",
      "sourceRef": "conversation.py; task_batches.py; task_training.py; tests"
    },
    {
      "key": "catalog:F13",
      "path": [
        "Runtime",
        "Supervised fine-tuning",
        "Conversation training",
        "Best-fit multi-conversation row packing"
      ],
      "value": "",
      "status": "yes",
      "note": "Pack multiple rendered conversations into fixed SFT rows while preserving BOS alignment and masks.",
      "sourceRef": "task_batches.py; test_task_batches.py"
    },
    {
      "key": "catalog:F14",
      "path": [
        "Runtime",
        "Supervised fine-tuning",
        "Conversation training",
        "Upstream SmolTalk and task mixture ordering"
      ],
      "value": "",
      "status": "yes",
      "note": "Train from the ordered SmolTalk, ARC, GSM8K, and identity mixture.",
      "sourceRef": "task_dataset.py; task_fine_tuning.py; tests"
    },
    {
      "key": "catalog:F15",
      "path": [
        "Runtime",
        "Supervised fine-tuning",
        "Task dataset semantics",
        "Finite task start, stop, and step slicing"
      ],
      "value": "",
      "status": "yes",
      "note": "Expose bounded logical views over task datasets with validated slice semantics.",
      "sourceRef": "task_dataset.py; dataset_split_planner.py; tests"
    },
    {
      "key": "catalog:F16",
      "path": [
        "Runtime",
        "Supervised fine-tuning",
        "Task dataset semantics",
        "Ordered task dataset sequences"
      ],
      "value": "",
      "status": "yes",
      "note": "Concatenate tasks into an ordered curriculum without losing per-task indexing.",
      "sourceRef": "task_dataset.py; task_batches.py"
    },
    {
      "key": "catalog:F17",
      "path": [
        "Runtime",
        "Supervised fine-tuning",
        "Task dataset semantics",
        "Immutable HubDataset row views"
      ],
      "value": "",
      "status": "yes",
      "note": "Return independent Python row objects from an immutable Arrow-backed logical view.",
      "sourceRef": "task_dataset.py; test_task_dataset.py"
    },
    {
      "key": "catalog:F18",
      "path": [
        "Runtime",
        "Reinforcement learning",
        "Rollout policy optimization",
        "GSM8K rollout policy optimization"
      ],
      "value": "",
      "status": "yes",
      "note": "Optimize sampled GSM8K completions using exact-answer rewards and policy gradients.",
      "sourceRef": "gsm8k_package_evaluation.py; task_training.py"
    },
    {
      "key": "catalog:F19",
      "path": [
        "Runtime",
        "Checkpoints and resume",
        "Checkpoint lifecycle",
        "Atomic save, load, resume, and latest-native recovery"
      ],
      "value": "",
      "status": "yes",
      "note": "Persist model, optimizer, metadata, loader, and loop state and recover a selected or latest checkpoint.",
      "sourceRef": "training_checkpoint.py; text_training.py; recovery tests"
    },
    {
      "key": "catalog:F20",
      "path": [
        "Runtime",
        "Checkpoints and resume",
        "Checkpoint lifecycle",
        "Task-specialization warm start"
      ],
      "value": "",
      "status": "yes",
      "note": "Initialize SFT from a base model and optionally restore optimizer momentum while retaining SFT rates.",
      "sourceRef": "task_fine_tuning.py; task_training.py; tests"
    },
    {
      "key": "catalog:F21",
      "path": [
        "Runtime",
        "Checkpoints and resume",
        "Checkpoint lifecycle",
        "Real upstream checkpoint and tokenizer interchange"
      ],
      "value": "",
      "status": "yes",
      "note": "Load and save the native model, optimizer, metadata, and tokenizer files used by upstream scripts.",
      "sourceRef": "upstream_checkpoint_importer.py; tiktoken_importer.py; tests"
    },
    {
      "key": "catalog:F22",
      "path": [
        "Runtime",
        "Inference, chat, and tool use",
        "Generation and chat",
        "KV-cached generation and sampling"
      ],
      "value": "",
      "status": "yes",
      "note": "Prefill once, clone cached attention state, and sample reproducible continuations with limits.",
      "sourceRef": "kv_cache.py; resident_session.py; tests"
    },
    {
      "key": "catalog:F23",
      "path": [
        "Runtime",
        "Inference, chat, and tool use",
        "Generation and chat",
        "Token-native chat"
      ],
      "value": "",
      "status": "yes",
      "note": "Represent and extend the conversation as native tokens with explicit terminal boundaries.",
      "sourceRef": "conversation.py; resident_session.py; tests"
    },
    {
      "key": "catalog:F24",
      "path": [
        "Runtime",
        "Inference, chat, and tool use",
        "Generation and chat",
        "Headless chat CLI"
      ],
      "value": "",
      "status": "yes",
      "note": "Run interactive or prompt-mode terminal chat over a loaded checkpoint.",
      "sourceRef": "chat_cli.py; test_chat_cli.py; resident_session.py; tests"
    },
    {
      "key": "catalog:F25",
      "path": [
        "Runtime",
        "Inference, chat, and tool use",
        "Tool execution",
        "Safe calculator evaluator"
      ],
      "value": "",
      "status": "yes",
      "note": "Evaluate an allowlisted subset of arithmetic and string-count expressions with a timeout.",
      "sourceRef": "calculator.py; calculator_tool_state.py; tests"
    },
    {
      "key": "catalog:F26",
      "path": [
        "Runtime",
        "Inference, chat, and tool use",
        "Tool execution",
        "Arbitrary Python execution"
      ],
      "value": "",
      "status": "yes",
      "note": "Run generated Python in a constrained subprocess with resource and environment controls.",
      "sourceRef": "humaneval_preparation.py; conversation.py"
    },
    {
      "key": "catalog:F27",
      "path": [
        "Runtime",
        "Evaluation and benchmarks",
        "Quality evaluation",
        "BPB, CORE, GSM8K, ARC, and MMLU evaluations"
      ],
      "value": "",
      "status": "yes",
      "note": "Compute validation bits-per-byte and the core base-model task suite.",
      "sourceRef": "bpb_package_evaluation.py; core_package_evaluation.py; gsm8k_package_evaluation.py; tests"
    },
    {
      "key": "catalog:F28",
      "path": [
        "Runtime",
        "Evaluation and benchmarks",
        "Quality evaluation",
        "ChatCORE orchestration and aggregation"
      ],
      "value": "",
      "status": "yes",
      "note": "Run and aggregate generative GSM8K and HumanEval with categorical ARC and MMLU chat evaluations.",
      "sourceRef": "gsm8k_package_evaluation.py; humaneval_preparation.py; chat_categorical_package_evaluation.py"
    },
    {
      "key": "catalog:F29",
      "path": [
        "Runtime",
        "Evaluation and benchmarks",
        "Quality evaluation",
        "Multiple-choice prompt formatting"
      ],
      "value": "",
      "status": "yes",
      "note": "Render categorical task choices into the canonical conversation prompt and answer contract.",
      "sourceRef": "chat_categorical_evaluation.py; tests"
    },
    {
      "key": "catalog:F30",
      "path": [
        "Runtime",
        "Evaluation and benchmarks",
        "Quality evaluation",
        "HumanEval"
      ],
      "value": "",
      "status": "yes",
      "note": "Render HumanEval prompts and score generated Python completions through the constrained executor.",
      "sourceRef": "humaneval_preparation.py; tests"
    },
    {
      "key": "catalog:F31",
      "path": [
        "Runtime",
        "Evaluation and benchmarks",
        "Inference performance benchmark",
        "Inference benchmark matrix"
      ],
      "value": "",
      "status": "yes",
      "note": "Measure prefill, decode, batch, prompt, weight, and VRAM characteristics.",
      "sourceRef": "infer_benchmark.py; resident_session.py; tests"
    },
    {
      "key": "catalog:F32",
      "path": [
        "Runtime",
        "Distributed runtime and scripts",
        "Distributed training and data",
        "DDP training and coordinated overflow and checkpoint state"
      ],
      "value": "",
      "status": "yes",
      "note": "Coordinate accumulation, overflow decisions, metrics, and checkpoint participation across ranks.",
      "sourceRef": "language_model_training.py; distributed_data_partition.py"
    },
    {
      "key": "catalog:F33",
      "path": [
        "Runtime",
        "Distributed runtime and scripts",
        "Distributed training and data",
        "Parquet row-group partition and resume planning"
      ],
      "value": "",
      "status": "yes",
      "note": "Assign row groups by rank and resume from a recorded parquet file, row group, and epoch.",
      "sourceRef": "distributed_data_partition.py; parquet_document_reader.py; partitioned_bestfit_iterator.py"
    },
    {
      "key": "catalog:F34",
      "path": [
        "Runtime",
        "Distributed runtime and scripts",
        "Attention runtime",
        "Flash Attention 3 and SDPA fallback"
      ],
      "value": "",
      "status": "yes",
      "note": "Use FA3 where available and a behaviorally tested SDPA fallback otherwise.",
      "sourceRef": "transformer_block.py; test_transformer_block.py"
    },
    {
      "key": "catalog:F35",
      "path": [
        "Runtime",
        "Distributed runtime and scripts",
        "Pipeline automation and baseline",
        "Official pipeline and run scripts"
      ],
      "value": "",
      "status": "yes",
      "note": "Orchestrate tokenizer, pretraining, SFT, RL, evaluation, and chat workflows.",
      "sourceRef": "package.json; worker.py; session_worker.py"
    },
    {
      "key": "catalog:F36",
      "path": [
        "Runtime",
        "Distributed runtime and scripts",
        "Pipeline automation and baseline",
        "Canonical headless test baseline"
      ],
      "value": "",
      "status": "yes",
      "note": "Run the upstream tokenizer, inference, task, optimizer, execution, and attention fallback test modules.",
      "sourceRef": "NanoChat.Engine/tests; NanoChat.AI/tests"
    }
  ]
}