Metadata-Version: 2.4
Name: brain-sentiment
Version: 0.1.0
Summary: Analyst revisions, PEAD, and sentiment alpha generation engine for WorldQuant BRAIN.
Author: Xtley001
License-Expression: MIT
Project-URL: Homepage, https://github.com/Xtley001/brain-libraries
Project-URL: Repository, https://github.com/Xtley001/brain-libraries
Project-URL: Documentation, https://github.com/Xtley001/brain-libraries
Project-URL: Bug Tracker, https://github.com/Xtley001/brain-libraries/issues
Keywords: worldquant,brain,alpha,quantitative-finance,sentiment-analysis,earnings-revisions,pead,factor-investing,algorithmic-trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: brain-alpha-core>=0.1.0
Requires-Dist: brain-store>=0.1.0
Requires-Dist: brain-decorrelator>=0.1.0
Requires-Dist: requests>=2.31
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: sim
Requires-Dist: wqb>=0.2.5; extra == "sim"
Dynamic: license-file

# brain-sentiment

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

[![CI](https://img.shields.io/github/actions/workflow/status/Xtley001/brain-libraries/ci.yml?branch=main)](https://github.com/Xtley001/brain-libraries/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
[![PyPI](https://img.shields.io/pypi/v/brain-sentiment)](https://pypi.org/project/brain-sentiment/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

`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](./docs/whitepaper.md).

## Installation

```bash
pip install brain-sentiment
```

## Quickstart

```python
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

| Archetype | Institutional Literature | Economic Hypothesis | ValueScore |
|---|---|---|:---:|
| **SUE Drift** | Bernard & Thomas (1989) | Standardized quarterly earnings surprises drift predictably for 60-90 days | **8.0** |
| **Revision Breadth** | Chan et al. (1996) | Net fraction of upward vs downward analyst revisions leads momentum | **8.0** |
| **Dispersion Arbitrage**| Diether et al. (2002) | Equities with high sell-side forecast disagreement suffer optimistic overpricing | **8.0** |
| **Revision Divergence** | Livnat & Mendenhall (2006) | Accelerating upward revisions lagging equity price provide reliable forward drift | **8.0** |

## 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

```bash
pytest tests/ -v
```

## Security

Report vulnerabilities per [SECURITY.md](SECURITY.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

Released under the [MIT License](../LICENSE). Maintained by [Xtley001](https://github.com/Xtley001).
