grynn-fplot 0.3.4__tar.gz

grynn_fplot-0.3.4/.devcontainer/devcontainer.json

@@ -0,0 +1,28 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "Python 3",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"features": {
+		"ghcr.io/devcontainers-extra/features/uv:1": {}
+	},
+	// Mount .venv to a named volume to separate container and host environments
+	// Copy git config from host (not synced, just copy)
+	"mounts": [
+		"source=grynn_fplot_venv,target=${containerWorkspaceFolder}/.venv,type=volume",
+		"source=${localEnv:HOME}/.gitconfig,target=/tmp/host-gitconfig,type=bind,readonly"
+	],
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "sudo chown -R vscode:vscode ${containerWorkspaceFolder}/.venv && cp /tmp/host-gitconfig ~/.gitconfig || true",
+	// Configure tool-specific properties.
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"chat.tools.global.autoApprove": true
+			}
+		}
+	}
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

grynn_fplot-0.3.4/.github/copilot-instructions.md

@@ -0,0 +1,141 @@
+# Financial Plotting CLI Tool
+Financial plotting CLI tool (fplot) is a Python application that provides both a command-line interface and a web interface for plotting stock price data, drawdowns, and financial analysis. Built with Python 3.12+, matplotlib, FastAPI, and managed with uv package manager.
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Setup
+- Install uv package manager: `pip install uv`
+- Bootstrap the development environment: `make dev`
+  - Takes ~3 minutes for fresh setup. NEVER CANCEL. Set timeout to 10+ minutes.
+  - Creates virtual environment and installs all dependencies including scipy, matplotlib, pandas
+  - Subsequent runs take <1 second due to caching
+- Install CLI tool system-wide: `make install`
+  - Takes ~3 minutes for fresh install. NEVER CANCEL. Set timeout to 10+ minutes.
+  - Makes `fplot` command available globally via uv tool install
+
+### Testing and Quality
+- Run tests: `make test` or `uv run pytest`
+  - Takes ~6 seconds. Set timeout to 30+ seconds.
+  - All tests must pass before committing changes
+- Run linter: `make lint` or `uvx ruff check`
+  - Takes <1 second. Set timeout to 30+ seconds.
+  - Code must pass linting before committing changes
+- Clean build artifacts: `make clean`
+
+### Build and Development
+- Development setup: `make dev`
+  - NEVER CANCEL: Takes up to 3 minutes for fresh setup. Set timeout to 10+ minutes.
+  - Downloads and builds many packages including scipy (35MB+), matplotlib, pandas
+  - Subsequent runs are nearly instantaneous due to uv caching
+- The project has no separate "build" step - it's a Python package installed directly
+
+## Running the Application
+
+### CLI Tool
+- Basic usage: `fplot <ticker> [options]`
+- Examples:
+  - `fplot AAPL` - Plot Apple stock (last 1 year default)
+  - `fplot AAPL --since "last 30 days"` - Plot Apple stock for last 30 days
+  - `fplot AAPL,TSLA --since "mar 2023"` - Compare multiple tickers
+  - `fplot --version` - Show version
+  - `fplot --help` - Show help
+
+### Web Interface
+- Start web server: `uv run python grynn_fplot/serve.py`
+  - Runs on http://0.0.0.0:8000
+  - Provides interactive HTML interface with Plotly charts
+  - Hot reloads on code changes in development
+
+### Network Requirements
+- CLI and web server require internet access to download financial data from Yahoo Finance
+- Without internet, commands will fail with DNS resolution errors (expected behavior)
+- All core functionality works offline with sample data
+
+## Validation
+
+### Always Test After Making Changes
+1. **Run the full test suite**: `make test` - must pass completely
+2. **Run the linter**: `make lint` - must pass without issues
+3. **Test CLI functionality**:
+   - `fplot --version` should show current version
+   - `fplot --help` should show usage information
+   - If internet is available, test with real ticker: `fplot AAPL --since "last 7 days"`
+4. **Test web server**:
+   - Start server: `uv run python grynn_fplot/serve.py`
+   - Verify http://localhost:8000 loads the HTML interface
+   - Check that page contains "Stock Chart" and plotly references
+5. **Test core functionality with sample data**:
+   - All core functions (normalize_prices, calculate_drawdowns, calculate_cagr, etc.) work correctly
+   - Date parsing handles various formats correctly
+
+### Manual Validation Scenarios
+- **CLI Workflow**: `fplot --version` → `fplot --help` → verify output is correct
+- **Web Workflow**: Start server → verify homepage loads → check HTML contains expected UI elements
+- **Date Parsing**: Test with "last 30 days", "YTD", "last 6 months", "2 years ago"
+
+## Common Tasks
+
+### Key Project Structure
+```
+/home/runner/work/grynn_cli_fplot/grynn_cli_fplot/
+├── grynn_fplot/                 # Main package
+│   ├── cli.py                   # CLI command implementation
+│   ├── core.py                  # Core financial functions
+│   ├── serve.py                 # FastAPI web server
+│   └── index.html               # Web UI template
+├── tests/                       # Test suite
+├── Makefile                     # Build automation
+├── pyproject.toml               # Package configuration
+└── uv.lock                      # Dependency lock file
+```
+
+### Dependencies and External Libraries
+- **Package Manager**: uv (modern Python package manager)
+- **Core Dependencies**: click, matplotlib, pandas, yfinance, scikit-learn
+- **Web Dependencies**: fastapi, uvicorn  
+- **Dev Dependencies**: pytest, ruff, mypy
+- **External Git Dependencies**: 
+  - grynn-pylib from https://github.com/Grynn/grynn_pylib.git
+  - yfinance from https://github.com/ranaroussi/yfinance.git
+
+### Timing Expectations and Timeouts
+- **CRITICAL**: NEVER CANCEL builds or dependency installations - they may take 3+ minutes
+- **make dev**: 3 minutes fresh, <1 second cached. Timeout: 10+ minutes.
+- **make install**: 3 minutes fresh, <1 second cached. Timeout: 10+ minutes.  
+- **make test**: 6 seconds. Timeout: 30+ seconds.
+- **make lint**: <1 second. Timeout: 30+ seconds.
+- **CLI commands**: <5 seconds (plus network time for data). Timeout: 60+ seconds.
+- **Web server startup**: 3 seconds. Timeout: 30+ seconds.
+
+### Key Files to Monitor
+- Always check `pyproject.toml` when changing dependencies
+- Always check `grynn_fplot/core.py` when modifying financial calculations
+- Always check `grynn_fplot/cli.py` when changing CLI behavior
+- Always check `tests/test_fplot.py` when adding new functionality
+
+### Development Environment Details
+- **Python Version**: 3.12+ required
+- **Virtual Environment**: Managed by uv in `.venv/`
+- **Package Installation**: Uses `uv tool install` for global CLI access
+- **Code Style**: Enforced by ruff linter with 120 character line length
+- **Testing**: pytest-based with unittest-style test classes
+
+## Troubleshooting
+
+### Common Issues
+- **ModuleNotFoundError**: Run `make dev` to ensure all dependencies are installed
+- **DNS/Network Errors**: Expected when internet is limited - test with sample data instead
+- **Build timeouts**: Increase timeout values - builds legitimately take 3+ minutes fresh
+- **Import errors**: Use `uv run` prefix for all Python commands to use virtual environment
+
+### Build Problems
+- Clean and rebuild: `make clean && make dev`
+- Check uv version: `uv --version` (should be 0.8+)
+- Verify Python version: `python3 --version` (should be 3.12+)
+
+### Testing Without Network
+- CLI will show DNS errors but this is expected behavior
+- Use core functionality tests with sample data to verify logic
+- Web server will start but data endpoints will fail (expected)

grynn_fplot-0.3.4/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

grynn_fplot-0.3.4/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Build package
+        run: uv build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'push' || github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/grynn-fplot
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

grynn_fplot-0.3.4/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/

grynn_fplot-0.3.4/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-toml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.2
+    hooks:
+      - id: ruff
+        name: ruff-lint
+        args: ["--fix"]
+      - id: ruff-format
+        name: ruff-format
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        name: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: package.lock.json
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: Run tests
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true

grynn_fplot-0.3.4/.secrets.baseline

@@ -0,0 +1,127 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {},
+  "generated_at": "2025-09-19T21:03:14Z"
+}

grynn_fplot-0.3.4/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

grynn_fplot-0.3.4/Makefile

@@ -0,0 +1,70 @@
+.PHONY: install clean test lint format coverage dev bump pre-commit pre-commit-install build publish
+
+test:
+	uv run pytest
+
+pre-commit: dev
+	uvx pre-commit run --all-files
+
+pre-commit-install:
+	uvx pre-commit install
+
+work-tree-is-clean:
+	@# Check if the working directory is clean
+	@if [ -n "$$(git status --porcelain)" ]; then \
+		echo "Error: Working directory is not clean. Please commit or stash your changes first."; \
+		git status --short; \
+		exit 1; \
+	else \
+		echo "Working directory is clean."; \
+	fi
+
+bump: test pre-commit-install work-tree-is-clean
+	@# 1. Bump version using uv
+	@uv version --bump patch
+	@# 2. Commit changes (work tree was clean before, so only version files changed)
+	@new_version=$$(uv version --short) && \
+	git commit -am "Bump version => v$$new_version" && \
+	git tag "v$$new_version" && \
+	echo "Created git commit and tag v$$new_version"
+
+install:
+	uv tool install --upgrade-package "grynn_fplot" "grynn_fplot @ $$PWD"
+
+dev:
+	uv sync --all-extras
+
+coverage: dev
+	uv run pytest --cov=src/grynn_cli_fplot --cov-report=term-missing
+
+lint: dev
+	uvx ruff check
+
+format: dev
+	uvx ruff format
+
+clean:
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name "*.pyo" -delete
+	find . -type f -name "*.pyd" -delete
+	find . -type f -name ".coverage" -delete
+	find . -type d -name "*.egg-info" -exec rm -rf {} +
+	find . -type d -name "*.egg" -exec rm -rf {} +
+	find . -type d -name ".pytest_cache" -exec rm -rf {} +
+	find . -type d -name ".mypy_cache" -exec rm -rf {} +
+	find . -type d -name ".ruff_cache" -exec rm -rf {} +
+	rm -rf ./dist
+	rm -rf ./build
+	rm -rf ./venv
+	rm -rf ./.venv
+	rm -rf .coverage
+	rm -rf htmlcov
+
+build: clean
+	uv build
+
+publish: build
+	@echo "Publishing to PyPI..."
+	@echo "Note: For CI/CD, use GitHub Actions with trusted publishing instead."
+	uv publish

grynn_fplot-0.3.4/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: grynn-fplot
+Version: 0.3.4
+Summary: CLI tool for plotting financial data and analyzing options
+Project-URL: Homepage, https://github.com/Grynn/grynn_cli_fplot
+Project-URL: Issues, https://github.com/Grynn/grynn_cli_fplot/issues
+Project-URL: Repository, https://github.com/Grynn/grynn_cli_fplot
+Author-email: Grynn <vishal.doshi@gmail.com>
+License: MIT
+Keywords: cli,finance,options,plotting,stocks
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.12
+Requires-Dist: click~=8.1.7
+Requires-Dist: dateparser~=1.2.0
+Requires-Dist: fastapi~=0.115.0
+Requires-Dist: grynn-pylib
+Requires-Dist: ipywidgets>=8.1.5
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: mplcursors~=0.5.3
+Requires-Dist: mplfinance>=0.12.9
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: uvicorn~=0.32.0
+Requires-Dist: yfinance
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.29.5; extra == 'dev'
+Requires-Dist: ipython>=8.18.1; extra == 'dev'
+Requires-Dist: mypy>=1.14.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fplot - Financial Plotting & Options Analysis CLI
+
+[![PyPI version](https://img.shields.io/pypi/v/grynn-fplot.svg)](https://pypi.org/project/grynn-fplot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/grynn-fplot.svg)](https://pypi.org/project/grynn-fplot/)
+
+A command-line tool for plotting comparative stock price history and analyzing options contracts.
+
+## Installation
+
+### From PyPI
+
+```shell
+pip install grynn-fplot
+```
+
+Or with uv:
+
+```shell
+uv tool install grynn-fplot
+```
+
+### From Source
+
+For development, install the package in editable mode:
+
+```shell
+make dev
+```
+
+Or install locally:
+
+```shell
+make install  # Uses uv tool install .
+```
+
+## Usage
+
+### Stock Plotting
+
+```shell
+fplot <ticker> [--since <date>] [--interval <interval>]
+```
+
+Examples:
+
+- `fplot AAPL`
+- `fplot AAPL --since 2020`
+- `fplot AAPL,TSLA --since "mar 2023"`
+
+### Options Listing
+
+```shell
+fplot <ticker> --call                  # List call options (default: 6 months max)
+fplot <ticker> --put                   # List put options (default: 6 months max)
+fplot <ticker> --call --max 3m         # List calls with 3 month max expiry
+fplot <ticker> --put --all             # List all available put options
+fplot <ticker> --call --min-dte 1y     # List long-dated calls (min 1 year)
+fplot <ticker> --call --filter "dte>1y"  # Filter using time expressions
+```
+
+Examples:
+
+- `fplot AAPL --call`
+- `fplot TSLA --put --max 3m`
+- `fplot AAPL --call --all`
+- `fplot AAPL --call --min-dte 1y`  # Long-dated calls (1+ year)
+- `fplot AAPL --call --min-dte 6m`  # Calls with 6+ months to expiry
+- `fplot AAPL --call --filter "dte>10, dte<50"`  # 10-50 days to expiry
+- `fplot AAPL --call --filter "dte>1y"`  # Options with 1+ year to expiry
+
+The options output includes pricing, return metrics, implied leverage, and efficiency:
+```
+AAPL 225C 35DTE ($5.25, 18.5%, 19.0x, eff:45)
+AAPL 230C 35DTE ($3.10, 25.2%, 32.3x, eff:78)
+AAPL 235C 35DTE ($1.85, 35.1%, 54.1x, eff:92)
+```
+
+Format: `TICKER STRIKE[C|P] DAYS_TO_EXPIRY (price, return_metric, leverage, eff:percentile)`
+- For calls: return_metric is CAGR to breakeven
+- For puts: return_metric is annualized return
+- Leverage: Implied leverage (Ω = Δ × S/O) where Δ is Black-Scholes delta, S is spot price, O is option price
+  - Delta calculated using actual implied volatility from Yahoo Finance
+  - Shows "N/A" if implied volatility is not available
+  - Shows the percentage change in option value for a 1% change in stock price
+  - Example: 10x leverage means a 1% stock move results in ~10% option move
+- Efficiency: Percentile rank (0-100) of leverage/CAGR ratio
+  - Higher = better (high leverage with low required stock movement)
+  - 80+ = top 20% most efficient options
+  - Shows "N/A" if leverage or return unavailable
+
+**Expiry Filtering Options:**
+- `--max <time>`: Filter to show only options expiring within the specified time
+  - Examples: `3m` (3 months), `6m` (6 months), `1y` (1 year), `2w` (2 weeks), `30d` (30 days)
+  - Default: `6m` (6 months)
+- `--min-dte <time>`: Minimum days to expiry (useful for long-dated options)
+  - Accepts plain days or time expressions: `300`, `1y`, `1.5y`, `6m`, `2w`
+  - Examples: `--min-dte 1y` (1+ year), `--min-dte 6m` (6+ months)
+  - Note: Using `--min-dte` automatically enables `--all` behavior
+- `--all`: Show all available expiries (overrides `--max`)
+
+**Advanced Filtering with `--filter`:**
+
+The `--filter` option supports complex filter expressions with logical operators:
+
+- **Syntax:**
+  - Comma (`,`) represents AND operation
+  - Plus (`+`) represents OR operation
+  - Comparison operators: `>`, `<`, `>=`, `<=`, `=`, `!=`
+  - Parentheses for grouping: `(expr1 + expr2), expr3`
+
+- **Filter Fields:**
+  - `dte`: Days to expiry
+  - `volume`: Option volume
+  - `price`: Last price
+  - `return`, `ret`, `ar`: Return metric (CAGR for calls, annualized return for puts) - all aliases work
+  - `strike_pct`, `sp`: Strike percentage above/below spot (positive = above spot, negative = below spot)
+  - `lt_days`: Days since last trade (useful for filtering stale options)
+  - `leverage`, `lev`: Implied leverage (Ω = Δ × S/O, using Black-Scholes delta)
+  - `efficiency`, `eff`: Efficiency percentile (leverage/CAGR ratio, 0-100 scale)
+
+- **Examples:**
+  - `--filter "dte>300"` - Options with more than 300 days to expiry
+  - `--filter "dte>10, dte<50"` - Options between 10-50 days (AND operation)
+  - `--filter "dte<30 + dte>300"` - Short-term OR long-dated (OR operation)
+  - `--filter "sp>5, sp<15"` - Strikes 5-15% above current spot price
+  - `--filter "(dte>300 + dte<30), sp>5"` - Complex nested filters
+  - `--filter "volume>=100"` - High volume options
+  - `--filter "lt_days<=7"` - Options traded within last 7 days
+  - `--filter "ar>50"` - Annualized return > 50%
+  - `--filter "leverage>10"` - High leverage options (10x or more)
+  - `--filter "lev>5, lev<20"` - Moderate leverage options (5x-20x)
+  - `--filter "efficiency>80"` - Top 20% most efficient options
+  - `--filter "eff>60, dte<60"` - Above-average efficiency with <60 days to expiry
+
+- **Time Values:**
+  - DTE-style expressions: `1y` (365 days), `6m` (180 days), `2w` (14 days)
+  - Duration expressions: `2d15h`, `30m`, `1d` (converted to hours for duration fields)
+  - Examples:
+    - `--filter "dte>1y"` - Options with more than 1 year to expiry
+    - `--filter "dte>6m"` - Options with more than 6 months to expiry
+    - `--filter "lt_days<=7"` - Options traded in the last week
+
+Options data is cached for 1 hour to improve performance and reduce API calls.
+
+## TODO
+
+- fplot --call | fzf lets you select a call; once a call is selected it should be possible to plot a chart for it (yfinance provides price history for option identifiers)
+- need more examples of usage with fzf to pick a call
+- use grynn_pylib to download options (does it have identifiers that can be used to fetch price history?)