Metadata-Version: 2.4
Name: vectrade
Version: 0.1.0
Summary: Official Python SDK for the VecTrade financial data and AI platform
Project-URL: Homepage, https://vectrade.io
Project-URL: Documentation, https://docs.vectrade.io/sdks/python
Project-URL: Repository, https://github.com/VecTrade-io/vectrade-python
Project-URL: Changelog, https://github.com/VecTrade-io/vectrade-python/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/VecTrade-io/vectrade-python/issues
Author-email: VecTrade <sdk@vectrade.io>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,api,finance,market-data,sdk,stocks,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
Requires-Dist: httpx<1.0,>=0.25.0
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'telemetry'
Description-Content-Type: text/markdown

# VecTrade Python SDK

[![CI](https://github.com/VecTrade-io/vectrade-python/actions/workflows/ci.yml/badge.svg)](https://github.com/VecTrade-io/vectrade-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/vectrade)](https://pypi.org/project/vectrade/)
[![codecov](https://codecov.io/gh/VecTrade-io/vectrade-python/branch/main/graph/badge.svg)](https://codecov.io/gh/VecTrade-io/vectrade-python)
[![License](https://img.shields.io/github/license/VecTrade-io/vectrade-python)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

Official Python SDK for the [VecTrade](https://vectrade.io) financial data and AI platform.

## Features

- **Sync & Async** — both `VecTrade` and `AsyncVecTrade` clients
- **Streaming AI** — generator-based streaming analysis
- **Type-safe** — Pydantic response models, mypy strict
- **Resilient** — automatic retries with exponential backoff
- **Minimal deps** — httpx + pydantic only

## Installation

```bash
pip install vectrade
```

With optional extras:

```bash
pip install "vectrade[pandas]"       # DataFrame support
pip install "vectrade[telemetry]"    # OpenTelemetry tracing
```

## Quick Start

```python
from vectrade import VecTrade

vt = VecTrade()  # reads VECTRADE_API_KEY from env

# Real-time quote
quote = vt.quotes.get("AAPL")
print(f"{quote.symbol}: ${quote.price}")

# Stream AI analysis
for chunk in vt.ai.stream("Analyze AAPL for long-term hold"):
    print(chunk.text, end="")
```

## Async Usage

```python
from vectrade import AsyncVecTrade

async with AsyncVecTrade() as vt:
    quote = await vt.quotes.get("AAPL")
```

## Available Resources

| Resource | Description |
|----------|-------------|
| `client.quotes` | Real-time and historical price quotes |
| `client.fundamentals` | Financial statements, ratios, company profiles |
| `client.technicals` | Technical indicators (RSI, MACD, Bollinger, etc.) |
| `client.news` | Market news and sentiment |
| `client.earnings` | Earnings reports and estimates |
| `client.analyst` | Analyst ratings and price targets |
| `client.insider` | Insider trading activity |
| `client.options` | Options chains and Greeks |
| `client.screener` | Stock screener with pagination |
| `client.webhooks` | Webhook management for real-time alerts |
| `client.developer` | API key and usage management |
| `client.ai` | AI-powered streaming analysis |

## Configuration

```python
vt = VecTrade(
    api_key="vq_live_...",       # or set VECTRADE_API_KEY
    sandbox=True,                # use sandbox environment
    timeout=60.0,                # request timeout (seconds)
    max_retries=3,               # retry on 429/5xx
)
```

## Error Handling

The SDK raises typed exceptions for all API errors:

```python
from vectrade import VecTrade, RateLimitError, AuthenticationError, NotFoundError

try:
    quote = vt.quotes.get("INVALID")
except NotFoundError as e:
    print(f"Symbol not found: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError as e:
    print(f"Bad API key: {e}")
```

All exceptions include `request_id` and `status_code` for debugging.

## Developer Self-Service

Manage your API keys and monitor usage programmatically:

```python
# Check your plan and quota
plan = vt.developer.get_plan()
print(f"Plan: {plan.plan_name}, Quota: {plan.monthly_quota}")

quota = vt.developer.get_quota()
print(f"Used: {quota.used}/{quota.monthly_quota} ({quota.usage_pct}%)")

# Manage API keys
keys = vt.developer.list_keys()
new_key = vt.developer.create_key(label="production", scopes="quotes,options")
vt.developer.revoke_key(key_id=new_key.id)
```

## Pagination

Use the built-in pagination helpers for list endpoints:

```python
# Screener with pagination
results = vt.screener.filter(
    market_cap_min=1_000_000_000,
    sector="Technology",
    limit=50,
    offset=0,
)
```

## Rate Limits

The SDK automatically handles rate limiting with exponential backoff. You can also check your limits:

```python
quota = vt.developer.get_quota()
print(f"Remaining: {quota.remaining} requests this period")
```

## Documentation

Full documentation is available at [docs.vectrade.io/sdks/python](https://docs.vectrade.io/sdks/python).

- [API Reference](https://docs.vectrade.io/api-reference/overview)
- [Authentication Guide](https://docs.vectrade.io/guides/authentication)
- [Error Handling](https://docs.vectrade.io/guides/error-handling)
- [Streaming Guide](https://docs.vectrade.io/guides/streaming)
- [Examples](examples/) — runnable scripts for common use cases

## Versioning

This SDK follows [Semantic Versioning](https://semver.org/):

- **MAJOR** — breaking changes to public API
- **MINOR** — new features, backward-compatible
- **PATCH** — bug fixes, backward-compatible

Pre-1.0 releases may include breaking changes in MINOR versions. Pin your dependency accordingly:

```toml
# pyproject.toml
dependencies = ["vectrade>=0.1,<0.2"]
```

## Requirements

- Python 3.9+
- No system dependencies — pure Python

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## License

MIT — see [LICENSE](LICENSE).
