Metadata-Version: 2.5
Name: cotbias
Version: 0.2.0
Summary: Official Python client & MCP Server for CFTC COT Bias Terminal Quant API
Project-URL: Homepage, https://cot-bias-terminal.com
Project-URL: Documentation, https://docs.cot-bias-terminal.com
Project-URL: Repository, https://github.com/cot-bias-terminal/cotbias
Author-email: COTBiasTerminal <support@cot-bias-terminal.com>
License: MIT
License-File: LICENSE
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: pydantic>=2.9.0
Provides-Extra: all
Requires-Dist: mcp>=2.0.0; extra == 'all'
Requires-Dist: pandas>=2.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'dev'
Requires-Dist: pandas>=2.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=2.0.0; extra == 'mcp'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0.0; extra == 'pandas'
Description-Content-Type: text/markdown

# cotbias

[![PyPI version](https://img.shields.io/pypi/v/cotbias.svg)](https://pypi.org/project/cotbias/)
[![Python versions](https://img.shields.io/pypi/pyversions/cotbias.svg)](https://pypi.org/project/cotbias/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Official Python SDK and Model Context Protocol (MCP) Server for the **CFTC Commitment of Traders (COT) Bias Terminal** Quant API.

Access institutional positioning metrics, 156-week historical timeseries across multiple CFTC report families, cross-market positioning screeners, and AI-driven market regime & attribution analysis directly in Python and in AI assistants (Claude Desktop, Cursor, Cline).

---

## Installation

### Core SDK (Lightweight, zero Pandas/NumPy overhead)
```bash
pip install cotbias
```

### With Pandas support (DataFrames)
```bash
pip install "cotbias[pandas]"
```

### With MCP Server (Claude Desktop, Cursor, AI agents)
```bash
pip install "cotbias[mcp]"
```

Or install all features:
```bash
pip install "cotbias[all]"
```

---

## 🤖 Model Context Protocol (MCP) Server

Connect your Quant API key directly into Claude Desktop or Cursor IDE:

```json
{
  "mcpServers": {
    "cotbias": {
      "command": "uvx",
      "args": ["cotbias[mcp]", "cotbias-mcp"],
      "env": {
        "COT_API_KEY": "cot_live_YOUR_ACTUAL_API_KEY"
      }
    }
  }
}
```

See [docs/mcp.md](docs/mcp.md) for full configuration details, available tools (`get_market_snapshot`, `get_ai_inference`, `get_timeseries`, `scan_markets`, `list_markets`), and quota preservation caching.

---

## Quickstart

Get your API key at [cot-bias-terminal.com](https://cot-bias-terminal.com). Set it as an environment variable:

```bash
export COT_API_KEY="cot_live_..."
```

### 1. Fetch Positioning Timeseries into Pandas

```python
from cotbias import CotClient

with CotClient() as cot:
    # Pull 156 weeks of combined futures & options data for Gold (GC) as a Pandas DataFrame
    df = cot.timeseries.get("GC", contract_type="futopt", lookback_weeks=156, as_dataframe=True)
    print(df[["commercial_net", "cot_52w_commercial", "z_score_156w_commercial"]].tail())
```

### 2. AI Market Regime & Qualitative Attribution

```python
from cotbias import CotClient

with CotClient() as cot:
    inf = cot.inference.get("GC")
    print(f"Asset: {inf.symbol}")
    print(f"Bias: {inf.ai_bias_score} | Regime: {inf.regime_status}")
    print(f"Primary Driver: {inf.primary_driver} ({inf.momentum})")
    print(f"Macro Rationale: {inf.qualitative_attribution.macro_rationale}")
```

### 3. Cross-Market Positioning Screener

```python
from cotbias import CotClient

with CotClient() as cot:
    # Find all markets where AI bias is Bullish and smart money is entering new longs
    res = cot.screener.scan(ai_bias_score="Bullish", momentum="New Longs (OI Expanding)")
    for item in res.results:
        print(f"{item.symbol}: {item.ai_bias_score} ({item.regime_status})")
```

### 4. Automatic Retries & Network Resilience

The SDK automatically retries transient 5xx errors, network timeouts, and transient rate limits with exponential backoff and jitter:

```python
from cotbias import CotClient

# Default max_retries=3. Set to 0 to disable or adjust for custom pipelines
with CotClient(max_retries=5, timeout=20.0) as cot:
    markets = cot.markets.list()
```

### 5. Asynchronous Client (FastAPI / Bots)

```python
import asyncio
from cotbias import AsyncCotClient


async def main():
    async with AsyncCotClient() as cot:
        # Fetch multiple markets concurrently
        gold_task = cot.timeseries.get("GC")
        sp500_task = cot.timeseries.get("ES")
        gold_ts, sp500_ts = await asyncio.gather(gold_task, sp500_task)
        print("Gold rows:", gold_ts.count, "| S&P 500 rows:", sp500_ts.count)


asyncio.run(main())
```

---

## Error Handling

All API errors inherit from `CotApiError`:

```python
from cotbias import CotClient
from cotbias.exceptions import (
    AuthenticationError,
    NotFoundError,
    PermissionDeniedError,
    RateLimitExceededError,
)

try:
    with CotClient() as cot:
        cot.timeseries.get("INVALID_TICKER")
except NotFoundError as e:
    print(f"Asset not found: {e.message}")
except RateLimitExceededError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except AuthenticationError as e:
    print("Invalid or missing API key.")
```

---

## License

MIT License. Developed for quantitative traders, portfolio managers, and market researchers.
