Fyrefly

A quant-based library to compute mathematical operations, run SQL queries, get AI-powered insights, and visualize your data.

Installation

pip install fyrefly

Usage — Math functions

from fyrefly import add, mul, div, mod, diff

add(5, 4, 6, 10)     # 25
mul(5, 4, 6, 10)     # 1200
div(100, 5, 2)       # 10.0
mod(17, 5)           # 2
diff(10, 3, 2)       # 5

Each function accepts any number of arguments:

add(1)                # 1
add(1, 2, 3, 4, 5)    # 15
mul()                  # 1 (identity)
diff(10, 3)            # 7

Usage — Quant formulas

from fyrefly import si, ci, si_ci_diff, profit, loss, ap, gp, hp, avg, avgc, mode, median, hyp, slope, centroid

# Interest
si(1000, 2, 5)                    # 100.0   (Simple Interest: p, n, r)
ci(1000, 2, 10)                   # 210.0   (Compound Interest, annual by default)
ci(1000, 2, 10, "semi-annual")    # 215.5   (compounded twice a year)
si_ci_diff(1000, 10, 2)           # 10.0    (CI - SI, supports n = 2 or 3 only)

# Profit / Loss — smart-detects if you called the wrong one
profit(120, 100)         # 20
profit(120, 100, "%")    # (20, 20.0)   value + percentage
loss(80, 100)             # 20
loss(80, 100, "%")        # (20, 20.0)
profit(80, 100)           # raises: "this is a LOSS, not a profit. Use loss(80, 100) instead."

# Sequences: AP, GP, HP
ap(2, 3, 4)          # [2, 5, 8, 11]        full sequence
ap.tn(2, 3, 4)       # 11                    nth term
ap.sn(2, 3, 4)       # 26.0                  sum of first n terms

gp(2, 3, 4)          # [2, 6, 18, 54]
gp.tn(2, 3, 4)       # 54
gp.sn(2, 3, 4)       # 80.0

hp(2, 3, 4)          # [2.0, 0.2857..., 0.1538..., 0.1052...]
hp.tn(2, 3, 4)       # 0.10526315789473684
hp.sn(2, 3, 4)       # 2.5448235974551765

# Averages, mode, median
avg(10, 12, 13)          # 11.666666666666666        plain average of individual numbers
avgc(5, 3, 10, 2)         # 7.0                        weighted avg from (value, count) pairs
mode(1, 1, 2, 2)          # [1, 2]
median(1, 2, 3, 4)        # 2.5

# Geometry
hyp(3, 4)                              # 5.0
slope((1, 2), (3, 4))                  # 1.0
centroid((1, 2), (3, 2), (4, 5))       # (2.6666666666666665, 3.0)

Usage — Data functions

from fyrefly import load, loadh, loadc, loads, sql, xtract, clean

c = load("data.csv")                 # loads a CSV/Excel/Google Sheet, previews it
loadh(c)                             # preview column headers
loadc(c)                             # preview record count
loads(c)                             # preview schema (columns + datatypes)

c = clean(c)                         # dedupe, strip whitespace, standardize column names

d = sql("select * from c where age > 30")   # run ANY SQL query on loaded data
xtract(d)                                    # export the result to CSV
xtract(sql("select * from c"), filename="all.csv")  # chained form also works

Note: for Google Sheets, the sheet must be shared as "Anyone with the link – Viewer" for load() to access it.

Usage — AI functions (require an API key)

from fyrefly import ask, insights

c = load("sales.csv")

# Ask questions in plain English — converted to SQL and run automatically
ask(c, "what were total sales by region last quarter?", api_key="AIza...")

# Query across multiple datasets (e.g. a join) — scales to any count
ask((c, d), "who are our top customers by total sales?", api_key="AIza...")
ask((c, d, e), "...", api_key="AIza...")

# Get a plain-English summary of a dataset
insights(c, api_key="AIza...")

The provider (Anthropic, OpenAI, Gemini, or any OpenAI-compatible API like Groq/Mistral) is auto-detected from your API key's format — you usually don't need to specify it. API keys can also be set via environment variables instead of passing them directly: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY.

Transient provider errors (rate limits, temporary server issues) are retried automatically with backoff before giving up.

⚠️ Never commit an API key into a script you push to GitHub. Use an environment variable instead:

export GEMINI_API_KEY="AIza..."

ask(c, "what were total sales by region?")   # picked up automatically from the env var

Usage — Visualization (no AI, no API key needed)

from fyrefly import viz

viz(c)                                # auto -> correlation heatmap
viz(c, "department")                  # auto -> bar chart of counts
viz(c, "age")                         # auto -> histogram
viz(c, "age", "salary")               # auto -> scatter (both numeric)
viz(c, "department", "salary")        # auto -> bar (mixed types)
viz(c, "age", "salary", kind="scatter")
viz(c, "department", "salary", kind="box")
viz(c, "department", kind="pie")
viz(c, "date", "revenue", kind="line")
viz(c, kind="pairplot", hue="department")
viz(c, "department", "salary", kind="bar", save="chart.png")   # also saves a file

Supported chart types: line, bar, barh, scatter, hist, box, violin, kde, pie, heatmap, pairplot, area, plus "auto" which picks a sensible chart based on your data.

Namespace-style shortcuts

Once exactly one DataFrame is loaded, you can also call chart types directly, without repeating the DataFrame each time:

c = load("data.csv")

viz.bar("department", "salary")
viz.scatter("age", "salary")
viz.line("date", "revenue")
viz.box("department", "salary")
viz.violin("department", "salary")
viz.hist("age")              # single-column kinds take just x
viz.kde("salary")
viz.pie("department")
viz.heatmap()                # no columns needed
viz.pairplot(hue="department")   # no columns needed

If more than one DataFrame is loaded, the shortcut can't guess which one you mean — pass it explicitly as the first argument instead: viz.bar(c, "department", "salary").

Functions

Development

pip install -e ".[dev]"
pytest

License

MIT