Metadata-Version: 2.4
Name: whytrend
Version: 0.1.0
Summary: Open Source Framework for Explainable Time Series Analysis
Project-URL: Homepage, https://github.com/AlexProvatorov/WhyTrend
Project-URL: Documentation, https://github.com/AlexProvatorov/WhyTrend#readme
Project-URL: Repository, https://github.com/AlexProvatorov/WhyTrend
Project-URL: Issues, https://github.com/AlexProvatorov/WhyTrend/issues
Author-email: Alexander Provatorov <sasha.provatorov@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: anomaly-detection,changepoint,explainability,llm,time-series
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: prophet>=1.1; extra == 'all'
Requires-Dist: pyarrow>=15.0; extra == 'all'
Requires-Dist: pytrends>=4.9; extra == 'all'
Requires-Dist: ruptures>=1.1; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
Requires-Dist: pyarrow>=15.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pytrends>=4.9; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: parquet
Requires-Dist: pyarrow>=15.0; extra == 'parquet'
Provides-Extra: prophet
Requires-Dist: prophet>=1.1; extra == 'prophet'
Provides-Extra: ranking
Requires-Dist: sentence-transformers>=3.0; extra == 'ranking'
Provides-Extra: ruptures
Requires-Dist: ruptures>=1.1; extra == 'ruptures'
Provides-Extra: trends
Requires-Dist: pytrends>=4.9; extra == 'trends'
Description-Content-Type: text/markdown

# WhyTrend

[![CI](https://github.com/AlexProvatorov/WhyTrend/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexProvatorov/WhyTrend/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/whytrend.svg)](https://pypi.org/project/whytrend/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

**Open Source Framework for Explainable Time Series Analysis**

WhyTrend detects anomalies, change points, and trend shifts in time series — then automatically explains *why* they happened using external context and LLMs.

If this project is useful to you, consider giving it a **star** on GitHub — it helps others discover the project. Forks and pull requests are welcome.

## Features

- Fluent `Pipeline` API for source → detection → collection → ranking → explanation
- Pluggable sources, detectors, collectors, rankers, and LLM providers
- Structured `Report` output (JSON and Markdown)
- Async collectors and LLM calls
- Works offline with `MockLLMProvider` and local models via `OllamaExplainer`

## Installation

### From PyPI

```bash
pip install whytrend
```

### Optional extras

```bash
pip install "whytrend[openai]"      # OpenAI API
pip install "whytrend[trends]"      # Google Trends
pip install "whytrend[prophet]"     # Prophet detector
pip install "whytrend[ranking]"     # Embedding ranker
pip install "whytrend[all]"           # everything
```

### From source (development)

```bash
git clone https://github.com/AlexProvatorov/WhyTrend.git
cd WhyTrend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Quickstart (CSV, no API keys)

```python
from whytrend import (
    BM25Ranker,
    CSVSource,
    LLMExplainer,
    MockLLMProvider,
    Pipeline,
    ZScoreDetector,
)

pipeline = (
    Pipeline(window_days=3)
    .add_source(CSVSource("your_series.csv", keyword="Python"))
    .add_detector(ZScoreDetector(threshold=1.0))
    .add_ranker(BM25Ranker(top_k=5))
    .add_explainer(LLMExplainer(MockLLMProvider()))
)

report = pipeline.run()
print(report.executive_summary)
print(report.to_markdown())
```

CSV must have `timestamp` and `value` columns. When developing from a clone, you can use
`tests/fixtures/python_interest.csv` as sample data.

Run the full demo (requires a repository clone):

```bash
git clone https://github.com/AlexProvatorov/WhyTrend.git
cd WhyTrend
pip install -e ".[dev]"
python examples/mvp_demo.py
```

## Production-style example

```python
from whytrend import (
    GoogleTrends,
    OpenAIExplainer,
    Pipeline,
    ProphetDetector,
)
from whytrend.collectors import HackerNewsCollector, WikipediaCollector
from whytrend.rankers import BM25Ranker

pipeline = (
    Pipeline()
    .add_source(GoogleTrends("Python"))
    .add_detector(ProphetDetector())
    .add_collector(HackerNewsCollector())
    .add_collector(WikipediaCollector())
    .add_ranker(BM25Ranker())
    .add_explainer(OpenAIExplainer())  # OPENAI_API_KEY env var or api_key="..."
)

report = pipeline.run()
print(report.executive_summary)
```

Use `OllamaExplainer(model="llama3.2")` for a local LLM instead of OpenAI.

For OpenAI, pass a key explicitly or set the environment variable:

```python
OpenAIExplainer(api_key="sk-...")
# or: export OPENAI_API_KEY=sk-...
```

## Architecture

```
Source → Detector → Event Builder → Collectors → Ranker → Explainer → Report
```

## Roadmap

Core MVP is in place. Next focus: **integrations and ecosystem**.

### v0.2 — More collectors
- [ ] Google News
- [ ] Reddit
- [ ] GitHub Releases
- [ ] RSS / Stack Overflow

### v0.3 — More detectors
- [ ] Ruptures (change-point)
- [ ] River / streaming detectors

### v0.4 — More LLM providers
- [ ] Anthropic, Gemini, DeepSeek
- [ ] Azure OpenAI, OpenRouter

### v0.5 — Reports and DX
- [ ] HTML / PDF reports
- [ ] CLI (`whytrend analyze ...`)
- [ ] Plugin registry (entry points)

Track progress in [GitHub Issues](https://github.com/AlexProvatorov/WhyTrend/issues).

## Development

Requires a repository clone:

```bash
git clone https://github.com/AlexProvatorov/WhyTrend.git
cd WhyTrend
pip install -e ".[dev]"
ruff check src tests
mypy src/whytrend
pytest
```

## Author

**Alexander Provatorov** — [GitHub @AlexProvatorov](https://github.com/AlexProvatorov)

## License

Licensed under the [Apache License, Version 2.0](LICENSE).
