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.
Files changed (55) hide show
  1. {theoryforge-0.2.0 → theoryforge-0.3.0}/PKG-INFO +11 -1
  2. {theoryforge-0.2.0 → theoryforge-0.3.0}/README.md +8 -0
  3. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/about.md +2 -2
  4. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/api.md +1 -0
  5. theoryforge-0.3.0/docs/getting-started.md +123 -0
  6. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/stylesheets/brand.css +14 -0
  7. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/theoryforge.bib +1 -1
  8. theoryforge-0.3.0/docs/workflow-modes.md +890 -0
  9. {theoryforge-0.2.0 → theoryforge-0.3.0}/mkdocs.yml +1 -1
  10. {theoryforge-0.2.0 → theoryforge-0.3.0}/pyproject.toml +4 -1
  11. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/__init__.py +4 -1
  12. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/core.py +6 -0
  13. theoryforge-0.3.0/src/theoryforge/render.py +93 -0
  14. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/conftest.py +1 -0
  15. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_diagram_redundancy.py +3 -2
  16. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_io.py +2 -1
  17. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_modes.py +2 -1
  18. theoryforge-0.3.0/tests/test_render_diagram.py +72 -0
  19. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_rigor.py +1 -0
  20. theoryforge-0.2.0/docs/getting-started.md +0 -74
  21. theoryforge-0.2.0/docs/workflow-modes.md +0 -492
  22. {theoryforge-0.2.0 → theoryforge-0.3.0}/.gitignore +0 -0
  23. {theoryforge-0.2.0 → theoryforge-0.3.0}/LICENSE +0 -0
  24. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/assets/logo.png +0 -0
  25. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/assets/logo.svg +0 -0
  26. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/changelog.md +0 -0
  27. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/index.md +0 -0
  28. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/licence.md +0 -0
  29. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/literature.md +0 -0
  30. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/methodology.md +0 -0
  31. {theoryforge-0.2.0 → theoryforge-0.3.0}/docs/stylesheets/extra.css +0 -0
  32. {theoryforge-0.2.0 → theoryforge-0.3.0}/overrides/partials/header.html +0 -0
  33. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/_num.py +0 -0
  34. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/_resources.py +0 -0
  35. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/develop.py +0 -0
  36. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/diagram.py +0 -0
  37. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/dossier.py +0 -0
  38. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/embedding.py +0 -0
  39. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/lit.py +0 -0
  40. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/osf.py +0 -0
  41. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/prereg.py +0 -0
  42. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/py.typed +0 -0
  43. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/redundancy.py +0 -0
  44. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/report_render.py +0 -0
  45. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/rigor.py +0 -0
  46. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/schema/rigor_checklist.yaml +0 -0
  47. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/schema/theory.schema.json +0 -0
  48. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/scoring.py +0 -0
  49. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/sem.py +0 -0
  50. {theoryforge-0.2.0 → theoryforge-0.3.0}/src/theoryforge/simulate.py +0 -0
  51. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_lit.py +0 -0
  52. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_p3.py +0 -0
  53. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_p4.py +0 -0
  54. {theoryforge-0.2.0 → theoryforge-0.3.0}/tests/test_scalar_singleton.py +0 -0
  55. {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.2.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.2.0). <a href="https://doi.org/10.5281/zenodo.21229964">https://doi.org/10.5281/zenodo.21229964</a></p>
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.2.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
  }
@@ -28,6 +28,7 @@ canonical path so the function, rather than the module, is shown.
28
28
  - compile_sem
29
29
  - embedding_redundancy
30
30
  - render_report
31
+ - render_diagram
31
32
  - osf_push
32
33
 
33
34
  ::: theoryforge.diagram.diagram
@@ -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&#45;&gt;c_perceived_threat -->
78
+ <g id="edge1" class="edge">
79
+ <title>c_arousal&#45;&gt;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&#45;&gt;c_arousal -->
85
+ <g id="edge3" class="edge">
86
+ <title>c_perceived_threat&#45;&gt;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&#45;&gt;c_avoidance -->
98
+ <g id="edge2" class="edge">
99
+ <title>c_perceived_threat&#45;&gt;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.2.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
  }