ai/backend.old/src/trigger/PRIORITIES.md

Priority System

Simple tuple-based priorities for deterministic execution ordering.

Basic Concept

Priorities are just Python tuples. Python compares tuples element-by-element, left-to-right:

(0, 1000, 5) < (0, 1001, 3)  # True: 0==0, but 1000 < 1001
(0, 1000, 5) < (1, 500, 2)   # True: 0 < 1
(0, 1000) < (0, 1000, 5)     # True: shorter wins if equal so far

Lower values = higher priority (processed first).

Priority Categories

class Priority(IntEnum):
    DATA_SOURCE = 0        # Market data, real-time feeds
    TIMER = 1              # Scheduled tasks, cron jobs
    USER_AGENT = 2         # User-agent interactions (chat)
    USER_DATA_REQUEST = 3  # User data requests (charts)
    SYSTEM = 4             # Background tasks, cleanup
    LOW = 5                # Retries after conflicts

Usage Examples

Simple Priority

# Just use the Priority enum
trigger = MyTrigger("task", priority=Priority.SYSTEM)
await queue.enqueue(trigger)

# Results in tuple: (4, queue_seq)

Compound Priority (Tuple)

# DataSource: sort by event time (older bars first)
trigger = DataUpdateTrigger(
    source_name="binance",
    symbol="BTC/USDT",
    resolution="1m",
    bar_data={"time": 1678896000, "open": 50000, ...}
)
await queue.enqueue(trigger)

# Results in tuple: (0, 1678896000, queue_seq)
#                    ^  ^            ^
#                    |  |            Queue insertion order (FIFO)
#                    |  Event time (candle end time)
#                    DATA_SOURCE priority

Manual Override

# Override at enqueue time
await queue.enqueue(
    trigger,
    priority_override=(Priority.DATA_SOURCE, custom_time, custom_sort)
)

# Queue appends queue_seq: (0, custom_time, custom_sort, queue_seq)

Common Patterns

Market Data (Process Chronologically)

# Bar from 10:00 → (0, 10:00_timestamp, queue_seq)
# Bar from 10:05 → (0, 10:05_timestamp, queue_seq)
#
# 10:00 bar processes first (earlier event_time)

DataUpdateTrigger(
    ...,
    bar_data={"time": event_timestamp, ...}
)

User Messages (FIFO Order)

# Message #1 → (2, msg1_timestamp, queue_seq)
# Message #2 → (2, msg2_timestamp, queue_seq)
#
# Message #1 processes first (earlier timestamp)

AgentTriggerHandler(
    session_id="user1",
    message_content="...",
    message_timestamp=unix_timestamp  # Optional, defaults to now
)

Scheduled Tasks (By Schedule Time)

# Job scheduled for 9 AM → (1, 9am_timestamp, queue_seq)
# Job scheduled for 2 PM → (1, 2pm_timestamp, queue_seq)
#
# 9 AM job processes first

CronTrigger(
    name="morning_sync",
    inner_trigger=...,
    scheduled_time=scheduled_timestamp
)

Execution Order Example

Queue contains:
1. DataSource (BTC @ 10:00) → (0, 10:00, 1)
2. DataSource (BTC @ 10:05) → (0, 10:05, 2)
3. Timer (scheduled 9 AM)   → (1, 09:00, 3)
4. User message #1          → (2, 14:30, 4)
5. User message #2          → (2, 14:35, 5)

Dequeue order:
1. DataSource (BTC @ 10:00)  ← 0 < all others
2. DataSource (BTC @ 10:05)  ← 0 < all others, 10:05 > 10:00
3. Timer (scheduled 9 AM)    ← 1 < remaining
4. User message #1           ← 2 < remaining, 14:30 < 14:35
5. User message #2           ← last

Short Tuple Wins

If tuples are equal up to the length of the shorter one, shorter tuple has higher priority:

(0, 1000) < (0, 1000, 5)      # True: shorter wins
(0,) < (0, 1000)              # True: shorter wins
(Priority.DATA_SOURCE,) < (Priority.DATA_SOURCE, 1000)  # True

This is Python's default tuple comparison behavior. In practice, we always append queue_seq, so this rarely matters (all tuples end up same length).

Integration with Triggers

Trigger Sets Its Own Priority

class MyTrigger(Trigger):
    def __init__(self, event_time):
        super().__init__(
            name="my_trigger",
            priority=Priority.DATA_SOURCE,
            priority_tuple=(Priority.DATA_SOURCE.value, event_time)
        )

Queue appends queue_seq automatically:

# Trigger's tuple: (0, event_time)
# After enqueue:   (0, event_time, queue_seq)

Override at Enqueue

# Ignore trigger's priority, use override
await queue.enqueue(
    trigger,
    priority_override=(Priority.TIMER, scheduled_time)
)

Why Tuples?

✅ Simple: No custom classes, just native Python tuples ✅ Flexible: Add as many sort keys as needed ✅ Efficient: Python's tuple comparison is highly optimized ✅ Readable: (0, 1000, 5) is obvious what it means ✅ Debuggable: Can print and inspect easily

Example:

# Old: CompoundPriority(primary=0, secondary=1000, tertiary=5)
# New: (0, 1000, 5)

# Same semantics, much simpler!

Advanced: Custom Sorting

Want to sort by multiple factors? Just add more elements:

# Sort by: priority → symbol → event_time → queue_seq
priority_tuple = (
    Priority.DATA_SOURCE.value,
    symbol_id,  # e.g., hash("BTC/USDT")
    event_time,
    # queue_seq appended by queue
)

Summary

• Priorities are tuples: (primary, secondary, ..., queue_seq)
• Lower = higher priority: Processed first
• Element-by-element comparison: Left-to-right
• Shorter tuple wins: If equal up to shorter length
• Queue appends queue_seq: Always last element (FIFO within same priority)

That's it! No complex classes, just tuples. 🎯