frontface-metacog 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- frontface_metacog-1.0.0/LICENSE +21 -0
- frontface_metacog-1.0.0/PKG-INFO +179 -0
- frontface_metacog-1.0.0/README.md +163 -0
- frontface_metacog-1.0.0/pyproject.toml +27 -0
- frontface_metacog-1.0.0/setup.cfg +4 -0
- frontface_metacog-1.0.0/src/frontface_metacog.egg-info/PKG-INFO +179 -0
- frontface_metacog-1.0.0/src/frontface_metacog.egg-info/SOURCES.txt +18 -0
- frontface_metacog-1.0.0/src/frontface_metacog.egg-info/dependency_links.txt +1 -0
- frontface_metacog-1.0.0/src/frontface_metacog.egg-info/top_level.txt +1 -0
- frontface_metacog-1.0.0/src/metacog/__init__.py +40 -0
- frontface_metacog-1.0.0/src/metacog/backends.py +113 -0
- frontface_metacog-1.0.0/src/metacog/engine.py +233 -0
- frontface_metacog-1.0.0/src/metacog/ledger.py +132 -0
- frontface_metacog-1.0.0/src/metacog/protocol.py +145 -0
- frontface_metacog-1.0.0/src/metacog/record.py +170 -0
- frontface_metacog-1.0.0/src/metacog/steelman.py +144 -0
- frontface_metacog-1.0.0/src/metacog/triggers.py +75 -0
- frontface_metacog-1.0.0/tests/test_ledger.py +109 -0
- frontface_metacog-1.0.0/tests/test_record_engine.py +226 -0
- frontface_metacog-1.0.0/tests/test_triggers_protocol.py +164 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ryan Wesley Hitchcock
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: frontface-metacog
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Five-step reasoning pressure test: trigger thresholds, steelman countermodel, load-bearing assumptions, collision, confidence revision
|
|
5
|
+
Author: Ryan Wesley Hitchcock
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ohpersonperson/frontface
|
|
8
|
+
Keywords: reasoning,metacognition,red-teaming,confidence,decision-analysis
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Requires-Python: >=3.10
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
# Confidence Auditor — five-step reasoning pressure test
|
|
18
|
+
|
|
19
|
+
Interrogation, not supervision. You hand it reasoning-in-progress; it
|
|
20
|
+
returns a **collision record** with a revised confidence — before→after,
|
|
21
|
+
per load-bearing assumption and overall. It never originates analysis.
|
|
22
|
+
It pressure-tests analysis that already exists.
|
|
23
|
+
|
|
24
|
+
No prerequisites. You don't need to know anything about the project's
|
|
25
|
+
history, any framework, or any belief system. The mechanism is the whole
|
|
26
|
+
product.
|
|
27
|
+
|
|
28
|
+
*(Lineage: this is the front-facing conversion of the `metacog` skill from
|
|
29
|
+
Ryan's skill-suite, MIT. What changed in the conversion is documented in
|
|
30
|
+
CHANGELOG.md — the name and nothing else, really; this was already the
|
|
31
|
+
cleanest skill in the suite.)*
|
|
32
|
+
|
|
33
|
+
## What it does
|
|
34
|
+
|
|
35
|
+
Five steps, in order, never reordered — evaluating before colliding is
|
|
36
|
+
the most common failure mode (you polish claims that should have died):
|
|
37
|
+
|
|
38
|
+
1. **Trigger Thresholds** — decide whether it's worth firing at all.
|
|
39
|
+
Fires on: stakes (hard-to-reverse decision), confidence-without-evidence,
|
|
40
|
+
contradiction-present (an uncollided counter-take exists),
|
|
41
|
+
premature-convergence (one take survived unchallenged), or explicit
|
|
42
|
+
invocation. No tripped threshold = stand down, honestly. A controller
|
|
43
|
+
that always fires is noise.
|
|
44
|
+
2. **Strongest Countermodel** — the strongest internally-coherent case
|
|
45
|
+
*against* the current conclusion. Steelman only: named premises, named
|
|
46
|
+
evidence, named mechanism. The package checks the countermodel
|
|
47
|
+
mechanically (see "Why it works") — a strawman fails the run. An
|
|
48
|
+
honest "I can't build a strong one" is a finding, not a failure.
|
|
49
|
+
3. **Load-Bearing Assumptions** — every assumption the conclusion depends
|
|
50
|
+
on, marked **load-bearing** (if false, the conclusion falls) or
|
|
51
|
+
**structural** (supports it, but it survives without it). Only
|
|
52
|
+
load-bearing assumptions go to collision.
|
|
53
|
+
4. **Collision** — the countermodel attacks each load-bearing assumption,
|
|
54
|
+
one at a time: **survives / weakened / broken**. Contradictions are
|
|
55
|
+
held in parallel non-subordinating sentences ("X is true. Y is also
|
|
56
|
+
true." — never "X, however Y"). The **surprise check**: if the
|
|
57
|
+
collision produced nothing neither side contained alone, it wasn't a
|
|
58
|
+
real collision — run it again, harder.
|
|
59
|
+
5. **Confidence Revision** — before→after per assumption and overall.
|
|
60
|
+
The delta is the output. A broken load-bearing assumption doesn't
|
|
61
|
+
merely lower confidence — it **demotes the conclusion to a hypothesis**
|
|
62
|
+
pending new evidence. "I feel less sure" (self-report) is distinguished
|
|
63
|
+
from "the assumption broke under the countermodel" (finding).
|
|
64
|
+
|
|
65
|
+
Core principle: **confidence and correctness are independent variables.**
|
|
66
|
+
This tool interrogates the gap between them.
|
|
67
|
+
|
|
68
|
+
## Why it works
|
|
69
|
+
|
|
70
|
+
Most reasoning failures are structural, not intellectual. Confidence
|
|
71
|
+
quietly outruns evidence. The first plausible story wins and alternatives
|
|
72
|
+
never get built. Contradictions get smoothed with "however." The audit
|
|
73
|
+
attacks all three mechanically:
|
|
74
|
+
|
|
75
|
+
- **Trigger gating** means it only fires when the stakes or the
|
|
76
|
+
contradiction warrant it — no theater runs.
|
|
77
|
+
- **The steelman check** (`steelman.py`) catches weak countermodels by
|
|
78
|
+
their mechanical signatures: too short to be specific, hedge phrases
|
|
79
|
+
with no named premises ("some might disagree..."), no evidence or
|
|
80
|
+
mechanism named, or a restatement of the conclusion in contrast
|
|
81
|
+
clothing. A weak countermodel fails the run before the collision can
|
|
82
|
+
be theater. This is the failure mode live-model evals found in small
|
|
83
|
+
models — checked in code, not just in prose.
|
|
84
|
+
- **Load-bearing classification** focuses the collision where it can
|
|
85
|
+
change the conclusion. Colliding structural assumptions is motion
|
|
86
|
+
without effect.
|
|
87
|
+
- **The demotion rule** makes broken assumptions costly: the conclusion
|
|
88
|
+
doesn't get a softer number, it gets demoted to a hypothesis.
|
|
89
|
+
|
|
90
|
+
## Quickstart
|
|
91
|
+
|
|
92
|
+
Zero dependencies beyond Python 3.10+ and a model to run the engine on.
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
cd metacog
|
|
96
|
+
python3 -m unittest discover -s tests # 39 offline tests — prove the machinery first
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
To run a real pressure test, you need a backend — any LLM that can follow
|
|
100
|
+
the protocol prompt:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Fully offline: local Ollama
|
|
104
|
+
python3 examples/run_local.py reasoning.txt --ollama
|
|
105
|
+
|
|
106
|
+
# OpenRouter (free-tier models work fine)
|
|
107
|
+
OPENROUTER_API_KEY=... OPENROUTER_MODEL="nvidia/nemotron-3-ultra-550b-a55b:free" \
|
|
108
|
+
python3 examples/run_local.py reasoning.txt --openrouter
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`reasoning.txt` is plain prose:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
CONCLUSION: Migrate billing to the new provider now
|
|
115
|
+
REASONING: Costs are lower and churn will drop.
|
|
116
|
+
EVIDENCE:
|
|
117
|
+
- Quote: $38k migration
|
|
118
|
+
- Q1 cohort churn 3.8%
|
|
119
|
+
CONFIDENCE: 80
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The engine returns a rendered collision record — the portable artifact.
|
|
123
|
+
The engine never writes files and never claims external persistence:
|
|
124
|
+
your code saves the record.
|
|
125
|
+
|
|
126
|
+
Or use it as a library:
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
from metacog import (
|
|
130
|
+
ReasoningInput, run, to_collision_record, OllamaBackend,
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
result = run(
|
|
134
|
+
ReasoningInput(
|
|
135
|
+
conclusion="Migrate billing to the new provider now",
|
|
136
|
+
reasoning="Costs are lower and churn will drop.",
|
|
137
|
+
evidence=["Quote: $38k migration", "Q1 cohort churn 3.8%"],
|
|
138
|
+
stated_confidence=80,
|
|
139
|
+
triggers=["stakes", "contradiction-present"],
|
|
140
|
+
),
|
|
141
|
+
OllamaBackend(),
|
|
142
|
+
)
|
|
143
|
+
assert result.ok
|
|
144
|
+
print(to_collision_record(result.record).render())
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Inputs, outputs
|
|
148
|
+
|
|
149
|
+
- **Input:** a conclusion, the reasoning behind it (prose), optional
|
|
150
|
+
evidence, optional stated confidence, optional claimed triggers.
|
|
151
|
+
- **Output:** a normalized record dict, or a rendered `collision-record`
|
|
152
|
+
Markdown document — complete, self-contained, no placeholders.
|
|
153
|
+
|
|
154
|
+
## Worked example
|
|
155
|
+
|
|
156
|
+
`examples/example-1-billing-migration.md` — a complete collision record
|
|
157
|
+
for a business decision (migrate billing providers?), annotated so a
|
|
158
|
+
stranger can follow each step.
|
|
159
|
+
|
|
160
|
+
*The field is constructed for teaching — it shows the audit's shape, not
|
|
161
|
+
real findings.*
|
|
162
|
+
|
|
163
|
+
## FAQ
|
|
164
|
+
|
|
165
|
+
**Does it replace the IFS interrogation engine?** No. It pressure-tests
|
|
166
|
+
reasoning that already exists; IFS interrogates a field from scratch.
|
|
167
|
+
They attach cleanly (the audit runs at the Collide→Refine boundary), but
|
|
168
|
+
each works standalone.
|
|
169
|
+
|
|
170
|
+
**Does it need an internet connection?** Only for the model call, and
|
|
171
|
+
only the backend you choose. With Ollama it's fully offline. The 30 unit
|
|
172
|
+
tests never touch the network.
|
|
173
|
+
|
|
174
|
+
**What does it cost?** The package is free and dependency-free. The model
|
|
175
|
+
call costs whatever your provider charges — free-tier models work.
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT. See LICENSE.
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# Confidence Auditor — five-step reasoning pressure test
|
|
2
|
+
|
|
3
|
+
Interrogation, not supervision. You hand it reasoning-in-progress; it
|
|
4
|
+
returns a **collision record** with a revised confidence — before→after,
|
|
5
|
+
per load-bearing assumption and overall. It never originates analysis.
|
|
6
|
+
It pressure-tests analysis that already exists.
|
|
7
|
+
|
|
8
|
+
No prerequisites. You don't need to know anything about the project's
|
|
9
|
+
history, any framework, or any belief system. The mechanism is the whole
|
|
10
|
+
product.
|
|
11
|
+
|
|
12
|
+
*(Lineage: this is the front-facing conversion of the `metacog` skill from
|
|
13
|
+
Ryan's skill-suite, MIT. What changed in the conversion is documented in
|
|
14
|
+
CHANGELOG.md — the name and nothing else, really; this was already the
|
|
15
|
+
cleanest skill in the suite.)*
|
|
16
|
+
|
|
17
|
+
## What it does
|
|
18
|
+
|
|
19
|
+
Five steps, in order, never reordered — evaluating before colliding is
|
|
20
|
+
the most common failure mode (you polish claims that should have died):
|
|
21
|
+
|
|
22
|
+
1. **Trigger Thresholds** — decide whether it's worth firing at all.
|
|
23
|
+
Fires on: stakes (hard-to-reverse decision), confidence-without-evidence,
|
|
24
|
+
contradiction-present (an uncollided counter-take exists),
|
|
25
|
+
premature-convergence (one take survived unchallenged), or explicit
|
|
26
|
+
invocation. No tripped threshold = stand down, honestly. A controller
|
|
27
|
+
that always fires is noise.
|
|
28
|
+
2. **Strongest Countermodel** — the strongest internally-coherent case
|
|
29
|
+
*against* the current conclusion. Steelman only: named premises, named
|
|
30
|
+
evidence, named mechanism. The package checks the countermodel
|
|
31
|
+
mechanically (see "Why it works") — a strawman fails the run. An
|
|
32
|
+
honest "I can't build a strong one" is a finding, not a failure.
|
|
33
|
+
3. **Load-Bearing Assumptions** — every assumption the conclusion depends
|
|
34
|
+
on, marked **load-bearing** (if false, the conclusion falls) or
|
|
35
|
+
**structural** (supports it, but it survives without it). Only
|
|
36
|
+
load-bearing assumptions go to collision.
|
|
37
|
+
4. **Collision** — the countermodel attacks each load-bearing assumption,
|
|
38
|
+
one at a time: **survives / weakened / broken**. Contradictions are
|
|
39
|
+
held in parallel non-subordinating sentences ("X is true. Y is also
|
|
40
|
+
true." — never "X, however Y"). The **surprise check**: if the
|
|
41
|
+
collision produced nothing neither side contained alone, it wasn't a
|
|
42
|
+
real collision — run it again, harder.
|
|
43
|
+
5. **Confidence Revision** — before→after per assumption and overall.
|
|
44
|
+
The delta is the output. A broken load-bearing assumption doesn't
|
|
45
|
+
merely lower confidence — it **demotes the conclusion to a hypothesis**
|
|
46
|
+
pending new evidence. "I feel less sure" (self-report) is distinguished
|
|
47
|
+
from "the assumption broke under the countermodel" (finding).
|
|
48
|
+
|
|
49
|
+
Core principle: **confidence and correctness are independent variables.**
|
|
50
|
+
This tool interrogates the gap between them.
|
|
51
|
+
|
|
52
|
+
## Why it works
|
|
53
|
+
|
|
54
|
+
Most reasoning failures are structural, not intellectual. Confidence
|
|
55
|
+
quietly outruns evidence. The first plausible story wins and alternatives
|
|
56
|
+
never get built. Contradictions get smoothed with "however." The audit
|
|
57
|
+
attacks all three mechanically:
|
|
58
|
+
|
|
59
|
+
- **Trigger gating** means it only fires when the stakes or the
|
|
60
|
+
contradiction warrant it — no theater runs.
|
|
61
|
+
- **The steelman check** (`steelman.py`) catches weak countermodels by
|
|
62
|
+
their mechanical signatures: too short to be specific, hedge phrases
|
|
63
|
+
with no named premises ("some might disagree..."), no evidence or
|
|
64
|
+
mechanism named, or a restatement of the conclusion in contrast
|
|
65
|
+
clothing. A weak countermodel fails the run before the collision can
|
|
66
|
+
be theater. This is the failure mode live-model evals found in small
|
|
67
|
+
models — checked in code, not just in prose.
|
|
68
|
+
- **Load-bearing classification** focuses the collision where it can
|
|
69
|
+
change the conclusion. Colliding structural assumptions is motion
|
|
70
|
+
without effect.
|
|
71
|
+
- **The demotion rule** makes broken assumptions costly: the conclusion
|
|
72
|
+
doesn't get a softer number, it gets demoted to a hypothesis.
|
|
73
|
+
|
|
74
|
+
## Quickstart
|
|
75
|
+
|
|
76
|
+
Zero dependencies beyond Python 3.10+ and a model to run the engine on.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
cd metacog
|
|
80
|
+
python3 -m unittest discover -s tests # 39 offline tests — prove the machinery first
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
To run a real pressure test, you need a backend — any LLM that can follow
|
|
84
|
+
the protocol prompt:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
# Fully offline: local Ollama
|
|
88
|
+
python3 examples/run_local.py reasoning.txt --ollama
|
|
89
|
+
|
|
90
|
+
# OpenRouter (free-tier models work fine)
|
|
91
|
+
OPENROUTER_API_KEY=... OPENROUTER_MODEL="nvidia/nemotron-3-ultra-550b-a55b:free" \
|
|
92
|
+
python3 examples/run_local.py reasoning.txt --openrouter
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`reasoning.txt` is plain prose:
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
CONCLUSION: Migrate billing to the new provider now
|
|
99
|
+
REASONING: Costs are lower and churn will drop.
|
|
100
|
+
EVIDENCE:
|
|
101
|
+
- Quote: $38k migration
|
|
102
|
+
- Q1 cohort churn 3.8%
|
|
103
|
+
CONFIDENCE: 80
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The engine returns a rendered collision record — the portable artifact.
|
|
107
|
+
The engine never writes files and never claims external persistence:
|
|
108
|
+
your code saves the record.
|
|
109
|
+
|
|
110
|
+
Or use it as a library:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from metacog import (
|
|
114
|
+
ReasoningInput, run, to_collision_record, OllamaBackend,
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
result = run(
|
|
118
|
+
ReasoningInput(
|
|
119
|
+
conclusion="Migrate billing to the new provider now",
|
|
120
|
+
reasoning="Costs are lower and churn will drop.",
|
|
121
|
+
evidence=["Quote: $38k migration", "Q1 cohort churn 3.8%"],
|
|
122
|
+
stated_confidence=80,
|
|
123
|
+
triggers=["stakes", "contradiction-present"],
|
|
124
|
+
),
|
|
125
|
+
OllamaBackend(),
|
|
126
|
+
)
|
|
127
|
+
assert result.ok
|
|
128
|
+
print(to_collision_record(result.record).render())
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Inputs, outputs
|
|
132
|
+
|
|
133
|
+
- **Input:** a conclusion, the reasoning behind it (prose), optional
|
|
134
|
+
evidence, optional stated confidence, optional claimed triggers.
|
|
135
|
+
- **Output:** a normalized record dict, or a rendered `collision-record`
|
|
136
|
+
Markdown document — complete, self-contained, no placeholders.
|
|
137
|
+
|
|
138
|
+
## Worked example
|
|
139
|
+
|
|
140
|
+
`examples/example-1-billing-migration.md` — a complete collision record
|
|
141
|
+
for a business decision (migrate billing providers?), annotated so a
|
|
142
|
+
stranger can follow each step.
|
|
143
|
+
|
|
144
|
+
*The field is constructed for teaching — it shows the audit's shape, not
|
|
145
|
+
real findings.*
|
|
146
|
+
|
|
147
|
+
## FAQ
|
|
148
|
+
|
|
149
|
+
**Does it replace the IFS interrogation engine?** No. It pressure-tests
|
|
150
|
+
reasoning that already exists; IFS interrogates a field from scratch.
|
|
151
|
+
They attach cleanly (the audit runs at the Collide→Refine boundary), but
|
|
152
|
+
each works standalone.
|
|
153
|
+
|
|
154
|
+
**Does it need an internet connection?** Only for the model call, and
|
|
155
|
+
only the backend you choose. With Ollama it's fully offline. The 30 unit
|
|
156
|
+
tests never touch the network.
|
|
157
|
+
|
|
158
|
+
**What does it cost?** The package is free and dependency-free. The model
|
|
159
|
+
call costs whatever your provider charges — free-tier models work.
|
|
160
|
+
|
|
161
|
+
## License
|
|
162
|
+
|
|
163
|
+
MIT. See LICENSE.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "frontface-metacog"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Five-step reasoning pressure test: trigger thresholds, steelman countermodel, load-bearing assumptions, collision, confidence revision"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [{ name = "Ryan Wesley Hitchcock" }]
|
|
13
|
+
keywords = ["reasoning", "metacognition", "red-teaming", "confidence", "decision-analysis"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Operating System :: OS Independent",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[project.urls]
|
|
21
|
+
Homepage = "https://github.com/ohpersonperson/frontface"
|
|
22
|
+
|
|
23
|
+
[tool.setuptools.packages.find]
|
|
24
|
+
where = ["src"]
|
|
25
|
+
|
|
26
|
+
[tool.pytest.ini_options]
|
|
27
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: frontface-metacog
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Five-step reasoning pressure test: trigger thresholds, steelman countermodel, load-bearing assumptions, collision, confidence revision
|
|
5
|
+
Author: Ryan Wesley Hitchcock
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ohpersonperson/frontface
|
|
8
|
+
Keywords: reasoning,metacognition,red-teaming,confidence,decision-analysis
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Requires-Python: >=3.10
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
# Confidence Auditor — five-step reasoning pressure test
|
|
18
|
+
|
|
19
|
+
Interrogation, not supervision. You hand it reasoning-in-progress; it
|
|
20
|
+
returns a **collision record** with a revised confidence — before→after,
|
|
21
|
+
per load-bearing assumption and overall. It never originates analysis.
|
|
22
|
+
It pressure-tests analysis that already exists.
|
|
23
|
+
|
|
24
|
+
No prerequisites. You don't need to know anything about the project's
|
|
25
|
+
history, any framework, or any belief system. The mechanism is the whole
|
|
26
|
+
product.
|
|
27
|
+
|
|
28
|
+
*(Lineage: this is the front-facing conversion of the `metacog` skill from
|
|
29
|
+
Ryan's skill-suite, MIT. What changed in the conversion is documented in
|
|
30
|
+
CHANGELOG.md — the name and nothing else, really; this was already the
|
|
31
|
+
cleanest skill in the suite.)*
|
|
32
|
+
|
|
33
|
+
## What it does
|
|
34
|
+
|
|
35
|
+
Five steps, in order, never reordered — evaluating before colliding is
|
|
36
|
+
the most common failure mode (you polish claims that should have died):
|
|
37
|
+
|
|
38
|
+
1. **Trigger Thresholds** — decide whether it's worth firing at all.
|
|
39
|
+
Fires on: stakes (hard-to-reverse decision), confidence-without-evidence,
|
|
40
|
+
contradiction-present (an uncollided counter-take exists),
|
|
41
|
+
premature-convergence (one take survived unchallenged), or explicit
|
|
42
|
+
invocation. No tripped threshold = stand down, honestly. A controller
|
|
43
|
+
that always fires is noise.
|
|
44
|
+
2. **Strongest Countermodel** — the strongest internally-coherent case
|
|
45
|
+
*against* the current conclusion. Steelman only: named premises, named
|
|
46
|
+
evidence, named mechanism. The package checks the countermodel
|
|
47
|
+
mechanically (see "Why it works") — a strawman fails the run. An
|
|
48
|
+
honest "I can't build a strong one" is a finding, not a failure.
|
|
49
|
+
3. **Load-Bearing Assumptions** — every assumption the conclusion depends
|
|
50
|
+
on, marked **load-bearing** (if false, the conclusion falls) or
|
|
51
|
+
**structural** (supports it, but it survives without it). Only
|
|
52
|
+
load-bearing assumptions go to collision.
|
|
53
|
+
4. **Collision** — the countermodel attacks each load-bearing assumption,
|
|
54
|
+
one at a time: **survives / weakened / broken**. Contradictions are
|
|
55
|
+
held in parallel non-subordinating sentences ("X is true. Y is also
|
|
56
|
+
true." — never "X, however Y"). The **surprise check**: if the
|
|
57
|
+
collision produced nothing neither side contained alone, it wasn't a
|
|
58
|
+
real collision — run it again, harder.
|
|
59
|
+
5. **Confidence Revision** — before→after per assumption and overall.
|
|
60
|
+
The delta is the output. A broken load-bearing assumption doesn't
|
|
61
|
+
merely lower confidence — it **demotes the conclusion to a hypothesis**
|
|
62
|
+
pending new evidence. "I feel less sure" (self-report) is distinguished
|
|
63
|
+
from "the assumption broke under the countermodel" (finding).
|
|
64
|
+
|
|
65
|
+
Core principle: **confidence and correctness are independent variables.**
|
|
66
|
+
This tool interrogates the gap between them.
|
|
67
|
+
|
|
68
|
+
## Why it works
|
|
69
|
+
|
|
70
|
+
Most reasoning failures are structural, not intellectual. Confidence
|
|
71
|
+
quietly outruns evidence. The first plausible story wins and alternatives
|
|
72
|
+
never get built. Contradictions get smoothed with "however." The audit
|
|
73
|
+
attacks all three mechanically:
|
|
74
|
+
|
|
75
|
+
- **Trigger gating** means it only fires when the stakes or the
|
|
76
|
+
contradiction warrant it — no theater runs.
|
|
77
|
+
- **The steelman check** (`steelman.py`) catches weak countermodels by
|
|
78
|
+
their mechanical signatures: too short to be specific, hedge phrases
|
|
79
|
+
with no named premises ("some might disagree..."), no evidence or
|
|
80
|
+
mechanism named, or a restatement of the conclusion in contrast
|
|
81
|
+
clothing. A weak countermodel fails the run before the collision can
|
|
82
|
+
be theater. This is the failure mode live-model evals found in small
|
|
83
|
+
models — checked in code, not just in prose.
|
|
84
|
+
- **Load-bearing classification** focuses the collision where it can
|
|
85
|
+
change the conclusion. Colliding structural assumptions is motion
|
|
86
|
+
without effect.
|
|
87
|
+
- **The demotion rule** makes broken assumptions costly: the conclusion
|
|
88
|
+
doesn't get a softer number, it gets demoted to a hypothesis.
|
|
89
|
+
|
|
90
|
+
## Quickstart
|
|
91
|
+
|
|
92
|
+
Zero dependencies beyond Python 3.10+ and a model to run the engine on.
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
cd metacog
|
|
96
|
+
python3 -m unittest discover -s tests # 39 offline tests — prove the machinery first
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
To run a real pressure test, you need a backend — any LLM that can follow
|
|
100
|
+
the protocol prompt:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Fully offline: local Ollama
|
|
104
|
+
python3 examples/run_local.py reasoning.txt --ollama
|
|
105
|
+
|
|
106
|
+
# OpenRouter (free-tier models work fine)
|
|
107
|
+
OPENROUTER_API_KEY=... OPENROUTER_MODEL="nvidia/nemotron-3-ultra-550b-a55b:free" \
|
|
108
|
+
python3 examples/run_local.py reasoning.txt --openrouter
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`reasoning.txt` is plain prose:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
CONCLUSION: Migrate billing to the new provider now
|
|
115
|
+
REASONING: Costs are lower and churn will drop.
|
|
116
|
+
EVIDENCE:
|
|
117
|
+
- Quote: $38k migration
|
|
118
|
+
- Q1 cohort churn 3.8%
|
|
119
|
+
CONFIDENCE: 80
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The engine returns a rendered collision record — the portable artifact.
|
|
123
|
+
The engine never writes files and never claims external persistence:
|
|
124
|
+
your code saves the record.
|
|
125
|
+
|
|
126
|
+
Or use it as a library:
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
from metacog import (
|
|
130
|
+
ReasoningInput, run, to_collision_record, OllamaBackend,
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
result = run(
|
|
134
|
+
ReasoningInput(
|
|
135
|
+
conclusion="Migrate billing to the new provider now",
|
|
136
|
+
reasoning="Costs are lower and churn will drop.",
|
|
137
|
+
evidence=["Quote: $38k migration", "Q1 cohort churn 3.8%"],
|
|
138
|
+
stated_confidence=80,
|
|
139
|
+
triggers=["stakes", "contradiction-present"],
|
|
140
|
+
),
|
|
141
|
+
OllamaBackend(),
|
|
142
|
+
)
|
|
143
|
+
assert result.ok
|
|
144
|
+
print(to_collision_record(result.record).render())
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Inputs, outputs
|
|
148
|
+
|
|
149
|
+
- **Input:** a conclusion, the reasoning behind it (prose), optional
|
|
150
|
+
evidence, optional stated confidence, optional claimed triggers.
|
|
151
|
+
- **Output:** a normalized record dict, or a rendered `collision-record`
|
|
152
|
+
Markdown document — complete, self-contained, no placeholders.
|
|
153
|
+
|
|
154
|
+
## Worked example
|
|
155
|
+
|
|
156
|
+
`examples/example-1-billing-migration.md` — a complete collision record
|
|
157
|
+
for a business decision (migrate billing providers?), annotated so a
|
|
158
|
+
stranger can follow each step.
|
|
159
|
+
|
|
160
|
+
*The field is constructed for teaching — it shows the audit's shape, not
|
|
161
|
+
real findings.*
|
|
162
|
+
|
|
163
|
+
## FAQ
|
|
164
|
+
|
|
165
|
+
**Does it replace the IFS interrogation engine?** No. It pressure-tests
|
|
166
|
+
reasoning that already exists; IFS interrogates a field from scratch.
|
|
167
|
+
They attach cleanly (the audit runs at the Collide→Refine boundary), but
|
|
168
|
+
each works standalone.
|
|
169
|
+
|
|
170
|
+
**Does it need an internet connection?** Only for the model call, and
|
|
171
|
+
only the backend you choose. With Ollama it's fully offline. The 30 unit
|
|
172
|
+
tests never touch the network.
|
|
173
|
+
|
|
174
|
+
**What does it cost?** The package is free and dependency-free. The model
|
|
175
|
+
call costs whatever your provider charges — free-tier models work.
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT. See LICENSE.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/frontface_metacog.egg-info/PKG-INFO
|
|
5
|
+
src/frontface_metacog.egg-info/SOURCES.txt
|
|
6
|
+
src/frontface_metacog.egg-info/dependency_links.txt
|
|
7
|
+
src/frontface_metacog.egg-info/top_level.txt
|
|
8
|
+
src/metacog/__init__.py
|
|
9
|
+
src/metacog/backends.py
|
|
10
|
+
src/metacog/engine.py
|
|
11
|
+
src/metacog/ledger.py
|
|
12
|
+
src/metacog/protocol.py
|
|
13
|
+
src/metacog/record.py
|
|
14
|
+
src/metacog/steelman.py
|
|
15
|
+
src/metacog/triggers.py
|
|
16
|
+
tests/test_ledger.py
|
|
17
|
+
tests/test_record_engine.py
|
|
18
|
+
tests/test_triggers_protocol.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
metacog
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""metacog — front-facing conversion of the metacog skill.
|
|
2
|
+
|
|
3
|
+
A five-step reasoning pressure test: check whether it is worth firing at
|
|
4
|
+
all (trigger thresholds), steelman the strongest countermodel, isolate
|
|
5
|
+
load-bearing assumptions, collide the countermodel against each one, and
|
|
6
|
+
revise confidence with a before→after delta.
|
|
7
|
+
|
|
8
|
+
Core invariant: confidence and correctness are independent variables.
|
|
9
|
+
See README.md for the plain-language version. See CHANGELOG.md for what
|
|
10
|
+
was decoupled from the original skill.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from . import backends, engine, protocol, record, steelman, triggers
|
|
14
|
+
from .backends import StubBackend, OpenRouterBackend, OllamaBackend
|
|
15
|
+
from .engine import (
|
|
16
|
+
LLMBackend, RunResult, ReasoningInput, build_user_message,
|
|
17
|
+
parse_model_json, normalize, run, to_collision_record,
|
|
18
|
+
)
|
|
19
|
+
from .protocol import (
|
|
20
|
+
SYSTEM_PROMPT, Countermodel, Assumption, CollisionResult,
|
|
21
|
+
ConfidenceRevision, ProtocolError, apply_demotions,
|
|
22
|
+
LOAD_BEARING, STRUCTURAL, SURVIVES, WEAKENED, BROKEN,
|
|
23
|
+
)
|
|
24
|
+
from .record import CollisionRecord, RecordError
|
|
25
|
+
from .steelman import SteelmanReport, check_countermodel
|
|
26
|
+
from .triggers import TriggerEvaluation, TriggerError, TRIGGERS
|
|
27
|
+
|
|
28
|
+
__version__ = "1.0.0"
|
|
29
|
+
__all__ = [
|
|
30
|
+
"backends", "engine", "protocol", "record", "steelman", "triggers",
|
|
31
|
+
"StubBackend", "OpenRouterBackend", "OllamaBackend",
|
|
32
|
+
"LLMBackend", "RunResult", "ReasoningInput", "build_user_message",
|
|
33
|
+
"parse_model_json", "normalize", "run", "to_collision_record",
|
|
34
|
+
"SYSTEM_PROMPT", "Countermodel", "Assumption", "CollisionResult",
|
|
35
|
+
"ConfidenceRevision", "ProtocolError", "apply_demotions",
|
|
36
|
+
"LOAD_BEARING", "STRUCTURAL", "SURVIVES", "WEAKENED", "BROKEN",
|
|
37
|
+
"CollisionRecord", "RecordError",
|
|
38
|
+
"SteelmanReport", "check_countermodel",
|
|
39
|
+
"TriggerEvaluation", "TriggerError", "TRIGGERS",
|
|
40
|
+
]
|