Metadata-Version: 2.4
Name: carl-core
Version: 0.1.2
Summary: Coherence math primitives for CARL (Coherence-Aware Reinforcement Learning)
Project-URL: Homepage, https://github.com/wheattoast11/carl
Project-URL: Documentation, https://github.com/wheattoast11/carl#readme
Project-URL: Repository, https://github.com/wheattoast11/carl
Project-URL: Issues, https://github.com/wheattoast11/carl/issues
Author-email: Tej Desai <tej@terminals.tech>
License-Expression: MIT
License-File: LICENSE
Keywords: carl,coherence,entropy,information-theory,reinforcement-learning,reward-shaping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: numpy
Requires-Dist: pydantic>=2.9
Description-Content-Type: text/markdown

# carl-core

Coherence math primitives for CARL — the foundational per-token field that every CARL metric derives from.

## Install

```
pip install carl-core
```

## Use

```python
from carl_core import CoherenceTrace, compute_phi

# From logits:
trace = CoherenceTrace.from_logits(logits, token_ids=tokens, step=0)
print(trace.phi_mean, trace.cloud_quality, trace.carl_reward())

# Raw phi:
phi, probs, entropy = compute_phi(logits)
```

## What's inside

- `CoherenceTrace` — per-token coherence field (phi, entropy, selected_prob, delta_phi)
- `CoherenceProbe` / `CoherenceSnapshot` — probe + snapshot for training-step metrics
- `CoherenceObserver` — periodic Claude-backed training health assessment
- `FrameBuffer` / `FrameRecord` — rolling temporal Phi buffer
- `compute_phi()` — order parameter from logits: `phi = 1 - H/log|V|`
- Constants: `KAPPA = 64/3`, `SIGMA = 3/16`, `DEFECT_THRESHOLD`, `T_STAR(d)`
- `InteractionChain` / `Step` / `ActionType` — typed interaction trace

## Depends on

numpy, pydantic.

## Part of

Carl Studio — Coherence-Aware Reinforcement Learning.
Full docs: https://github.com/wheattoast11/carl
