feat(examples): add slug-to-chart for Polymarket price visualization

[guzus]

Summary

• Add examples/slug_to_chart/ module that generates Bloomberg-style price charts from prediction market data
• Multi-exchange support: Polymarket (default), Limitless, Opinion
• Smart x-axis date formatting that adapts to data range
• Multi-line legend for events with many outcomes
• Configurable intervals, min price threshold, and top N filtering

Supported Exchanges

Exchange	Intervals	Notes
Polymarket	1m, 1h, 6h, 1d, 1w, max	Default exchange
Limitless	1m, 1h, 1d, 1w	Short-term markets
Opinion	1m, 1h, 1d, 1w, max	Requires authentication

Usage

# Polymarket (default)
uv run python -m examples.slug_to_chart who-will-trump-nominate-as-fed-chair

# Limitless
uv run python -m examples.slug_to_chart --exchange limitless <slug>

# Opinion
uv run python -m examples.slug_to_chart --exchange opinion "search query"

Example Output

Test plan

• Tested with real Polymarket event slugs
• Verified chart generation with multiple outcomes
• Tested --top parameter for filtering outcomes
• Verified smart x-axis formatting for different date ranges
• Tested multi-line legend wrapping

🤖 Generated with Claude Code

[claude]

PR Review: Slug to Chart Feature

Summary

This PR adds a well-structured module for generating Bloomberg-style price charts from prediction market data. The code is clean and supports multiple exchanges (Polymarket, Limitless, Opinion).

---

Code Quality & Best Practices

Strengths

• Clean architecture: Well-separated concerns across modules (chart, fetcher, labels, CLI)
• Type hints: Good use of Literal types and type annotations
• Documentation: Clear docstrings and helpful README
• Error handling: Appropriate try-except blocks with user-friendly messages
• Smart defaults: Sensible fallbacks for unsupported intervals per exchange

Issues & Suggestions

1. Hardcoded "Polymarket" in chart footer (chart.py:123)

The footer always says "Source: Polymarket" even when using Limitless or Opinion exchanges.

Fix: Pass exchange name to generate_chart() and use it dynamically

2. Bare exception catches (fetcher.py:53, 121, 159)

Using bare except Exception: swallows all errors, making debugging difficult.

Recommendation: Catch specific exceptions or at least log the error

3. Magic numbers in chart.py (lines 50, 60-71, 104)

Hard-coded values like [-2, 102], date_range > 365 reduce maintainability.

Recommendation: Extract as named constants

4. Missing validation in main.py

No validation for negative or zero --top values, --min-price outside 0-1 range, or --fidelity < 1

---

Potential Bugs

1. Duplicate label collision (fetcher.py:156-157)

The duplicate handling appends outcome name, but this could still collide if multiple markets have the same question and outcome.

2. Empty price_data edge case (chart.py:57)

If price_data is empty, pd.concat() will raise an error. Add check before concatenation.

3. Binary market assumption (fetcher.py:128)

Assumes binary markets are always ["Yes", "No"] in that exact order. Other exchanges might use different conventions.

---

Performance Considerations

1. Sequential API calls (fetcher.py:149-160)

Price history is fetched sequentially for each outcome. For events with many outcomes, this could be slow.

Optimization: Use asyncio or ThreadPoolExecutor for parallel fetching.

2. Memory usage with large fidelity

Setting fidelity to very high values could consume significant memory. Add max limit validation.

---

Security Concerns

1. Path traversal risk (main.py:78) - CRITICAL

User-controlled slug is used in filename without proper sanitization. An attacker could potentially use special characters to write to unexpected locations.

Fix: Sanitize more thoroughly with regex to allow only safe characters

2. No authentication handling

README mentions "Opinion requires authentication" but code doesn't show how to configure credentials.

Recommendation: Document how to set up authentication per CLAUDE.md guideline #4.

---

Test Coverage - CRITICAL

No tests found for this feature.

Per CLAUDE.md guideline #5 ("Run and Debug yourself PROACTIVELY"), this module should include:

• Unit tests for extract_short_label() with various label formats
• Integration tests for chart generation
• Tests for edge cases (empty data, single outcome, etc.)
• Tests for error handling paths

Recommendation: Add tests/examples/test_slug_to_chart.py with comprehensive coverage.

---

Adherence to CLAUDE.md

Guideline	Status	Notes
1. Focused & clean	✅	Code is clean and well-organized
2. No unnecessary docs	✅	README is helpful, not bloated
3. Use UV	✅	Examples use uv run
4. Single source of truth	⚠️	Authentication setup unclear
5. Run and debug proactively	❌	No tests included

---

Additional Recommendations

1. Add --dry-run flag to preview what will be fetched without generating chart
2. Color scheme configurability: Allow users to pass custom color palette
3. Error recovery: Add retry logic for transient API failures
4. Progress indicators: Use rich library (already a dependency) for progress bars

---

Conclusion

This is a solid feature implementation with clean architecture and good multi-exchange support. The main concerns are:

1. Missing test coverage (critical per CLAUDE.md Create debugging frontend for trading strategies #5)
2. Path traversal security risk in filename generation
3. Hardcoded "Polymarket" source when using other exchanges

Recommendation: Request changes to add tests and fix security issue before merging.