Metadata-Version: 2.4
Name: folioforecast
Version: 0.1.0
Summary: FolioForecast Python SDK and MCP server — portfolio optimization, stress testing, and asset metadata for AI agents, robo-advisors, and fintech apps.
Project-URL: Homepage, https://www.folioforecast.com
Project-URL: Documentation, https://www.folioforecast.com/developers
Project-URL: Repository, https://github.com/shadow6-actual/V6_EODHD_POpt
Project-URL: Issues, https://github.com/shadow6-actual/V6_EODHD_POpt/issues
Project-URL: API Reference, https://www.folioforecast.com/api/v1/openapi.yaml
Author-email: FolioForecast <support@folioforecast.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,claude,cvar,finance,mcp,model-context-protocol,optimization,portfolio,quantitative-finance,risk-parity,sharpe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# folioforecast

Python SDK and MCP server for [FolioForecast](https://www.folioforecast.com) — programmatic portfolio optimization for AI agents, robo-advisors, and fintech apps.

One API call to optimize, search, or stress-test any portfolio. Same engine that powers the FolioForecast web app, wrapped in a clean Python interface and a drop-in Model Context Protocol server for Claude Desktop, Claude Code, Cursor, and Windsurf.

## Install

```bash
pip install folioforecast
```

For the MCP server:

```bash
pip install "folioforecast[mcp]"
```

Python 3.10+.

## Get an API key

Sign up at [folioforecast.com](https://www.folioforecast.com/hub?tab=settings) and create a key. Production keys start with `ff_live_`; sandbox keys start with `ff_test_` (no billing).

## SDK quick start

```python
import folioforecast as ff

client = ff.Client(api_key="ff_live_...")

result = client.optimize(
    tickers=["AAPL.US", "MSFT.US", "GOOGL.US", "AMZN.US"],
    goal="max_sharpe",
)

print(result.weights)    # {'AAPL.US': 0.30, 'MSFT.US': 0.25, ...}
print(result.metrics)    # {'sharpe': 1.42, 'volatility': 0.18, ...}
```

All SDK methods are synchronous. Use it inside `asyncio.to_thread(...)` if you need to call it from an async context.

### Ticker search

```python
hits = client.search_tickers("apple", limit=5)
for h in hits:
    print(h.symbol, h.name, h.exchange)
```

Free — 0 compute units.

### Stress test

```python
result = client.stress_test(
    tickers=["SPY.US", "TLT.US", "GLD.US"],
    weights={"SPY.US": 0.6, "TLT.US": 0.3, "GLD.US": 0.1},
    scenarios=["2008_gfc", "covid_2020"],
)
print(result.scenarios)
```

### Asset metadata

```python
meta = client.asset_metadata(tickers=["AAPL.US", "AGG.US", "GLD.US"])
for m in meta:
    print(m.symbol, m.sector, m.asset_class)
```

### Usage and billing

```python
print(client.usage())   # current period compute units consumed / remaining
print(client.health())  # API status
```

### Error handling

```python
from folioforecast import AuthError, BillingError, RateLimitError, APIError

try:
    client.optimize(tickers=["AAPL.US"], goal="max_sharpe")
except AuthError:
    print("API key is missing or invalid")
except BillingError:
    print("Add a payment method at https://www.folioforecast.com/hub?tab=settings")
except RateLimitError as e:
    print(f"Slow down — retry after {e.retry_after}s")
except APIError as e:
    print(f"API error {e.status_code}: {e}")
```

### Context-manager use

```python
with ff.Client(api_key="ff_live_...") as client:
    result = client.optimize(tickers=["VOO.US", "AGG.US"], goal="min_volatility")
```

## MCP server for Claude Desktop

The `folioforecast[mcp]` extra installs a full MCP server so Claude Desktop (and other MCP clients) can call the FolioForecast API directly.

### 1. Install

```bash
pip install "folioforecast[mcp]"
```

### 2. Configure Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "folioforecast": {
      "command": "folioforecast-mcp",
      "env": {
        "FOLIOFORECAST_API_KEY": "ff_live_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see the FolioForecast tools appear in the attachment menu.

### 3. Try it

In a **new** Claude Desktop chat, ask:

> Optimize a portfolio of AAPL, MSFT, GOOGL, and AMZN for maximum Sharpe ratio.

Claude will call `optimize_portfolio` and show you the weights and metrics.

### Works in

Claude Desktop, Claude Code, Cursor, Windsurf, and any other MCP-capable client. **Does not work in claude.ai web, the Claude mobile app, or claude.com** — those surfaces do not load third-party MCP servers. For ChatGPT, use the pre-built [FolioForecast Custom GPTs](https://www.folioforecast.com/developers) instead.

### Tools exposed

| Tool | Description | Cost |
|------|-------------|------|
| `optimize_portfolio` | Run mean-variance optimization across 20 methods (Sharpe, min-vol, risk parity, Kelly, CVaR, etc.) | 1–2 units |
| `search_tickers` | Search 165,000+ tickers by symbol or name | Free |
| `stress_test` | Crisis scenario analysis (2008 GFC, COVID, etc.) | 1 unit/scenario |
| `get_asset_metadata` | Sector, industry, asset class, market cap | 0.1 units/ticker |

Parity note: this Python package mirrors the four portfolio tools in the Node MCP server at v1.0.0. Budget and retirement tools are rolling out in the next release.

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FOLIOFORECAST_API_KEY` | Yes (for MCP server) | Your API key |
| `FOLIOFORECAST_API_URL` | No | Override the base URL (default: `https://www.folioforecast.com/api/v1`) |

The SDK accepts `api_key` as a constructor argument and falls back to the env var if omitted.

## Links

- Docs: <https://www.folioforecast.com/developers>
- OpenAPI spec: <https://www.folioforecast.com/api/v1/openapi.yaml>
- Dashboard / key management: <https://www.folioforecast.com/hub?tab=settings>
- Repository: <https://github.com/shadow6-actual/V6_EODHD_POpt>

## License

MIT — see [LICENSE](LICENSE).

---

FolioForecast is a calculation engine. Your AI does the thinking — we do the math. Results are historical analysis, not predictions. Not financial advice.
