# jamestrichmond/small-cheap-experiments architecture

> Architecture diagram of the GitHub repository jamestrichmond/small-cheap-experiments, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamestrichmond/small-cheap-experiments
- Repository: https://github.com/jamestrichmond/small-cheap-experiments

## Overview

This is a refund-only runtime telemetry spike: it probes an agent before a refund, compares its stated intent with the action, and appends a hash-chained replay record. The agent remains responsible for invoking the refund tool; the runtime’s pre-tool hook returns a decision, but the README emphasizes logging rather than enforcing a hard block. The graph covers the sampled hook-to-storage flow and documented replay purpose; it does not imply a dashboard or external hash backup, and the Diet bridge is only a stub.

Main entry points: [`src/probe_runtime/hooks.py`](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/hooks.py) (Refund hooks), [`src/probe_runtime/store.py`](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/store.py) (Replay store), [`src/probe_runtime/models.py`](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/models.py) (Runtime types), [`src/probe_runtime/probes.py`](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/probes.py) (Probe sampler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_probe["Probe and decision"]
  node_probes["Probe sampler<br/>[probes.py]"]
  node_probe_bank["Held-out probes"]
  node_hooks["Refund hooks<br/>[hooks.py]"]
  node_gate["Decision gate<br/>[gate.py]"]
  node_models["Runtime types<br/>[models.py]"]
end

subgraph group_evaluation["Scoring and replay"]
  node_scoring["Behavior scoring<br/>[score.py]"]
  node_diet["Diet escalation stub<br/>[diet_bridge.py]"]
  node_store[("Replay store<br/>[store.py]")]
  node_chain["Hash-chain integrity<br/>[hash_chain.py]"]
end

subgraph group_integration["External participants"]
  node_agent(("AI agent"))
  node_refund_api["Refund tool"]
  node_analyst(("Risk analyst"))
end

node_agent -->|"requests pre-check"| node_hooks
node_hooks -->|"samples probe"| node_probes
node_probes -->|"loads probes"| node_probe_bank
node_hooks -->|"gets decision"| node_gate
node_hooks -->|"parses response"| node_models
node_gate -->|"reads parsed type"| node_models
node_hooks -->|"returns probe and decision"| node_agent
node_agent -.->|"invokes refund"| node_refund_api
node_agent -->|"reports tool result"| node_hooks
node_hooks -->|"scores frames"| node_scoring
node_scoring -->|"uses parsed types"| node_models
node_hooks -->|"appends record"| node_store
node_store -->|"seals and verifies"| node_chain
node_analyst -.->|"reviews replay"| node_store

click node_probes "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/probes.py"
click node_probe_bank "https://github.com/jamestrichmond/small-cheap-experiments/tree/main/probes/holdout"
click node_hooks "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/hooks.py"
click node_gate "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/gate.py"
click node_models "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/models.py"
click node_scoring "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/score.py"
click node_diet "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/diet_bridge.py"
click node_store "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/store.py"
click node_chain "https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/hash_chain.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_probes,node_probe_bank,node_hooks,node_gate,node_models toneBlue
class node_scoring,node_diet,node_store,node_chain toneAmber
class node_agent,node_refund_api,node_analyst toneMint
```

## Components

### Probe and decision

- [Probe sampler](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/probes.py): `src/probe_runtime/probes.py`
- [Held-out probes](https://github.com/jamestrichmond/small-cheap-experiments/tree/main/probes/holdout): `probes/holdout`
- [Refund hooks](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/hooks.py): `src/probe_runtime/hooks.py`
- [Decision gate](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/gate.py): `src/probe_runtime/gate.py`
- [Runtime types](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/models.py): `src/probe_runtime/models.py`

### Scoring and replay

- [Behavior scoring](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/score.py): `src/probe_runtime/score.py`
- [Diet escalation stub](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/diet_bridge.py): `src/probe_runtime/diet_bridge.py`
- [Replay store](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/store.py): `src/probe_runtime/store.py`
- [Hash-chain integrity](https://github.com/jamestrichmond/small-cheap-experiments/blob/main/src/probe_runtime/hash_chain.py): `src/probe_runtime/hash_chain.py`

### External participants

- **AI agent**
- **Refund tool**
- **Risk analyst**

## Connections

- AI agent → Refund hooks: requests pre-check (evidence: `src/probe_runtime/hooks.py`)
- Refund hooks → Probe sampler: samples probe (evidence: `src/probe_runtime/hooks.py`)
- Probe sampler → Held-out probes: loads probes (evidence: `src/probe_runtime/probes.py`)
- Refund hooks → Decision gate: gets decision (evidence: `src/probe_runtime/hooks.py`)
- Refund hooks → Runtime types: parses response (evidence: `src/probe_runtime/hooks.py`)
- Decision gate → Runtime types: reads parsed type (evidence: `src/probe_runtime/gate.py`)
- Refund hooks → AI agent: returns probe and decision (evidence: `src/probe_runtime/hooks.py`)
- AI agent → Refund tool: invokes refund
- AI agent → Refund hooks: reports tool result (evidence: `src/probe_runtime/hooks.py`)
- Refund hooks → Behavior scoring: scores frames (evidence: `src/probe_runtime/hooks.py`)
- Behavior scoring → Runtime types: uses parsed types (evidence: `src/probe_runtime/score.py`)
- Refund hooks → Replay store: appends record (evidence: `src/probe_runtime/hooks.py`)
- Replay store → Hash-chain integrity: seals and verifies (evidence: `src/probe_runtime/store.py`)
- Risk analyst → Replay store: reviews replay