Osprey Sml Reference

SML (Osprey Rules) Reference

SML is a Python-like language for defining moderation rules in Osprey. Rules extract data from events, evaluate conditions, and emit effects (labels, verdicts, list actions).

Core Type System

Four fundamental types make up SML:

EntityJson & Entity — Typed Identifiers

EntityJson extracts entity IDs from event JSON; Entity constructs them from known values. Labels attach to entities, not raw strings.

# CORRECT — UserId is an Entity; labels attach to it
UserId: Entity[str] = EntityJson(type='UserId', path='$.did', required=False)

# WRONG — JsonData produces str, not Entity[str]. Labels can't attach to str.
UserId: str = JsonData(path='$.did')

• EntityJson(type, path, required) → Entity[str] or Entity[int]. Use for IDs: UserId, Handle, AtUri, PdsHost.
• Entity(type, id) → construct entity from known values (e.g., computed AT-URI).

JsonData — Primitive Extraction

JsonData extracts primitive values from event JSON.

DisplayName: str = JsonData(path='$.eventMetadata.profile.displayName', required=False, coerce_type=True)
PostsCount: int = JsonData(path='$.eventMetadata.profile.postsCount', required=False)

Returns: str, int, float, bool, Optional[T], or List[T].

Optional[T] — Nullable Types

Use ResolveOptional to unwrap optional values with a default.

AccountAgeSeconds: Optional[int] = JsonData(path='$.eventMetadata.accountAge', required=False)
AccountAgeSecondsUnwrapped: int = ResolveOptional(optional_value=AccountAgeSeconds, default_value=999999999)

Core Constructs

Rule — AND of Conditions

Rule(when_all=[...], description=f'...')  # → RuleT

Combines multiple conditions with AND logic. All items in when_all must be the same type (all bool or all RuleT).

NewAccountSpam = Rule(
    when_all=[
        AccountAgeSeconds < Day,
        PostsCount > 50,
        FollowersCount < 5,
    ],
    description=f'New account spam (age={AccountAgeSeconds}s, posts={PostsCount})',
)

WhenRules — OR Trigger + Effects

WhenRules(rules_any=[...], then=[...])  # → None

Triggers effects when ANY rule passes. Always use rules_any=, never rules_all=.

WhenRules(
    rules_any=[NewAccountSpam, BotBehavior],
    then=[
        LabelAdd(entity=UserId, label='spam'),
        AtprotoLabel(entity=UserId, label='spam', comment='Auto-detected', expiration_in_hours=168),
    ],
)

Import & Require

Import(rules=['path/to/file.sml'])  # Load models/rules from other files
Require(rule='path/to/file.sml', require_if=condition)  # Conditional inclusion

Operators & Type Rules

All items in when_all must be the same type:

• RegexMatch(...), comparisons (X < Y), or/and on bools → bool
• Rule(...) → RuleT; RuleT or RuleT → RuleT
• Use infix or (A or B or C), NOT function-call or(A, B, C)
• not works on both bool and RuleT

# CORRECT — all bool
WhenRules(
    rules_any=[
        Rule(when_all=[PostText != '', RegexMatch(pattern=r'...', target=PostText)]),
    ],
    then=[...],
)

# WRONG — mixing RuleT and bool in when_all
Rule(when_all=[MyRule, SomeCondition == True])  # Can't mix Rule and bool

Effects

Apply effects when rules pass:

• LabelAdd(entity, label, apply_if?, expires_after?, delay_action_by?) — add label
• LabelRemove(entity, label, ...) — remove label
• AtprotoLabel(entity, label, comment, expiration_in_hours) — emit to Bluesky Ozone
• AtprotoTag(entity, tag, comment, neg?, apply_if?) — add/remove Ozone tag (neg=True to remove)
• DeclareVerdict(verdict) — for synchronous callers

WhenRules(
    rules_any=[SomeRule],
    then=[
        LabelAdd(entity=UserId, label='flagged', expires_after=TimeDelta(days=7)),
        LabelAdd(entity=AtUri, label='violation'),
    ],
)

Key UDFs Quick Reference

Progressive Disclosure

For detailed patterns and implementation examples, see:

• 25 Labeling Patterns — references/labeling-patterns.md. Covers all common use cases: content matching, rate limiting, strike systems, ML scoring, cross-entity labeling, caching, and more.
• Naming Conventions & Anti-Patterns — references/sml-conventions.md. Variable naming, time constants, RegexMatch rules, IncrementWindow keys, type system pitfalls, and what NOT to do. Also includes a Reviewer Checklist section with structured CONV-prefixed check IDs for systematic convention review.