DECACAP LOCAL COMPANION
=======================

Purpose
-------
This loopback-only companion connects the DecaCap Workbench in your browser to
your own local model runtime. It also prepares approved prompt/output pairs and
can launch a real local fine-tuning process when a compatible toolkit exists.

Nothing is installed on DecaCap's server. Your model files, datasets, adapters,
training logs, and pairing token stay on your computer.

Quick start
-----------
1. Install and start a local runtime. Ollama is the default. LM Studio,
   llama.cpp, vLLM, and other OpenAI-compatible servers can be selected in the
   generated configuration file.
2. Run:

   Windows:
     double-click start-windows.bat

   macOS or Linux:
     python3 decacap_companion.py

3. On first start, the companion creates decacap-companion.json and prints a
   pairing token.
4. Open DecaCap Workbench, click GoldCap, open Connection + Learning Settings,
   and paste the pairing token.
5. Choose the runtime model name shown by GoldCap.

Real training
-------------
Data preparation is not training. The companion always writes a canonical
chat-format train.jsonl, plus the requested export format. A real training job
starts only when one of these user-owned profiles is ready:

- MLX LoRA / QLoRA on Apple silicon:
    pip install "mlx-lm[train]"

- Custom command:
  Set training.custom_command in decacap-companion.json. The browser cannot
  submit or alter this command. Available placeholders:
    {base_model}
    {data_dir}
    {train_file}
    {output_dir}
    {iterations}

Axolotl and LLaMA Factory are detected and reported, but their YAML settings
depend on the exact base model and template. Configure either through the
custom command rather than accepting model-specific command text from a
website.

Example custom command
----------------------
For an existing Axolotl YAML that already points to the DecaCap train file:

  "custom_command": [
    "axolotl",
    "train",
    "C:\\path\\to\\your\\config.yml"
  ]

Security boundaries
-------------------
- Binds only to 127.0.0.1.
- Requires a random bearer pairing token.
- Accepts browser requests only from the DecaCap production origin and local
  agent-preview origins listed in decacap-companion.json.
- Refuses remote runtime addresses by default.
- Never accepts an executable or shell command from the website.
- Runs commands without a shell.
- Stores all artifacts under decacap-local-data beside the companion.
- Does not impose a duration cutoff on local inference. The Workbench user owns
  stop authority in Solo mode; the assigned Queen supervisor owns it in
  Collaboration and Dual modes.

Runtime configuration
---------------------
The generated decacap-companion.json defaults to Ollama:

  "runtime": {
    "type": "ollama",
    "base_url": "http://127.0.0.1:11434",
    "api_key": "",
    "default_model": ""
  }

For an OpenAI-compatible local server:

  "runtime": {
    "type": "openai-compatible",
    "base_url": "http://127.0.0.1:1234",
    "api_key": "",
    "default_model": ""
  }

Restart the companion after editing the configuration file.
