factorweave 0.1.2

Official Python client for the Factor Weave quant data API — factors, similarity search, leak-free labels, derived analytics, MCP.

factorweave — official Python client

Typed client for the Factor Weave quant data API. Factor data, vector similarity, leak-free forward-return labels, derived market analytics (factor dispersion, regime, risk-cluster tags, 32-D embeddings) and MCP — for ~12,000 US-listed tickers.

Install

pip install factorweave
# optional adapters:
pip install 'factorweave[pandas]'
pip install 'factorweave[polars]'

Authenticate

Get a free account at https://factorweave.com, then mint a long-lived dev key on the Profile page (fw_live_…).

import factorweave as fw
client = fw.Client(api_key="fw_live_...")
# or, with an email/password login:
client = fw.Client(); client.login("[e-mail]", "...")

Quick recipes

# Latest factor row for a ticker
row = client.features("AAPL")
print(row[0]["rsi"], row[0]["comp_score"])

# 252-day factor history → polars
hist = client.features("AAPL", start="2024-01-01", end="2024-12-31").to_polars()

# Top 25 momentum names today
client.top("mom", n=25).to_pandas()

# Factor analogues — historical, not co-moving same-day ETFs
n = client.find_similar("NVDA", method="cosine", min_lookback_days=30)
for row in n["neighbors"][:5]:
    print(row["ticker"], row["date"], row["features"]["rsi"])

# Derived analytics
client.market_context()                # FREE-friendly: today only
client.market_context(history=True)    # HOBBY+: 252-day history
client.report_card("AAPL")             # HOBBY+
client.risk_cluster("TSLA")            # PRO+
client.embedding("AAPL")               # QUANT

Errors

Failures raise typed exceptions you can catch granularly:

from factorweave import AuthError, TierError, RateLimitError, NotFoundError

try:
    client.risk_cluster("AAPL")
except TierError as e:
    print(f"Need {e.required_tier}, you have {e.your_tier}")
except RateLimitError:
    print("daily quota exhausted")

Honest framing

Factor Weave is a research substrate, not a return-prediction service. Our own leak-free testing — research note — shows factor similarity does not forecast returns. The supervised similarity method is a return-weighted projection, not an oracle. Use the data for screening, peer-finding, regime-aware research, and assembling leak-free backtest datasets.

Resources

• Docs: https://factorweave.com/#docs
• OpenAPI spec: https://factorweave.com/api/openapi.json
• Swagger UI: https://factorweave.com/api/docs/swagger
• MCP setup: https://factorweave.com/mcp.html
• Support: [e-mail]