The Problem

Algorithmic traders need programmatic access to ICT‑style “smart‑money” indicators (fair‑value gaps, order blocks, etc.). Existing Python libraries rarely implement the full ICT suite, forcing developers to recreate logic from scattered blog posts, which is error‑prone and hard to validate.

What This Does

The repository ships a single package smartmoneyconcepts that exposes the ICT indicator set through functions in smartmoneyconcepts/smc.py. Importing smc gives access to fvg, swing_highs_lows, bos_choch, ob, liquidity, previous_high_low, sessions, and retracements. Test helpers in tests/generate_gif.py illustrate how to overlay these signals on candlestick plots.

The package is built with the classic setup.py installer, so pip install . or the published PyPI wheel installs the smc module and its public API.

How It Is Wired

Execution starts at the entry point setup.py (install time) which registers the smartmoneyconcepts distribution. At runtime a user imports smartmoneyconcepts.smc and calls one of the indicator functions.

  • Core hub – smartmoneyconcepts/smc.py defines 13 public functions and one class. It is the sole internal provider; every test and helper imports from it.
  • Primary call flow –
  • swing_highs_lows is invoked from 7 places (most often by the higher‑level indicators).
  • fvg, ob, bos_choch, liquidity, previous_high_low, sessions, and retracements each call swing_highs_lows or share its output, forming a thin dependency tree.
  • Tests – tests/unit_tests.py imports smartmoneyconcepts.smc and exercises each indicator against CSV fixtures under tests/test_data.
  • Visualization helper – tests/generate_gif.py reads the same CSVs, calls the indicator functions, and writes a GIF (tests/test.gif). It opens the output file without a context manager, which could leak a file handle on error.

No circular imports appear; the internal import graph consists of 5 modules with 3 edges, giving a stable, low‑instability architecture. The only external I/O is reading CSV fixtures and writing the GIF in the test helper.

How To Use It

# Clone and install the package
git clone https://github.com/moses-y/smart-money-concepts
cd smart-money-concepts
pip install .
# Example usage in a trading script
import pandas as pd
from smartmoneyconcepts import smc

ohlc = pd.read_csv('path/to/EURUSD_15M.csv')
fvg_res = smc.fvg(ohlc, join_consecutive=False)
swing = smc.swing_highs_lows(ohlc, swing_length=50)
bos, choch = smc.bos_choch(ohlc, swing, close_break=True)

No additional configuration files or environment variables are required; the functions operate on a pandas DataFrame with columns ['open','high','low','close','volume'].

Real‑World Use

A quant team can embed smc into a back‑testing pipeline: load historical OHLC data, compute fvg and ob, feed the binary signals into a machine‑learning model, and generate trade‑execution rules that react to detected order‑block breakouts. The library’s pure‑Python design keeps the stack simple and portable across Linux, macOS, and Windows.

Code Health & Issues

  • HIGH – CI never runs the test suite (.github/workflows/unittest.yaml lacks a test step). Add a pytest step to the existing workflow.
  • MEDIUM – GITHUB_TOKEN permissions are not scoped; declare permissions: contents: read to enforce least‑privilege.
  • MEDIUM – Large binary tests/test.gif (7.3 MiB) should be moved to Git LFS or external storage.
  • MEDIUM – Checkout retains the token; set persist-credentials: false and supply a token only where needed.
  • LOW – No job timeout is set; add timeout-minutes to prevent runaway runs.
  • HIGH (cognitive load) – smartmoneyconcepts/smc.py and tests/generate_gif.py contain nesting depth 8, making control flow hard to follow. Refactor with early returns or guard clauses.
  • MEDIUM (oversized file) – smc.py spans 798 lines; consider splitting into modules by logical group (e.g., fvg.py, swing.py, structure.py).
  • MEDIUM (resource safety) – tests/generate_gif.py opens files without a context manager; wrap with with open(...) as f:.

No missing license (present) and no committed secrets were detected.

The Bottom Line

smartmoneyconcepts delivers a functional, single‑file implementation of ICT indicators that can be dropped into Python trading pipelines with minimal setup. The codebase is small but suffers from deep nesting, an oversized core module, and incomplete CI configuration. Teams comfortable refactoring for readability and tightening the CI pipeline will find the indicator set useful; otherwise the library may require additional engineering effort before production use.