# G-Prophet Python SDK

Official Python client for the [G-Prophet](https://gprophet.com) AI Stock Prediction API.

## Installation

```bash
pip install gprophet
```

To also use the MCP Server (for AI agents like Claude, Kiro, etc.):

```bash
pip install gprophet[mcp]
```

## Quick Start

```python
from gprophet import GProphet

client = GProphet(api_key="gp_sk_your_key_here")

# Check balance
print(client.balance())

# Get a stock quote
quote = client.quote("AAPL", market="US")
print(f"AAPL: ${quote['price']}")

# AI prediction
pred = client.predict("AAPL", market="US", days=7)
print(f"Predicted: ${pred['predicted_price']} ({pred['direction']})")

# Technical analysis
tech = client.technical("AAPL", market="US")
print(f"Signal: {tech['overall_signal']}")

# Batch quotes
quotes = client.batch_quote(["AAPL", "GOOGL", "MSFT"], market="US")
for q in quotes["results"]:
    if q["success"]:
        print(f"{q['symbol']}: ${q['price']}")

# AI stock analysis (async with auto-polling)
analysis = client.analyze_stock("AAPL", market="US", wait=True)
print(analysis["analysis"]["summary"])
```

## MCP Server (for AI Agents)

After installing with `pip install gprophet[mcp]`, a `gprophet-mcp` command is available.

See [MCP Server documentation](https://github.com/g-prophet/gprophet-python/tree/main/mcp-server) for setup details.

## API Reference

### System
- `client.health()` — Health check
- `client.info()` — API metadata, pricing, supported markets

### Account
- `client.balance()` — Points balance and quota info
- `client.usage(days=7)` — Usage statistics

### Predictions
- `client.predict(symbol, market, days, algorithm)` — AI price prediction
- `client.compare(symbol, market, days, algorithms)` — Multi-algorithm comparison

### Market Data
- `client.quote(symbol, market)` — Real-time quote
- `client.batch_quote(symbols, market)` — Batch quotes
- `client.history(symbol, market, period)` — Historical OHLCV
- `client.search(keyword, market, limit)` — Search symbols

### Technical Analysis
- `client.technical(symbol, market, indicators)` — Technical indicators & signals

### Sentiment
- `client.fear_greed(days)` — Crypto Fear & Greed Index
- `client.market_overview(market)` — Market overview

### Analysis
- `client.analyze_stock(symbol, market, locale, wait)` — AI stock analysis (58 pts)
- `client.analyze_comprehensive(symbol, market, locale, wait)` — Multi-agent analysis (150 pts)
- `client.task_status(task_id)` — Check async task status

## Error Handling

```python
from gprophet import GProphet
from gprophet.client import GProphetError, RateLimitError, InsufficientPointsError

client = GProphet(api_key="gp_sk_...")

try:
    result = client.predict("AAPL", market="US")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except InsufficientPointsError as e:
    print(f"Need {e.required} points, have {e.available}")
except GProphetError as e:
    print(f"API error [{e.code}]: {e.message}")
```

## Configuration

```python
client = GProphet(
    api_key="gp_sk_...",
    base_url="https://gprophet.com/api/external/v1",  # Custom base URL
    timeout=60,       # Request timeout (seconds)
    max_retries=3,    # Auto-retry on rate limit
)
```

## License

MIT
