@trac3er/oh-my-god 2.0.0-beta.3 → 2.1.0-alpha

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OMG - Oh-My-God for Claude Code",
-    "version": "2.0.0-beta.3",
+    "version": "2.1.0-alpha",
     "homepage": "https://github.com/trac3er00/OMG",
     "repository": "git@github.com:trac3er00/OMG.git"
   },
@@ -14,7 +14,7 @@
     {
       "name": "omg",
       "description": "OMG standalone orchestration layer for Claude Code",
-      "version": "2.0.0-beta.3",
+      "version": "2.1.0-alpha",
       "source": "./",
       "author": {
         "name": "trac3er00"
@@ -32,5 +32,5 @@
       ]
     }
   ],
-  "version": "2.0.0-beta.3"
+  "version": "2.1.0-alpha"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "omg",
-  "version": "2.0.0-beta.3",
+  "version": "2.1.0-alpha",
   "description": "OMG standalone orchestration layer for Claude Code - multi-agent coordination with Codex/Gemini",
   "author": {
     "name": "trac3er00"

package/README.md

@@ -454,6 +454,49 @@ AST-based dependency graph builder for Python (stdlib `ast`), with regex fallbac
 - Command: `/OMG:arch`
 - Flag: `CODEBASE_VIZ`
 
+## Experimental Features (v2.1.0-alpha)
+
+🟠 **Alpha stability** — all features in this section are experimental. APIs may change between releases.
+
+OMG v2.1.0-alpha ships four tiers of experimental capabilities, each independently gated by a feature flag. All tiers are disabled by default and require no external dependencies (stdlib-only).
+
+**Tier-1: Parallel Agent Dispatch** — Real concurrent dispatch to multiple OMG agents. Supports broadcast, shard, and routed distribution modes with configurable result aggregation. Also includes `UltraworkerRouter` for high-throughput priority-queue batching.
+
+**Tier-2: Persistent Memory** — SQLite-backed episodic, semantic, and procedural memory with FTS5 full-text search. Memories persist across sessions and can be scoped to `session`, `project`, or `user`. Includes a migration utility for existing `.omg/state/memory/*.md` files.
+
+**Tier-3: Pattern Intelligence** — AST-based pattern mining and anti-pattern detection across your codebase. Detects structural patterns, computes deviation scores, and generates refactoring suggestions with effort estimates.
+
+**Tier-4: Advanced Integration** — OpenAPI schema-driven tool generation, SSE streaming for agent output, human-in-the-loop checkpoints, local telemetry collection, A/B experiment tagging, and automatic parameter tuning.
+
+### Enabling experimental features
+
+Via environment variable (per-session):
+
+```bash
+export OMG_PARALLEL_DISPATCH_ENABLED=1   # Tier-1: parallel dispatch
+export OMG_ULTRAWORKER_ENABLED=1         # Tier-1: ultraworker router
+export OMG_EXPERIMENTAL_MEMORY_ENABLED=1 # Tier-2: persistent memory
+export OMG_PATTERN_INTELLIGENCE_ENABLED=1 # Tier-3: pattern intelligence
+export OMG_ADVANCED_INTEGRATION_ENABLED=1 # Tier-4: advanced integration
+```
+
+Via `settings.json` (persistent):
+
+```json
+{
+  "_omg": {
+    "features": {
+      "PARALLEL_DISPATCH": true,
+      "EXPERIMENTAL_MEMORY": true,
+      "PATTERN_INTELLIGENCE": true,
+      "ADVANCED_INTEGRATION": true
+    }
+  }
+}
+```
+
+For full API reference, code examples, migration guide, and troubleshooting, see [docs/experimental-features.md](docs/experimental-features.md).
+
 ## Feature Flags
 
 All features are disabled by default. Enable via environment variables or `settings.json`:

package/claude_experimental/__init__.py

@@ -0,0 +1,27 @@
+"""
+claude_experimental — Experimental features for OMG (Oh My God).
+
+Tier availability:
+  Tier-1: parallel  — Real parallel agent dispatch
+  Tier-2: memory    — SQLite-backed episodic/semantic/procedural memory
+  Tier-3: patterns  — AST-based pattern intelligence
+  Tier-4: integration — OpenAPI tool gen, SSE streaming, telemetry, auto-tuning
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0-alpha"
+__all__ = ["parallel", "memory", "patterns", "integration"]
+
+
+def tier_availability() -> dict:
+    """Return availability status for all 4 tiers."""
+    from claude_experimental.parallel import is_available as p_avail
+    from claude_experimental.memory import is_available as m_avail
+    from claude_experimental.patterns import is_available as pat_avail
+    from claude_experimental.integration import is_available as i_avail
+    return {
+        "parallel": p_avail(),
+        "memory": m_avail(),
+        "patterns": pat_avail(),
+        "integration": i_avail(),
+    }

package/claude_experimental/_compat.py

@@ -0,0 +1,12 @@
+"""Import compatibility layer — ensures claude_experimental is importable from any OMG entry point."""
+from __future__ import annotations
+import os
+import sys
+
+
+def ensure_package_on_path() -> None:
+    """Add the OMG project root to sys.path so claude_experimental is importable."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(here)  # parent of claude_experimental/
+    if project_root not in sys.path:
+        sys.path.insert(0, project_root)

package/claude_experimental/_degradation.py

@@ -0,0 +1,210 @@
+"""Cross-tier graceful degradation framework.
+
+Provides fallback behavior when experimental features are unavailable,
+with three degradation strategies: transparent fallback, annotated fallback,
+and circuit breaker with automatic recovery.
+
+No feature flag gate — this is meta-management infrastructure, always available.
+"""
+from __future__ import annotations
+
+import enum
+import functools
+import sys
+import time
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# ---------------------------------------------------------------------------
+# Degradation tiers
+# ---------------------------------------------------------------------------
+
+
+class DegradationTier(enum.Enum):
+    """Strategy for handling feature failures."""
+
+    TRANSPARENT_FALLBACK = "transparent_fallback"
+    """On exception, return fallback_value silently."""
+
+    ANNOTATED_FALLBACK = "annotated_fallback"
+    """On exception, log to stderr and return fallback_value."""
+
+    CIRCUIT_BREAKER = "circuit_breaker"
+    """After 3 consecutive failures within 60s, auto-disable for 5 minutes."""
+
+
+# ---------------------------------------------------------------------------
+# Circuit breaker constants
+# ---------------------------------------------------------------------------
+
+_CB_FAILURE_THRESHOLD = 3
+_CB_FAILURE_WINDOW = 60.0  # seconds — failures must be within this window
+_CB_OPEN_DURATION = 300.0  # seconds — circuit stays open for 5 minutes
+
+
+# ---------------------------------------------------------------------------
+# GracefulDegradation
+# ---------------------------------------------------------------------------
+
+
+class GracefulDegradation:
+    """Wraps function execution with tier-appropriate fallback behavior.
+
+    Parameters
+    ----------
+    tier : DegradationTier
+        The degradation strategy to use.
+    fallback_value : Any
+        Value returned when the wrapped function fails (or circuit is open).
+    feature_name : str
+        Human-readable name for logging (used in ANNOTATED_FALLBACK stderr).
+    """
+
+    def __init__(
+        self,
+        tier: DegradationTier = DegradationTier.ANNOTATED_FALLBACK,
+        fallback_value: Any = None,
+        feature_name: str = "unknown",
+    ) -> None:
+        self._tier = tier
+        self._fallback_value = fallback_value
+        self._feature_name = feature_name
+
+        # Stats
+        self._failures: int = 0
+        self._successes: int = 0
+
+        # Circuit breaker state
+        self._consecutive_failures: int = 0
+        self._last_failure_time: float = 0.0
+        self._circuit_open_until: float = 0.0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def execute(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        """Execute *fn* with degradation protection.
+
+        Returns the result of *fn* on success, or *fallback_value* on failure
+        (behavior depends on the configured tier).
+        """
+        # Circuit breaker: if circuit is open, return fallback immediately
+        if self._tier is DegradationTier.CIRCUIT_BREAKER:
+            now = time.monotonic()
+            if self._circuit_open_until > 0 and now < self._circuit_open_until:
+                # Circuit is open — skip fn entirely
+                return self._fallback_value
+            # If circuit was open but time has elapsed, auto-close
+            if self._circuit_open_until > 0 and now >= self._circuit_open_until:
+                self._circuit_open_until = 0.0
+                self._consecutive_failures = 0
+
+        try:
+            result = fn(*args, **kwargs)
+        except Exception as exc:
+            return self._handle_failure(exc)
+        else:
+            self._handle_success()
+            return result
+
+    def get_stats(self) -> dict[str, Any]:
+        """Return degradation statistics."""
+        circuit_open = (
+            self._circuit_open_until > 0
+            and time.monotonic() < self._circuit_open_until
+        )
+        return {
+            "failures": self._failures,
+            "successes": self._successes,
+            "circuit_open": circuit_open,
+            "feature_name": self._feature_name,
+        }
+
+    def reset(self) -> None:
+        """Reset circuit breaker state (does not reset stats counters)."""
+        self._consecutive_failures = 0
+        self._last_failure_time = 0.0
+        self._circuit_open_until = 0.0
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _handle_failure(self, exc: Exception) -> Any:
+        """Process a failure according to the configured tier."""
+        self._failures += 1
+
+        if self._tier is DegradationTier.TRANSPARENT_FALLBACK:
+            # Completely silent — no output
+            return self._fallback_value
+
+        if self._tier is DegradationTier.ANNOTATED_FALLBACK:
+            print(
+                f"[OMG DEGRADED] {self._feature_name}: {exc}",
+                file=sys.stderr,
+            )
+            return self._fallback_value
+
+        if self._tier is DegradationTier.CIRCUIT_BREAKER:
+            now = time.monotonic()
+
+            # If last failure was outside the window, reset consecutive count
+            if (
+                self._last_failure_time > 0
+                and (now - self._last_failure_time) > _CB_FAILURE_WINDOW
+            ):
+                self._consecutive_failures = 0
+
+            self._consecutive_failures += 1
+            self._last_failure_time = now
+
+            # Trip the circuit after threshold consecutive failures
+            if self._consecutive_failures >= _CB_FAILURE_THRESHOLD:
+                self._circuit_open_until = now + _CB_OPEN_DURATION
+
+            return self._fallback_value
+
+        # Fallback for unknown tiers (should not happen)
+        return self._fallback_value  # pragma: no cover
+
+    def _handle_success(self) -> None:
+        """Process a success — resets consecutive failure count."""
+        self._successes += 1
+        if self._tier is DegradationTier.CIRCUIT_BREAKER:
+            self._consecutive_failures = 0
+
+
+# ---------------------------------------------------------------------------
+# Decorator
+# ---------------------------------------------------------------------------
+
+
+def graceful_degrade(
+    tier: DegradationTier,
+    fallback_value: Any = None,
+    feature_name: str = "",
+) -> Callable[[F], F]:
+    """Decorator that wraps a function with graceful degradation.
+
+    Usage::
+
+        @graceful_degrade(DegradationTier.ANNOTATED_FALLBACK, fallback_value=[], feature_name="search")
+        def search(query: str) -> list[str]:
+            ...
+    """
+
+    def decorator(fn: F) -> F:
+        name = feature_name or fn.__qualname__
+        dg = GracefulDegradation(tier=tier, fallback_value=fallback_value, feature_name=name)
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return dg.execute(fn, *args, **kwargs)
+
+        # Expose the GracefulDegradation instance for inspection/reset
+        wrapper._degradation = dg  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

package/claude_experimental/_flags.py

@@ -0,0 +1,35 @@
+"""Feature flag integration for claude_experimental — lazy import from hooks/_common.py."""
+from __future__ import annotations
+import importlib
+import os
+import sys
+
+
+KNOWN_FLAGS: dict[str, str] = {
+    "PARALLEL_DISPATCH": "OMG_PARALLEL_DISPATCH_ENABLED",
+    "ULTRAWORKER": "OMG_ULTRAWORKER_ENABLED",
+    "ADVANCED_MEMORY": "OMG_ADVANCED_MEMORY_ENABLED",
+    "PATTERN_INTELLIGENCE": "OMG_PATTERN_INTELLIGENCE_ENABLED",
+    "ADVANCED_INTEGRATION": "OMG_ADVANCED_INTEGRATION_ENABLED",
+}
+
+
+def _hooks_dir() -> str:
+    """Return absolute path to hooks/ dir relative to this file."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.join(here, "..", "hooks")
+
+
+def get_feature_flag(flag_name: str, default: bool = False) -> bool:
+    """Lazy-import get_feature_flag from hooks/_common.py and call it."""
+    hooks_dir = _hooks_dir()
+    if hooks_dir not in sys.path:
+        sys.path.insert(0, hooks_dir)
+    try:
+        common_module = importlib.import_module("_common")
+        getter = getattr(common_module, "get_feature_flag", None)
+        if callable(getter):
+            return bool(getter(flag_name, default))
+        return default
+    except (ImportError, Exception):
+        return default

package/claude_experimental/_lifecycle.py

@@ -0,0 +1,122 @@
+"""Feature flag lifecycle management — tracks feature flag stages (ALPHA → BETA → STABLE → DEPRECATED)."""
+from __future__ import annotations
+
+import sys
+from enum import Enum
+
+
+class LifecycleStage(str, Enum):
+    """Feature flag lifecycle stages."""
+
+    ALPHA = "alpha"
+    BETA = "beta"
+    STABLE = "stable"
+    DEPRECATED = "deprecated"
+
+
+class FeatureFlagLifecycle:
+    """Tracks feature flag lifecycle stages and provides warnings for alpha/deprecated features."""
+
+    def __init__(self) -> None:
+        """Initialize a new lifecycle registry."""
+        self._registry: dict[str, dict[str, str]] = {}
+
+    def register(
+        self,
+        flag_name: str,
+        status: str = "alpha",
+        since_version: str = "2.0.0-beta.3",
+        description: str = "",
+    ) -> None:
+        """Register a feature flag with its lifecycle status.
+
+        Args:
+            flag_name: Name of the feature flag (e.g., 'PARALLEL_DISPATCH')
+            status: Lifecycle stage ('alpha', 'beta', 'stable', 'deprecated')
+            since_version: Version when this status was set
+            description: Human-readable description of the feature
+        """
+        self._registry[flag_name] = {
+            "status": status,
+            "since_version": since_version,
+            "description": description,
+        }
+
+    def check_health(self) -> dict[str, dict[str, str]]:
+        """Return health status of all registered features.
+
+        Returns:
+            Dict mapping flag_name to {status, since_version, description}
+        """
+        return {
+            flag_name: {
+                "status": info["status"],
+                "since_version": info["since_version"],
+                "description": info["description"],
+            }
+            for flag_name, info in self._registry.items()
+        }
+
+    def use_feature(self, flag_name: str) -> None:
+        """Log usage of a feature flag, warning if alpha or deprecated.
+
+        Args:
+            flag_name: Name of the feature flag being used
+        """
+        if flag_name not in self._registry:
+            return
+
+        status = self._registry[flag_name]["status"]
+
+        if status == LifecycleStage.ALPHA.value:
+            _ = sys.stderr.write(
+                f"[OMG ALPHA] Feature '{flag_name}' is alpha. Behavior may change.\n"
+            )
+        elif status == LifecycleStage.DEPRECATED.value:
+            _ = sys.stderr.write(
+                f"[OMG DEPRECATED] Feature '{flag_name}' is deprecated. Please migrate.\n"
+            )
+
+    def get_registry(self) -> dict[str, dict[str, str]]:
+        """Return the complete registry of all registered features.
+
+        Returns:
+            Dict mapping flag_name to {status, since_version, description}
+        """
+        return dict(self._registry)
+
+
+# Module-level default lifecycle instance with pre-registered experimental flags
+_DEFAULT_LIFECYCLE = FeatureFlagLifecycle()
+
+# Pre-register all 5 experimental flags as ALPHA
+_DEFAULT_LIFECYCLE.register(
+    "PARALLEL_DISPATCH",
+    status="alpha",
+    since_version="2.0.0-beta.3",
+    description="Parallel task dispatch across multiple workers",
+)
+_DEFAULT_LIFECYCLE.register(
+    "EXPERIMENTAL_MEMORY",
+    status="alpha",
+    since_version="2.0.0-beta.3",
+    description="Experimental memory system with semantic/episodic/procedural tiers",
+)
+_DEFAULT_LIFECYCLE.register(
+    "PATTERN_INTELLIGENCE",
+    status="alpha",
+    since_version="2.0.0-beta.3",
+    description="Pattern detection and mining with anti-pattern analysis",
+)
+_DEFAULT_LIFECYCLE.register(
+    "ADVANCED_INTEGRATION",
+    status="alpha",
+    since_version="2.0.0-beta.3",
+    description="Advanced integration features (checkpoints, telemetry, experiments)",
+)
+_DEFAULT_LIFECYCLE.register(
+    "ULTRAWORKER",
+    status="alpha",
+    since_version="2.0.0-beta.3",
+    description="Ultra-high-performance worker pool with dynamic scaling",
+)

package/claude_experimental/integration/__init__.py

@@ -0,0 +1,16 @@
+"""claude_experimental.integration — Tier-4: OpenAPI tool gen, SSE streaming, telemetry, auto-tuning."""
+from __future__ import annotations
+
+
+def is_available() -> bool:
+    from claude_experimental._flags import get_feature_flag
+    return get_feature_flag("ADVANCED_INTEGRATION", default=False)
+
+
+def _require_enabled() -> None:
+    if not is_available():
+        raise RuntimeError(
+            "Tier-4 advanced integration is disabled. "
+            "Enable with: OMG_ADVANCED_INTEGRATION_ENABLED=1 or "
+            "settings.json _omg.features.ADVANCED_INTEGRATION: true"
+        )

package/claude_experimental/integration/_placeholder.py

@@ -0,0 +1,7 @@
+"""Placeholder — implementation pending for this tier."""
+
+def _not_implemented(*args, **kwargs):
+    raise NotImplementedError(
+        "This tier's implementation is pending. "
+        "Check the claude_experimental package for available features."
+    )