theoryforge 0.2.0__tar.gz → 0.3.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.
- {theoryforge-0.2.0 → theoryforge-0.3.0}/PKG-INFO +11 -1
- {theoryforge-0.2.0 → theoryforge-0.3.0}/README.md +8 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/about.md +2 -2
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/api.md +1 -0
- theoryforge-0.3.0/docs/getting-started.md +123 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/stylesheets/brand.css +14 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/theoryforge.bib +1 -1
- theoryforge-0.3.0/docs/workflow-modes.md +890 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/mkdocs.yml +1 -1
- {theoryforge-0.2.0 → theoryforge-0.3.0}/pyproject.toml +4 -1
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/__init__.py +4 -1
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/core.py +6 -0
- theoryforge-0.3.0/src/theoryforge/render.py +93 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/conftest.py +1 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_diagram_redundancy.py +3 -2
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_io.py +2 -1
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_modes.py +2 -1
- theoryforge-0.3.0/tests/test_render_diagram.py +72 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_rigor.py +1 -0
- theoryforge-0.2.0/docs/getting-started.md +0 -74
- theoryforge-0.2.0/docs/workflow-modes.md +0 -492
- {theoryforge-0.2.0 → theoryforge-0.3.0}/.gitignore +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/LICENSE +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/assets/logo.png +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/assets/logo.svg +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/changelog.md +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/index.md +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/licence.md +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/literature.md +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/methodology.md +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/stylesheets/extra.css +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/overrides/partials/header.html +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/_num.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/_resources.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/develop.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/diagram.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/dossier.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/embedding.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/lit.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/osf.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/prereg.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/py.typed +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/redundancy.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/report_render.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/rigor.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/schema/rigor_checklist.yaml +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/schema/theory.schema.json +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/scoring.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/sem.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/simulate.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_lit.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_p3.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_p4.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_scalar_singleton.py +0 -0
- {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_validation_parity.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: theoryforge
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Systematic theory development.
|
|
5
5
|
Project-URL: Homepage, https://github.com/pablobernabeu/theoryforge
|
|
6
6
|
Project-URL: Repository, https://github.com/pablobernabeu/theoryforge
|
|
@@ -24,6 +24,8 @@ Provides-Extra: dev
|
|
|
24
24
|
Requires-Dist: mypy; extra == 'dev'
|
|
25
25
|
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
26
26
|
Requires-Dist: ruff; extra == 'dev'
|
|
27
|
+
Provides-Extra: render
|
|
28
|
+
Requires-Dist: graphviz>=0.20; extra == 'render'
|
|
27
29
|
Description-Content-Type: text/markdown
|
|
28
30
|
|
|
29
31
|
# theoryforge (Python) <img src="docs/assets/logo.png" align="right" height="138" alt="theoryforge hex logo" />
|
|
@@ -48,6 +50,7 @@ t = tf.read("../fixtures/panic-network.theory.yaml")
|
|
|
48
50
|
t.validate() # structural validation against the shared schema
|
|
49
51
|
print(t.report("json")) # 12-item rigour checklist + gate
|
|
50
52
|
print(t.diagram("nomological_net"))# Graphviz DOT
|
|
53
|
+
# t.render_diagram("nomological_net") # rendered inline; needs theoryforge[render]
|
|
51
54
|
t.redundancy_check() # lexical jingle-jangle screen
|
|
52
55
|
|
|
53
56
|
# BUILD a theory programmatically (provenance auto-logged)
|
|
@@ -82,6 +85,13 @@ your own theory files when running the examples.
|
|
|
82
85
|
pip install theoryforge
|
|
83
86
|
```
|
|
84
87
|
|
|
88
|
+
The optional render extra adds native diagram rendering (`render_diagram()`,
|
|
89
|
+
which wraps the DOT views in a `graphviz.Source`):
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pip install "theoryforge[render]"
|
|
93
|
+
```
|
|
94
|
+
|
|
85
95
|
To work on the package itself, install an editable checkout with the development extras:
|
|
86
96
|
|
|
87
97
|
```bash
|
|
@@ -20,6 +20,7 @@ t = tf.read("../fixtures/panic-network.theory.yaml")
|
|
|
20
20
|
t.validate() # structural validation against the shared schema
|
|
21
21
|
print(t.report("json")) # 12-item rigour checklist + gate
|
|
22
22
|
print(t.diagram("nomological_net"))# Graphviz DOT
|
|
23
|
+
# t.render_diagram("nomological_net") # rendered inline; needs theoryforge[render]
|
|
23
24
|
t.redundancy_check() # lexical jingle-jangle screen
|
|
24
25
|
|
|
25
26
|
# BUILD a theory programmatically (provenance auto-logged)
|
|
@@ -54,6 +55,13 @@ your own theory files when running the examples.
|
|
|
54
55
|
pip install theoryforge
|
|
55
56
|
```
|
|
56
57
|
|
|
58
|
+
The optional render extra adds native diagram rendering (`render_diagram()`,
|
|
59
|
+
which wraps the DOT views in a `graphviz.Source`):
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install "theoryforge[render]"
|
|
63
|
+
```
|
|
64
|
+
|
|
57
65
|
To work on the package itself, install an editable checkout with the development extras:
|
|
58
66
|
|
|
59
67
|
```bash
|
|
@@ -4,14 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
If you use the Python package in your work, please cite it:
|
|
6
6
|
|
|
7
|
-
<p style="margin: 0 0 0.6em 0; padding-left: 1.8em; text-indent: -1.8em;">Bernabeu, P. (2026). <em>theoryforge: Systematic theory development</em> (Python package version 0.
|
|
7
|
+
<p style="margin: 0 0 0.6em 0; padding-left: 1.8em; text-indent: -1.8em;">Bernabeu, P. (2026). <em>theoryforge: Systematic theory development</em> (Python package version 0.3.0). <a href="https://doi.org/10.5281/zenodo.21229964">https://doi.org/10.5281/zenodo.21229964</a></p>
|
|
8
8
|
|
|
9
9
|
```bibtex
|
|
10
10
|
@Manual{theoryforge,
|
|
11
11
|
title = {theoryforge: Systematic theory development},
|
|
12
12
|
author = {Pablo Bernabeu},
|
|
13
13
|
year = {2026},
|
|
14
|
-
note = {Python package version 0.
|
|
14
|
+
note = {Python package version 0.3.0},
|
|
15
15
|
doi = {10.5281/zenodo.21229964},
|
|
16
16
|
url = {https://doi.org/10.5281/zenodo.21229964},
|
|
17
17
|
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
This guide walks through installing the Python package and running a first session against an existing theory file.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
Install from PyPI with pip:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install theoryforge
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Sample theories
|
|
14
|
+
|
|
15
|
+
The examples below read a sample theory bundled with the project repository. The fixture files live under `fixtures/` in the repository at [github.com/pablobernabeu/theoryforge](https://github.com/pablobernabeu/theoryforge), for example [`fixtures/panic-network.theory.yaml`](https://github.com/pablobernabeu/theoryforge/blob/main/fixtures/panic-network.theory.yaml). Download a fixture, or point the path at one of your own theory files.
|
|
16
|
+
|
|
17
|
+
## A first session
|
|
18
|
+
|
|
19
|
+
Import the package and read a theory from a YAML file. Adjust the path to the file on your own machine.
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
import theoryforge as tf
|
|
23
|
+
|
|
24
|
+
t = tf.read("panic-network.theory.yaml")
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Validate the theory. With no arguments this checks the required fields and enum membership, returning `True` on success and raising `ValueError` with a list of problems otherwise. Pass `full=True` to additionally check referential integrity: that ids are unique within each collection, that every cross-reference between constructs, propositions, predictions and alternatives points to a declared id, and that assumption, test-outcome and evidence entries reference declared predictions.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
t.validate()
|
|
31
|
+
t.validate(full=True) # also checks referential integrity
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Produce the rigour report. The `"json"` format returns the 12-item rigour checklist together with the overall gate. `t.check()` returns the same information as a plain Python dictionary; `t.report(format=...)` renders it as a string, in `"json"` or `"html"`.
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
print(t.report("json"))
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Working from the dictionary that `t.check()` returns, individual results are easy to read off, including each checklist item in order.
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
report = t.check()
|
|
44
|
+
report["aggregate_score"] # 84.8
|
|
45
|
+
report["gate"] # 'pass'
|
|
46
|
+
report["n_blockers_failed"] # 0
|
|
47
|
+
report["items"][0]["id"] # 'falsifiability'
|
|
48
|
+
report["items"][0]["status"] # 'pass'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Export a diagram. The digraph types, such as `nomological_net`, return Graphviz DOT, which you can render with Graphviz or inspect directly, and the `causal_dag` type returns dagitty syntax for causal-inference tooling.
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
print(t.diagram("nomological_net"))
|
|
55
|
+
print(t.diagram("causal_dag"))
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
With the optional render extra (`pip install theoryforge[render]`), `render_diagram(t, "nomological_net")` wraps the DOT in a `graphviz.Source` that displays inline in a notebook; the `causal_dag` view is the one exception, since dagitty syntax renders in a dagitty tool rather than Graphviz. Rendered, the nomological net reads as a figure.
|
|
59
|
+
|
|
60
|
+
<div class="tf-figure tf-diagram"><svg width="561pt" height="49pt"
|
|
61
|
+
viewBox="0.00 0.00 561.43 48.61" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
62
|
+
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 44.6141)">
|
|
63
|
+
<title>nomological_net</title>
|
|
64
|
+
<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-44.6141 557.426,-44.6141 557.426,4 -4,4"/>
|
|
65
|
+
<!-- c_arousal -->
|
|
66
|
+
<g id="node1" class="node">
|
|
67
|
+
<title>c_arousal</title>
|
|
68
|
+
<path fill="none" stroke="#000000" d="M124.2158,-40.6141C124.2158,-40.6141 11.928,-40.6141 11.928,-40.6141 5.928,-40.6141 -.072,-34.6141 -.072,-28.6141 -.072,-28.6141 -.072,-16.6141 -.072,-16.6141 -.072,-10.6141 5.928,-4.6141 11.928,-4.6141 11.928,-4.6141 124.2158,-4.6141 124.2158,-4.6141 130.2158,-4.6141 136.2158,-10.6141 136.2158,-16.6141 136.2158,-16.6141 136.2158,-28.6141 136.2158,-28.6141 136.2158,-34.6141 130.2158,-40.6141 124.2158,-40.6141"/>
|
|
69
|
+
<text text-anchor="middle" x="68.0719" y="-18.4141" font-family="Times,serif" font-size="14.00" fill="#000000">Physiological arousal</text>
|
|
70
|
+
</g>
|
|
71
|
+
<!-- c_perceived_threat -->
|
|
72
|
+
<g id="node2" class="node">
|
|
73
|
+
<title>c_perceived_threat</title>
|
|
74
|
+
<path fill="none" stroke="#000000" d="M317.7883,-40.6141C317.7883,-40.6141 235.6601,-40.6141 235.6601,-40.6141 229.6601,-40.6141 223.6601,-34.6141 223.6601,-28.6141 223.6601,-28.6141 223.6601,-16.6141 223.6601,-16.6141 223.6601,-10.6141 229.6601,-4.6141 235.6601,-4.6141 235.6601,-4.6141 317.7883,-4.6141 317.7883,-4.6141 323.7883,-4.6141 329.7883,-10.6141 329.7883,-16.6141 329.7883,-16.6141 329.7883,-28.6141 329.7883,-28.6141 329.7883,-34.6141 323.7883,-40.6141 317.7883,-40.6141"/>
|
|
75
|
+
<text text-anchor="middle" x="276.7242" y="-18.4141" font-family="Times,serif" font-size="14.00" fill="#000000">Perceived threat</text>
|
|
76
|
+
</g>
|
|
77
|
+
<!-- c_arousal->c_perceived_threat -->
|
|
78
|
+
<g id="edge1" class="edge">
|
|
79
|
+
<title>c_arousal->c_perceived_threat</title>
|
|
80
|
+
<path fill="none" stroke="#000000" d="M136.3925,-22.6141C161.1432,-22.6141 188.9758,-22.6141 213.2884,-22.6141"/>
|
|
81
|
+
<polygon fill="#000000" stroke="#000000" points="213.4734,-26.1142 223.4734,-22.6141 213.4734,-19.1142 213.4734,-26.1142"/>
|
|
82
|
+
<text text-anchor="middle" x="179.7932" y="-26.8141" font-family="Times,serif" font-size="14.00" fill="#000000">increases</text>
|
|
83
|
+
</g>
|
|
84
|
+
<!-- c_perceived_threat->c_arousal -->
|
|
85
|
+
<g id="edge3" class="edge">
|
|
86
|
+
<title>c_perceived_threat->c_arousal</title>
|
|
87
|
+
<path fill="none" stroke="#000000" d="M223.3708,-5.2813C217.3752,-3.8622 211.313,-2.6531 205.4426,-1.8141 185.9221,.9757 164.8604,-.1373 145.2323,-2.9451"/>
|
|
88
|
+
<polygon fill="#000000" stroke="#000000" points="144.4398,.4729 135.1146,-4.5561 145.5406,-6.44 144.4398,.4729"/>
|
|
89
|
+
<text text-anchor="middle" x="179.7932" y="-5.8141" font-family="Times,serif" font-size="14.00" fill="#000000">causes</text>
|
|
90
|
+
</g>
|
|
91
|
+
<!-- c_avoidance -->
|
|
92
|
+
<g id="node3" class="node">
|
|
93
|
+
<title>c_avoidance</title>
|
|
94
|
+
<path fill="none" stroke="#000000" d="M541.4868,-40.6141C541.4868,-40.6141 429.2438,-40.6141 429.2438,-40.6141 423.2438,-40.6141 417.2438,-34.6141 417.2438,-28.6141 417.2438,-28.6141 417.2438,-16.6141 417.2438,-16.6141 417.2438,-10.6141 423.2438,-4.6141 429.2438,-4.6141 429.2438,-4.6141 541.4868,-4.6141 541.4868,-4.6141 547.4868,-4.6141 553.4868,-10.6141 553.4868,-16.6141 553.4868,-16.6141 553.4868,-28.6141 553.4868,-28.6141 553.4868,-34.6141 547.4868,-40.6141 541.4868,-40.6141"/>
|
|
95
|
+
<text text-anchor="middle" x="485.3653" y="-18.4141" font-family="Times,serif" font-size="14.00" fill="#000000">Avoidance behaviour</text>
|
|
96
|
+
</g>
|
|
97
|
+
<!-- c_perceived_threat->c_avoidance -->
|
|
98
|
+
<g id="edge2" class="edge">
|
|
99
|
+
<title>c_perceived_threat->c_avoidance</title>
|
|
100
|
+
<path fill="none" stroke="#000000" d="M329.913,-22.6141C353.3616,-22.6141 381.3891,-22.6141 407.1476,-22.6141"/>
|
|
101
|
+
<polygon fill="#000000" stroke="#000000" points="407.2695,-26.1142 417.2695,-22.6141 407.2694,-19.1142 407.2695,-26.1142"/>
|
|
102
|
+
<text text-anchor="middle" x="373.6552" y="-26.8141" font-family="Times,serif" font-size="14.00" fill="#000000">increases</text>
|
|
103
|
+
</g>
|
|
104
|
+
</g>
|
|
105
|
+
</svg></div>
|
|
106
|
+
|
|
107
|
+
Run the lexical redundancy screen. This returns every construct pair with a lexical similarity of their definitions and an `ok`/`review` flag, marking `review` the pairs whose definitions overlap enough to suggest jingle-jangle redundancy.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
t.redundancy_check()
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
A theory can be written back to disk with `t.write()`. The format follows the file extension, `.json` for JSON and otherwise YAML.
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
t.write("panic-network.theory.yaml") # YAML; use a .json path for JSON
|
|
117
|
+
reloaded = tf.read("panic-network.theory.yaml")
|
|
118
|
+
reloaded.id == t.id # True
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Next steps
|
|
122
|
+
|
|
123
|
+
The same `Theory` object supports the building, development and testing modes (`severity()`, `appraise_amendment()`, `preregister()`) and the literature layer (`read_corpus`, `litmap`, `landscape`). See the [API reference](api.md) for the full function list.
|
|
@@ -288,6 +288,20 @@
|
|
|
288
288
|
margin: 0 auto;
|
|
289
289
|
}
|
|
290
290
|
.tf-figure svg text { fill: currentColor; }
|
|
291
|
+
|
|
292
|
+
/* Rendered Graphviz diagrams (render_diagram output) carry their own white
|
|
293
|
+
canvas and ink-on-white text fills, so they must NOT inherit the
|
|
294
|
+
currentColor text rule above: in dark mode that would paint light text on
|
|
295
|
+
the white canvas. Present them as a rounded white card instead, sized by
|
|
296
|
+
their own aspect ratio up to a wider cap than the chart views. */
|
|
297
|
+
.tf-figure.tf-diagram svg {
|
|
298
|
+
max-width: 640px;
|
|
299
|
+
background: #fff;
|
|
300
|
+
border-radius: 10px;
|
|
301
|
+
padding: 10px;
|
|
302
|
+
border: 1px solid rgba(14, 34, 51, .12);
|
|
303
|
+
}
|
|
304
|
+
.tf-figure.tf-diagram svg text { fill: #1a1a1a; }
|
|
291
305
|
/* ---- Header source chip and primary sidebar ------------------------------ */
|
|
292
306
|
/* The source widget otherwise reserves a wide fixed column and fills it with
|
|
293
307
|
version/stars/forks facts; reduce it to the icon and host name. */
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title = {theoryforge: Systematic theory development},
|
|
3
3
|
author = {Pablo Bernabeu},
|
|
4
4
|
year = {2026},
|
|
5
|
-
note = {Python package version 0.
|
|
5
|
+
note = {Python package version 0.3.0},
|
|
6
6
|
doi = {10.5281/zenodo.21229964},
|
|
7
7
|
url = {https://doi.org/10.5281/zenodo.21229964},
|
|
8
8
|
}
|