Fix pie/donut chart label overlap with post-processing

[ghostiee-11]

Description

Pie chart labels overlap on small slices because Vega-Lite doesn't do collision avoidance on arc text marks. No matter what the LLM generates, adjacent small slices will have labels piled on top of each other.

I added a _fix_arc_labels post-processing step that repositions labels outside the pie using theta encoding with a radius offset. For charts with many categories (>8), labels are dropped entirely in favor of the legend + tooltip.

MRVE

import lumen.ai as lmai
lmai.ExplorerUI().servable()

Upload any CSV with a category column, ask "plot as pie chart".

Before

After

How Has This Been Tested?

• 10 unit tests in test_agents.py
• Manual end-to-end with local server

AI Disclosure

I identified the issue while testing pie charts, designed the approach (post-processing hook after validate_spec), and verified through tests + manual testing. AI helped scaffold the implementation.

Checklist

• Tests added and passing
• Added documentation

[codecov]

Codecov Report

❌ Patch coverage is 97.41379% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.31%. Comparing base (f382192) to head (bf493c6).

Files with missing lines	Patch %	Lines
lumen/ai/agents/vega_lite.py	93.61%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1767      +/-   ##
==========================================
+ Coverage   68.18%   68.31%   +0.13%     
==========================================
  Files         170      170              
  Lines       28535    28651     +116     
==========================================
+ Hits        19456    19574     +118     
+ Misses       9079     9077       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[philippjfr]

I'm not necessarily against this but my general feeling is that this starts us down an path of maintaining an endless list of post-processing optimizations for vega charts. I know we already do something like this for geographic plots so I get why you went down this path. I'll let @ahuang11 chime in with his opinion.

[ghostiee-11]

Thanks, Philip!! That's a fair concern. I went with post-processing because Vega-Lite has no collision avoidance for text on arc marks, so prompt-only fixes are unreliable for small slices. I tried several prompt-only approaches first, but they kept failing depending on data distribution. The post-processing is intentionally narrow - it only fires when an arc layer exists and only touches the text layer.

Happy to hear what he thinks and adjust if needed.

[ahuang11]

Few thoughts:

I'm okay with plot patches in the code. However, here, I think a minor prompt or example might be sufficient?

Alternatively, I think the better solution is ingesting vega lite docs as embeddings (right now I think we ingested examples, but not plot pages) https://vega.github.io/vega-lite/docs/arc.html

Also, it might make sense to implement code patches as a separate class mixin(?) and a method that detects these patches, rather than having patching logic directly in the VegaLiteAgent.

[ghostiee-11]

Thanks Andrew! Good points. Here's what I'm thinking:

1. Prompt/example first - I already added a pie/donut example in the prompt template, but I'll test whether that alone produces reliable results before layering on post-processing. Will report back with results.
2. Mixin pattern - If prompt-only still fails on edge cases (small slices with similar values), I'll refactor the patch logic into a separate mixin to keep VegaLiteAgent clean.
3. Docs as embeddings - Happy to tackle ingesting the arc docs page into the vector store as a separate PR since the DB files are pre-built and hosted externally.

Will start with prompt-only testing and update here.