pgframx 0.1.0__py3-none-any.whl

pgframx/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.1.0"
+
+from pgframx.orchestrator import Orchestrator
+from pgframx.event import Event
+from pgframx.app import create_app
+
+__all__ = ["Orchestrator", "Event", "create_app"]

pgframx/app.py

@@ -0,0 +1,27 @@
+from flask import Flask
+from typing import Optional
+
+from pgframx.orchestrator import Orchestrator
+from pgframx.config import Config
+from pgframx.utils import setup_logging
+from pgframx.blueprints import events_bp, listeners_bp, health_bp
+
+def create_app(orchestrator: Orchestrator, config_class=Config) -> Flask:
+    """Flask application factory. Sets up logging, blueprints, and configures the Orchestrator."""
+    app = Flask("pgframx")
+    
+    # Load configuration
+    app.config.from_mapping(config_class.to_dict())
+    
+    # Setup logging based on configured level
+    setup_logging(app.config.get("PGFRAMX_LOG_LEVEL", "INFO"))
+    
+    # Store Orchestrator reference in app configuration for blueprints to access
+    app.config["ORCHESTRATOR"] = orchestrator
+    
+    # Register blueprints with appropriate prefixes
+    app.register_blueprint(events_bp, url_prefix="/events")
+    app.register_blueprint(listeners_bp, url_prefix="/listeners")
+    app.register_blueprint(health_bp, url_prefix="/health")
+    
+    return app

pgframx/blueprints/__init__.py

@@ -0,0 +1,5 @@
+from pgframx.blueprints.events import events_bp
+from pgframx.blueprints.listeners import listeners_bp
+from pgframx.blueprints.health import health_bp
+
+__all__ = ["events_bp", "listeners_bp", "health_bp"]

pgframx/blueprints/events.py

@@ -0,0 +1,63 @@
+from flask import Blueprint, jsonify, request, current_app
+
+events_bp = Blueprint("events", __name__)
+
+def get_orchestrator():
+    return current_app.config["ORCHESTRATOR"]
+
+@events_bp.route("", methods=["GET"])
+def list_events():
+    orc = get_orchestrator()
+    # Return list of distinct patterns registered in the listeners registry
+    patterns = list(set(listener.pattern for listener in orc.listeners.list_all()))
+    return jsonify({"events": patterns})
+
+@events_bp.route("/emit", methods=["POST"])
+def emit_event():
+    orc = get_orchestrator()
+    payload = request.get_json() or {}
+    
+    name = payload.get("name")
+    if not name:
+        return jsonify({"error": "Event 'name' is required"}), 400
+        
+    data = payload.get("data", {})
+    meta = payload.get("meta", {})
+    async_dispatch = bool(payload.get("async", False))
+    
+    event = orc.emit(name, data=data, meta=meta, async_dispatch=async_dispatch)
+    
+    return jsonify({
+        "name": event.name,
+        "data": event.data,
+        "meta": event.meta,
+        "status": event.status
+    }), 201
+
+@events_bp.route("/<path:name>/listeners", methods=["GET"])
+def get_event_listeners(name):
+    orc = get_orchestrator()
+    listeners = orc.listeners.get_listeners_for_event(name)
+    return jsonify({
+        "event": name,
+        "listeners": [l.to_dict() for l in listeners]
+    })
+
+@events_bp.route("/log", methods=["GET"])
+def get_event_log():
+    orc = get_orchestrator()
+    log_data = []
+    for event in orc.event_log:
+        log_data.append({
+            "name": event.name,
+            "data": event.data,
+            "meta": event.meta,
+            "status": event.status
+        })
+    return jsonify({"log": log_data})
+
+@events_bp.route("/log", methods=["DELETE"])
+def clear_event_log():
+    orc = get_orchestrator()
+    orc.event_log.clear()
+    return jsonify({"message": "Event log cleared successfully"})

pgframx/blueprints/health.py

@@ -0,0 +1,75 @@
+import time
+from flask import Blueprint, jsonify, current_app
+
+health_bp = Blueprint("health", __name__)
+
+def get_orchestrator():
+    return current_app.config["ORCHESTRATOR"]
+
+@health_bp.route("", methods=["GET"])
+def health_check():
+    orc = get_orchestrator()
+    uptime = time.time() - orc.start_time
+    
+    return jsonify({
+        "status": "healthy",
+        "uptime_seconds": round(uptime, 2),
+        "listeners_count": len(orc.listeners.list_all()),
+        "event_log_size": len(orc.event_log),
+        "scheduler_enabled": orc.scheduler_enabled,
+        "scheduler_running": orc.scheduler.scheduler.running if orc.scheduler else False
+    })
+
+@health_bp.route("/scheduler", methods=["GET"])
+def scheduler_status():
+    orc = get_orchestrator()
+    if not orc.scheduler:
+        return jsonify({
+            "scheduler_enabled": False,
+            "message": "Scheduler is disabled"
+        })
+        
+    jobs = orc.scheduler.list_jobs()
+    return jsonify({
+        "scheduler_enabled": True,
+        "scheduler_running": orc.scheduler.scheduler.running,
+        "jobs": jobs
+    })
+
+@health_bp.route("/scheduler/jobs/<string:job_id>", methods=["DELETE"])
+def delete_scheduled_job(job_id):
+    orc = get_orchestrator()
+    if not orc.scheduler:
+        return jsonify({"error": "Scheduler is disabled"}), 400
+        
+    success = orc.unschedule(job_id)
+    if success:
+        return jsonify({"message": f"Scheduled job {job_id} removed successfully"})
+    else:
+        return jsonify({"error": f"Scheduled job {job_id} not found"}), 404
+
+@health_bp.route("/scheduler/jobs", methods=["POST"])
+def add_scheduled_job():
+    orc = get_orchestrator()
+    if not orc.scheduler:
+        return jsonify({"error": "Scheduler is disabled"}), 400
+        
+    from flask import request
+    payload = request.get_json() or {}
+    event_name = payload.get("name")
+    if not event_name:
+        return jsonify({"error": "Field 'name' (event name) is required"}), 400
+        
+    cron = payload.get("cron")
+    interval = payload.get("interval")
+    data = payload.get("data", {})
+    
+    try:
+        job_id = orc.schedule(event_name, cron=cron, interval=interval, data=data)
+        return jsonify({
+            "message": "Job scheduled successfully",
+            "job_id": job_id,
+            "name": event_name
+        }), 201
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400

pgframx/blueprints/listeners.py

@@ -0,0 +1,43 @@
+from flask import Blueprint, jsonify, request, current_app
+
+listeners_bp = Blueprint("listeners", __name__)
+
+def get_orchestrator():
+    return current_app.config["ORCHESTRATOR"]
+
+@listeners_bp.route("", methods=["GET"])
+def list_listeners():
+    orc = get_orchestrator()
+    listeners = orc.listeners.list_all()
+    return jsonify({"listeners": [l.to_dict() for l in listeners]})
+
+@listeners_bp.route("/register", methods=["POST"])
+def register_listener():
+    orc = get_orchestrator()
+    payload = request.get_json() or {}
+    
+    pattern = payload.get("pattern")
+    webhook_url = payload.get("webhook_url")
+    
+    if not pattern:
+        return jsonify({"error": "Field 'pattern' is required"}), 400
+    if not webhook_url:
+        return jsonify({"error": "Field 'webhook_url' is required for dynamic listeners"}), 400
+        
+    listener_id = orc.listeners.register(pattern=pattern, webhook_url=webhook_url)
+    
+    return jsonify({
+        "message": "Listener registered dynamically",
+        "id": listener_id,
+        "pattern": pattern,
+        "webhook_url": webhook_url
+    }), 201
+
+@listeners_bp.route("/<string:listener_id>", methods=["DELETE"])
+def deregister_listener(listener_id):
+    orc = get_orchestrator()
+    success = orc.listeners.deregister(listener_id)
+    if success:
+        return jsonify({"message": f"Listener {listener_id} removed successfully"})
+    else:
+        return jsonify({"error": f"Listener {listener_id} not found"}), 404

pgframx/cli.py

@@ -0,0 +1,297 @@
+import click
+import requests
+import json
+import os
+import sys
+import importlib.util
+from typing import Any, Dict
+
+from pgframx.config import Config
+
+def get_base_url() -> str:
+    host = Config.PGFRAMX_HOST
+    # Map 0.0.0.0 to localhost for client requests
+    if host == "0.0.0.0":
+        host = "127.0.0.1"
+    return f"http://{host}:{Config.PGFRAMX_PORT}"
+
+@click.group()
+def main():
+    """pgframx CLI — Manage and orchestrate events."""
+    pass
+
+@main.command()
+@click.option("--dir", "target_dir", default=".", help="Directory to scaffold pgframx project.")
+def init(target_dir):
+    """Scaffold a new pgframx project in cwd."""
+    click.echo(f"Scaffolding new pgframx project in '{target_dir}'...")
+    
+    os.makedirs(target_dir, exist_ok=True)
+    
+    # 1. Create main.py
+    main_py_path = os.path.join(target_dir, "main.py")
+    if os.path.exists(main_py_path):
+        click.confirm("main.py already exists. Overwrite?", abort=True)
+        
+    main_py_content = """from pgframx import Orchestrator, create_app
+
+# Instantiate the core event orchestrator
+orc = Orchestrator()
+
+# Register a basic listener
+@orc.on("user.login")
+def handle_login(event):
+    print(f"[Listener] User logged in: {event.data}")
+
+# Register before hook
+@orc.before("user.*")
+def before_user_events(event):
+    print(f"[Before Hook] intercepting: {event.name}")
+
+# Create the Flask application
+app = create_app(orc)
+
+if __name__ == "__main__":
+    # If run directly, run Flask dev server
+    app.run(host="0.0.0.0", port=5050, debug=True)
+"""
+    with open(main_py_path, "w") as f:
+        f.write(main_py_content)
+    click.echo("  Created main.py")
+
+    # 2. Create .pgframx.env
+    env_path = os.path.join(target_dir, ".pgframx.env")
+    if not os.path.exists(env_path):
+        env_content = """PGFRAMX_HOST=0.0.0.0
+PGFRAMX_PORT=5050
+PGFRAMX_DEBUG=True
+PGFRAMX_LOG_LEVEL=INFO
+PGFRAMX_SCHEDULER_ENABLED=True
+PGFRAMX_EVENT_LOG_MAX=1000
+"""
+        with open(env_path, "w") as f:
+            f.write(env_content)
+        click.echo("  Created .pgframx.env")
+        
+    # 3. Create README.md if it doesn't exist
+    readme_path = os.path.join(target_dir, "README.md")
+    if not os.path.exists(readme_path):
+        readme_content = """# pgframx Project
+
+This is a pgframx event management orchestrator project scaffold.
+
+## Running the Server
+
+```bash
+pgframx run
+```
+
+## Emitting Events
+
+```bash
+pgframx emit user.login --data '{"email": "user@example.com"}'
+```
+"""
+        with open(readme_path, "w") as f:
+            f.write(readme_content)
+        click.echo("  Created README.md")
+        
+    click.echo("Scaffolding complete! Run 'pgframx run' to start.")
+
+@main.command()
+def run():
+    """Start the Flask orchestrator server."""
+    sys.path.insert(0, os.getcwd())
+    
+    # Try to load local main.py or app.py
+    app = None
+    orchestrator = None
+    
+    for filename in ["main.py", "app.py"]:
+        if os.path.exists(filename):
+            click.echo(f"Loading local application configuration from '{filename}'...")
+            try:
+                # Load module dynamically
+                spec = importlib.util.spec_from_file_location("local_app", filename)
+                if spec and spec.loader:
+                    module = importlib.util.module_from_spec(spec)
+                    spec.loader.exec_module(module)
+                    
+                    # Look for app or orc
+                    if hasattr(module, "app"):
+                        app = getattr(module, "app")
+                    if hasattr(module, "orc"):
+                        orchestrator = getattr(module, "orc")
+                    elif hasattr(module, "orchestrator"):
+                        orchestrator = getattr(module, "orchestrator")
+                    break
+            except Exception as e:
+                click.echo(f"Warning: Failed to import '{filename}': {e}")
+                
+    if not app:
+        click.echo("No local Flask app instance found in main.py/app.py. Starting default Orchestrator...")
+        from pgframx.orchestrator import Orchestrator
+        from pgframx.app import create_app
+        orchestrator = Orchestrator()
+        app = create_app(orchestrator)
+        
+    click.echo(f"Starting server on {Config.PGFRAMX_HOST}:{Config.PGFRAMX_PORT}...")
+    try:
+        app.run(
+            host=Config.PGFRAMX_HOST,
+            port=Config.PGFRAMX_PORT,
+            debug=Config.PGFRAMX_DEBUG,
+            use_reloader=False  # Avoid double startup of scheduler background threads
+        )
+    except KeyboardInterrupt:
+        click.echo("\nStopping orchestrator server...")
+        if orchestrator:
+            orchestrator.shutdown()
+
+@main.command()
+@click.argument("event_name")
+@click.option("--data", default="{}", help="JSON string data payload.")
+@click.option("--async", "async_dispatch", is_flag=True, help="Emit event asynchronously.")
+def emit(event_name, data, async_dispatch):
+    """Emit event from CLI."""
+    url = f"{get_base_url()}/events/emit"
+    try:
+        parsed_data = json.loads(data)
+    except json.JSONDecodeError as e:
+        click.echo(f"Error parsing JSON payload: {e}", err=True)
+        return
+        
+    payload = {
+        "name": event_name,
+        "data": parsed_data,
+        "async": async_dispatch
+    }
+    
+    try:
+        response = requests.post(url, json=payload)
+        if response.status_code == 201:
+            click.echo(json.dumps(response.json(), indent=2))
+        else:
+            click.echo(f"Error ({response.status_code}): {response.text}", err=True)
+    except requests.exceptions.ConnectionError:
+        click.echo(f"Error: Could not connect to pgframx server at {get_base_url()}. Is it running?", err=True)
+
+@main.group(name="list")
+def list_group():
+    """List resources (events, listeners)."""
+    pass
+
+@list_group.command(name="events")
+def list_events():
+    """Print registered events."""
+    url = f"{get_base_url()}/events"
+    try:
+        response = requests.get(url)
+        if response.status_code == 200:
+            events = response.json().get("events", [])
+            if not events:
+                click.echo("No event patterns registered.")
+            for event in events:
+                click.echo(f"- {event}")
+        else:
+            click.echo(f"Error ({response.status_code}): {response.text}", err=True)
+    except requests.exceptions.ConnectionError:
+        click.echo(f"Error: Could not connect to pgframx server. Is it running?", err=True)
+
+@list_group.command(name="listeners")
+def list_listeners():
+    """Print registered listeners."""
+    url = f"{get_base_url()}/listeners"
+    try:
+        response = requests.get(url)
+        if response.status_code == 200:
+            listeners = response.json().get("listeners", [])
+            if not listeners:
+                click.echo("No listeners registered.")
+            for l in listeners:
+                click.echo(f"ID: {l['id']}")
+                click.echo(f"  Pattern: {l['pattern']}")
+                click.echo(f"  Dynamic: {l['is_dynamic']}")
+                if l['is_dynamic']:
+                    click.echo(f"  Webhook: {l['webhook_url']}")
+                else:
+                    click.echo(f"  Callback: {l['callback_name']}")
+                click.echo("")
+        else:
+            click.echo(f"Error ({response.status_code}): {response.text}", err=True)
+    except requests.exceptions.ConnectionError:
+        click.echo(f"Error: Could not connect to pgframx server. Is it running?", err=True)
+
+@main.group(name="schedule")
+def schedule_group():
+    """Manage scheduled jobs."""
+    pass
+
+@schedule_group.command(name="list")
+def list_jobs():
+    """List scheduled jobs."""
+    url = f"{get_base_url()}/health/scheduler"
+    try:
+        response = requests.get(url)
+        if response.status_code == 200:
+            data = response.json()
+            if not data.get("scheduler_enabled"):
+                click.echo("Scheduler is disabled.")
+                return
+            jobs = data.get("jobs", [])
+            if not jobs:
+                click.echo("No scheduled jobs found.")
+            for job in jobs:
+                click.echo(f"Job ID: {job['id']}")
+                click.echo(f"  Event Name: {job['name']}")
+                click.echo(f"  Trigger: {job['trigger']}")
+                click.echo(f"  Next Run: {job['next_run_time']}")
+                click.echo("")
+        else:
+            click.echo(f"Error ({response.status_code}): {response.text}", err=True)
+    except requests.exceptions.ConnectionError:
+        click.echo(f"Error: Could not connect to pgframx server. Is it running?", err=True)
+
+@schedule_group.command(name="add")
+@click.argument("event_name")
+@click.option("--cron", default=None, help="Cron expression (e.g. '*/5 * * * *')")
+@click.option("--interval", default=None, type=int, help="Interval in seconds")
+@click.option("--data", default="{}", help="JSON string event data payload")
+def add_job(event_name, cron, interval, data):
+    """Schedule a recurring event."""
+    url = f"{get_base_url()}/health/scheduler/jobs"
+    try:
+        parsed_data = json.loads(data)
+    except json.JSONDecodeError as e:
+        click.echo(f"Error parsing JSON payload: {e}", err=True)
+        return
+        
+    payload = {
+        "name": event_name,
+        "cron": cron,
+        "interval": interval,
+        "data": parsed_data
+    }
+    
+    try:
+        response = requests.post(url, json=payload)
+        if response.status_code == 201:
+            click.echo(json.dumps(response.json(), indent=2))
+        else:
+            click.echo(f"Error ({response.status_code}): {response.text}", err=True)
+    except requests.exceptions.ConnectionError:
+        click.echo(f"Error: Could not connect to pgframx server. Is it running?", err=True)
+
+@schedule_group.command(name="remove")
+@click.argument("job_id")
+def remove_job(job_id):
+    """Remove a scheduled job by ID."""
+    url = f"{get_base_url()}/health/scheduler/jobs/{job_id}"
+    try:
+        response = requests.delete(url)
+        if response.status_code == 200:
+            click.echo(response.json().get("message"))
+        else:
+            click.echo(f"Error ({response.status_code}): {response.text}", err=True)
+    except requests.exceptions.ConnectionError:
+        click.echo(f"Error: Could not connect to pgframx server. Is it running?", err=True)

pgframx/config.py

@@ -0,0 +1,29 @@
+import os
+from dotenv import load_dotenv
+
+# Try loading from .pgframx.env first, fallback to standard .env
+if os.path.exists(".pgframx.env"):
+    load_dotenv(".pgframx.env")
+else:
+    load_dotenv()
+
+class Config:
+    PGFRAMX_HOST = os.getenv("PGFRAMX_HOST", "0.0.0.0")
+    PGFRAMX_PORT = int(os.getenv("PGFRAMX_PORT", "5050"))
+    PGFRAMX_DEBUG = os.getenv("PGFRAMX_DEBUG", "False").lower() in ("true", "1", "yes")
+    PGFRAMX_LOG_LEVEL = os.getenv("PGFRAMX_LOG_LEVEL", "INFO")
+    PGFRAMX_SCHEDULER_ENABLED = os.getenv("PGFRAMX_SCHEDULER_ENABLED", "True").lower() in ("true", "1", "yes")
+    PGFRAMX_EVENT_LOG_MAX = int(os.getenv("PGFRAMX_EVENT_LOG_MAX", "1000"))
+    PGFRAMX_THREAD_POOL_SIZE = int(os.getenv("PGFRAMX_THREAD_POOL_SIZE", "10"))
+
+    @classmethod
+    def to_dict(cls) -> dict:
+        return {
+            "PGFRAMX_HOST": cls.PGFRAMX_HOST,
+            "PGFRAMX_PORT": cls.PGFRAMX_PORT,
+            "PGFRAMX_DEBUG": cls.PGFRAMX_DEBUG,
+            "PGFRAMX_LOG_LEVEL": cls.PGFRAMX_LOG_LEVEL,
+            "PGFRAMX_SCHEDULER_ENABLED": cls.PGFRAMX_SCHEDULER_ENABLED,
+            "PGFRAMX_EVENT_LOG_MAX": cls.PGFRAMX_EVENT_LOG_MAX,
+            "PGFRAMX_THREAD_POOL_SIZE": cls.PGFRAMX_THREAD_POOL_SIZE
+        }

pgframx/event.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+@dataclass
+class Event:
+    name: str
+    data: Dict[str, Any] = field(default_factory=dict)
+    meta: Dict[str, Any] = field(default_factory=dict)  # timestamp, source, trace_id, etc.
+    status: str = "pending"  # pending | dispatched | failed

pgframx/hooks.py

@@ -0,0 +1,51 @@
+import fnmatch
+from typing import Callable, Dict, List
+import logging
+
+logger = logging.getLogger("pgframx.hooks")
+
+class HookRegistry:
+    def __init__(self):
+        # Maps patterns (str) to lists of callbacks
+        self.before_hooks: Dict[str, List[Callable]] = {}
+        self.after_hooks: Dict[str, List[Callable]] = {}
+
+    def register_before(self, pattern: str, callback: Callable):
+        if pattern not in self.before_hooks:
+            self.before_hooks[pattern] = []
+        self.before_hooks[pattern].append(callback)
+        logger.debug(f"Registered before hook on pattern '{pattern}': {callback.__name__}")
+
+    def register_after(self, pattern: str, callback: Callable):
+        if pattern not in self.after_hooks:
+            self.after_hooks[pattern] = []
+        self.after_hooks[pattern].append(callback)
+        logger.debug(f"Registered after hook on pattern '{pattern}': {callback.__name__}")
+
+    def run_before(self, event) -> bool:
+        """Runs all before hooks matching the event name.
+        If a hook raises an exception, execution stops and we return False (failed).
+        Otherwise returns True.
+        """
+        for pattern, callbacks in self.before_hooks.items():
+            if fnmatch.fnmatch(event.name, pattern):
+                for callback in callbacks:
+                    try:
+                        callback(event)
+                    except Exception as e:
+                        logger.error(f"Before hook '{callback.__name__}' failed for event '{event.name}': {e}", exc_info=True)
+                        event.status = "failed"
+                        return False
+        return True
+
+    def run_after(self, event):
+        """Runs all after hooks matching the event name.
+        Failure in an after hook does not halt event execution but is logged.
+        """
+        for pattern, callbacks in self.after_hooks.items():
+            if fnmatch.fnmatch(event.name, pattern):
+                for callback in callbacks:
+                    try:
+                        callback(event)
+                    except Exception as e:
+                        logger.error(f"After hook '{callback.__name__}' failed for event '{event.name}': {e}", exc_info=True)

pgframx/listeners.py

@@ -0,0 +1,90 @@
+import uuid
+import fnmatch
+import requests
+from typing import Callable, Dict, List, Any
+import logging
+
+logger = logging.getLogger("pgframx.listeners")
+
+class Listener:
+    def __init__(self, pattern: str, callback: Callable, listener_id: str = None, is_dynamic: bool = False, webhook_url: str = None):
+        self.id = listener_id or str(uuid.uuid4())
+        self.pattern = pattern
+        self.callback = callback
+        self.is_dynamic = is_dynamic
+        self.webhook_url = webhook_url
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "pattern": self.pattern,
+            "callback_name": self.callback.__name__ if self.callback else None,
+            "is_dynamic": self.is_dynamic,
+            "webhook_url": self.webhook_url
+        }
+
+    def execute(self, event) -> bool:
+        """Executes the listener's callback or sends a webhook if dynamic.
+        Returns True if successful, False otherwise.
+        """
+        if self.webhook_url:
+            try:
+                # Dynamic webhook listener
+                response = requests.post(self.webhook_url, json={
+                    "event_name": event.name,
+                    "data": event.data,
+                    "meta": event.meta,
+                    "status": event.status
+                }, timeout=5)
+                if response.status_code >= 200 and response.status_code < 300:
+                    return True
+                else:
+                    logger.error(f"Webhook listener {self.id} returned status code {response.status_code}")
+                    return False
+            except Exception as e:
+                logger.error(f"Webhook listener {self.id} failed: {e}", exc_info=True)
+                return False
+        elif self.callback:
+            try:
+                self.callback(event)
+                return True
+            except Exception as e:
+                logger.error(f"Callback listener {self.id} failed: {e}", exc_info=True)
+                return False
+        return False
+
+
+class ListenerRegistry:
+    def __init__(self):
+        # Dictionary of listener_id -> Listener
+        self.listeners: Dict[str, Listener] = {}
+
+    def register(self, pattern: str, callback: Callable = None, listener_id: str = None, webhook_url: str = None) -> str:
+        is_dynamic = webhook_url is not None
+        listener = Listener(
+            pattern=pattern,
+            callback=callback,
+            listener_id=listener_id,
+            is_dynamic=is_dynamic,
+            webhook_url=webhook_url
+        )
+        self.listeners[listener.id] = listener
+        logger.debug(f"Registered listener {listener.id} for pattern '{pattern}'")
+        return listener.id
+
+    def deregister(self, listener_id: str) -> bool:
+        if listener_id in self.listeners:
+            del self.listeners[listener_id]
+            logger.debug(f"Deregistered listener {listener_id}")
+            return True
+        return False
+
+    def get_listeners_for_event(self, event_name: str) -> List[Listener]:
+        matched = []
+        for listener in self.listeners.values():
+            if fnmatch.fnmatch(event_name, listener.pattern):
+                matched.append(listener)
+        return matched
+
+    def list_all(self) -> List[Listener]:
+        return list(self.listeners.values())

pgframx/orchestrator.py

@@ -0,0 +1,134 @@
+import time
+import uuid
+import logging
+from collections import deque
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, List, Optional
+from datetime import datetime
+
+from pgframx.event import Event
+from pgframx.listeners import ListenerRegistry
+from pgframx.hooks import HookRegistry
+
+logger = logging.getLogger("pgframx.orchestrator")
+
+class Orchestrator:
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        self.config = config or {}
+        self.start_time = time.time()
+        
+        # Load config limits
+        self.event_log_max = int(self.config.get("PGFRAMX_EVENT_LOG_MAX", 1000))
+        self.scheduler_enabled = bool(self.config.get("PGFRAMX_SCHEDULER_ENABLED", True))
+        
+        # Initialize registries
+        self.listeners = ListenerRegistry()
+        self.hooks = HookRegistry()
+        
+        # Event dispatch history log
+        self.event_log = deque(maxlen=self.event_log_max)
+        
+        # Thread Pool for async emissions
+        self.executor = ThreadPoolExecutor(max_workers=self.config.get("PGFRAMX_THREAD_POOL_SIZE", 10))
+        
+        # Scheduler placeholder (initialized dynamically to avoid circular imports)
+        self.scheduler = None
+        if self.scheduler_enabled:
+            from pgframx.scheduler import EventScheduler
+            self.scheduler = EventScheduler(self)
+            self.scheduler.start()
+
+    # Decorators
+    def on(self, pattern: str):
+        """Decorator to register an event listener."""
+        def decorator(func: Callable):
+            self.listeners.register(pattern, callback=func)
+            return func
+        return decorator
+
+    def before(self, pattern: str):
+        """Decorator to register a before hook."""
+        def decorator(func: Callable):
+            self.hooks.register_before(pattern, func)
+            return func
+        return decorator
+
+    def after(self, pattern: str):
+        """Decorator to register an after hook."""
+        def decorator(func: Callable):
+            self.hooks.register_after(pattern, func)
+            return func
+        return decorator
+
+    # Scheduler delegation
+    def schedule(self, event_name: str, cron: Optional[str] = None, interval: Optional[int] = None, data: Optional[Dict[str, Any]] = None) -> str:
+        """Schedules a recurring event using cron or interval."""
+        if not self.scheduler:
+            raise RuntimeError("Scheduler is disabled or not initialized.")
+        return self.scheduler.add_job(event_name, cron=cron, interval=interval, data=data)
+
+    def unschedule(self, job_id: str) -> bool:
+        """Removes a scheduled job."""
+        if not self.scheduler:
+            raise RuntimeError("Scheduler is disabled or not initialized.")
+        return self.scheduler.remove_job(job_id)
+
+    # Core Dispatcher
+    def emit(self, name: str, data: Optional[Dict[str, Any]] = None, meta: Optional[Dict[str, Any]] = None, async_dispatch: bool = False) -> Event:
+        """Emits an event and dispatches it to matched listeners."""
+        data = data or {}
+        meta = meta or {}
+        
+        # Build meta defaults
+        meta.setdefault("timestamp", datetime.utcnow().isoformat() + "Z")
+        meta.setdefault("trace_id", str(uuid.uuid4()))
+        meta.setdefault("source", "pgframx")
+        
+        event = Event(name=name, data=data, meta=meta, status="pending")
+        self.event_log.append(event)
+        
+        if async_dispatch:
+            self.executor.submit(self._run_dispatch, event)
+            logger.debug(f"Submitted event '{name}' for async dispatch (trace_id: {meta['trace_id']})")
+        else:
+            self._run_dispatch(event)
+            
+        return event
+
+    def _run_dispatch(self, event: Event):
+        logger.info(f"Dispatching event '{event.name}' (trace_id: {event.meta['trace_id']})")
+        
+        # 1. Run before hooks
+        if not self.hooks.run_before(event):
+            logger.warning(f"Event '{event.name}' execution aborted by before hooks")
+            event.status = "failed"
+            return
+
+        # 2. Find listeners
+        matched_listeners = self.listeners.get_listeners_for_event(event.name)
+        if not matched_listeners:
+            logger.debug(f"No listeners found matching event name '{event.name}'")
+            event.status = "dispatched"
+            # Still run after hooks
+            self.hooks.run_after(event)
+            return
+
+        # 3. Execute listeners
+        all_success = True
+        for listener in matched_listeners:
+            logger.debug(f"Executing listener '{listener.id}' for event '{event.name}'")
+            success = listener.execute(event)
+            if not success:
+                all_success = False
+
+        event.status = "dispatched" if all_success else "failed"
+        logger.info(f"Finished dispatching event '{event.name}'. Status: {event.status}")
+        
+        # 4. Run after hooks
+        self.hooks.run_after(event)
+
+    def shutdown(self):
+        """Clean shutdown of thread pool and scheduler."""
+        if self.scheduler:
+            self.scheduler.shutdown()
+        self.executor.shutdown(wait=False)

pgframx/scheduler.py

@@ -0,0 +1,90 @@
+import logging
+from typing import Any, Dict, List, Optional
+from apscheduler.schedulers.background import BackgroundScheduler
+from apscheduler.triggers.cron import CronTrigger
+from apscheduler.triggers.interval import IntervalTrigger
+
+logger = logging.getLogger("pgframx.scheduler")
+
+class EventScheduler:
+    def __init__(self, orchestrator):
+        self.orchestrator = orchestrator
+        self.scheduler = BackgroundScheduler()
+
+    def start(self):
+        """Starts the background scheduler thread."""
+        if not self.scheduler.running:
+            self.scheduler.start()
+            logger.info("Background event scheduler started.")
+
+    def shutdown(self):
+        """Shuts down the scheduler."""
+        if self.scheduler.running:
+            self.scheduler.shutdown()
+            logger.info("Background event scheduler shut down.")
+
+    def add_job(self, event_name: str, cron: Optional[str] = None, interval: Optional[int] = None, data: Optional[Dict[str, Any]] = None) -> str:
+        """Adds a job to emit an event periodically.
+        cron can be a standard 5-field cron string or a dictionary of cron parameters.
+        interval is the duration in seconds.
+        """
+        data = data or {}
+        
+        # Define the trigger function
+        def trigger_emit():
+            logger.info(f"Scheduled trigger fired for event '{event_name}'")
+            self.orchestrator.emit(event_name, data=data, meta={"source": "scheduler"})
+
+        # Build trigger
+        if cron:
+            # Simple 5-field cron parsing or direct string
+            if isinstance(cron, str):
+                parts = cron.split()
+                if len(parts) == 5:
+                    trigger = CronTrigger(
+                        minute=parts[0],
+                        hour=parts[1],
+                        day=parts[2],
+                        month=parts[3],
+                        day_of_week=parts[4]
+                    )
+                else:
+                    # Try direct cron expression parsing
+                    trigger = CronTrigger.from_crontab(cron)
+            else:
+                trigger = CronTrigger(**cron)
+        elif interval is not None:
+            trigger = IntervalTrigger(seconds=int(interval))
+        else:
+            raise ValueError("Must specify either 'cron' or 'interval'")
+
+        job = self.scheduler.add_job(
+            trigger_emit,
+            trigger=trigger,
+            name=event_name,
+            replace_existing=True
+        )
+        logger.info(f"Added scheduled job {job.id} for event '{event_name}'")
+        return job.id
+
+    def remove_job(self, job_id: str) -> bool:
+        """Removes a scheduled job by its ID."""
+        try:
+            self.scheduler.remove_job(job_id)
+            logger.info(f"Removed scheduled job {job_id}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to remove job {job_id}: {e}")
+            return False
+
+    def list_jobs(self) -> List[Dict[str, Any]]:
+        """Lists details of all currently scheduled jobs."""
+        jobs_list = []
+        for job in self.scheduler.get_jobs():
+            jobs_list.append({
+                "id": job.id,
+                "name": job.name,
+                "next_run_time": job.next_run_time.isoformat() if job.next_run_time else None,
+                "trigger": str(job.trigger)
+            })
+        return jobs_list

pgframx/utils.py

@@ -0,0 +1,23 @@
+import logging
+import sys
+from typing import Any, Dict
+
+def setup_logging(level: str = "INFO"):
+    """Sets up default logging console handlers for the package."""
+    log_level = getattr(logging, level.upper(), logging.INFO)
+    
+    # Configure root logger or package logger
+    logger = logging.getLogger("pgframx")
+    logger.setLevel(log_level)
+    
+    # Check if handler already exists
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setLevel(log_level)
+        formatter = logging.Formatter(
+            '[%(asctime)s] %(levelname)s in %(name)s: %(message)s'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    
+    logger.info(f"Logging initialized at level: {level}")

pgframx-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: pgframx
+Version: 0.1.0
+Summary: Flask-based event management orchestration framework
+Project-URL: Homepage, https://github.com/pgwiz/pgframx
+Project-URL: Repository, https://github.com/pgwiz/pgframx
+Author-email: pgwiz <peter@wiptech.co.ke>
+License: MIT License
+        
+        Copyright (c) 2026 pgwiz
+        
+        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.
+License-File: LICENSE
+Keywords: events,flask,framework,orchestration,scheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: apscheduler>=3.10.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: flask>=3.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# pgframx
+
+**Flask-based event management orchestration framework.**
+
+Orchestrate events, not chaos.
+
+## Install
+
+```bash
+pip install pgframx
+```
+
+## Quickstart
+
+```python
+from pgframx import Orchestrator, create_app
+
+orc = Orchestrator()
+
+@orc.on("order.placed")
+def handle_order(event):
+    print(f"Order received: {event.data}")
+
+app = create_app(orc)
+
+if __name__ == "__main__":
+    app.run(port=5050)
+```
+
+## CLI
+
+```bash
+pgframx init        # Create a new project scaffold in current directory
+pgframx run         # Start the Flask orchestrator server
+pgframx emit <event> --data '{}'  # Emit event from CLI to running server
+pgframx list events               # List all registered events
+pgframx list listeners            # List all registered listeners
+pgframx schedule list             # List scheduled cron/interval jobs
+pgframx schedule add <event> --interval 10  # Schedule recurring events
+pgframx schedule remove <job_id>  # Remove scheduled jobs
+```
+
+## Features
+- **Decorators**: Event registration, before hooks, and after hooks.
+- **Wildcard matching**: Match events using wildcards (`user.*`).
+- **Scheduling**: Chronological/interval-based triggers via APScheduler.
+- **REST API**: Mountable blueprints exposing route endpoints for events, listeners, and health checks.
+- **Dynamic Webhooks**: Register webhooks dynamically via the REST API or CLI.
+- **Full CLI**: Manage your event broker process from the terminal.

pgframx-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+pgframx/__init__.py,sha256=JzZZuDXXLU6qwoFD5m9MESXPNTRQdEKbxYtozwNZ1l4,187
+pgframx/app.py,sha256=dFIGjLZ1OqA91kHsvJAgI88SDeSWqpxLnkZ9ES4Ypq4,1031
+pgframx/cli.py,sha256=Kih3vLpeP3LFRStHldBG8x-jH0kn6wSZ_yvWBJmtamA,10362
+pgframx/config.py,sha256=Ug37Iunr4P5bnfwfUjw7AhEYobNWxpyQHslAnEcoCjA,1221
+pgframx/event.py,sha256=B_Zer7yOm_K0vQRVq9xljRNL1gklajU1HjQvBrCO170,317
+pgframx/hooks.py,sha256=7sBjgj88OG81WU3RLLWZhtH9TaRR9jqYObjrk2Wwd1o,2216
+pgframx/listeners.py,sha256=zjyz4aJnCjBqsbqLjkDwQudiMbanC2B91cT_ZW3ebMk,3322
+pgframx/orchestrator.py,sha256=XN-ShoDstwk_9Czy6mOsJ7KSfWBFrEAICEbeZfmkl_4,5172
+pgframx/scheduler.py,sha256=q4mNzUa9_m1GAa-qpHGG--3rJXvB-hcTh1FnhNm8QKg,3405
+pgframx/utils.py,sha256=FqOZKY-Oqb-eYam_ZAL9TkeUGW5XnZ2SlERBUy0Ih_k,763
+pgframx/blueprints/__init__.py,sha256=mjHMod2Wy7o3mm69lGLJ4bkJQek3dnW-GBA7kn9Sv7k,204
+pgframx/blueprints/events.py,sha256=QiNTVYrNVgqzPFbP35gPKypBqXnKLKvA6SLkxOH7MBY,1909
+pgframx/blueprints/health.py,sha256=guwZNivc2H51qtgjNGBg7x56bfm7I-lzs1S9yPaULzI,2415
+pgframx/blueprints/listeners.py,sha256=tn2mUQMEJWS59jPTol0amL3YNsxB5y8-Ac_6Cn6oT6w,1473
+pgframx-0.1.0.dist-info/METADATA,sha256=TlAQef4o-COuUuvPfw0VLb3ktNfLfHm8P9P-CICc6uE,3542
+pgframx-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pgframx-0.1.0.dist-info/entry_points.txt,sha256=rbr83kzoA-b00fru1k5aD2yldsIf6_WiIewK4bKt5FE,45
+pgframx-0.1.0.dist-info/licenses/LICENSE,sha256=ENolhwlfECA8Dc-6NbN2jWAnhZEsbrjsfBO7HZUmIu8,1062
+pgframx-0.1.0.dist-info/RECORD,,

pgframx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pgframx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pgframx = pgframx.cli:main

pgframx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pgwiz
+
+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.