Metadata-Version: 2.4
Name: polyglot-stream-heal
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Summary: Sub-millisecond incremental O(n) Hierarchical Multi-Grammar Pushdown Transducer for streaming polyglot LLM output healing
Keywords: llm,streaming,json-repair,mermaid,pushdown-transducer
Author-email: David Charles Michael <davidchar@gmail.com>
Maintainer-email: David Charles Michael <davidchar@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Author ORCID, https://orcid.org/0009-0007-8679-6941
Project-URL: Companion Paper, https://github.com/davidhcar/polyglot-stream-heal/blob/main/paper/paper.pdf
Project-URL: Documentation, https://docs.rs/polyglot-stream-heal
Project-URL: Homepage, https://github.com/davidhcar/polyglot-stream-heal
Project-URL: Repository, https://github.com/davidhcar/polyglot-stream-heal

# `polyglot-stream-heal` (Python Native `PyO3` Binding — `PyPI`)

**Sub-millisecond incremental $O(n)$ Hierarchical Multi-Grammar Pushdown Transducer (HM-PDT) for streaming polyglot LLM output healing and cardinality-bounded layout partitioning.**

- **Author:** David Charles Michael (`davidchar@gmail.com`)
- **License:** MIT
- **Native Rust Performance in Python:** Compiled via `PyO3` + `maturin` (`abi3-py39+`), delivering **$34.7\times$ lower median chunk latency** ($6.4\,\mu\text{s}$ vs. $222.2\,\mu\text{s}$) and **$267.6\times$ lower cumulative stream overhead** at $32\text{ KB}$ than pure-Python `json-repair`, while additionally healing 14 Mermaid diagram dialects, HTML5 sandboxes, and wide Markdown tables.

---

## 1. Installation

```bash
pip install polyglot-stream-heal
```

Or install the pre-built wheel directly from `dist/pypi/`:
```bash
pip install dist/pypi/polyglot_stream_heal-0.1.0-cp39-abi3-manylinux_2_34_x86_64.whl
```

---

## 2. How to Implement & Verified Output

### Runnable Code Snippet (`python3 examples/demo_python.py`)

```python
import json
import polyglot_stream_heal as psh

print("=== 1. Stateful Streaming Transducer (Python PyO3) ===")
transducer = psh.IncrementalTransducer(max_table_cols=5, max_chart_bars=10)
stream_chunks = [
    "### Telemetry Stream\n```json\n",
    '{"service": "router", "active": tru, "p99_ms": 12.',
]
for chunk in stream_chunks:
    transducer.push_chunk(chunk)

active_seg = json.loads(transducer.snapshot_active_json())
print("Active Segment Modality:", active_seg["modality"])
print("Healed JSON Content    :", active_seg["content"])

print("\n=== 2. Context-Free Mermaid Dyck Node Healing ===")
raw_mermaid = "flowchart TD\n  subgraph Shard_A (Primary: US-East)\n    N1[Compute O(f(g(x)))] -- rpc --> N2[(Ledger (v2))]"
print(psh.heal_mermaid(raw_mermaid))
```

### Exact Verified Output (`examples/VERIFIED_OUTPUT.txt`)

```text
=== 1. Stateful Streaming Transducer (Python PyO3) ===
Active Segment Modality: json
Healed JSON Content    : {"active":true,"p99_ms":12.0,"service":"router"}

=== 2. Context-Free Mermaid Dyck Node Healing ===
flowchart TD
  subgraph sg_Shard_A__Primary__US ["Shard_A (Primary: US-East)"]
  N1["Compute O(f(g(x)))"] -->|rpc| N2[("Ledger (v2)")]
  end
```

---

## 3. Publishing to `PyPI`

### Pre-Built Artifact Location
- `dist/pypi/polyglot_stream_heal-0.1.0-cp39-abi3-manylinux_2_34_x86_64.whl`

### Option A: Automated 1-Command Publish via WSL2 Docker
1. Create a PyPI API token at `https://pypi.org/manage/account/token/` (begins with `pypi-...`).
2. Run from the repository root:
   ```bash
   PYPI_API_TOKEN=pypi-your_token_here ./publish_packages.sh --pypi
   ```

### Option B: Direct CLI Publish (`twine` or `maturin`)
```bash
python3 -m twine upload dist/pypi/polyglot_stream_heal-0.1.0-*.whl -u __token__ -p <YOUR_PYPI_API_TOKEN>
```

