spell-exploder 0.1.0__tar.gz

spell_exploder-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,178 @@
+# 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/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spell-exploder"
+version = "0.1.0"
+description = "Analyze natural language through complex systems science, information theory, and evolutionary game theory."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Spellcaster Contributors"},
+]
+keywords = [
+    "nlp",
+    "information-theory",
+    "complex-systems",
+    "text-analysis",
+    "evolutionary-game-theory",
+    "linguistics",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "spacy>=3.4",
+    "scipy>=1.9",
+    "python-Levenshtein>=0.20",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.5", "seaborn>=0.12"]
+graphs = ["networkx>=3.0"]
+ml = ["sentence-transformers>=2.0", "scikit-learn>=1.0"]
+all = ["spell-exploder[viz,graphs,ml]"]
+dev = ["pytest>=7.0", "spell-exploder[all]"]
+
+[project.urls]
+Homepage = "https://github.com/inc-research/spell-exploder"
+Documentation = "https://github.com/inc-research/spell-exploder#readme"
+Repository = "https://github.com/inc-research/spell-exploder"
+
+[tool.setuptools.packages.find]
+include = ["spell_exploder*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

spell_exploder-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spell_exploder-0.1.0/spell_exploder/__init__.py

@@ -0,0 +1,205 @@
+"""
+Spell Exploder
+===========
+
+Analyze natural language text through complex systems science,
+information theory, information-theoretic physics analogues,
+and evolutionary game theory.
+
+Quick Start
+-----------
+>>> import spell_exploder
+>>> result = spell_exploder.analyze_complexity("draft_a.txt", "draft_b.txt")
+>>> result.to_dataframe()
+
+Analyzers
+---------
+For full control, import the analyzer classes directly::
+
+    from spell_exploder.analyzers import (
+        TextComplexityAnalyzer,   # LCX  — compression, volatility, synergy
+        ValenceModelAnalyzer,     # LCVM — entropy, MI, action frames, collapse
+        AdaptiveEvolutionAnalyzer,# APE  — POS clustering, evolutionary dynamics
+        KeywordERPAnalyzer,       # KEPM — keyword structural coherence
+    )
+
+Results
+-------
+All analyzers return structured dataclass results with ``.to_dataframe()``
+methods for easy integration with pandas, matplotlib, or any other tooling.
+
+Export
+------
+>>> from spell_exploder.io import export_csv, export_json
+>>> export_csv(result, "output.csv")
+>>> export_json(result, "output.json")
+"""
+
+from spell_exploder._version import __version__
+
+from spell_exploder.analyzers.complexity_index import TextComplexityAnalyzer
+from spell_exploder.analyzers.valence_model import ValenceModelAnalyzer
+from spell_exploder.analyzers.adaptive_evolution import AdaptiveEvolutionAnalyzer
+from spell_exploder.analyzers.keyword_erp import KeywordERPAnalyzer
+
+from spell_exploder.io.readers import load_texts, texts_from_strings
+from spell_exploder.io.exporters import export_csv, export_json
+
+from spell_exploder.results.complexity import (
+    ComplexityComparisonResult,
+    ComplexityFlowResult,
+)
+from spell_exploder.results.valence import ValenceModelResult
+from spell_exploder.results.evolution import EvolutionResult
+from spell_exploder.results.keyword import KeywordERPResult
+
+
+# ── Convenience functions ────────────────────────────────────────────────────
+
+def analyze_complexity(
+    *texts_or_paths: str,
+    labels: list[str] | None = None,
+    from_files: bool = True,
+) -> ComplexityComparisonResult:
+    """
+    One-liner complexity analysis.
+
+    Parameters
+    ----------
+    *texts_or_paths : str
+        File paths (when *from_files* is True) or raw text strings.
+    labels : list[str] or None
+        Human-readable labels.
+    from_files : bool
+        Whether to read from files or treat as raw strings.
+
+    Returns
+    -------
+    ComplexityComparisonResult
+    """
+    return TextComplexityAnalyzer().compare(
+        list(texts_or_paths), labels=labels, from_files=from_files,
+    )
+
+
+def analyze_valence(
+    *texts_or_paths: str,
+    labels: list[str] | None = None,
+    from_files: bool = True,
+    window_sizes: tuple[int, ...] = (25, 50, 100, 250, 500),
+) -> ValenceModelResult:
+    """
+    One-liner valence model analysis.
+
+    Parameters
+    ----------
+    *texts_or_paths : str
+        File paths or raw text strings.
+    labels : list[str] or None
+        Human-readable labels.
+    from_files : bool
+        Whether to read from files.
+    window_sizes : tuple[int, ...]
+        Window sizes for multiscale collapse.
+
+    Returns
+    -------
+    ValenceModelResult
+    """
+    return ValenceModelAnalyzer(window_sizes=window_sizes).analyze(
+        list(texts_or_paths), labels=labels, from_files=from_files,
+    )
+
+
+def analyze_evolution(
+    *texts_or_paths: str,
+    labels: list[str] | None = None,
+    from_files: bool = True,
+    use_embeddings: bool = True,
+    alpha_semantic: float = 0.5,
+) -> EvolutionResult:
+    """
+    One-liner adaptive evolution analysis.
+
+    Documents should be in chronological order (earliest first).
+
+    Parameters
+    ----------
+    *texts_or_paths : str
+        File paths or raw text strings.
+    labels : list[str] or None
+        Human-readable labels.
+    from_files : bool
+        Whether to read from files.
+    use_embeddings : bool
+        Whether to use sentence-transformer embeddings.
+    alpha_semantic : float
+        Blend weight for semantic vs. structural distance.
+
+    Returns
+    -------
+    EvolutionResult
+    """
+    return AdaptiveEvolutionAnalyzer(
+        use_embeddings=use_embeddings,
+        alpha_semantic=alpha_semantic,
+    ).analyze(
+        list(texts_or_paths), labels=labels, from_files=from_files,
+    )
+
+
+def analyze_keywords(
+    *texts_or_paths: str,
+    keywords: list[str],
+    labels: list[str] | None = None,
+    from_files: bool = True,
+    context_window: int = 25,
+) -> KeywordERPResult:
+    """
+    One-liner keyword ERP analysis.
+
+    Parameters
+    ----------
+    *texts_or_paths : str
+        File paths or raw text strings.
+    keywords : list[str]
+        Keywords to analyse.
+    labels : list[str] or None
+        Human-readable labels.
+    from_files : bool
+        Whether to read from files.
+    context_window : int
+        ±N sentences around each keyword mention.
+
+    Returns
+    -------
+    KeywordERPResult
+    """
+    return KeywordERPAnalyzer(
+        keywords=keywords,
+        context_window=context_window,
+    ).analyze(
+        list(texts_or_paths), labels=labels, from_files=from_files,
+    )
+
+
+__all__ = [
+    "__version__",
+    "analyze_complexity",
+    "analyze_valence",
+    "analyze_evolution",
+    "analyze_keywords",
+    "TextComplexityAnalyzer",
+    "ValenceModelAnalyzer",
+    "AdaptiveEvolutionAnalyzer",
+    "KeywordERPAnalyzer",
+    "load_texts",
+    "texts_from_strings",
+    "export_csv",
+    "export_json",
+    "ComplexityComparisonResult",
+    "ComplexityFlowResult",
+    "ValenceModelResult",
+    "EvolutionResult",
+    "KeywordERPResult",
+]

spell_exploder-0.1.0/spell_exploder/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"