Imported from guyru/limit_price_calculator (AGENTS.md). Install upstream with npx skills add guyru/limit_price_calculator. Copyright stays with the author.

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

A Python CLI tool that calculates optimal buy/sell limit prices based on historical stock price movements using empirical distributions of N-day drawdowns and rallies.

Running the Script

This project uses uv for dependency management. Always run Python scripts with:

# Analyze CSV data
uv run python limit_price_calculator.py data.csv -w 5 -p 0.7

# Fetch from Yahoo Finance
uv run python limit_price_calculator.py AAPL -w 5 -p 0.7 --fetch

# Fetch from TASE (Tel Aviv Stock Exchange) - auto-detected by 6-8 digit security ID
uv run python limit_price_calculator.py 01159235 -w 5 -p 0.7 -y 2

# Sensitivity table
uv run python limit_price_calculator.py data.csv -t

Architecture

The tool consists of two main modules:

limit_price_calculator.py

Main CLI script that performs statistical analysis on OHLC (Open, High, Low, Close) price data:

1. Data ingestion: Load from CSV, fetch via yfinance API, or fetch from TASE API
   • Auto-detects TASE security IDs (6-8 digit numbers)
   • Displays prices in appropriate currency (₪ for TASE, $ for others)
2. Forward-looking analysis: Uses rolling N-day windows to calculate:
   • Drawdowns (for buy limits): minimum low reached after each close
   • Rallies (for sell limits): maximum high reached after each close
3. Percentile-based pricing: Uses empirical distributions to find prices with specified execution probability
   • Example: 70% execution probability = 30th percentile of historical movements

Key Functions

• calculate_drawdowns() / calculate_rallies(): Core rolling window analysis
• get_buy_limit_price() / get_sell_limit_price(): Apply percentile-based pricing
• analyze_price_data(): Orchestrates full analysis pipeline
• sensitivity_table(): Matrix of results across different probabilities and windows
• is_tase_security_id(): Detects TASE security IDs (6-8 digit numbers)
• fetch_tase_data(): Thin wrapper around tasekit.download() that normalises the result (maps adjusted close → Close, drops the raw Close column)

TASE data fetching

TASE data is fetched via the tasekit library. fetch_tase_data() calls tasekit.download(security_id, years=years) and renames the Adj Close column to Close so the rest of the pipeline can treat it uniformly.

CSV Format

Expects standard OHLC CSV with columns: Date, Open, High, Low, Close, Volume (case-insensitive, handles variations like "Adj Close")

Sanity Tests

After every change, run these sanity checks before finishing.

Required automated test suite

Run from the repository root:

uv run pytest

Integration tests (live TASE API) are excluded by default via addopts = "-m 'not integration'" in pyproject.toml. To run them explicitly:

uv run pytest -m integration

Optional manual smoke checks

If you need to verify the CLI output manually, run:

# Basic analysis should succeed
uv run python limit_price_calculator.py tests/data/output.csv -w 5 -p 0.7

# Sensitivity table should succeed
uv run python limit_price_calculator.py tests/data/output.csv -t

# Percentile mode should succeed with explicit and implicit prices
uv run python limit_price_calculator.py tests/data/output.csv --price-percentile 33000
uv run python limit_price_calculator.py tests/data/output.csv --price-percentile

At minimum, visually confirm this invariant for percentile output:

• A very low reference price should show a very small Higher Than percentage and a very large Lower Than percentage.
• A very high reference price should show the opposite.