# CARL Studio

> Coherence-Aware Reinforcement Learning SDK. Train, observe, and evaluate LLMs
> using information-theoretic reward signals. pip install carl-studio.

## API
- [TrainingConfig](src/carl_studio/types/config.py): Pydantic config — model, method, compute, rewards, cascade
- [CARLSettings](src/carl_studio/settings.py): Layered settings — env vars, ~/.carl/config.yaml, presets
- [CoherenceProbe](src/carl_studio/primitives/coherence_probe.py): Measure Phi, entropy, discontinuities, cloud quality from logits
- [CoherenceTrace](src/carl_studio/primitives/coherence_trace.py): Per-token arrays — phi, entropy, selected_prob, delta_phi
- [CARLReward](src/carl_studio/training/rewards/composite.py): 50% multiscale + 30% cloud + 20% discontinuity
- [CascadeManager](src/carl_studio/training/cascade.py): Adaptive stage gating — self-calibrating from metric distribution
- [EvalRunner](src/carl_studio/eval/runner.py): Phase 1 (tool-call) + Phase 2' (environment) eval with 3-format parser
- [CARLTrainer](src/carl_studio/training/trainer.py): Async dispatch to HF Jobs, RunPod, local
- [ComputeBackend](src/carl_studio/compute/protocol.py): Protocol for compute backends
- [HFJobsBackend](src/carl_studio/compute/hf_jobs.py): HuggingFace Jobs — provision, execute, status, logs, stop
- [Tier](src/carl_studio/tier.py): FREE/PAID gating from cached camp subscription truth
- [ConsentManager](src/carl_studio/consent.py): Privacy-first consent state machine — all flags off by default
- [X402Client](src/carl_studio/x402.py): x402 HTTP payment rail client — no web3 dep, facilitator-based
- [ContractWitness](src/carl_studio/contract.py): Chain-agnostic service agreement with deterministic witness hashing
- [CarlitoRegistry](src/carl_studio/carlito.py): Agent spawning from graduated curriculum tracks

## CLI
- `carl observe --url URL`: Crystal metrics on any Trackio run (no GPU)
- `carl observe --live --url URL`: Real-time Textual TUI dashboard (FREE + `carl-studio[tui]`)
- `carl observe --diagnose`: Claude-powered coherence diagnosis (FREE, BYOK Anthropic)
- `carl train --model MODEL --method grpo --compute a100`: Train with CARL rewards
- `carl train --send-it`: Full autonomous pipeline: SFT -> gate -> GRPO -> eval -> push (PAID)
- `carl eval --adapter HUB_ID`: Run eval gate on checkpoint
- `carl eval --remote`: Submit eval as HF Job
- `carl config show`: Display settings
- `carl config init`: Interactive setup wizard
- `carl config preset research|production|quick`: Apply preset
- `carl run status ID`: Job status
- `carl run logs ID`: Job logs
- `carl run stop ID`: Cancel job
- `carl bundle`: Generate self-contained PEP 723 training script
- `carl camp account`: Inspect managed tier, credits, and account capabilities
- `carl camp logout`: Drop managed session and return to local-first FREE mode
- `carl camp consent show/update/reset`: Privacy-first consent management (all off by default)
- `carl camp x402 status/configure/check`: x402 HTTP payment rail configuration
- `carl camp contract sign/list/verify`: Service contract witnessing with deterministic hashes
- `carl carlito list/show/spawn/retire`: Manage carlitos — small specialized agents from graduated tracks
- `carl lab mcp`: Start MCP server with 9 tools (PAID)

## Constants (never configurable)
- KAPPA = 64/3 (conservation constant)
- SIGMA = 3/16 (semantic quantum)
- DEFECT_THRESHOLD = 0.03 (minimum |delta_phi|)
- KAPPA * SIGMA = 4 (bits per dimension)

## Environments
- [CodeSandboxEnv](src/carl_studio/environments/builtins/code_sandbox.py): read_file, write_file, execute_code, run_shell
- [SQLSandboxEnv](src/carl_studio/environments/builtins/sql_sandbox.py): execute_query, list_tables, describe_table, insert_data

## Config Schema
- `TrainingConfig.model_json_schema()` for full JSON Schema
- `CARLSettings.load()` for layered config resolution

## Tiers
- FREE: observe, observe --live, observe --diagnose, train, eval, bench, align, learn, push, bundle, compute
- PAID: --send-it, auto-gating, scheduled runs, sync, credits, marketplace publish, MCP server, orchestration
