carl-core 0.1.2__tar.gz

carl_core-0.1.2/.gitignore

@@ -0,0 +1,41 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.env
+.venv/
+venv/
+env/
+
+# Local model-routing cache (regenerated at runtime)
+.model_cache.json
+.model_cache*.json
+
+# macOS Finder duplicate artifacts
+* 2.py
+* 3.py
+* 2.json
+* 3.json
+* 2.md
+* 3.md
+
+# Ad-hoc scratch / patch scripts at repo root (do not commit)
+/fix_*.py
+/patch_*.py
+.claude/scheduled_tasks.lock
+# v0.18 Track B — project-local .carl/ scaffold
+.carl/
+
+# Project-local training config. CARLSettings layers this file in, and
+# users commonly drop dataset paths, hub namespaces, and occasionally
+# secrets into it. Keep it out of version control by default — commit a
+# `carl.yaml.example` template instead if you want to share settings.
+carl.yaml

carl_core-0.1.2/CLAUDE.md

@@ -0,0 +1,63 @@
+# carl-core — scoped project memory
+
+## Purpose
+
+The foundational layer of the CARL stack. Pure coherence math + interaction trace primitive. Every CARL metric is a reduction of the per-token coherence field defined here. Zero network calls, zero training deps.
+
+## Public API
+
+- `CoherenceTrace`, `select_traces` (from `coherence_trace`)
+- `CoherenceProbe`, `CoherenceSnapshot` (from `coherence_probe`)
+- `CoherenceObserver` (from `coherence_observer`, anthropic is an optional, lazy import)
+- `FrameBuffer`, `FrameRecord` (from `frame_buffer`)
+- `compute_phi` (from `math`)
+- `KAPPA`, `SIGMA`, `DEFECT_THRESHOLD`, `T_STAR` (from `constants`)
+- `InteractionChain`, `Step`, `ActionType` (from `interaction`)
+  - `Step.probe_call: dict | None` (v0.11) — fingerprint of the coherence
+    probe invocation that populated phi/kuramoto_r/channel_coherence.
+    12-hex sha256 digests, not full payloads.
+  - `InteractionChain.register_coherence_probe(fn)` / `clear_coherence_probe()` —
+    opt-in hook invoked at `record()` for `LLM_REPLY` / `TOOL_CALL` /
+    `TRAINING_STEP` / `EVAL_PHASE` / `REWARD` when no explicit coherence
+    kwargs are passed.
+- `PresenceReport`, `compose_presence_report` (from `presence`, v0.11)
+- `success_rate_probe` (from `presence`, v0.11) — default endogenous probe;
+  estimates `kuramoto_r` from chain's tail success rate per action type.
+- `BreakAndRetryStrategy`, `CircuitOpenError` (from `resilience`, v0.8) —
+  composes `RetryPolicy` + `CircuitBreaker`. Used by x402 facilitator calls
+  and `carl update`'s PyPI fetch.
+- `CARLError` + subclasses (from `errors`): `ConfigError`, `ValidationError`,
+  `CredentialError`, `NetworkError`, `BudgetError`, `PermissionError`,
+  `CARLTimeoutError`. All carry stable `code` under `carl.<namespace>`.
+- `canonical_json`, `content_hash`, `content_hash_bytes` (from `hashing`)
+- `CircuitBreaker`, `RetryPolicy`, `retry`, `async_retry`, `poll` (from `retry`)
+- `PathEscape`, `SandboxedPath`, `safe_resolve`, `within` (from `safepath`)
+- `Tier`, `FEATURE_TIERS`, `TierGateError`, `feature_tier`, `tier_allows` (from `tier`)
+- `MemoryItem`, `MemoryLayer`, `MemoryStore` (from `memory`)
+- `InteractionStore` (from `interaction_store`)
+
+## Dependencies
+
+- **Required:** `numpy`, `pydantic>=2.9`
+- **Optional (lazy-imported):** `anthropic` (for `CoherenceObserver`), `terminals_runtime` (for private math helpers — graceful fallback)
+
+## Depends on us
+
+- `carl_studio.training.*` — rewards, probes, trace callback
+- `carl_studio.eval.runner` — evaluation gating
+- `carl_studio.observe.*` — training dashboard
+
+## Conventions
+
+- `from __future__ import annotations` at top of every file.
+- Modern type syntax (`list[X]`, `dict[K, V]`, `X | None`).
+- Pydantic v2 models for configs and serialized data.
+- No heavy imports at module level — keep import time fast.
+- Constants are module-level, derived from conservation law (NOT tuning parameters).
+
+## Do NOT
+
+- Do NOT add torch, transformers, trl, or any training deps here.
+- Do NOT add HTTP clients or API wrappers other than the existing lazy `anthropic` import in `coherence_observer`.
+- Do NOT import from `carl_studio.*` — carl-core is the foundation; it depends on nothing upstream.
+- Do NOT rename constants (`KAPPA`, `SIGMA`) — these are mathematical constants from the conservation law, with published DOIs.

carl_core-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intuition Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

carl_core-0.1.2/PKG-INFO

@@ -0,0 +1,70 @@
+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

carl_core-0.1.2/README.md

@@ -0,0 +1,41 @@
+# 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

carl_core-0.1.2/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "carl-core"
+version = "0.1.2"
+description = "Coherence math primitives for CARL (Coherence-Aware Reinforcement Learning)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Tej Desai", email = "tej@terminals.tech" },
+]
+keywords = [
+    "coherence",
+    "information-theory",
+    "entropy",
+    "carl",
+    "reinforcement-learning",
+    "reward-shaping",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "numpy",
+    "pydantic>=2.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/wheattoast11/carl"
+Documentation = "https://github.com/wheattoast11/carl#readme"
+Repository = "https://github.com/wheattoast11/carl"
+Issues = "https://github.com/wheattoast11/carl/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/carl_core"]
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+pythonVersion = "3.11"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

carl_core-0.1.2/src/carl_core/__init__.py

@@ -0,0 +1,233 @@
+"""carl-core: coherence math primitives for CARL.
+
+This package is the foundation of the CARL stack. Every metric is a reduction
+of the per-token CoherenceTrace field defined here. Zero training dependencies,
+zero network calls — pure math + a typed interaction trace primitive.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.2"
+
+from carl_core.constants import KAPPA, SIGMA, DEFECT_THRESHOLD, T_STAR
+from carl_core.coherence_trace import CoherenceTrace, LayeredTrace, select_traces
+from carl_core.coherence_probe import (
+    CARL_LAYER_PROBE_ENABLED,
+    CoherenceProbe,
+    CoherenceSnapshot,
+)
+from carl_core.coherence_observer import CoherenceObserver
+from carl_core.frame_buffer import FrameBuffer, FrameRecord
+from carl_core.math import compute_phi
+from carl_core.interaction import ActionType, InteractionChain, Step
+from carl_core.presence import PresenceReport, compose_presence_report, success_rate_probe
+from carl_core.interaction_store import InteractionStore
+from carl_core.errors import (
+    CARLError,
+    ConfigError,
+    ValidationError,
+    CredentialError,
+    NetworkError,
+    BudgetError,
+    PermissionError,
+    CARLTimeoutError,
+)
+from carl_core.hashing import canonical_json, content_hash, content_hash_bytes
+from carl_core.memory import MemoryItem, MemoryLayer, MemoryStore
+from carl_core.retry import (
+    CircuitBreaker,
+    CircuitState,
+    RetryPolicy,
+    async_retry,
+    poll,
+    retry,
+)
+from carl_core.resilience import BreakAndRetryStrategy, CircuitOpenError
+from carl_core.safepath import PathEscape, SandboxedPath, safe_resolve, within
+from carl_core.tier import (
+    FEATURE_TIERS,
+    Tier,
+    TierGateError,
+    feature_tier,
+    tier_allows,
+)
+from carl_core.timeutil import ISO8601_Z, now_iso, now_iso_ms
+from carl_core.eml import (
+    CLAMP_X,
+    EPS,
+    MAX_DEPTH,
+    EMLNode,
+    EMLOp,
+    EMLTree,
+    eml,
+    eml_array,
+    eml_scalar_reward,
+)
+from carl_core.resonant import Resonant, compose_resonants, make_resonant
+from carl_core.signing import (
+    MIN_SECRET_LEN,
+    SIG_LEN,
+    sign_platform_countersig,
+    sign_tree_software,
+    verify_platform_countersig,
+    verify_software_signature,
+)
+from carl_core.heartbeat import (
+    ChainAppender,
+    GradientFn,
+    HeartbeatConfig,
+    HeartbeatState,
+    adam_step,
+    detect_resonant_modes,
+    heartbeat,
+    initial_state,
+    is_resonant,
+    run_heartbeat,
+)
+from carl_core.optimizer_state import (
+    DEFAULT_OPT_STATE_DIR,
+    AdamMoments,
+    OptimizerStateStore,
+)
+from carl_core.connection import (
+    VALID_TRANSITIONS,
+    AsyncBaseConnection,
+    BaseConnection,
+    CARLConnectionError,
+    ChannelCoherence,
+    ConnectionAuthError,
+    ConnectionBase,
+    ConnectionClosedError,
+    ConnectionDirection,
+    ConnectionKind,
+    ConnectionPolicyError,
+    ConnectionRegistry,
+    ConnectionScope,
+    ConnectionSpec,
+    ConnectionState,
+    ConnectionStats,
+    ConnectionTransitionError,
+    ConnectionTransport,
+    ConnectionTrust,
+    ConnectionUnavailableError,
+    can_transition,
+    channel_coherence_diff,
+    channel_coherence_distance,
+    get_registry,
+    reset_registry,
+)
+
+__all__ = [
+    "KAPPA",
+    "SIGMA",
+    "DEFECT_THRESHOLD",
+    "T_STAR",
+    "CoherenceTrace",
+    "LayeredTrace",
+    "select_traces",
+    "CARL_LAYER_PROBE_ENABLED",
+    "CoherenceProbe",
+    "CoherenceSnapshot",
+    "CoherenceObserver",
+    "FrameBuffer",
+    "FrameRecord",
+    "compute_phi",
+    "ActionType",
+    "InteractionChain",
+    "InteractionStore",
+    "Step",
+    "PresenceReport",
+    "compose_presence_report",
+    "success_rate_probe",
+    "CARLError",
+    "ConfigError",
+    "ValidationError",
+    "CredentialError",
+    "NetworkError",
+    "BudgetError",
+    "PermissionError",
+    "CARLTimeoutError",
+    "canonical_json",
+    "content_hash",
+    "content_hash_bytes",
+    "MemoryItem",
+    "MemoryLayer",
+    "MemoryStore",
+    "CircuitBreaker",
+    "CircuitState",
+    "RetryPolicy",
+    "async_retry",
+    "poll",
+    "retry",
+    "BreakAndRetryStrategy",
+    "CircuitOpenError",
+    "PathEscape",
+    "SandboxedPath",
+    "safe_resolve",
+    "within",
+    "Tier",
+    "FEATURE_TIERS",
+    "TierGateError",
+    "feature_tier",
+    "tier_allows",
+    # time helpers
+    "ISO8601_Z",
+    "now_iso",
+    "now_iso_ms",
+    # connection primitive
+    "ConnectionSpec",
+    "ConnectionScope",
+    "ConnectionKind",
+    "ConnectionDirection",
+    "ConnectionTransport",
+    "ConnectionTrust",
+    "ConnectionState",
+    "VALID_TRANSITIONS",
+    "can_transition",
+    "CARLConnectionError",
+    "ConnectionUnavailableError",
+    "ConnectionAuthError",
+    "ConnectionTransitionError",
+    "ConnectionClosedError",
+    "ConnectionPolicyError",
+    "BaseConnection",
+    "AsyncBaseConnection",
+    "ConnectionBase",
+    "ConnectionStats",
+    "ConnectionRegistry",
+    "get_registry",
+    "reset_registry",
+    # channel coherence (cross-channel observable)
+    "ChannelCoherence",
+    "channel_coherence_diff",
+    "channel_coherence_distance",
+    # EML primitive (Odrzywolek magma)
+    "EPS",
+    "MAX_DEPTH",
+    "CLAMP_X",
+    "EMLOp",
+    "EMLNode",
+    "EMLTree",
+    "eml",
+    "eml_array",
+    "eml_scalar_reward",
+    # Resonant (perceive -> cognize -> act)
+    "Resonant",
+    "make_resonant",
+    "compose_resonants",
+    # Heartbeat — CARL standing-wave loop
+    "HeartbeatState",
+    "HeartbeatConfig",
+    "GradientFn",
+    "ChainAppender",
+    "adam_step",
+    "heartbeat",
+    "is_resonant",
+    "run_heartbeat",
+    "detect_resonant_modes",
+    "initial_state",
+    # Optimizer state — durable Adam (m, v)
+    "DEFAULT_OPT_STATE_DIR",
+    "AdamMoments",
+    "OptimizerStateStore",
+    "__version__",
+]