omniokg v2.1.1 - Fix streaming output for interactive docs + comprehensive documentation

[1minds3t]

Critical Fix

• BREAKING: Fixed execute endpoint to stream output in real-time via SSE
  • Changed from buffered subprocess.run() to streaming subprocess.Popen()
  • Implements Server-Sent Events (SSE) for line-by-line output delivery
  • Prevents timeout/hanging issues in interactive documentation console
  • Essential for demo functionality in web-based docs

Bridge API Improvements

• Added streaming generator pattern to execute_omnipkg_command()
• Enhanced CORS origins for local development (localhost:5000, 127.0.0.1:8085)
• Improved error handling with streaming error messages
• Added health check telemetry logging
• Cloudflare Worker telemetry forwarding (fire-and-forget)
• DEV_MODE now allows missing Origin header for curl/testing

Documentation Overhaul (Interactive)

• New Structure: Organized into sections with .pages.yml navigation
  • CLI Commands: overview, details, run command deep-dive
  • Platform Support: CI verification matrix, 70+ builds documented
  • Demos: 4 interactive examples (C extensions, Rich, TensorFlow, uv)
• Enhanced MkDocs Config:
  • Fixed site_url for Cloudflare Pages deployment
  • Added navigation.instant, .tracking, .sections, .expand features
  • Enabled mkdocs-awesome-pages-plugin for auto-navigation
  • Added mkdocs-macros, minify, redirects plugins
  • YAML front matter support via meta extension
• All docs now include:
  • Generated metadata headers (title, doc_type, status, created date)
  • Interactive command execution via embedded terminal
  • Real-time streaming output (powered by fixed SSE endpoint)

Package Metadata Updates

• Version bump: 2.1.0 → 2.1.1
• Updated conda recipes with new PyPI SHA256
• Fixed aiohttp version constraint (>=3.13.3) for Conda-Forge
• Added flask + flask-cors to dependencies for Conda-Forge
• Updated doc URLs to omnipkg.pages.dev
• Added interactive console URL to package description

Files Changed

• src/omnipkg/apis/local_bridge.py: SSE streaming implementation
• docs/: +15 new markdown files with interactive content
• mkdocs.yml: Complete restructure with modern nav features
• pyproject.toml: Version bump + metadata refresh
• requirements-docs.txt: Added missing MkDocs plugins

Testing

• Interactive docs console tested with streaming output
• CORS validated for localhost + Cloudflare origins
• Health check telemetry confirmed working
• All 24 conda-forge builds passing (verified via CI links in docs)

Fixes #N/A (emergency release for docs functionality)

---

# GitHub Release Notes

## 🚨 v2.1.1 - Critical Streaming Fix + Interactive Documentation

**Release Date**: January 7, 2026

### 🔥 Breaking Change - Streaming Output API

The `/execute` endpoint now **streams output in real-time** using Server-Sent Events (SSE) instead of buffering the entire response. This is **essential** for the interactive documentation console to work properly.

**Before (v2.1.0):**
```python
# Buffered - waits for completion
result = subprocess.run(cmd, capture_output=True, timeout=180)
return jsonify({"output": result.stdout})

After (v2.1.1):

# Streaming - yields line-by-line
def generate():
    for line in execute_omnipkg_command(cmd):
        yield f"data: {json.dumps({'line': line})}\n\n"
    yield "data: {\"done\": true}\n\n"

Why This Matters

Without streaming, the interactive docs console would:

• ❌ Hang waiting for commands to complete (3 minute timeout)
• ❌ Show nothing until the entire command finished
• ❌ Make demos unusable for long-running commands
• ❌ Provide poor UX for users testing omnipkg via browser

📚 New Interactive Documentation

Visit omnipkg.pages.dev to explore:

Live Command Execution 🎮

Run real omnipkg commands directly in your browser:

omnipkg install requests@2.31.0 --isolated
omnipkg list-pkgs
omnipkg run requests -- python -c "import requests; print(requests.__version__)"

Output streams live as it happens on your local machine!

New Documentation Sections

• 📖 CLI Commands - Complete command reference with examples
• 🎯 Platform Support - 70+ CI builds across all platforms
• 🎬 Interactive Demos - 4 live demonstrations:
  • C Extension Version Switching
  • Rich Module Styling
  • TensorFlow Dependency Management
  • UV Binary Hot-Swapping

🛠️ Bridge API Enhancements

CORS Origins Expanded:

ALLOWED_ORIGINS = {
    "https://1minds3t.echo-universe.ts.net",  # Tailscale Funnel
    "https://omnipkg.pages.dev",              # Cloudflare Pages
    "https://omnipkg.workers.dev",            # CF Worker
    "http://localhost:5000",                  # MkDocs local dev
    "http://127.0.0.1:8085",                  # Bridge local
}

New Features:

• ✅ Health check telemetry logging
• ✅ Cloudflare Worker analytics forwarding
• ✅ DEV_MODE allows missing Origin for testing
• ✅ Improved error messages with streaming context

📦 Installation

# PyPI (recommended)
pip install omnipkg==2.1.1

# conda-forge (24 platform variants)
conda install -c conda-forge omnipkg=2.1.1

# Development
pip install git+https://github.com/1minds3t/omnipkg@v2.1.1

🔍 What's Included

Python Support: 3.10, 3.11, 3.12, 3.13
Platforms: Linux (x86_64, aarch64, ppc64le, s390x), macOS (Intel, Apple Silicon), Windows (x86_64)
Total CI Builds: 70+ (24 conda-forge + 22 GitHub Actions + 12 piwheels + ARM64 QEMU)

📊 Verification

All builds passing:

• ✅ conda-forge Azure Pipelines
• ✅ GitHub Actions - Cross-Platform
• ✅ piwheels ARM32

🚀 Try It Now

Interactive Console (no installation required):
👉 https://1minds3t.echo-universe.ts.net/omnipkg/

Documentation (with embedded console):
👉 https://omnipkg.pages.dev/

---

📝 Full Changelog

Compare: v2.1.0...v2.1.1

Files Changed: 30 files (+1,975 additions, -160 deletions)

---

⚠️ Upgrade Notes

If you're running the local bridge (omnipkg bridge), you must upgrade to v2.1.1 for the interactive docs to work correctly. The streaming API change is not backwards compatible with v2.1.0 clients.

pip install --upgrade omnipkg
omnipkg bridge  # Restart with new streaming endpoint

---

Questions? Open an issue or visit the interactive docs 🚀

---

This discussion was created from the release omniokg v2.1.1 - Fix streaming output for interactive docs + comprehensive documentation.