ArcheAI quant demo — end to end in one notebook¶
What this does: pulls per-executive behavioral histories for a 50-ticker pilot scope, joins them to your own returns, and runs the published horserace recipe — baseline vs baseline + ArcheAI — reporting within-quarter rank IC with the baseline named.
What this is not: a reproduction of the published numbers. The SDK ships no prices, no earnings surprises and no returns. The returns in this demo are synthetic (generated below with a declared seed, labelled as such) so the notebook runs top-to-bottom on a trial key in a clean environment. Replace them with your own returns file to get a real read.
Research signals intended to inform professional judgment — not investment advice.
0. Install and authenticate¶
pip install "archeai-sdk[quant]>=1.1"
The [quant] extra pins everything this notebook needs — pandas, pyarrow (to read the
export), lightgbm and scikit-learn (the gradient-boosting backends; the kit uses lightgbm
when present and falls back to scikit-learn). Put your key in ARCHE_API_KEY. A trial key
is the pilot experience: a ticker allow-list, a history window, and daily caps, all reported
back by the API.
import os, io, time, math
import numpy as np
import pandas as pd
from arche_ai import ArcheClient, ArcheAPIError
from arche_ai import event_study as es
API_KEY = os.environ.get("ARCHE_API_KEY") or input("ArcheAI API key: ")
BASE = os.environ.get("ARCHE_BASE_URL", "https://api.arche-ai.com")
client = ArcheClient(api_key=API_KEY, base_url=BASE)
acct = client.account()
print(f"credits: {acct['credits']}")
trial = acct.get("trial")
if trial:
print(f"trial '{trial['label']}': {len(trial.get('allowedTickers') or [])} tickers, "
f"history from {trial.get('historyFrom')}, {trial.get('maxHistoryCallsPerDay')} history calls/day, "
f"expires {trial.get('expiresAt')}")
else:
print("no trial scope on this workspace (full access, subject to credits)")
T0 = time.time()
credits: 2586 trial '1b quant-demo pilot (stage)': 50 tickers, history from 2023Q4, 500 history calls/day, expires 2026-11-01T00:07:55.000Z
1. The universe: the pilot's allow-list¶
On a trial, the allow-list is the universe — the API will refuse anything else
(TRIAL_TICKER_DENIED). Without a trial we fall back to a 50-name list.
FALLBACK_50 = ["AAPL","MSFT","AMZN","GOOG","META","NVDA","JPM","XOM","WMT","PG","COST","HD","KO","PEP","MRK",
"PFE","CSCO","ORCL","INTC","AMD","DIS","NKE","MCD","SBUX","BA","CAT","GE","HON","UNP","UPS",
"CVX","COP","SLB","T","VZ","CMCSA","NFLX","ADBE","CRM","IBM","GS","MS","BAC","C","WFC","AXP",
"V","MA","PYPL","ICE"]
TICKERS = (trial or {}).get("allowedTickers") or FALLBACK_50
print(len(TICKERS), "tickers:", TICKERS[:8], "...")
50 tickers: ['AAPL', 'MSFT', 'AMZN', 'GOOG', 'META', 'NVDA', 'JPM', 'XOM'] ...
2. Pull the histories — bulk export first, per-ticker fallback¶
export_history() returns one Parquet of every (ticker, executive, quarter) row in scope,
watermarked with your workspace id and delivered under a research-use license (printed
below). It needs a workspace grant + an active scope; if your key doesn't have them the
notebook falls back to behavioral_history() per ticker (5 credits each).
CACHE = "archeai_history_export.parquet" # re-runs load this file; delete it to export again
hist = None
if os.path.exists(CACHE):
hist = client.export_history(cache=CACHE)
print(f"loaded cached export {CACHE} ({len(hist):,} rows) — no API call, no credits; "
f"generated {client.last_export.get('generated_at')}, job {client.last_export.get('job_id')}")
else:
try:
# 1) price first: exact rows + charge with every gate applied, nothing queued or charged
est = client.export_history(tickers=TICKERS, dry_run=True)
print(f"export would be {est['rows']:,} rows over {est['scope']['tickers']} tickers "
f"({est['scope']['from']} -> {est['scope']['to']}) and cost {est['creditsRequired']} credits "
f"(you have {est['creditsAvailable']}; {est['scope']['exportsUsedToday']}/{est['scope']['maxExportsPerDay']} exports used today)")
# 2) then run it, saving the Parquet so the next run is free
hist = client.export_history(tickers=TICKERS, cache=CACHE)
meta = client.last_export
print(f"bulk export: {meta['rows']:,} rows, {meta['companies']} companies, {meta['executives']} executives, "
f"quarters {meta['quarters'][0]} -> {meta['quarters'][1]}, {meta['creditsCharged']} credits charged")
print("file sha256:", meta["fileSha256"][:16], "| artifact:", meta["artifact_version"], "| cached to", CACHE)
print("LICENSE:", meta["license"])
except ArcheAPIError as e:
print(f"export unavailable ({e.code}: {e.message[:90]}) -> per-ticker fallback (5 credits per ticker)")
frames = []
for t in TICKERS:
try:
frames.append(client.behavioral_history(t))
except ArcheAPIError as e2:
print(f" {t}: {e2.code}")
hist = pd.concat(frames, ignore_index=True)
print(hist.shape, "columns:", list(hist.columns)[:8], "...")
hist.head(3)
export would be 3,888 rows over 50 tickers (2023Q4 -> 2099Q4) and cost 389 credits (you have 2586; 5/20 exports used today)
bulk export: 3,888 rows, 50 companies, 487 executives, quarters 2023Q4 -> 2026Q4, 389 credits charged file sha256: 8472212f9b941191 | artifact: behavioral-history-export-v1 | cached to archeai_history_export.parquet LICENSE: Internal research use only, by the licensed workspace. No redistribution, resale, or sharing of the file or its rows; no training, fine-tuning, or distillation of models that reproduce ArcheAI outputs. Rows are watermarked with your workspace id. Research signals; not investment advice. (3888, 23) columns: ['workspace_id', 'ticker', 'company_id', 'resolved_by', 'company_name', 'speaker_id', 'executive', 'quarter'] ...
| workspace_id | ticker | company_id | resolved_by | company_name | speaker_id | executive | quarter | as_of_quarter | n_calls | ... | style_tentative_assertive | style_authority_people | style_formal_conversational | style_uncertain_certain | style_pessimistic_optimistic | big5_openn | big5_consc | big5_extra | big5_agree | big5_neuro | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 4 | AAPL | 24937 | ticker | Apple Inc. | 106800 | Timothy Cook | 2023Q4 | 2023Q4 | 4 | ... | -0.111 | -0.131 | 0.221 | 0.039 | 0.210 | 4.6547 | 5.0773 | 4.7237 | 4.0154 | 3.2288 |
| 1 | 4 | AAPL | 24937 | ticker | Apple Inc. | 106800 | Timothy Cook | 2024Q1 | 2024Q1 | 2 | ... | -0.525 | -0.163 | -0.000 | -0.071 | 0.103 | 4.6780 | 5.1324 | 4.7171 | 4.1414 | 3.3121 |
| 2 | 4 | AAPL | 24937 | ticker | Apple Inc. | 106800 | Timothy Cook | 2024Q2 | 2024Q2 | 1 | ... | -0.130 | 0.044 | 0.459 | 0.512 | 0.378 | 4.6719 | 5.1114 | 4.6461 | 4.0310 | 3.4048 |
3 rows × 23 columns
2b. What the 12 scores mean¶
Every row is one executive in one quarter, scored from that quarter's calls only. Twelve level scores:
| column | the two poles (label as served by the API) | units |
|---|---|---|
style_intellectual_colloquial |
intellectual ↔ colloquial | z vs executive-register norm |
style_concrete_abstract |
concrete ↔ abstract | z |
style_tentative_assertive |
tentative ↔ assertive | z |
style_authority_people |
authority ↔ people-focused | z |
style_formal_conversational |
formal ↔ conversational | z |
style_uncertain_certain |
uncertain ↔ certain | z |
style_pessimistic_optimistic |
pessimistic ↔ optimistic | z |
big5_openn big5_consc big5_extra big5_agree big5_neuro |
expressed Big Five from language | 1–7 scale (4 = midpoint) |
Direction. For every style_* score, positive = more of the second pole in the name
(the API's own rule: "+ = more of the second pole in the label"). So style_uncertain_certain
= +1.2 reads "one standard deviation more certain than the typical executive";
style_pessimistic_optimistic = −0.8 reads "more pessimistic than typical".
Units. The seven style_* scores are z-scores against the norm distribution of executive
earnings-call speech (norms_earnings_qa_v1): 0 is the typical executive, ±1 is one
population standard deviation. The Big Five are on the psychologist-reference 1–7 scale.
What counts as notable. Level scores describe a person; the research signal is the
move: dev_* (next cell) is each score's departure from the same executive's own prior
eight quarters, z-scored on that executive's history — a quarter in which the executive
sounded unlike themselves. On the study panel (55,228 executive-quarters) the tails are
fatter than Gaussian because the personal baseline rests on 4–8 quarters: |dev_*| ≥ 1 on
36% of executive-quarters, ≥ 2 on 10%, ≥ 3 on 3%. Treat ≥ 2 as "notable" and ≥ 3
as "rare". A large level score with a small dev_* is a stable trait, not an event; the
published lift is carried by the dev_* block.
Full definitions, confidence by text volume, and the research-signal framing:
interpreting-scores.md (shipped in the package docs).
3. Point-in-time features¶
For every (ticker, executive, quarter): the 12 level scores (7 communication-style
dimensions, 5 Big Five) and dev_* — each score's deviation from the same executive's
own prior quarters, z-scored. No future quarter ever enters a row. That dev_* block is the
proprietary self-baseline method the published study rests on.
feat = es.point_in_time_features(hist)
print(feat.shape, "| executives with >= 4 prior quarters:",
int((feat["n_hist_quarters"] >= 4).sum()), "of", len(feat))
feat[["ticker","speaker_id","quarter","n_hist_quarters","style_pessimistic_optimistic","dev_style_pessimistic_optimistic"]].dropna().head(5)
(3888, 36) | executives with >= 4 prior quarters: 1984 of 3888
| ticker | speaker_id | quarter | n_hist_quarters | style_pessimistic_optimistic | dev_style_pessimistic_optimistic | |
|---|---|---|---|---|---|---|
| 4 | AAPL | 106800 | 2024Q4 | 4 | 0.474 | 1.819803 |
| 5 | AAPL | 106800 | 2025Q1 | 5 | 0.340 | 0.553916 |
| 6 | AAPL | 106800 | 2025Q2 | 6 | 0.058 | -1.030532 |
| 7 | AAPL | 106800 | 2025Q3 | 7 | -0.012 | -1.272869 |
| 8 | AAPL | 106800 | 2025Q4 | 8 | -0.372 | -2.994788 |
4. Your returns — the contract (this is the handoff point)¶
For your numbers to be comparable with the published ones, build your events file to the
study's definitions (horserace_study/compute_returns.py, fetch_sue.py). One row per
earnings call:
| column | definition (exactly as the study computed it) |
|---|---|
ticker |
the ticker the call belongs to (upper-case); joined to the API rows on ticker |
call_date |
the earnings-call date (calendar date). The notebook maps it to the call's quarter for the join. |
| T0 | the first trading day on or after call_date. Calls are pre-market or after-hours; this alignment is conservative (a pre-market call's T0 is the call day; an after-hours call's T0 is the next trading day — both are "the first session that could trade on the call", so T0→T+1 never includes a return that pre-dates the call). |
car_1 |
T+1 close ÷ T0 close − 1, minus the same return on SPY (simple returns, split/dividend-adjusted closes). The immediate reaction. |
car_5 |
T+5 close ÷ T0 close − 1, minus SPY's. Five trading days, not calendar. |
mom_21 |
T−21 close → T−1 close simple return (strictly pre-event) |
mom_63 |
T−63 → T−1 simple return |
vol_21 |
standard deviation of daily simple returns over T−21..T−1 (≥ 10 bars required) |
dollar_vol |
log1p of mean (close × volume) over T−21..T−1 |
sue |
seasonal-random-walk earnings surprise: (EPS_q − EPS_{q−4}) / std(EPS_{q−i} − EPS_{q−4−i}, i = 1..4), quarterly diluted EPS, from filings filed before call_date (point-in-time) |
eps_yoy |
EPS_q − EPS_{q−4} (same point-in-time rule) |
Conventions that matter: market adjustment is SPY-subtracted, not beta-adjusted; horizons
are trading days; prices are adjusted closes; nothing in a baseline column may use a bar
on or after T0; nothing in sue/eps_yoy may use a filing on or after call_date. If your
returns are beta-adjusted, open-to-close, or calendar-day, say so when you compare — the
published IC is not directly comparable. A CSV template with these columns is written next
to this notebook.
The returns generated here are synthetic — random draws with a declared seed, built only
so the pipeline runs end to end. Any IC they produce is noise by construction and says
nothing about ArcheAI. Replace events with your file to get a real result.
TEMPLATE = "my_events_TEMPLATE.csv"
pd.DataFrame(columns=["ticker","call_date","car_1","car_5","mom_21","mom_63","vol_21","dollar_vol","sue","eps_yoy"]).to_csv(TEMPLATE, index=False)
print("template written:", TEMPLATE)
SYNTHETIC = True
rng = np.random.default_rng(20261017)
qs = sorted(feat["quarter"].unique())
qs = [q for q in qs if q >= "2018Q1"]
rows = []
for t in feat["ticker"].unique():
for q in qs:
y, n = int(q[:4]), int(q[-1])
call_date = pd.Timestamp(year=y, month=3*n-1, day=15) # mid-quarter stand-in for the call date
rows.append(dict(ticker=t, call_date=call_date,
car_1=rng.normal(0, 0.05), car_5=rng.normal(0, 0.08),
mom_21=rng.normal(0, 0.06), mom_63=rng.normal(0, 0.10), vol_21=abs(rng.normal(0.02, 0.01)),
dollar_vol=rng.normal(17, 1.5), sue=rng.normal(0, 1), eps_yoy=rng.normal(0.05, 0.3)))
events = pd.DataFrame(rows)
print("SYNTHETIC events:", events.shape, "| to use your own: events = pd.read_csv('my_events.csv', parse_dates=['call_date'])")
template written: my_events_TEMPLATE.csv
SYNTHETIC events: (650, 10) | to use your own: events = pd.read_csv('my_events.csv', parse_dates=['call_date'])
5. Join events to features (point-in-time)¶
Each event is joined to the executive rows for the quarter of the call — scores from that
quarter's calls; dev_* from earlier quarters only. The executive with the most words that
quarter is kept (the study's choice).
panel = es.join_events(events, feat)
matched = panel["speaker_id"].notna()
have = panel[matched].copy()
# Unmatched events are reported, not dropped silently. Three reasons are distinguishable:
# ticker_not_in_history : the ticker has no rows in the export/history at all
# (not in scope, not covered, or a ticker-string mismatch)
# quarter_not_covered : the ticker is covered but has no executive row for the call's
# quarter (no call collected that quarter, or outside your
# history window / trial floor)
# call_date_unparseable : call_date did not parse to a quarter
tick_set = set(feat["ticker"])
tq_set = set(zip(feat["ticker"], feat["quarter"]))
def _reason(r):
if pd.isna(r.get("quarter")): return "call_date_unparseable"
if r["ticker"] not in tick_set: return "ticker_not_in_history"
if (r["ticker"], r["quarter"]) not in tq_set: return "quarter_not_covered"
return "unknown"
unmatched = panel.loc[~matched, ["ticker", "call_date", "quarter"]].copy()
unmatched["reason"] = unmatched.apply(_reason, axis=1)
print(f"{len(have):,} of {len(panel):,} events matched an executive-quarter; "
f"{int(have['n_hist_quarters'].ge(4).sum()):,} of those have >= 4 quarters of self-history for dev_*")
if len(unmatched):
print(f"{len(unmatched):,} unmatched, by reason:")
print(unmatched["reason"].value_counts().to_string())
print("first few:")
print(unmatched.head(8).to_string(index=False))
else:
print("0 unmatched events")
no_dev = have["n_hist_quarters"].lt(4).sum()
if no_dev:
print(f"{int(no_dev):,} matched events have < 4 quarters of self-history: dev_* is NaN for them "
"(early quarters in scope / trial floor); they stay in the panel with level scores only")
610 of 650 events matched an executive-quarter; 406 of those have >= 4 quarters of self-history for dev_*
40 unmatched, by reason:
reason
quarter_not_covered 40
first few:
ticker call_date quarter reason
AAPL 2026-11-15 2026Q4 quarter_not_covered
ADBE 2026-11-15 2026Q4 quarter_not_covered
AMD 2026-11-15 2026Q4 quarter_not_covered
AMZN 2026-11-15 2026Q4 quarter_not_covered
BA 2026-11-15 2026Q4 quarter_not_covered
BAC 2026-11-15 2026Q4 quarter_not_covered
CAT 2026-11-15 2026Q4 quarter_not_covered
CMCSA 2026-11-15 2026Q4 quarter_not_covered
204 matched events have < 4 quarters of self-history: dev_* is NaN for them (early quarters in scope / trial floor); they stay in the panel with level scores only
6. The horserace — baseline vs baseline + ArcheAI, baseline named¶
Within-quarter Spearman rank IC, averaged over test quarters with >= 30 events. The model
is the study's recipe (gradient boosting on a quarter-demeaned target). baseline_definition
in the result names exactly what you supplied.
BASELINE = ["mom_21","mom_63","vol_21","dollar_vol","sue","eps_yoy"]
quarters = sorted(have["quarter"].unique())
split = quarters[int(len(quarters)*0.6)]
train_q = [q for q in quarters if q < split]
test_q = [q for q in quarters if q >= split]
out = {}
for target in ("car_1", "car_5"):
out[target] = es.horserace(have, target=target, baseline_cols=BASELINE,
train_quarters=train_q, test_quarters=test_q, min_events=30)
table = pd.DataFrame({t: {"baseline IC": r["baseline"], "baseline + ArcheAI IC": r["baseline_plus_archeai"],
"lift": r["lift"], "test quarters": int(len(r["baseline_by_quarter"]))}
for t, r in out.items()}).T
print("BASELINE:", out["car_1"]["baseline_definition"])
print("train", train_q[0], "->", train_q[-1], "| test", test_q[0], "->", test_q[-1],
"| n_train", out["car_1"]["n_train"], "n_test", out["car_1"]["n_test"])
if SYNTHETIC:
print("RETURNS ARE SYNTHETIC — these ICs are noise by construction.")
table.round(4)
BASELINE: your columns: mom_21, mom_63, vol_21, dollar_vol, sue, eps_yoy train 2023Q4 -> 2025Q2 | test 2025Q3 -> 2026Q4 | n_train 350 n_test 260 RETURNS ARE SYNTHETIC — these ICs are noise by construction.
| baseline IC | baseline + ArcheAI IC | lift | test quarters | |
|---|---|---|---|---|
| car_1 | 0.0110 | 0.0226 | 0.0116 | 5.0 |
| car_5 | -0.0124 | -0.0469 | -0.0345 | 5.0 |
7. How to read this¶
- The number that matters is the lift, baseline → baseline + ArcheAI, at the horizon you trade, against the baseline you named. A lift with an unnamed baseline is not a result.
- Published reference, for context only (P1 test window 2022–2025, 18,791 events,
baseline = price momentum 21/63 d + 21-d volatility + dollar volume + SUE + EPS y/y):
T+1 IC +0.050 vs +0.003; T+5 +0.031 vs −0.001. Combinatorial purged CV (36 paths, baseline
price + LM sentiment + SUE): lift positive in 36/36 paths at T+1. 2026 forward,
strictly out-of-sample, three quarters: frozen v5 T+1 +0.028 vs its own baseline +0.005.
Source:
quant_headline_metrics.jsonin the data room. Expect the API feature block to carry part of that — the study also used Q&A-dynamics and register-shift features that are research-only. - With synthetic returns the table above is noise. Swap in your returns; keep your baseline columns; keep the within-quarter IC; keep the train/test split chronological.
- Trial floors truncate
dev_*for the earliest quarters in scope —n_hist_quarterstells you how much self-history each row rests on.
print(f"total wall time: {time.time()-T0:.0f}s | credits now: {client.account()['credits']}")
total wall time: 10s | credits now: 2197