Metadata-Version: 2.4
Name: factorweave
Version: 0.2.0
Summary: Official Python client for the Factor Weave quant data API — factors, similarity search, leak-free labels, derived analytics, MCP.
Author-email: Factor Weave <support@factorweave.com>
Maintainer-email: Blazing Customs <support@factorweave.com>
License: MIT
Project-URL: Homepage, https://factorweave.com/
Project-URL: Documentation, https://factorweave.com/#docs
Project-URL: Source, https://github.com/Blazing-Customs/factorweave-tools/tree/main/python
Project-URL: Issues, https://github.com/Blazing-Customs/factorweave-tools/issues
Project-URL: Changelog, https://github.com/Blazing-Customs/factorweave-tools/releases
Project-URL: Repository, https://github.com/Blazing-Customs/factorweave-tools
Project-URL: OpenAPI spec, https://factorweave.com/api/openapi.json
Keywords: quant,factor,vector-similarity,backtest,stock,embeddings,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"
Provides-Extra: polars
Requires-Dist: polars>=0.20; extra == "polars"
Provides-Extra: all
Requires-Dist: pandas>=1.5; extra == "all"
Requires-Dist: polars>=0.20; extra == "all"
Dynamic: license-file

# factorweave — official Python client

Typed client for the [Factor Weave](https://factorweave.com/) 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

```bash
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_…`).

```python
import factorweave as fw
client = fw.Client(api_key="fw_live_...")
# or, with an email/password login:
client = fw.Client(); client.login("you@example.com", "...")
```

## Quick recipes

```python
# 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:

```python
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](https://factorweave.com/research.html) —
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: support@factorweave.com
