luzia/QUICK_START.md

Luzia Status System - Quick Start Guide

TL;DR: The status system is deployed and ready. Add 3 lines of code to start publishing events.

---

30-Second Setup

1. Verify Installation

python3 -c "from luzia_status_sync_wrapper import get_sync_publisher; print('✓ Ready')"

2. Add to Your Code

Copy this into your task dispatcher:

from luzia_status_sync_wrapper import get_sync_publisher

publisher = get_sync_publisher()

# When task starts
publisher.publish_task_started(
    task_id="project-task123",
    project="myproject",
    description="What the task does",
    estimated_duration_seconds=600
)

# When task completes
publisher.publish_task_completed(
    task_id="project-task123",
    elapsed_seconds=615,
    findings_count=2,
    status="APPROVED"
)

# When task fails
publisher.publish_task_failed(
    task_id="project-task123",
    error=str(exception),
    elapsed_seconds=300,
    retry_count=1,
    retriable=True
)

3. Test It

# Run example
python3 /opt/server-agents/orchestrator/examples/status_integration_example.py

# Check status
luzia status

---

Common Tasks

Task Just Started - Publish Event

publisher.publish_task_started(
    task_id="my-task-123",
    project="admin",
    description="Code review and fixes",
    estimated_duration_seconds=600
)

Task Progressing - Update Progress (Every 30 Seconds)

publisher.publish_progress(
    task_id="my-task-123",
    progress_percent=50,              # 0-100
    current_step=2,                   # Which step (1, 2, 3...)
    total_steps=4,                    # Total steps
    current_step_name="Processing",   # Name of current step
    elapsed_seconds=300,              # How long so far
    estimated_remaining_seconds=300   # Est time left
)

Task Completed Successfully

publisher.publish_task_completed(
    task_id="my-task-123",
    elapsed_seconds=600,
    findings_count=2,                 # Number of findings
    recommendations_count=1,          # Number of recommendations
    status="APPROVED"                 # or "NEEDS_WORK", "REJECTED"
)

Task Failed

publisher.publish_task_failed(
    task_id="my-task-123",
    error="Connection timeout",
    elapsed_seconds=300,
    retry_count=1,                    # Which attempt failed
    retriable=True                    # Can it be retried?
)

Task Warning (Time Running Out, etc.)

publisher.publish_warning(
    task_id="my-task-123",
    warning_type="DURATION_EXCEEDED",
    message="Task approaching time limit",
    current_step=3,
    total_steps=4,
    current_step_name="Validating",
    elapsed_seconds=480,
    progress_percent=75,
    recommendation="May need optimization"
)

Task Queued (System Busy)

publisher.publish_task_queued(
    task_id="my-task-123",
    project="admin",
    description="Code review",
    reason="System resource limit",
    queue_position=3,
    queue_ahead=["task-100", "task-101"],
    estimated_wait_seconds=300
)

System Alert

publisher.publish_system_alert(
    alert_type="MEMORY_WARNING",
    message="Memory at 85%",
    recommendation="Queued tasks will wait",
    severity="warning"                # or "critical"
)

---

Check Status

# Show dashboard
luzia status

# Show only warnings/errors
luzia status --alerts

# Show specific project
luzia status --project admin

# Show last N updates
luzia status --recent 10

# Export to JSON
luzia status --export json
# Creates: /tmp/luzia_status_20260109_120000.json

# Export to Markdown
luzia status --export markdown

---

Customize Behavior

Edit /etc/luzia/status_config.toml:

[status_updates]
verbosity = "normal"              # quiet, normal, verbose
progress_update_threshold_percent = 25  # Show at 25%, 50%, 75%
progress_update_min_interval_seconds = 30  # Min time between updates

[display]
use_colors = true
use_emojis = true
compact_format = true

[logging]
enabled = true
log_file = "/var/log/luzia/status.log"
log_level = "INFO"

---

Test Integration

Run the full test suite:

cd /opt/server-agents/orchestrator/lib
python3 test_status_integration.py

All tests should pass (7/7).

---

Files Deployed

• /etc/luzia/status_config.toml - Configuration
• /opt/server-agents/orchestrator/lib/luzia_status_*.py - Core modules
• /opt/server-agents/orchestrator/lib/test_status_integration.py - Tests
• /opt/server-agents/orchestrator/examples/status_integration_example.py - Examples
• /opt/server-agents/orchestrator/LUZIA_STATUS_INTEGRATION.md - Full docs
• /opt/server-agents/orchestrator/STATUS_DEPLOYMENT_COMPLETE.md - Deployment info

---

Complete Example

from luzia_status_sync_wrapper import get_sync_publisher
import time

def run_task():
    publisher = get_sync_publisher()
    task_id = "admin-review-123"

    # Task starts
    publisher.publish_task_started(
        task_id=task_id,
        project="admin",
        description="Code review",
        estimated_duration_seconds=600
    )

    start = time.time()

    try:
        # Step 1
        print("Step 1: Analyzing...")
        time.sleep(2)

        publisher.publish_progress(
            task_id=task_id,
            progress_percent=25,
            current_step=1,
            total_steps=4,
            current_step_name="Analyzing",
            elapsed_seconds=int(time.time() - start),
            estimated_remaining_seconds=450
        )

        # Step 2
        print("Step 2: Reviewing...")
        time.sleep(2)

        publisher.publish_progress(
            task_id=task_id,
            progress_percent=50,
            current_step=2,
            total_steps=4,
            current_step_name="Reviewing",
            elapsed_seconds=int(time.time() - start),
            estimated_remaining_seconds=300
        )

        # Step 3
        print("Step 3: Fixing...")
        time.sleep(2)

        # Step 4
        print("Step 4: Testing...")
        time.sleep(2)

        publisher.publish_progress(
            task_id=task_id,
            progress_percent=100,
            current_step=4,
            total_steps=4,
            current_step_name="Testing",
            elapsed_seconds=int(time.time() - start),
            estimated_remaining_seconds=0
        )

        # Success
        elapsed = int(time.time() - start)
        publisher.publish_task_completed(
            task_id=task_id,
            elapsed_seconds=elapsed,
            findings_count=3,
            status="APPROVED"
        )

        print("✓ Task completed successfully")

    except Exception as e:
        elapsed = int(time.time() - start)
        publisher.publish_task_failed(
            task_id=task_id,
            error=str(e),
            elapsed_seconds=elapsed,
            retry_count=1,
            retriable=True
        )
        raise

if __name__ == "__main__":
    run_task()

---

Need Help?

1. Check tests: python3 /opt/server-agents/orchestrator/lib/test_status_integration.py
2. See examples: /opt/server-agents/orchestrator/examples/status_integration_example.py
3. Read full docs: /opt/server-agents/orchestrator/LUZIA_STATUS_INTEGRATION.md
4. Check logs: tail -f /var/log/luzia/status.log

---

Status: ✓ Ready for production use

Add the 3-line import and start publishing. It's that simple.