brain-sentiment

Analyst revisions, PEAD, and sentiment alpha generation engine for WorldQuant BRAIN.

brain_sentiment generates quantitative equity alphas on WorldQuant BRAIN sentiment and revision datasets (sentiment1, sentiment2, ValueScore: 8.0). It codifies Post-Earnings Announcement Drift (PEAD), Standardized Unexpected Earnings (SUE), and analyst revision diffusion into turnover-controlled (< 12%) Fast Expressions with sub-industry neutralization. For institutional literature citations and mathematical derivations, see the whitepaper.

Installation

pip install brain-sentiment

Quickstart

from brain_sentiment import SentimentAlphaEngine

engine = SentimentAlphaEngine()

# Generate 5 turnover-controlled sentiment candidates
candidates = engine.generate_candidates(count=5)

for cand in candidates:
    print(f"[{cand.tags}] {cand.expression}\n")

Core Sentiment Archetypes

Architecture

brain_sentiment/
├── brain_sentiment/
│   ├── __init__.py        # Public re-exports (SentimentAlphaEngine, SentimentCandidate)
│   ├── data/
│   │   └── catalog.json   # Live BRAIN sentiment field catalog
│   ├── catalog.py         # SentimentCatalog field groupings & loader
│   ├── archetypes.py      # Quantitative sentiment strategy descriptors
│   ├── dedup.py           # AST expression deduplicator (delegates to brain_core)
│   ├── generator.py       # Candidate generation engine
│   ├── py.typed           # PEP 561 typing marker
│   └── strategies/        # Modular strategy implementations (pead, revision_breadth)
├── tests/                 # Unit tests covering catalog, engine, strategies, templates
└── docs/
    ├── API.md             # Complete API specification
    └── whitepaper.md      # Quantitative sentiment theory & PEAD dynamics

Testing

pytest tests/ -v

Security

Report vulnerabilities per SECURITY.md.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

Released under the MIT License. Maintained by Xtley001.