feat(atproto): resolve DID to handle and display name via enrichment UDFs

[julietshen]

Closes #417. Stacked on #236 (hailey/atproto-jetstream-sample) — review after #236 lands.

What this adds

JetStream events identify the actor only by DID, so the event stream and rules can't search by handle or display name. This adds two enrichment UDFs in the atproto plugin — AtprotoHandle(did) and AtprotoDisplayName(did) — that resolve a DID against Bluesky's public, unauthenticated AppView (app.bsky.actor.getProfile), over a shared per-DID profile cache, failing soft when the API errors or rate-limits.

Enrichment is opt-in (off by default). Each unique DID costs an external API call, which is exactly the dependency you don't want in #236's load-testing scenario. So the default rules run against the raw firehose with no outbound calls; the enrichment lives in models/enrichment.sml, which main.sml does not import by default. The README documents the one-step opt-in (plus the lexicographically-sorted import) and how to extend it with more profile fields (account age, follower/post counts, existing moderation labels) rather than shipping them all wired-in.

It also removes the dead IdentityHandle model and corrects the README's identity-event shape — JetStream identity events carry only did/seq/time, never a handle (verified against live traffic).

Verified live

• Default (off): rules validate, zero outbound calls, no Handle/DisplayName in output, __error_count: 0.
• Opt-in (on): hundreds of handles/display names resolve against the real firehose (e.g. real bsky.social handles), __error_count: 0, rate-limited lookups fail soft.
• 31 unit tests pass (fetch, cache, missing-field and transport-error fail-soft).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• main

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 855af7ee-7fe0-474d-bbeb-feec46761990

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch julietshen/atproto-profile-enrichment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[haileyok]

i think i'd suggest a larger cache size, maybe around 100k?

[haileyok]

im not super familiar with how to best do this in python and particularly with gevent and locks... i might suggeset to claude to try and use functools's lru_cache decorator for this though.

https://docs.python.org/3/library/functools.html#functools.lru_cache

[haileyok]

tbh we probably also want this to be an expiry cache, since both handles are display names are subject to change

a preferred approach to having the cached items expire though is to have the cache get bust for the given key whenever an identity event (for handles) comes through jetstream or whenever a profile update events comes through. that way we are immediately responding to those things.

this adds some complexity that might not be worth fully ironing out here, but that would be the canonical example of how to do this i think

[haileyok]

hmm. this is interesting and im not exactly sure how to best do this with SML.

it's probably most likely that we're going to want both the handle and the DID in whatever model deals with user events. in that case, especially since these are going to get executed async, i think we'll end up with two requests getting made for the handle. the current locking won't actually stop a second request for being made for a user. this, i think, will double the amount of requests we are making to the api.

there's a couple of things that we could probably do, but the easiest might just be to do something like:

1. Have some UDF called AtprotoProfile that returns the profile object
2. Use JsonValue on the result of AtprotoProfile to pull out the handle and display name from the AtprotoProfile UDF's result

i think this will work with SML? but im not sure...

[haileyok]

left some comments. i think this code would work as is, but most of these are suggestions on how we can reduce the number of requests we have to make...

i'd be less hesitant to make sure we get this right if i didn't think that people would actually end up using these in real world use cases, but i figure there's a good chance that they will, so i'd definitely like to at least get right stuff like handling display name/handle updates

[julietshen]

Thanks @haileyok, this was really helpful! I ended up keeping the two DID-based UDFs but reworked the cache underneath them to incorporate all your feedback.

• Bumped the size to 100k

• On the double-request thing you flagged: you were right (ofc), and I confirmed it. Since the async UDFs run concurrently in the gevent pool, handle and display name both miss a cold cache and each fire their own getProfile. So I made in-flight fetches shared: if a request for a DID is already running, the second caller just waits on it instead of making its own. This should reduce the calls.

• I also added a 1-hour expiry, since handles and display names change and the old cache held onto them forever. I left a note in the code and README that the proper version of this is to bust a DID's entry when an identity or profile-update event comes through JetStream, but that felt like more than this example needs.

• On lru_cache: I tried to use it but it doesn't get us the in-flight dedup or the expiry, so it would've walked back the other two things. The hand-rolled cache is a little more code but does all three in one place.

I seriously considered your AtprotoProfile-returns-the-object idea and i like it but JsonData only reads the raw event data, not another feature's output, so there's no JsonValue-to-pull-from-a-feature to lean on, and a plain dict isn't a valid feature type. To make it work you'd need a custom language type (like we have for Entity and TimeDelta) plus the two-step SML wiring, which kinda felt heavy for an example. LMK what you think though, i can have Claude do it.