theoryforge 0.1.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 (51) hide show
  1. theoryforge-0.1.0/.gitignore +34 -0
  2. theoryforge-0.1.0/LICENSE +21 -0
  3. theoryforge-0.1.0/PKG-INFO +113 -0
  4. theoryforge-0.1.0/README.md +85 -0
  5. theoryforge-0.1.0/docs/about.md +58 -0
  6. theoryforge-0.1.0/docs/api.md +37 -0
  7. theoryforge-0.1.0/docs/assets/logo.png +0 -0
  8. theoryforge-0.1.0/docs/assets/logo.svg +35 -0
  9. theoryforge-0.1.0/docs/changelog.md +45 -0
  10. theoryforge-0.1.0/docs/getting-started.md +54 -0
  11. theoryforge-0.1.0/docs/index.md +52 -0
  12. theoryforge-0.1.0/docs/licence.md +9 -0
  13. theoryforge-0.1.0/docs/literature.md +298 -0
  14. theoryforge-0.1.0/docs/methodology.md +120 -0
  15. theoryforge-0.1.0/docs/stylesheets/brand.css +338 -0
  16. theoryforge-0.1.0/docs/stylesheets/extra.css +20 -0
  17. theoryforge-0.1.0/docs/theoryforge.bib +8 -0
  18. theoryforge-0.1.0/docs/workflow-modes.md +429 -0
  19. theoryforge-0.1.0/mkdocs.yml +94 -0
  20. theoryforge-0.1.0/overrides/partials/header.html +82 -0
  21. theoryforge-0.1.0/pyproject.toml +58 -0
  22. theoryforge-0.1.0/src/theoryforge/__init__.py +66 -0
  23. theoryforge-0.1.0/src/theoryforge/_num.py +19 -0
  24. theoryforge-0.1.0/src/theoryforge/_resources.py +14 -0
  25. theoryforge-0.1.0/src/theoryforge/core.py +321 -0
  26. theoryforge-0.1.0/src/theoryforge/develop.py +62 -0
  27. theoryforge-0.1.0/src/theoryforge/diagram.py +267 -0
  28. theoryforge-0.1.0/src/theoryforge/dossier.py +59 -0
  29. theoryforge-0.1.0/src/theoryforge/embedding.py +51 -0
  30. theoryforge-0.1.0/src/theoryforge/lit.py +261 -0
  31. theoryforge-0.1.0/src/theoryforge/osf.py +53 -0
  32. theoryforge-0.1.0/src/theoryforge/prereg.py +61 -0
  33. theoryforge-0.1.0/src/theoryforge/py.typed +0 -0
  34. theoryforge-0.1.0/src/theoryforge/redundancy.py +71 -0
  35. theoryforge-0.1.0/src/theoryforge/report_render.py +31 -0
  36. theoryforge-0.1.0/src/theoryforge/rigor.py +228 -0
  37. theoryforge-0.1.0/src/theoryforge/schema/rigor_checklist.yaml +72 -0
  38. theoryforge-0.1.0/src/theoryforge/schema/theory.schema.json +177 -0
  39. theoryforge-0.1.0/src/theoryforge/scoring.py +42 -0
  40. theoryforge-0.1.0/src/theoryforge/sem.py +43 -0
  41. theoryforge-0.1.0/src/theoryforge/simulate.py +46 -0
  42. theoryforge-0.1.0/tests/conftest.py +19 -0
  43. theoryforge-0.1.0/tests/test_diagram_redundancy.py +81 -0
  44. theoryforge-0.1.0/tests/test_io.py +31 -0
  45. theoryforge-0.1.0/tests/test_lit.py +88 -0
  46. theoryforge-0.1.0/tests/test_modes.py +72 -0
  47. theoryforge-0.1.0/tests/test_p3.py +29 -0
  48. theoryforge-0.1.0/tests/test_p4.py +52 -0
  49. theoryforge-0.1.0/tests/test_rigor.py +50 -0
  50. theoryforge-0.1.0/tests/test_scalar_singleton.py +64 -0
  51. theoryforge-0.1.0/tests/test_validation_parity.py +94 -0
@@ -0,0 +1,34 @@
1
+ # R
2
+ .Rproj.user/
3
+ .Rhistory
4
+ .RData
5
+ .Ruserdata
6
+ *.Rcheck/
7
+ *.tar.gz
8
+ r/theoryforge/man/*.Rd.bak
9
+
10
+ # Python
11
+ __pycache__/
12
+ *.py[cod]
13
+ *.egg-info/
14
+ .eggs/
15
+ build/
16
+ dist/
17
+ .venv/
18
+ venv/
19
+ .pytest_cache/
20
+ .mypy_cache/
21
+ .ruff_cache/
22
+
23
+ # Quarto / docs build
24
+ /_site/
25
+ *.html.bak
26
+ .quarto/
27
+ /python/site/
28
+ /r/theoryforge/docs/
29
+ # Manuscript kept out of the public repo pending journal submission
30
+ /manuscript/
31
+
32
+ # OS
33
+ .DS_Store
34
+ Thumbs.db
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pablo Bernabeu
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,113 @@
1
+ Metadata-Version: 2.4
2
+ Name: theoryforge
3
+ Version: 0.1.0
4
+ Summary: Systematic theory development.
5
+ Project-URL: Homepage, https://github.com/pablobernabeu/theoryforge
6
+ Project-URL: Repository, https://github.com/pablobernabeu/theoryforge
7
+ Project-URL: Issues, https://github.com/pablobernabeu/theoryforge/issues
8
+ Author-email: Pablo Bernabeu <pcbernabeu@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: falsifiability,metascience,psychology,reproducibility,theory
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: pyyaml>=6.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: mypy; extra == 'dev'
25
+ Requires-Dist: pytest>=7.0; extra == 'dev'
26
+ Requires-Dist: ruff; extra == 'dev'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # theoryforge (Python) <img src="docs/assets/logo.png" align="right" height="138" alt="theoryforge hex logo" />
30
+
31
+ Systematic theory development: a rigorous, reproducible workflow for building, developing and
32
+ testing scientific theories. This is the Python twin of [the R package](https://pablobernabeu.github.io/theoryforge/r/) of the same name,
33
+ and the two return identical results.
34
+
35
+ The rendered documentation site, with the API reference and worked guides, is at
36
+ <https://pablobernabeu.github.io/theoryforge/python/>.
37
+
38
+ Prefer to click rather than install? The
39
+ [interactive web app](https://pablobernabeu.github.io/theoryforge/apps/py/) runs this package in
40
+ your browser via [Pyodide](https://pyodide.org/): load a theory, run any operation, and export the
41
+ visualisation (SVG/PNG) and the Python code to reproduce it.
42
+
43
+ ```python
44
+ import theoryforge as tf
45
+
46
+ # read + check an existing theory
47
+ t = tf.read("../fixtures/panic-network.theory.yaml")
48
+ t.validate() # structural validation against the shared schema
49
+ print(t.report("json")) # 12-item rigour checklist + gate
50
+ print(t.diagram("nomological_net"))# Graphviz DOT
51
+ t.redundancy_check() # lexical jingle-jangle screen
52
+
53
+ # BUILD a theory programmatically (provenance auto-logged)
54
+ b = (tf.new_theory("demo", "Demo theory")
55
+ .add_construct("a", "Alpha", "the first thing", measurement=["m1"], boundary_conditions=["adults"])
56
+ .add_proposition("p1", "a", "b", "increases", mechanism="a drives b")
57
+ .add_prediction("pred1", "a point claim", "point", derives_from=["p1"]))
58
+
59
+ # DEVELOP: progressive vs degenerating appraisal of an amendment
60
+ v1 = tf.read("../fixtures/panic-network.theory.yaml")
61
+ v2 = tf.read("../fixtures/panic-network-2026-v2.theory.yaml")
62
+ print(v2.appraise_amendment(v1)) # -> {'verdict': 'progressive', ...}
63
+
64
+ # TEST: operationalised severity + a preregistration document
65
+ t.severity() # per-prediction risk + computed severity
66
+ print(t.preregister()) # markdown prereg
67
+
68
+ # LITERATURE: map the field, then position the theory against it
69
+ corpus = tf.read_corpus("../fixtures/panic-corpus.yaml")
70
+ tf.litmap(corpus) # keyword co-occurrence, themes, co-citation
71
+ t.landscape(corpus) # -> themes flagged 'under_theorised' / 'crowded' (redundancy risk)
72
+ # tf.fetch_corpus("panic disorder theory") # optional OpenAlex fetch (network call)
73
+ ```
74
+
75
+ The `../fixtures/*.yaml` files referenced above are sample theories that live in the
76
+ [project repository](https://github.com/pablobernabeu/theoryforge); adjust the paths to
77
+ your own theory files when running the examples.
78
+
79
+ ## Install
80
+
81
+ ```bash
82
+ pip install theoryforge
83
+ ```
84
+
85
+ To work on the package itself, install an editable checkout with the development extras:
86
+
87
+ ```bash
88
+ pip install -e ".[dev]"
89
+ ```
90
+
91
+ ## Test
92
+
93
+ ```bash
94
+ pytest
95
+ ```
96
+
97
+ ## What the package provides
98
+
99
+ The deterministic core covers theory-object I/O and validation, the 12-item rigour checklist
100
+ with its weighted aggregate score and blocker gate, ten diagram exporters and a lexical
101
+ redundancy screen. The three workflow modes sit on the same object: a BUILDING builder API with
102
+ auto-logged provenance, the Lakatosian amendment appraisal (DEVELOPMENT), and the
103
+ operationalised severity rubric with preregistration export (TESTING). The literature layer
104
+ comprises `read_corpus`, `litmap` (keyword co-occurrence, deterministic connected-component
105
+ themes and co-citation), `landscape` (which maps a theory and its alternatives onto the themes,
106
+ flagging under-theorised fronts and redundancy risk), `lit_diagram`, the network-dependent
107
+ `fetch_corpus` OpenAlex adapter, and `new_evidence_dois` (a deterministic check for candidate
108
+ DOIs, from any search tool, not yet cited by a theory). `compile_sem` translates constructs and
109
+ propositions to lavaan model syntax, and `dossier` assembles a reviewer-facing audit bundle.
110
+ Simulation and adapters round the package out: `simulate` (a deterministic dynamical-system
111
+ runner over the construct network), `render_report` (a Quarto report wrapping the dossier),
112
+ `embedding_redundancy` (an opt-in, embedder-dependent screen) and `osf_push` (an OSF
113
+ deposit adapter, dry-run by default).
@@ -0,0 +1,85 @@
1
+ # theoryforge (Python) <img src="docs/assets/logo.png" align="right" height="138" alt="theoryforge hex logo" />
2
+
3
+ Systematic theory development: a rigorous, reproducible workflow for building, developing and
4
+ testing scientific theories. This is the Python twin of [the R package](https://pablobernabeu.github.io/theoryforge/r/) of the same name,
5
+ and the two return identical results.
6
+
7
+ The rendered documentation site, with the API reference and worked guides, is at
8
+ <https://pablobernabeu.github.io/theoryforge/python/>.
9
+
10
+ Prefer to click rather than install? The
11
+ [interactive web app](https://pablobernabeu.github.io/theoryforge/apps/py/) runs this package in
12
+ your browser via [Pyodide](https://pyodide.org/): load a theory, run any operation, and export the
13
+ visualisation (SVG/PNG) and the Python code to reproduce it.
14
+
15
+ ```python
16
+ import theoryforge as tf
17
+
18
+ # read + check an existing theory
19
+ t = tf.read("../fixtures/panic-network.theory.yaml")
20
+ t.validate() # structural validation against the shared schema
21
+ print(t.report("json")) # 12-item rigour checklist + gate
22
+ print(t.diagram("nomological_net"))# Graphviz DOT
23
+ t.redundancy_check() # lexical jingle-jangle screen
24
+
25
+ # BUILD a theory programmatically (provenance auto-logged)
26
+ b = (tf.new_theory("demo", "Demo theory")
27
+ .add_construct("a", "Alpha", "the first thing", measurement=["m1"], boundary_conditions=["adults"])
28
+ .add_proposition("p1", "a", "b", "increases", mechanism="a drives b")
29
+ .add_prediction("pred1", "a point claim", "point", derives_from=["p1"]))
30
+
31
+ # DEVELOP: progressive vs degenerating appraisal of an amendment
32
+ v1 = tf.read("../fixtures/panic-network.theory.yaml")
33
+ v2 = tf.read("../fixtures/panic-network-2026-v2.theory.yaml")
34
+ print(v2.appraise_amendment(v1)) # -> {'verdict': 'progressive', ...}
35
+
36
+ # TEST: operationalised severity + a preregistration document
37
+ t.severity() # per-prediction risk + computed severity
38
+ print(t.preregister()) # markdown prereg
39
+
40
+ # LITERATURE: map the field, then position the theory against it
41
+ corpus = tf.read_corpus("../fixtures/panic-corpus.yaml")
42
+ tf.litmap(corpus) # keyword co-occurrence, themes, co-citation
43
+ t.landscape(corpus) # -> themes flagged 'under_theorised' / 'crowded' (redundancy risk)
44
+ # tf.fetch_corpus("panic disorder theory") # optional OpenAlex fetch (network call)
45
+ ```
46
+
47
+ The `../fixtures/*.yaml` files referenced above are sample theories that live in the
48
+ [project repository](https://github.com/pablobernabeu/theoryforge); adjust the paths to
49
+ your own theory files when running the examples.
50
+
51
+ ## Install
52
+
53
+ ```bash
54
+ pip install theoryforge
55
+ ```
56
+
57
+ To work on the package itself, install an editable checkout with the development extras:
58
+
59
+ ```bash
60
+ pip install -e ".[dev]"
61
+ ```
62
+
63
+ ## Test
64
+
65
+ ```bash
66
+ pytest
67
+ ```
68
+
69
+ ## What the package provides
70
+
71
+ The deterministic core covers theory-object I/O and validation, the 12-item rigour checklist
72
+ with its weighted aggregate score and blocker gate, ten diagram exporters and a lexical
73
+ redundancy screen. The three workflow modes sit on the same object: a BUILDING builder API with
74
+ auto-logged provenance, the Lakatosian amendment appraisal (DEVELOPMENT), and the
75
+ operationalised severity rubric with preregistration export (TESTING). The literature layer
76
+ comprises `read_corpus`, `litmap` (keyword co-occurrence, deterministic connected-component
77
+ themes and co-citation), `landscape` (which maps a theory and its alternatives onto the themes,
78
+ flagging under-theorised fronts and redundancy risk), `lit_diagram`, the network-dependent
79
+ `fetch_corpus` OpenAlex adapter, and `new_evidence_dois` (a deterministic check for candidate
80
+ DOIs, from any search tool, not yet cited by a theory). `compile_sem` translates constructs and
81
+ propositions to lavaan model syntax, and `dossier` assembles a reviewer-facing audit bundle.
82
+ Simulation and adapters round the package out: `simulate` (a deterministic dynamical-system
83
+ runner over the construct network), `render_report` (a Quarto report wrapping the dossier),
84
+ `embedding_redundancy` (an opt-in, embedder-dependent screen) and `osf_push` (an OSF
85
+ deposit adapter, dry-run by default).
@@ -0,0 +1,58 @@
1
+ # About
2
+
3
+ ## Citing theoryforge
4
+
5
+ If you use the Python package in your work, please cite it:
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.1.0). <a href="https://doi.org/10.5281/zenodo.21229964">https://doi.org/10.5281/zenodo.21229964</a></p>
8
+
9
+ ```bibtex
10
+ @Manual{theoryforge,
11
+ title = {theoryforge: Systematic theory development},
12
+ author = {Pablo Bernabeu},
13
+ year = {2026},
14
+ note = {Python package version 0.1.0},
15
+ doi = {10.5281/zenodo.21229964},
16
+ url = {https://doi.org/10.5281/zenodo.21229964},
17
+ }
18
+ ```
19
+
20
+ You can <a href="../theoryforge.bib" download>download the BibTeX entry</a>. The package
21
+ installs with `pip install theoryforge`.
22
+
23
+ ## The developer
24
+
25
+ theoryforge is developed and maintained by
26
+ [Pablo Bernabeu](https://pablobernabeu.github.io), a researcher in the
27
+ Department of Education at the University of Oxford. His work spans cognitive psychology and
28
+ neuroscience, linguistics, education and digital technologies, and research methods and open
29
+ science, with hands-on experience in behavioural and EEG experiments, corpus analysis,
30
+ computational modelling and statistics. He develops open, reproducible research software in R
31
+ and Python, and is a Fellow of the Software Sustainability Institute. His
32
+ [ORCID record](https://orcid.org/0000-0003-1083-2460) lists his other work.
33
+
34
+ This Python package has a feature-parity twin written in R. Its documentation lives at the
35
+ [theoryforge (R) site](https://pablobernabeu.github.io/theoryforge/r/), keeping a theory
36
+ development workflow legible across both languages.
37
+
38
+ ## Licence
39
+
40
+ theoryforge is released under the MIT licence, a permissive licence that allows use,
41
+ modification and redistribution provided the copyright and licence notices are kept. The full
42
+ text is reproduced on this site's [licence page](licence.md).
43
+
44
+ ## Versioning and archival
45
+
46
+ Releases are tagged on [GitHub](https://github.com/pablobernabeu/theoryforge/releases) and
47
+ archived on [Zenodo](https://doi.org/10.5281/zenodo.21229964). The concept DOI,
48
+ 10.5281/zenodo.21229964, always resolves to the latest version, so a citation stays current
49
+ without naming a version. The [changelog](changelog.md) records what changed in each release.
50
+
51
+ ## Contributing and support
52
+
53
+ Bugs and feature requests are best reported on the
54
+ [GitHub issues page](https://github.com/pablobernabeu/theoryforge/issues), and the
55
+ [contributing guide](https://github.com/pablobernabeu/theoryforge/blob/main/.github/CONTRIBUTING.md)
56
+ explains how to set up a development environment and propose a change. Because the OSF deposit
57
+ adapter takes a personal access token, never paste that token, or any other secret, into an
58
+ issue; replace it with a placeholder.
@@ -0,0 +1,37 @@
1
+ # API reference
2
+
3
+ Every public function and the `Theory` class. The three functions whose name
4
+ matches their module (`diagram`, `dossier`, `simulate`) are documented by their
5
+ canonical path so the function, rather than the module, is shown.
6
+
7
+ ::: theoryforge
8
+ options:
9
+ members:
10
+ - Theory
11
+ - read
12
+ - write
13
+ - new_theory
14
+ - check
15
+ - report
16
+ - redundancy_check
17
+ - tokens
18
+ - jaccard
19
+ - severity
20
+ - appraise_amendment
21
+ - preregister
22
+ - read_corpus
23
+ - litmap
24
+ - landscape
25
+ - lit_diagram
26
+ - fetch_corpus
27
+ - new_evidence_dois
28
+ - compile_sem
29
+ - embedding_redundancy
30
+ - render_report
31
+ - osf_push
32
+
33
+ ::: theoryforge.diagram.diagram
34
+
35
+ ::: theoryforge.dossier.dossier
36
+
37
+ ::: theoryforge.simulate.simulate
Binary file
@@ -0,0 +1,35 @@
1
+ <svg viewBox="0 0 174 200" xmlns="http://www.w3.org/2000/svg">
2
+ <defs>
3
+ <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
4
+ <stop offset="0" stop-color="#22384f"/>
5
+ <stop offset="1" stop-color="#101b27"/>
6
+ </linearGradient>
7
+ <radialGradient id="ember" cx="0.5" cy="0.38" r="0.72">
8
+ <stop offset="0" stop-color="#ffce72"/>
9
+ <stop offset="1" stop-color="#ef9d2c"/>
10
+ </radialGradient>
11
+ <marker id="ah" markerWidth="5" markerHeight="5" refX="4.2" refY="2.3" orient="auto">
12
+ <path d="M0,0 L4.6,2.3 L0,4.6 Z" fill="#7ad0c1"/>
13
+ </marker>
14
+ </defs>
15
+
16
+ <path d="M87,7 L167,53.5 L167,146.5 L87,193 L7,146.5 L7,53.5 Z"
17
+ fill="url(#bg)" stroke="#4cc2b0" stroke-width="7" stroke-linejoin="round"/>
18
+ <path d="M87,15.4 L159.8,57.7 L159.8,142.3 L87,184.6 L14.2,142.3 L14.2,57.7 Z"
19
+ fill="none" stroke="#ffffff" stroke-opacity="0.06" stroke-width="1.4" stroke-linejoin="round"/>
20
+
21
+ <!-- construct network (shifted down to centre the content) -->
22
+ <g stroke="#7ad0c1" stroke-width="2.2" fill="none">
23
+ <line x1="70" y1="65" x2="104" y2="65" marker-end="url(#ah)"/>
24
+ <line x1="67" y1="74" x2="80" y2="88" marker-end="url(#ah)"/>
25
+ <line x1="107" y1="74" x2="94" y2="88" marker-end="url(#ah)"/>
26
+ </g>
27
+ <circle cx="61" cy="65" r="9" fill="#4cc2b0" stroke="#101b27" stroke-width="2.2"/>
28
+ <circle cx="113" cy="65" r="9" fill="#4cc2b0" stroke="#101b27" stroke-width="2.2"/>
29
+ <circle cx="87" cy="97" r="10" fill="url(#ember)" stroke="#101b27" stroke-width="2.2"/>
30
+
31
+ <!-- wordmark -->
32
+ <text x="87" y="139" text-anchor="middle"
33
+ font-family="Segoe UI, Helvetica, Arial, sans-serif"
34
+ font-size="24" font-weight="700" letter-spacing="-0.4"><tspan fill="#f3f6f7">theory</tspan><tspan fill="#f6b24a">forge</tspan></text>
35
+ </svg>
@@ -0,0 +1,45 @@
1
+ # Changelog
2
+
3
+ Source: [NEWS.md](https://github.com/pablobernabeu/theoryforge/blob/main/r/theoryforge/NEWS.md)
4
+
5
+ ---
6
+
7
+ ## theoryforge 0.1.0
8
+
9
+ First public release. The package provides a reproducible workflow for building,
10
+ developing and testing scientific theories, with behaviour pinned by a shared
11
+ specification
12
+ ([`API_SPEC.md`](https://github.com/pablobernabeu/theoryforge/blob/main/API_SPEC.md)) so the R
13
+ and Python twins return identical verdicts and byte-identical diagram intermediate
14
+ representations.
15
+
16
+ * Core: theory-object input, output and structural validation; a 12-item
17
+ rigour checklist with a weighted aggregate score and a blocker gate; diagram
18
+ intermediate representations (nomological net, provenance, causal DAG); and a
19
+ deterministic lexical construct-redundancy screen. Where the schema expects an
20
+ array of strings, a nonempty scalar string is read as a singleton list
21
+ (API_SPEC.md section 4), so natural YAML such as `derives_from: p1` yields the
22
+ same rigour verdict and gate in both twins; an empty or whitespace-only scalar
23
+ counts as absent.
24
+ * Workflow modes: a builder API with auto-logged provenance (BUILDING); an
25
+ operationalised severity rubric and preregistration export (TESTING); and a
26
+ Lakatosian progressive-versus-degenerating amendment appraisal (DEVELOPMENT).
27
+ * Literature layer: a deterministic bibliometric mapping (`litmap`,
28
+ `landscape`, `lit_diagram`), a parity-exempt OpenAlex corpus adapter, and a
29
+ deterministic, dependency-free check for DOIs not yet cited by a theory
30
+ (`new_evidence_dois`), for use with a search from any source, including the
31
+ companion `scopusflow` package. `lit_diagram` lists the valid types in its
32
+ unknown-type error, matching `diagram`.
33
+ * Testing and review: lavaan model-syntax compilation (`compile_sem`) and a
34
+ reviewer-facing audit dossier (`dossier`).
35
+ * Simulation, reporting and deposit: a deterministic dynamical-system runner
36
+ (`simulate`), a Quarto report wrapper (`render_report`), an opt-in
37
+ embedding redundancy screen (`embedding_redundancy`), and an OSF deposit
38
+ adapter (`osf_push`, dry-run by default). `osf_push` percent-encodes the
39
+ filename component of the upload URL, keeping the dry-run request identical
40
+ across the twins.
41
+ * Cross-language determinism: the literature layer and the amendment appraisal
42
+ sort keywords and ids by codepoint regardless of locale, so mixed-case inputs
43
+ order identically in both twins.
44
+ * Metadata: `theoryforge.__version__` is read from the installed distribution's
45
+ metadata rather than duplicated in source.
@@ -0,0 +1,54 @@
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
+ Export a diagram. The `nomological_net` type returns Graphviz DOT, which you can render with Graphviz or inspect directly.
41
+
42
+ ```python
43
+ print(t.diagram("nomological_net"))
44
+ ```
45
+
46
+ 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.
47
+
48
+ ```python
49
+ t.redundancy_check()
50
+ ```
51
+
52
+ ## Next steps
53
+
54
+ 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.
@@ -0,0 +1,52 @@
1
+ # theoryforge <span class="mrd-lang">(Python)</span>
2
+
3
+ theoryforge treats a scientific theory as a versioned, machine-checkable object, so that
4
+ building, developing and testing it becomes systematic and reproducible. It targets the
5
+ familiar weaknesses of soft-science theorising: vague constructs, unfalsifiable claims,
6
+ redundant 'jingle-jangle' constructs and amendments that quietly weaken a theory rather than
7
+ strengthen it. Each weakness becomes something the package can surface and check.
8
+
9
+ The package scaffolds the three workflow modes (building, development and testing), scores a
10
+ theory against a 12-item structural rigour checklist drawn from the methodology literature, generates
11
+ diagrams and positions the theory within the bibliometric literature. This is the Python twin
12
+ of [the R package](https://pablobernabeu.github.io/theoryforge/r/) of the same name, and the
13
+ two return identical results (see the [API reference](api.md) for the shared specification
14
+ behind that guarantee).
15
+
16
+ For the fuller rationale, what each rigour check establishes, and exactly how every reported
17
+ value is computed, see [Methodological foundations](methodology.md). For a step-by-step
18
+ walkthrough, see [Getting started](getting-started.md). The repository
19
+ [README](https://github.com/pablobernabeu/theoryforge) gives an overview and the
20
+ [API reference](api.md) lists every function.
21
+
22
+ !!! tip "Try it in your browser (no install)"
23
+ The [**interactive web app**](https://pablobernabeu.github.io/theoryforge/apps/py/) runs this
24
+ package entirely client-side via [Pyodide](https://pyodide.org/). Load a theory, run any
25
+ operation, and export both the visualisation (SVG/PNG) and the Python code to reproduce it.
26
+
27
+ ## Install
28
+
29
+ ```bash
30
+ pip install theoryforge
31
+ ```
32
+
33
+ ## At a glance
34
+
35
+ ```python
36
+ import theoryforge as tf
37
+
38
+ t = tf.read("panic-network.theory.yaml")
39
+ t.check() # 12-item rigour checklist + gate
40
+ t.severity() # operationalised severity rubric
41
+ t.preregister() # preregistration document
42
+ corpus = tf.read_corpus("panic-corpus.yaml")
43
+ t.landscape(corpus) # under-theorised fronts + redundancy risk
44
+ ```
45
+
46
+ ## Author
47
+
48
+ theoryforge is written and maintained by
49
+ [Pablo Bernabeu](https://pablobernabeu.github.io). The R and
50
+ Python packages share one specification and are released under the MIT licence.
51
+
52
+ Archived on Zenodo: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21229964.svg)](https://doi.org/10.5281/zenodo.21229964)
@@ -0,0 +1,9 @@
1
+ # Licence
2
+
3
+ theoryforge is released under the MIT licence, reproduced below from the
4
+ repository's [`LICENSE`](https://github.com/pablobernabeu/theoryforge/blob/main/python/LICENSE)
5
+ file.
6
+
7
+ ```text
8
+ --8<-- "LICENSE"
9
+ ```