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.

In [1]:
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.

In [2]:
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).

In [3]:
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'] ...
Out[3]:
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.

In [4]:
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
Out[4]:
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.

In [5]:
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).

In [6]:
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.

In [7]:
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.
Out[7]:
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.json in 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_quarters tells you how much self-history each row rests on.
In [8]:
print(f"total wall time: {time.time()-T0:.0f}s | credits now: {client.account()['credits']}")
total wall time: 10s | credits now: 2197