# MarketPilot AI — Cross-Model Trading Research & Agent Skills

MarketPilot AI combines 17 cross-model agent skills with a Python research engine for market scans, news and filings, entry/exit plans, position sizing, risk checks, scenario replay, walk-forward testing, alerts, journaling and portfolio review. Built for ChatGPT, Claude, Grok, Gemini and Codex; transparent, testable and paper-only; traders decide.

![MarketPilot AI](docs/assets/hero.svg)

**From market discovery to risk review—one transparent, human-led workflow across models.**

[Watch the 10-second overview](docs/assets/marketpilot-overview.mp4) · [Open the GitHub Pages site](index.html) · [Read the architecture](docs/ARCHITECTURE.md)

![Workflow preview](docs/assets/workflow-preview.gif)

## The 11 core workflows

| Skill | Purpose |
|---|---|
| Scanner | Daily setups, opening-range breakouts and a filtered public symbol universe |
| News | Headline tags, timestamps and optional SEC filing metadata |
| Entry | Closed-bar trigger checks and stale-data guard |
| Exit | ATR-based stop and target planning |
| Time Machine | Historical replay plus seeded OHLC bootstrap scenarios |
| Risk | Exact-order PASS/BLOCK checks and fingerprinting |
| Budget | Whole-share sizing from risk, fees, slippage and position caps |
| Broker | Local paper ledger only—no live broker connection or order routing |
| Alerts | One-shot, manually checked price alerts |
| Analyst | SEC XBRL metrics and filing metadata |
| Disclosures | U.S. House PTR index, document retrieval and cautious text extraction |

**Plus six research modules:** Market Regime, Strategy Lab (chronological walk-forward), Portfolio Exposure, Data Quality, Trade Journal and Post-Trade Review.

## Quick start

Python 3.10+ is required. Runtime dependencies: none (Python standard library only).

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e .

# Offline tests
python -m compileall -q src
PYTHONPATH=src python -m unittest discover -s tests -v

# Example deterministic calculations
marketpilot budget --equity 10000 --risk-pct 0.5 --entry 100 --stop 98
marketpilot risk --symbol DEMO --quantity 5 --entry 100 --stop 98 --target 104 --equity 10000 --quote-age-seconds 5
```

For an end-to-end offline demo, use `examples/synthetic_ohlcv.csv`; it is generated synthetic data, not historical market data. Regenerate it with `python examples/generate_synthetic_data.py`. To install reusable skills locally, run `python scripts/install_skills.py all` for Claude Code plus the shared Agent Skills path (Codex, Grok and Gemini CLI), or choose a dedicated `claude`, `codex`, `grok` or `gemini` target. A skills-only OpenAI plugin manifest is included for hosts that support this package format. Gemini Apps can import individual skills, with current script/network limits. See [model compatibility](docs/MODEL_COMPATIBILITY.md).

## What it can—and cannot—replace

MarketPilot AI consolidates common scanner, alert, journal, sizing, risk-check and backtest workflows that are often spread across paid tools. It does **not** replace exchange-grade real-time feeds, institutional research terminals, a brokerage, tax software, or regulated financial advice. Yahoo chart/RSS endpoints are unofficial and may lag or throttle; SEC and House data are public records with their own limits.

## Safety and evidence

- **No live trading:** the broker module only records locally confirmed simulated tickets.
- **No secrets in prompts or Git:** API credentials are not required for core features; SEC identity is read from a local `SEC_USER_AGENT` environment variable.
- **No fabricated results:** the included tests use deterministic synthetic fixtures. No profitability or accuracy claim is made.
- **Simulation is not prediction:** same-bar stop/target ambiguity resolves conservatively to the stop; bootstrap assumptions and sample limitations are reported.

Read the [data-source limits](docs/DATA_SOURCES.md), [safety model](docs/SAFETY.md), and [model compatibility guide](docs/MODEL_COMPATIBILITY.md) before use. Contributors can follow the [testing guide](docs/TESTING.md) and [contribution guidelines](CONTRIBUTING.md).

## License and credit

Original MarketPilot AI materials are licensed CC BY-NC 4.0. This is a non-commercial Creative Commons license, not an OSI-approved open-source software license and is not specifically designed for software; see [LICENSE](LICENSE) for the terms. The independent project was informed by the workflow concepts in [Jake Schincariol's day-trader-skill](https://github.com/Jakeschincariol/day-trader-skill), which is MIT-licensed. Full attribution is in [NOTICE.md](NOTICE.md).