Metadata-Version: 2.4
Name: coldhat
Version: 0.1.0
Summary: Your AI rules on any chat in one line: author, check, publish and measure coldHat hats.
Author: Vincent Gonzalez
License-Expression: MIT
Project-URL: Homepage, https://coldhat.f-keys.com
Project-URL: Source, https://github.com/vince-gonzalez/coldhat
Project-URL: Issues, https://github.com/vince-gonzalez/coldhat/issues
Keywords: ai,llm,claude,chatgpt,grok,system-prompt,mcp,evals,prompt-engineering
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.13; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=3.28; extra == "openai"
Provides-Extra: all
Requires-Dist: anthropic>=1.13; extra == "all"
Requires-Dist: openai>=3.28; extra == "all"
Dynamic: license-file

```
╔════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                            ║
║                  ██████╗ ██████╗ ██╗     ██████╗ ██╗  ██╗ █████╗ ████████╗                 ║
║                 ██╔════╝██╔═══██╗██║     ██╔══██╗██║  ██║██╔══██╗╚══██╔══╝                 ║
║                 ██║     ██║   ██║██║     ██║  ██║███████║███████║   ██║                    ║
║                 ██║     ██║   ██║██║     ██║  ██║██╔══██║██╔══██║   ██║                    ║
║                 ╚██████╗╚██████╔╝███████╗██████╔╝██║  ██║██║  ██║   ██║                    ║
║                  ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝                    ║
║                                                                                            ║
║                            will another model keep your rules?                             ║
║                                                                                            ║
╚════════════════════════════════════════════════════════════════════════════════════════════╝
```

[![ci](https://github.com/vince-gonzalez/coldhat/actions/workflows/ci.yml/badge.svg)](https://github.com/vince-gonzalez/coldhat/actions/workflows/ci.yml)

**coldHat** puts your working rules on any AI chat in one line. Type this into Claude,
ChatGPT or Grok:

```
open sesame coldhat.f-keys.com/u/vince-gonzalez
```

The assistant reads the hat, answers with its hat code to prove it read it, and works by
those rules for the rest of the chat. **Live at [coldhat.f-keys.com](https://coldhat.f-keys.com).**

![Claude and Grok each put on the frontier hat from one typed line and answer with its hat code](https://raw.githubusercontent.com/vince-gonzalez/coldhat/main/docs/demo-frontier.gif)

*Recorded 2026-10-11 in Claude (incognito) and Grok (private). Both quote `33963b16`, the frontier
hat's live code, which they can only know by reading the page. Models keep their own copy of a
page for a while, so after an edit the code they quote can trail the live one. A playful
version, with the main hat's joke opener, is in [docs/demo.gif](docs/demo.gif).*

| You want to | Do this |
|---|---|
| Wear a hat | type `open sesame coldhat.f-keys.com/u/<github-user>` |
| Wear one in a chat that can't browse | **Copy hat** on [coldhat.f-keys.com](https://coldhat.f-keys.com), then paste |
| Make your own | write it at [coldhat.f-keys.com/make](https://coldhat.f-keys.com/make), or start from [coldhat-starter](https://github.com/vince-gonzalez/coldhat-starter) |
| Bring the instructions you already keep for Claude, ChatGPT, Grok or Cursor | [coldhat.f-keys.com/import](https://coldhat.f-keys.com/import): shared rules become your hat, the rest become sets you load by name |
| Add it to an app once | add the MCP connector `https://coldhat.f-keys.com/mcp` (tool `wear_hat`, prompt `open_sesame`) |

**Try one now.** Starter hats anyone can wear:

| Hat | Type this |
|---|---|
| Code reviewer: verdict first, findings by severity with line, failure and fix | `open sesame coldhat.f-keys.com/u/vince-gonzalez/reviewer` |
| Grant writer: rubric first, every number sourced, every limit met | `open sesame coldhat.f-keys.com/u/vince-gonzalez/grants` |
| Plain-English editor: shorter, clearer, still your voice | `open sesame coldhat.f-keys.com/u/vince-gonzalez/editor` |
| Frontier: mechanical register, rules over manners | `open sesame coldhat.f-keys.com/u/vince-gonzalez/frontier` |

A hat is a `hat.md` in a public GitHub repository named `coldhat`, so only its owner can
change it. Extra hats go in `hats/<name>.md` at `/u/<user>/<name>`. Dated facts under
`## Status` (`- label: value · as of YYYY-MM-DD · check after N days`) are checked by the
server against today's date, and the assistant asks about any that have gone stale.
[Which chat boxes work](evals/chatbox-results.md) was measured, not assumed.

### Edit your hat in your own editor

```bash
pip install -e .                 # once, from a clone of your coldhat repository
coldhat check hat.md             # the same checks the server and the web editor run
coldhat publish hat.md -m "Won the grant"
```

`publish` checks the file, commits only that file, pushes, and waits until the live hat code
matches your local one.

### Under the hood

- `worker/`: the Cloudflare Worker behind coldhat.f-keys.com: hat pages, the editor,
  `llms.txt`, the MCP server. Edge-cached, rate-limited, every name checked before GitHub is
  asked. 53 tests run in workerd.
- `src/coldhat/`: the Python toolchain for authoring hats as cards, locking them, and
  measuring them with evals across models.

```
hat (files you own)  ->  compile  ->  hat.md | Claude skill | OpenAI bundle | paste file
                                       |
                     evals: bait questions, graded  ->  runs (fingerprinted)
                                       |
                     tune: edit cards, re-run, compare  ->  fine-tuning JSONL
```

## A hat (as cards)

```
hats/vince/
  coldhat.json   manifest: id, version, activation phrases, file digests
  hat.md         brim: activation table and precedence
  head.md        voice, register, example answers
  footer.md      the check before every answer
  cards/         the body: one rule per file
```

A card:

```markdown
---
id: work-premise
load: always
tags: irreversible public account destructive force push premise verify command
---
# State the premise before anything irreversible

Before anything irreversible, public or touching an account, state the premise...
```

`load: always` cards sit in the instructions. `load: retrieve` cards are fetched
when a task calls for them, so the hat can grow without filling the context.

**Activation.** `open sesame` puts on head, body and footer. `open sesame head`
puts on the voice alone. `hat off` removes it.

**Integrity.** `coldhat lock` records a sha256 for every file. A hat whose files
differ from the lock refuses to load. The fingerprint is a hash over all of
them, and every eval run records it, so a score always names the exact hat
that earned it.

**Authority.** A hat describes how to work. It grants no tools, permissions or
access; the host's own rules and the user's live instructions outrank it.

## Delivery modes

| Mode | Instructions carry | The other cards arrive |
|---|---|---|
| `inline` | every card | already there |
| `tool` | always-on cards and a titled list of the rest | the model calls `coldhat_lookup` |
| `rag` | always-on cards | the host attaches matching cards to each message |

Retrieval is BM25 over card titles, tags and bodies; standard library only and
deterministic.

## Commands

```bash
pip install -e ".[all]"
```

| Command | What it does |
|---|---|
| `coldhat lock HAT` | record file digests |
| `coldhat validate HAT` | check structure and lock |
| `coldhat inspect HAT` | activation, always-on cards, instruction size per mode |
| `coldhat retrieve HAT "query"` | which cards a task pulls |
| `coldhat build HAT` | write `dist/<id>/`: `MASTER.md`, a Claude skill folder, OpenAI bundles |
| `coldhat run HAT SUITE --provider anthropic\|openai` | put the hat on a model and run every case |
| `coldhat sheet SUITE --out replies.json` | print the questions for a chat window and write a blank replies file |
| `coldhat grade HAT SUITE replies.json --label NAME` | grade replies collected by hand |
| `coldhat report RUN [RUN]` | show a run, or compare two case by case |
| `coldhat agree HAT RUN_A RUN_B` | judge whether two models took the same positions |
| `coldhat export HAT --suite SUITE [--run RUN]` | write chat-format fine-tuning JSONL |

`run` and `grade` exit 0 when every case passed, 1 when any failed, and 2 when
none failed but some could not be fully graded.

Credentials come from each SDK's own environment variables
(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`). Name the OpenAI model with `--model`
or `COLDHAT_OPENAI_MODEL`. Claude defaults to `claude-opus-5-5`, with the API's
refusal fallback enabled.

## Evals

A suite is a JSON list of cases. Each case is a prompt, usually a bait question
built to tempt the model into breaking one rule, and a list of checks:

| Check | Passes when |
|---|---|
| `regex` | the pattern is in the reply |
| `not_regex` | the pattern is absent |
| `max_words` | the reply is at most `n` words |
| `judge` | a grading model says the reply meets the rubric |

`voice_bans` run on every reply: announced honesty, filler words, a closing
"want me to...?" menu.

A judge check with no judge model is `not_run`. A judge that errors is `error`.
Either one makes the case `incomplete`, which is never counted as a pass. An
empty reply fails outright, since it would otherwise pass every "must not
contain" check.

## Tuning

1. Run the suite on a model.
2. Read the failures. Each one points at a card, the head, or a missing card.
3. Edit, `coldhat lock`, run again.
4. `coldhat report OLD NEW` shows which cases flipped and confirms the hat changed.

Once a hat scores well, `coldhat export` turns the head's example answers, the
suite's reference answers and the replies from judged, passing runs into
training data. It only takes replies from runs of the current fingerprint, so
behavior from an older hat cannot leak in.

## Chat-window run

1. `coldhat build hats/vince` and copy `dist/vince/MASTER.md` into the chat.
2. `coldhat sheet evals/vince.json --out claude.json`, send each question in that chat, paste each reply into the file.
3. Repeat in a second model's chat with `--out gpt.json`.
4. `coldhat grade hats/vince evals/vince.json claude.json --label claude`, same for `gpt.json`.
5. `coldhat report` on both runs, and `coldhat agree` to see whether they took the same positions.

## Security

A hat is instructions, not a credential, and `open sesame` is not a password. Commits pass a secret and private-term scrubber before they exist, CI runs it again with gitleaks over the full history, hats refuse to read outside their own folder, and the only tool a hat exposes is a read-only search over its own cards. Details and limits are in [SECURITY.md](SECURITY.md).

To install the commit hook in a clone:

```bash
git config core.hooksPath .githooks
git config scrub.privateTerms /path/to/your/private-terms.sha256
```

`python tools/scrub.py --hash WORD` prints the line to add for a term.

## Tests

```bash
python -m unittest discover -s tests
```

No network and no keys. Each gate is tested on input built to pass it and
input built to fail it, and both provider adapters are driven through their
tool loops with fake clients.

---

```
╔════════════════════════════════════════════════════════════╗
║                                                            ║
║      ███████╗      ██╗  ██╗███████╗██╗   ██╗███████╗       ║
║      ██╔════╝      ██║ ██╔╝██╔════╝╚██╗ ██╔╝██╔════╝       ║
║      █████╗  █████╗█████╔╝ █████╗   ╚████╔╝ ███████╗       ║
║      ██╔══╝  ╚════╝██╔═██╗ ██╔══╝    ╚██╔╝  ╚════██║       ║
║      ██║           ██║  ██╗███████╗   ██║   ███████║       ║
║      ╚═╝           ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝       ║
║                                                            ║
║               ·   C  R  E  A  T  I  V  E   ·               ║
║                                                            ║
║          ────────────────────────────────────────          ║
║                                                            ║
║                      Vincent Gonzalez                      ║
║                         f-keys.com                         ║
║                 ORCID 0009-0005-3640-014X                  ║
║                                                            ║
╚════════════════════════════════════════════════════════════╝
```

Part of [F-Keys](https://f-keys.com) — independent hardware, software
and internet products. See the [working log](https://f-keys.com/log/)
and [live status](https://f-keys.com/status/).
