theoryforge 0.2.0__tar.gz → 0.4.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.4.0}/PKG-INFO +11 -1
  2. {theoryforge-0.2.0 → theoryforge-0.4.0}/README.md +8 -0
  3. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/about.md +2 -2
  4. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/api.md +1 -0
  5. theoryforge-0.4.0/docs/getting-started.md +124 -0
  6. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/stylesheets/brand.css +19 -0
  7. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/theoryforge.bib +1 -1
  8. theoryforge-0.4.0/docs/workflow-modes.md +1017 -0
  9. {theoryforge-0.2.0 → theoryforge-0.4.0}/mkdocs.yml +1 -1
  10. {theoryforge-0.2.0 → theoryforge-0.4.0}/pyproject.toml +4 -1
  11. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/__init__.py +4 -1
  12. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/core.py +6 -0
  13. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/diagram.py +107 -31
  14. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/lit.py +16 -6
  15. theoryforge-0.4.0/src/theoryforge/render.py +93 -0
  16. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/conftest.py +1 -0
  17. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_diagram_redundancy.py +9 -6
  18. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_io.py +2 -1
  19. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_lit.py +9 -1
  20. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_modes.py +4 -3
  21. theoryforge-0.4.0/tests/test_render_diagram.py +72 -0
  22. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_rigor.py +1 -0
  23. theoryforge-0.2.0/docs/getting-started.md +0 -74
  24. theoryforge-0.2.0/docs/workflow-modes.md +0 -492
  25. {theoryforge-0.2.0 → theoryforge-0.4.0}/.gitignore +0 -0
  26. {theoryforge-0.2.0 → theoryforge-0.4.0}/LICENSE +0 -0
  27. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/assets/logo.png +0 -0
  28. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/assets/logo.svg +0 -0
  29. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/changelog.md +0 -0
  30. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/index.md +0 -0
  31. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/licence.md +0 -0
  32. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/literature.md +0 -0
  33. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/methodology.md +0 -0
  34. {theoryforge-0.2.0 → theoryforge-0.4.0}/docs/stylesheets/extra.css +0 -0
  35. {theoryforge-0.2.0 → theoryforge-0.4.0}/overrides/partials/header.html +0 -0
  36. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/_num.py +0 -0
  37. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/_resources.py +0 -0
  38. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/develop.py +0 -0
  39. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/dossier.py +0 -0
  40. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/embedding.py +0 -0
  41. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/osf.py +0 -0
  42. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/prereg.py +0 -0
  43. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/py.typed +0 -0
  44. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/redundancy.py +0 -0
  45. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/report_render.py +0 -0
  46. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/rigor.py +0 -0
  47. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/schema/rigor_checklist.yaml +0 -0
  48. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/schema/theory.schema.json +0 -0
  49. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/scoring.py +0 -0
  50. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/sem.py +0 -0
  51. {theoryforge-0.2.0 → theoryforge-0.4.0}/src/theoryforge/simulate.py +0 -0
  52. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_p3.py +0 -0
  53. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_p4.py +0 -0
  54. {theoryforge-0.2.0 → theoryforge-0.4.0}/tests/test_scalar_singleton.py +0 -0
  55. {theoryforge-0.2.0 → theoryforge-0.4.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.4.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.4.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.4.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,124 @@
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="446pt" height="69pt"
61
+ viewBox="0.00 0.00 445.97 69.20" 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(14.4 54.8)">
63
+ <title>nomological_net</title>
64
+ <!-- c_arousal -->
65
+ <g id="node1" class="node">
66
+ <title>c_arousal</title>
67
+ <path fill="#e4f1f1" stroke="#1e7b7b" stroke-width="1.1" d="M76.2612,-40.602C76.2612,-40.602 11.9128,-40.602 11.9128,-40.602 5.9128,-40.602 -.0872,-34.602 -.0872,-28.602 -.0872,-28.602 -.0872,-11.798 -.0872,-11.798 -.0872,-5.798 5.9128,.202 11.9128,.202 11.9128,.202 76.2612,.202 76.2612,.202 82.2612,.202 88.2612,-5.798 88.2612,-11.798 88.2612,-11.798 88.2612,-28.602 88.2612,-28.602 88.2612,-34.602 82.2612,-40.602 76.2612,-40.602"/>
68
+ <text text-anchor="middle" x="44.087" y="-23.5" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#12283a">Physiological</text>
69
+ <text text-anchor="middle" x="44.087" y="-10.3" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#12283a">arousal</text>
70
+ </g>
71
+ <!-- c_perceived_threat -->
72
+ <g id="node2" class="node">
73
+ <title>c_perceived_threat</title>
74
+ <path fill="#e4f1f1" stroke="#1e7b7b" stroke-width="1.1" d="M255.0714,-38.2C255.0714,-38.2 174.9202,-38.2 174.9202,-38.2 168.9202,-38.2 162.9202,-32.2 162.9202,-26.2 162.9202,-26.2 162.9202,-14.2 162.9202,-14.2 162.9202,-8.2 168.9202,-2.2 174.9202,-2.2 174.9202,-2.2 255.0714,-2.2 255.0714,-2.2 261.0714,-2.2 267.0714,-8.2 267.0714,-14.2 267.0714,-14.2 267.0714,-26.2 267.0714,-26.2 267.0714,-32.2 261.0714,-38.2 255.0714,-38.2"/>
75
+ <text text-anchor="middle" x="214.9958" y="-16.9" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#12283a">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="#7b909f" d="M88.5451,-20.2C109.0718,-20.2 133.7345,-20.2 155.8073,-20.2"/>
81
+ <polygon fill="#7b909f" stroke="#7b909f" points="155.8743,-22.6501 162.8743,-20.2 155.8742,-17.7501 155.8743,-22.6501"/>
82
+ <text text-anchor="middle" x="125.566" y="-23.2" font-family="Helvetica,sans-Serif" font-size="10.00" fill="#0f6e6e">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="#7b909f" d="M162.8635,-5.8055C157.5243,-4.7435 152.1542,-3.8393 146.958,-3.2 128.0852,-.8779 123.0087,-.5869 104.174,-3.2 101.2746,-3.6023 98.3185,-4.1088 95.3497,-4.6931"/>
88
+ <polygon fill="#7b909f" stroke="#7b909f" points="94.7481,-2.3164 88.4207,-6.1851 95.7796,-7.1066 94.7481,-2.3164"/>
89
+ <text text-anchor="middle" x="125.566" y="-6.2" font-family="Helvetica,sans-Serif" font-size="10.00" fill="#0f6e6e">causes</text>
90
+ </g>
91
+ <!-- c_avoidance -->
92
+ <g id="node3" class="node">
93
+ <title>c_avoidance</title>
94
+ <path fill="#e4f1f1" stroke="#1e7b7b" stroke-width="1.1" d="M405.3454,-40.602C405.3454,-40.602 353.6411,-40.602 353.6411,-40.602 347.6411,-40.602 341.6411,-34.602 341.6411,-28.602 341.6411,-28.602 341.6411,-11.798 341.6411,-11.798 341.6411,-5.798 347.6411,.202 353.6411,.202 353.6411,.202 405.3454,.202 405.3454,.202 411.3454,.202 417.3454,-5.798 417.3454,-11.798 417.3454,-11.798 417.3454,-28.602 417.3454,-28.602 417.3454,-34.602 411.3454,-40.602 405.3454,-40.602"/>
95
+ <text text-anchor="middle" x="379.4932" y="-23.5" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#12283a">Avoidance</text>
96
+ <text text-anchor="middle" x="379.4932" y="-10.3" font-family="Helvetica,sans-Serif" font-size="11.00" fill="#12283a">behaviour</text>
97
+ </g>
98
+ <!-- c_perceived_threat&#45;&gt;c_avoidance -->
99
+ <g id="edge2" class="edge">
100
+ <title>c_perceived_threat&#45;&gt;c_avoidance</title>
101
+ <path fill="none" stroke="#7b909f" d="M267.0438,-20.2C288.6829,-20.2 313.5608,-20.2 334.4062,-20.2"/>
102
+ <polygon fill="#7b909f" stroke="#7b909f" points="334.5994,-22.6501 341.5993,-20.2 334.5993,-17.7501 334.5994,-22.6501"/>
103
+ <text text-anchor="middle" x="304.4256" y="-23.2" font-family="Helvetica,sans-Serif" font-size="10.00" fill="#0f6e6e">increases</text>
104
+ </g>
105
+ </g>
106
+ </svg></div>
107
+
108
+ 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.
109
+
110
+ ```python
111
+ t.redundancy_check()
112
+ ```
113
+
114
+ A theory can be written back to disk with `t.write()`. The format follows the file extension, `.json` for JSON and otherwise YAML.
115
+
116
+ ```python
117
+ t.write("panic-network.theory.yaml") # YAML; use a .json path for JSON
118
+ reloaded = tf.read("panic-network.theory.yaml")
119
+ reloaded.id == t.id # True
120
+ ```
121
+
122
+ ## Next steps
123
+
124
+ 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,25 @@
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 at the diagram's own
296
+ natural size, so a four-node graph stays small and its type stays at
297
+ Graphviz's legible default; the IR wraps its labels and stacks its
298
+ layouts so every view fits a documentation column; should one still
299
+ overflow, it shrinks to the column rather than forcing a scrollbar. */
300
+ .tf-figure.tf-diagram { overflow-x: auto; }
301
+ .tf-figure.tf-diagram svg {
302
+ width: auto;
303
+ max-width: 100%;
304
+ background: #fff;
305
+ border-radius: 10px;
306
+ padding: 10px;
307
+ border: 1px solid rgba(14, 34, 51, .12);
308
+ }
309
+ .tf-figure.tf-diagram svg text { fill: #1a1a1a; }
291
310
  /* ---- Header source chip and primary sidebar ------------------------------ */
292
311
  /* The source widget otherwise reserves a wide fixed column and fills it with
293
312
  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.4.0},
6
6
  doi = {10.5281/zenodo.21229964},
7
7
  url = {https://doi.org/10.5281/zenodo.21229964},
8
8
  }