Skip to content

reference.md

Latest commit

 

History

History
200 lines (163 loc) · 7.96 KB

reference.md

File metadata and controls

200 lines (163 loc) · 7.96 KB
last_updated 2026-04-17
author Tej Desai
applies_to v0.8.0

CARL Studio Reference

Detailed documentation for carl-studio. For the quick overview, see README.md.

Credential and provider setup lives in docs/auth.md.

Architecture

Layer 4  MCP Server       16 tools for AI agent consumption
         ──────────────────────────────────────────────────
Layer 3  CLI              carl start | doctor | project | train | run | observe | eval | infer | chat | frame
         ──────────────────────────────────────────────────
Layer 2  Training         CARLTrainer, CascadeRewardManager, environments
         ──────────────────────────────────────────────────
Layer 1  SDK              TrainingConfig, EvalRunner, CoherenceProbe, Settings
         ──────────────────────────────────────────────────
Layer 0  Primitives       compute_phi(), kappa, sigma, CoherenceTrace

The Reward

R_CARL = 0.50 * R_coherence + 0.30 * R_cloud + 0.20 * R_discontinuity
Component Measures Intuition
Multiscale coherence Phi consistency across dyadic block scales "Is the model coherent at all resolutions?"
Cloud quality P(selected) * Phi "Is it confident AND correct?"
Discontinuity targeting Sharp Phi transitions at structural boundaries "Does it commit at the right moments?"

Cascade Gating

CARL rewards are length-biased. Without gating, they dominate sparse task signal and cause mode collapse. The cascade solves this:

Stage A (early):   task rewards only         "learn to use tools"
Stage B (gated):   task + CARL rewards       "now do it coherently"

The gate self-calibrates from the task metric's running distribution. No hardcoded threshold.

The Conservation Law

kappa = 64/3          T* = kappa * d         (decompression boundary)
sigma = 3/16          kappa * sigma = 4      (bits per embedding dimension)
Phi = 1 - H(P)/log|V|                        (order parameter)

Three papers, independently reproducible:

CLI Reference

Core:

carl start                                Guided local-first bootstrap summary
carl doctor                               Readiness checks + blockers
carl project init                         Create carl.yaml interactively
carl project show                         Display project defaults
carl train [--config carl.yaml]           Train with CARL rewards
carl run list                             List locally tracked runs
carl run show <run-id>                    Inspect local run metadata
carl run status <run-id|job-id>           Remote status (resolves local IDs)
carl run logs <run-id|job-id>             Remote logs (resolves local IDs)
carl run stop <run-id|job-id>             Cancel remote job from local run ID
carl observe --url URL --run RUN          See coherence metrics on a Trackio run
carl observe --file PATH                  See coherence metrics from a local JSONL log
carl eval [--adapter HUB_ID]              Pass/fail checkpoint gate
carl infer                                Run local inference helper
carl chat [--session ID]                  Agentic chat with tool use, sessions, cost tracking
carl frame set/show/clear                 WorkFrame analytical lens (domain/function/role/objectives)

Namespaces:

carl camp ...                             Account/login/logout/sync/credits/marketplace/consent/contract/x402 surfaces
carl lab carlito ...                      Manage carlitos -- small specialized agents you train and spawn
carl lab curriculum ...                   Training curriculum FSM tracking
carl lab ...                              Experimental and advanced/internal workflows

Install notes:

pip install carl-studio                   Base CLI + one-shot observe
pip install 'carl-studio[training]'       Local train/eval stack
pip install 'carl-studio[hf]'             Hub jobs + publish
pip install 'carl-studio[tui]'            observe --live
pip install 'carl-studio[observe]'        observe --diagnose
pip install 'carl-studio[all]'            Everything

Auth notes:

HF Hub / HF Jobs / push   HF_TOKEN or prior `hf auth login`
Anthropic features        ANTHROPIC_API_KEY or --api-key
Camp platform truth       `carl camp login` / `carl camp logout` / `carl camp account`
Privacy consent           `carl camp consent show` / `carl camp consent update`
x402 payment rail         `carl camp x402 configure` / `carl camp x402 status`
Contract witnessing       `carl camp contract sign` / `carl camp contract verify`
Carlito management        `carl lab carlito list` / `carl lab carlito spawn` / `carl lab carlito show`
RunPod backend            RUNPOD_API_KEY
.env files                supported if you load them yourself; not auto-loaded

Optional workflows:

carl observe --live                       Real-time TUI dashboard
carl observe --diagnose                   Claude-powered analysis
carl train --send-it                      Full SFT->gate->GRPO->eval->push pipeline
carl lab mcp                              Start MCP server (16 tools)
carl lab repl                             Simple chat REPL (no tool use)

Compute Backends

Backend Flag VRAM
HuggingFace Jobs --compute l4x1 / a10g-large / a100-large / l40sx1 24-80 GB
Local --compute local Your GPU
Other backends Configure backend in carl.yaml / carl project Depends

Environments

Environment Tools Use Case
CodeSandboxEnv read_file, write_file, execute_code, run_shell Coding agents
SQLSandboxEnv execute_query, list_tables, describe_table, insert_data Data agents

Model Support

ModelSpec.from_pretrained() auto-detects architecture, modality, thinking mode, quantization, and LoRA targets from any HuggingFace config.json.

Model Status
Qwen 3.5 9B VLM Primary -- 92% task completion, 99% format
Qwen 3.5 35B MoE Tested (attention-only LoRA)
Gemma 4 Planned (TRL tool support pending)

Python API

Observe

from carl_studio.observe.data_source import TrackioSource

source = TrackioSource(
    space="wheattoast11-trackio",
    project="my-project",
    run="my-run",
)
frames = source.poll()
for f in frames:
    print(f"step={f.step}  phi={f.phi:.3f}  reward={f.reward_mean:.3f}")

Train

from carl_studio import CARLTrainer, TrainingConfig

trainer = CARLTrainer(TrainingConfig(
    run_name="my-agent",
    base_model="Qwen/Qwen3.5-9B",
    output_repo="username/my-model",
    method="grpo",
    dataset_repo="username/my-data",
    compute_target="a100-large",
))
run = await trainer.train()

Eval

carl eval --adapter username/my-model --phase phase2prime

Settings

carl config init            # Interactive setup
carl config preset research # Apply research preset (verbose, all metrics)
carl config set tier paid   # Set tier (free/paid)
carl config show            # Verify detected credentials (masked by default)

IP Boundaries

What Where License
Conservation law, Phi, rewards, CLI CARL Studio (this repo) MIT
Resonance LR, SLOT/TTT, Kuramoto, diagnosis terminals-runtime BUSL-1.1
Audio coherence (CHORD), cross-substrate Terminals Platform BUSL-1.1