Metadata-Version: 2.4
Name: eventedge
Version: 0.1.1
Summary: A zero-dependency Python toolkit for event-contract and prediction-market research.
Author: creampig666
License: MIT
Project-URL: Homepage, https://github.com/creampig666/eventedge
Project-URL: Issues, https://github.com/creampig666/eventedge/issues
Keywords: prediction-markets,event-contracts,polymarket,quant,arbitrage,kelly
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# EventEdge

[![CI](https://github.com/creampig666/eventedge/actions/workflows/ci.yml/badge.svg)](https://github.com/creampig666/eventedge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

EventEdge is a zero-dependency Python toolkit for event-contract and
prediction-market research. It focuses on transparent math for binary market
quotes, fee/slippage-aware expected value, Kelly sizing, watchlist reporting,
resolution-rule checklists, and no-arbitrage checks for related events.

The first release is deliberately small but useful: deterministic calculations,
a CLI, CSV scanning, Markdown reports, resolution-rule validation, examples, 
and tests. The goal is to become a practical research helper for maintainers,
analysts, and students who need reproducible tooling around Polymarket-style and
event-contract-style markets.

## Features

- Evaluate YES/NO positions with fair probability, fees, slippage, and position
  size.
- Compute probability edge, expected value, expected ROI, break-even probability,
  win/loss payoff, expected profit, and capped Kelly fraction.
- Scan and rank a CSV watchlist for fee-adjusted opportunities.
- Generate Markdown reports for research notes or pull requests.
- Validate resolution-rule metadata and flag ambiguous wording before a market
  enters a research watchlist.
- Check YES+NO complement bundles and exhaustive outcome bundles for
  guaranteed-profit conditions.
- Check conjunction, union, and implication bounds between related event
  markets.
- Accept decimal, percent, and cent-style probabilities such as `0.42`, `42%`,
  and `42c`.
- Run fully offline with the Python standard library.

## Install

From a local clone:

```powershell
python -m pip install -e .
```

No third-party packages are required.

## CLI Examples

Evaluate a YES position:

```powershell
eventedge evaluate --market-id btc-100k --yes-price 0.42 --fair-yes 0.50 --size-usd 100 --fee-bps 25 --slippage-bps 10
```

Evaluate a NO position:

```powershell
eventedge evaluate --market-id eth-etf --yes-price 0.64 --fair-yes 0.55 --side NO --size-usd 100
```

Scan a CSV watchlist:

```powershell
eventedge scan-csv examples/markets.csv --min-edge 0.03 --fee-bps 25 --slippage-bps 10
```

Generate a Markdown watchlist report:

```powershell
eventedge report-csv examples/markets.csv --min-edge 0.03 --output watchlist-report.md
```

Check a binary YES+NO complement bundle:

```powershell
eventedge complement --yes-price 47c --no-price 50c
```

Check an exhaustive outcome bundle:

```powershell
eventedge bundle "candidate-a=0.31,candidate-b=0.28,candidate-c=0.36"
```

Check conjunction bounds:

```powershell
eventedge bounds --p-a 0.60 --p-b 0.55 --p-ab 0.40
```

Check union bounds:

```powershell
eventedge union --p-a 60% --p-b 55% --p-a-or-b 70%
```

Generate a resolution-rule checklist:

```powershell
eventedge resolution-check --market-id btc-100k --title "BTC above 100k" --rule-text "Resolves YES if Coinbase BTC-USD daily close is greater than 100000." --data-source "Coinbase BTC-USD daily close" --source-url "https://example.com/btc-usd" --metric daily_close --resolution-datetime 2026-12-31T23:59:00+00:00 --timezone UTC --comparator ">" --threshold 100000 --markdown
```

## Python Example

```python
from eventedge import FeeModel, read_quotes_csv, evaluate_quotes, rank_evaluations

quotes = read_quotes_csv("examples/markets.csv")
results = evaluate_quotes(quotes, fee_model=FeeModel(fee_bps=25, slippage_bps=10))
ranked = rank_evaluations(results, min_edge=0.03)

for result in ranked:
    print(result.market_id, result.expected_profit, result.kelly_fraction)
```

## CSV Format

`scan-csv` expects:

```csv
market_id,yes_price,fair_yes,side,size_usd
btc-100k,0.42,0.50,YES,100
eth-etf,0.64,0.55,NO,100
```

`side` and `size_usd` are optional. Defaults are `YES` and `100`. `group` and
`notes` columns are accepted and reserved for future report enrichment.

## Formula Notes

The core payoff model is documented in [docs/FORMULAS.md](docs/FORMULAS.md).
Short version: a contract bought at cost `c` pays `1` if the selected side is
true and `0` otherwise, so expected value per share is `p - c`. The capped Kelly
fraction used here is

```text
f* = max(0, min(cap, (p - c) / (1 - c)))
```

where `p` is the researcher's fair probability and `c` is the fee-adjusted entry
cost.

## Resolution Rule Notes

Resolution risk is documented in
[docs/RESOLUTION_CHECKLIST.md](docs/RESOLUTION_CHECKLIST.md). EventEdge checks
that a market has an explicit data source, metric, threshold, timestamp,
timezone, and rule text, then flags ambiguous words such as `official`,
`significant`, `around`, and `reported`.

## Project Scope

EventEdge is research infrastructure, not an execution bot. It does not place
orders, hold API keys, or promise profitability. Its job is to make event-market
math auditable and easy to test.

Near-term roadmap:

- Add optional public-data connectors behind explicit extras.
- Add notebook examples for prediction-market research.
- Add richer arbitrage primitives for related event trees.
- Add richer Markdown reports with grouped watchlists and assumptions.

## Development

Run tests:

```powershell
python -m unittest discover -s tests
```

Run the CLI from source without installing:

```powershell
$env:PYTHONPATH = "src"
python -m eventedge.cli evaluate --market-id demo --yes-price 0.42 --fair-yes 0.50
```

## Contributing

Issues and pull requests are welcome once the repository is public. Useful
contributions include test cases for market math, new no-arbitrage checks,
example datasets, and documentation improvements.

## License

MIT.
