spell-exploder 0.1.0__py3-none-any.whl

spell_exploder-0.1.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: spell-exploder
+Version: 0.1.0
+Summary: Analyze natural language through complex systems science, information theory, and evolutionary game theory.
+Author: Spellcaster Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/inc-research/spell-exploder
+Project-URL: Documentation, https://github.com/inc-research/spell-exploder#readme
+Project-URL: Repository, https://github.com/inc-research/spell-exploder
+Keywords: nlp,information-theory,complex-systems,text-analysis,evolutionary-game-theory,linguistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: spacy>=3.4
+Requires-Dist: scipy>=1.9
+Requires-Dist: python-Levenshtein>=0.20
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Requires-Dist: seaborn>=0.12; extra == "viz"
+Provides-Extra: graphs
+Requires-Dist: networkx>=3.0; extra == "graphs"
+Provides-Extra: ml
+Requires-Dist: sentence-transformers>=2.0; extra == "ml"
+Requires-Dist: scikit-learn>=1.0; extra == "ml"
+Provides-Extra: all
+Requires-Dist: spell-exploder[graphs,ml,viz]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: spell-exploder[all]; extra == "dev"
+Dynamic: license-file
+
+# Spell Exploder
+
+Analyze natural language text through complex systems science, information theory, information-theoretic physics analogues, and evolutionary game theory.
+
+Spell Exploder provides four complementary analyzers that reveal the hidden structural, informational, and evolutionary properties of text — from sentence-level compression dynamics to document-scale syntactic evolution.
+
+## Installation
+
+```bash
+pip install spell-exploder
+```
+
+**Required dependencies** (installed automatically): `numpy`, `pandas`, `spacy`, `scipy`, `python-Levenshtein`
+
+**Optional dependencies:**
+
+```bash
+# Sentence embeddings for APE hybrid clustering
+pip install spell-exploder[ml]      # sentence-transformers, scikit-learn
+
+# Visualization (convenience plotting)
+pip install spell-exploder[viz]     # matplotlib, seaborn
+
+# Everything
+pip install spell-exploder[all]
+```
+
+**spaCy model** (required):
+
+```bash
+python -m spacy download en_core_web_sm
+```
+
+## Quick Start
+
+### One-liner API
+
+```python
+import spell_exploder
+
+# Complexity flow analysis (LCX)
+result = spell_exploder.analyze_complexity("essay_a.txt", "essay_b.txt")
+df = result.to_dataframe()
+
+# Valence model (LCVM) — entropy, MI, action frames, multiscale collapse
+result = spell_exploder.analyze_valence("essay_a.txt", "essay_b.txt")
+profile = spell_exploder.ValenceModelAnalyzer().build_complexity_profile(result)
+
+# Adaptive evolution (APE) — syntactic species dynamics
+result = spell_exploder.analyze_evolution("early_draft.txt", "final_draft.txt")
+print(result.to_dataframe())
+
+# Keyword structural coherence (KEPM)
+result = spell_exploder.analyze_keywords(
+    "essay.txt",
+    keywords=["information", "network"],
+)
+```
+
+### Full-control API
+
+```python
+from spell_exploder.analyzers import TextComplexityAnalyzer
+
+analyzer = TextComplexityAnalyzer()
+result = analyzer.compare(
+    ["Human text here.", "AI text here."],
+    labels=["Human", "AI"],
+    from_files=False,
+)
+for flow in result.flows:
+    print(f"{flow.label}: {len(flow.sentences)} sentences")
+    print(f"  Final k_hist: {flow.sentences[-1].k_hist}")
+```
+
+## Analyzers
+
+### TextComplexityAnalyzer (LCX)
+
+Sentence-by-sentence complexity flow via compression (zlib), Levenshtein volatility, and synergy ratios.
+
+```python
+from spell_exploder.analyzers import TextComplexityAnalyzer
+
+lcx = TextComplexityAnalyzer()
+result = lcx.compare(["file_a.txt", "file_b.txt"])
+```
+
+**Key metrics:** cumulative compressed size (`k_hist`), edit distance (`volatility`), volatility/marginal-info ratio (`synergy`)
+
+### ValenceModelAnalyzer (LCVM)
+
+The most comprehensive analyzer — ~30 metrics per document across five dimensions:
+
+| Dimension | Metrics |
+|-----------|---------|
+| **Variation** | Shannon entropy of token distributions |
+| **Redundancy** | Multiscale entropy-collapse curves |
+| **Organisation** | MI(Verb; Subject), MI(Verb; Object), coupling strength |
+| **Repertoire** | Action-frame density, verb diversity |
+| **Semantic breadth** | Schema-keyword concentration, valence entropy |
+
+```python
+from spell_exploder.analyzers import ValenceModelAnalyzer
+
+vm = ValenceModelAnalyzer()
+result = vm.analyze(["essay_a.txt", "essay_b.txt"])
+profile = vm.build_complexity_profile(result)
+print(vm.profile_for_print(profile))
+```
+
+### AdaptiveEvolutionAnalyzer (APE)
+
+Treats syntactic structures as biological species competing for "cognitive market share" across document revisions.
+
+```python
+from spell_exploder.analyzers import AdaptiveEvolutionAnalyzer
+
+ape = AdaptiveEvolutionAnalyzer(use_embeddings=False)  # NCD-only mode
+result = ape.analyze(["draft_v1.txt", "draft_v2.txt"])
+
+for species in result.species[:5]:
+    print(f"  Group {species.cluster_id}: {species.status.value} "
+          f"(Δ={species.delta:+.3f})")
+```
+
+### KeywordERPAnalyzer (KEPM)
+
+Analyses structural coherence of keyword usage through POS co-occurrence spectral entropy and NCD-based structural similarity.
+
+```python
+from spell_exploder.analyzers import KeywordERPAnalyzer
+
+kw = KeywordERPAnalyzer(keywords=["information", "network"])
+result = kw.analyze(["essay.txt"])
+df = result.to_dataframe()
+```
+
+## Export
+
+All results can be exported to CSV or JSON:
+
+```python
+from spell_exploder.io import export_csv, export_json
+
+export_csv(result, "output.csv")
+export_json(result, "output.json")
+```
+
+## Result Objects
+
+Every analyzer returns a structured result with:
+
+- **`.to_dataframe()`** — flat pandas DataFrame for analysis
+- **Direct attribute access** — full nested data (e.g., `result.posts[0].schema_valence_entropy`)
+- **NumPy array properties** — e.g., `flow.k_hist_array`, `flow.volatility_array`
+
+## Architecture
+
+```
+spell_exploder/
+├── analyzers/          # 4 analyzer classes (LCX, LCVM, APE, KEPM)
+├── core/               # Shared math: entropy, compression, MI, JS divergence
+├── extractors/         # NLP extraction: action frames, noun deps, sentences
+├── results/            # Structured dataclass results with .to_dataframe()
+├── io/                 # Text loading and result export (CSV, JSON)
+├── utils/              # Smoothing, statistics, lazy imports
+└── visualization/      # Optional convenience plotting (requires matplotlib)
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- spaCy with `en_core_web_sm` (or another English model)
+
+## License
+
+MIT

spell_exploder-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+spell_exploder/__init__.py,sha256=WOCQu_4AN8CX2iuaDR9FSZ1MbbxMnBBkWE8zeUMnO5o,5715
+spell_exploder/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+spell_exploder/exceptions.py,sha256=KdnM8EGaCgYfyaadxypRgxHT1Lqa8BW8_vlFFFzbc1s,767
+spell_exploder/analyzers/__init__.py,sha256=FfF84oUzvhQKbbBm5wMr_jR_ketWLAwoHRhqPIPH4VE,569
+spell_exploder/analyzers/adaptive_evolution.py,sha256=XuDyioJTXkaXQsmtNNGG_XhzOsvi25e7sBbN2a1Rjzw,15575
+spell_exploder/analyzers/complexity_index.py,sha256=nQhHxDh_hm7dRvCm0CD0-gFP7ozCZIsmH282B270plI,7286
+spell_exploder/analyzers/keyword_erp.py,sha256=4br3nOCSX_m26-G0HsdMtbjegxJxq0Ih-6teJgEF6W8,16292
+spell_exploder/analyzers/valence_model.py,sha256=VU51mbFp5WEmPYozD-gikdfVcEGxyLuJgJlgsyxucyA,19221
+spell_exploder/core/__init__.py,sha256=Y62KSe91xleJuM3_KSjmy9qiYgyQ4cqYDPeWaw0JUHg,1097
+spell_exploder/core/compression.py,sha256=40GLBreGzBmxe09Yt9Jep3ZjZsbHL_qewXWlX12dbeI,2670
+spell_exploder/core/entropy.py,sha256=HjcaowHhBCqX5CgcZ5udDgsnmM0iNfmo-kq71kBzxMU,5726
+spell_exploder/core/information.py,sha256=AWLb9crr7WqOxT99YSbr2kB-DqM3KsH9SmfvJUaqVYA,4734
+spell_exploder/core/nlp.py,sha256=nFhUIAp0KQjtZdWy6BtSrZtxaKv_bd-c9rXdGCxoZ0U,3099
+spell_exploder/extractors/__init__.py,sha256=xk8VAU0ZFaiJTJYYO8JfGHcmFP8ZRwpSPzy9L86Lfqc,895
+spell_exploder/extractors/action_frames.py,sha256=hotGPsH8DkKKS8kbEhsYETXr0datCpbSBDPd6NBEjqg,3583
+spell_exploder/extractors/noun_dependencies.py,sha256=zc4QxTTNYclb_YfmzMbAjWKn_XX55RzW5wVHk8MPR8w,3120
+spell_exploder/extractors/sentence_parser.py,sha256=FJXy9Wnvx8bYYRbYAuJgThs2z4MEvU3j7wNDnXcpgAA,5146
+spell_exploder/graphs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spell_exploder/io/__init__.py,sha256=gTSxDn4x1Fv9n1bHl7dlJodTsyuIwW4Qrb_4NeUofpc,319
+spell_exploder/io/exporters.py,sha256=aq8rFjLrRUOwRO2UwcJxm_J7epRPzkmjZtI2lwbo3qU,2242
+spell_exploder/io/readers.py,sha256=Kf5wdRh1gceTr1MGNZUiMaimoV2ICRknsUKV60CLANU,3072
+spell_exploder/results/__init__.py,sha256=wxbv6xyZnGG_nKWaBM9-BFuideGZpPIPuggM4e9pvX4,1031
+spell_exploder/results/complexity.py,sha256=33-Sxd8XMQomSE7rpbMZCpUoWzkTvBoQbAS4jOrqHck,3344
+spell_exploder/results/evolution.py,sha256=q5XU6mHZ7c85yjfIpwUMfoAy15Xpi4Q_zQkuMzceP2o,4312
+spell_exploder/results/keyword.py,sha256=fBJGPzmT2UyolF42fiSzbLKh6crTLmdyArVHggxZLdo,4334
+spell_exploder/results/valence.py,sha256=UOEzUH0IuqwlMLtvVJ25BbdWEXs1bgwiG0G27uC921Q,5382
+spell_exploder/utils/__init__.py,sha256=BoR6-2S1Y149atqZLXkFr5vl1b93O-xPE14qTvxh_Lk,270
+spell_exploder/utils/imports.py,sha256=3E0K1oHhuPeTVbidgCcMVLX_cFJVRZnTD50MfxYw7H8,1415
+spell_exploder/utils/smoothing.py,sha256=oOvc_jmWNS8M40fiCxBDC8U3MGvBVOwk1VwecGC9QT4,1107
+spell_exploder/utils/statistics.py,sha256=MRbPqmEr3q43B87x8B4fPJD2eoxvqFELd7-vP8YZppU,1574
+spell_exploder/visualization/__init__.py,sha256=r2aZme8AHBzFj_kh6LZnumXCrYMo_ky-QhWZjy-xacU,655
+spell_exploder/visualization/plots.py,sha256=Wprpy6gL0CdmKNGGnnoDvSwA3R3tr7UEnx89zJW9ZsQ,16535
+spell_exploder-0.1.0.dist-info/licenses/LICENSE,sha256=Bl-aIarlo_QhU4Lc2j8uW9IJFI13--oTYdgIhXkTq44,1081
+spell_exploder-0.1.0.dist-info/METADATA,sha256=V68GEZb6Z_SxjCXs07YCZzmDMbK3ThRT6K0eNzNwa-4,7156
+spell_exploder-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+spell_exploder-0.1.0.dist-info/top_level.txt,sha256=f6X_qVJNZ98HxlVtdsxcWmS3xNkEoE9gZyTk0uXOZGk,15
+spell_exploder-0.1.0.dist-info/RECORD,,

spell_exploder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spell_exploder-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spellcaster Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spell_exploder-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spell_exploder