Metadata-Version: 2.4
Name: chronohorn
Version: 0.1.1
Summary: Family-agnostic experiment tracker and architecture-search runtime for predictive descendants.
Author: Chronohorn contributors
License: MIT
Project-URL: Homepage, https://chronohorn.com/
Project-URL: Documentation, https://chronohorn.com/
Project-URL: Repository, https://github.com/asuramaya/chronohorn
Project-URL: Issues, https://github.com/asuramaya/chronohorn/issues
Project-URL: Changelog, https://github.com/asuramaya/chronohorn/blob/main/CHANGELOG.md
Keywords: predictive-coding,runtime,artifact-evaluation,compression,sequence-modeling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: decepticons>=0.1.1
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Provides-Extra: train
Requires-Dist: sentencepiece>=0.2; extra == "train"
Provides-Extra: torch
Requires-Dist: sentencepiece>=0.2; extra == "torch"
Requires-Dist: torch>=2.8; extra == "torch"
Provides-Extra: cuda
Requires-Dist: sentencepiece>=0.2; extra == "cuda"
Requires-Dist: torch>=2.8; extra == "cuda"
Requires-Dist: mamba-ssm>=2.0; extra == "cuda"
Requires-Dist: causal-conv1d>=1.4; extra == "cuda"
Provides-Extra: metal
Requires-Dist: sentencepiece>=0.2; extra == "metal"
Requires-Dist: mlx>=0.25; extra == "metal"
Dynamic: license-file

# Chronohorn

Family-agnostic experiment tracker and architecture-search runtime for predictive descendants. Built on the shared [`decepticons`](https://github.com/asuramaya/decepticons) kernel.

<p align="center">
  <img src="docs/chronohorn.jpg" alt="Chronohorn" width="520">
</p>

## What It Does

- **Tracks experiments** from any model family, stores them in SQLite, and keeps legality/trust state attached to results
- **Analyzes curves and frontiers** with saturation, marginal ranking, velocity, and ablation-board views
- **Runs the search loop** through manifest-driven fleet dispatch, drain, result pull-back, and auto-deepen/control surfaces
- **Exposes runtime state to agents** through 64 MCP tools, a terminal observer, and an HTTP runtime dashboard

Chronohorn is family-agnostic at the runtime layer. Family-specific mutation policy lives under `python/chronohorn/families/<name>/`; the shared mechanism layer stays in the [`decepticons`](https://github.com/asuramaya/decepticons) kernel.

## Quick Start

```bash
# Install from PyPI (decepticons kernel pulled automatically)
python3 -m pip install chronohorn

# Or monorepo dev install: shared kernel first, then runtime
python3 -m pip install -e ../decepticons
python3 -m pip install -e .

# Ingest results and view the observer/dashboard
chronohorn observe serve --result-dir out/results

# Emit a family-owned scan manifest
chronohorn fleet emit-family-matrix --family causal-bank --regime gated-retention

# Full daemon: drain + fleet probe + observer + MCP
chronohorn runtime --manifest manifests/frontier_gated_retention.jsonl

# CLI help
chronohorn --help
```

## MCP Integration

Chronohorn exposes a stateful MCP surface for experiment querying, frontier analysis, ablation tracking, fleet control, saturation detection, learning-curve comparison, and manifest/runtime management. The exact tool set changes with the runtime; the live registry is in [`python/chronohorn/mcp.py`](./python/chronohorn/mcp.py). Run `chronohorn mcp` for stdio transport. See [`.mcp.json`](./.mcp.json) for a client configuration example.

## Repo Boundary

The intended split is:

```text
decepticons -> chronohorn -> heinrich
kernel         runtime       evidence / audit
```

- `decepticons` owns reusable mechanisms, config validation, and export-friendly kernel surfaces
- `chronohorn` owns training, replay, scoring, scan emission, fleet execution, and runtime control
- `heinrich` is outside the runtime path and owns external evidence packaging

See [docs/REPO_BOUNDARY.md](./docs/REPO_BOUNDARY.md) and [docs/STACK.md](./docs/STACK.md) for the promoted boundary.

## Repo Guide

The repo has a few different kinds of material that matter for different reasons:

- [docs/README.md](./docs/README.md) points to canonical live docs vs historical docs
- [manifests/README.md](./manifests/README.md) explains named regimes, generated queue files, and archive intent
- [state/README.md](./state/README.md) explains the tracked runtime snapshot and handoff files
- [scripts/README.md](./scripts/README.md) explains which scripts are wrappers vs maintenance utilities

## Adding a Model Family

Create a package at `python/chronohorn/families/<name>/` implementing the `FamilyTrainingAdapter` protocol. The registry auto-discovers it — no manual registration. See `CLAUDE.md` for the full protocol reference and conventions.

## Current Focus

The active causal-bank search is organized around cheap O(n) architecture screening before promotion:

- `10k` rapid ablation lanes for mechanism screening
- scale/context survival rows aimed at pushing the frontier toward `1.0`
- primary learned-substrate experiments around `gated_delta`
- VRAM-tier-aware fleet placement so small CUDA rows can prefer the smallest sufficient GPU lane

Current manifests live under [`manifests/`](./manifests/), and current results/launch state live under [`out/results/`](./out/results/) and [`out/fleet/`](./out/fleet/).

## License

MIT — see [LICENSE](LICENSE).
