Metadata-Version: 2.4
Name: forecite
Version: 0.1.0
Summary: Official Python SDK for the Forecite API — scored news feed (REST), Verdict scoring, and realtime WebSocket streaming.
Project-URL: Homepage, https://forecite.dev
Project-URL: Repository, https://github.com/forecite/forecite-python
Project-URL: Documentation, https://github.com/forecite/forecite-python#readme
Project-URL: Bug Tracker, https://github.com/forecite/forecite-python/issues
Author-email: Forecite <hello@forecite.dev>
License: MIT
License-File: LICENSE
Keywords: finance,forecite,market-data,news,realtime,sdk,sentiment,trading,websocket
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.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: requests>=2.28
Requires-Dist: websocket-client>=1.6
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# forecite (Python SDK)

[![PyPI version](https://img.shields.io/pypi/v/forecite.svg)](https://pypi.org/project/forecite/)
[![Python versions](https://img.shields.io/pypi/pyversions/forecite.svg)](https://pypi.org/project/forecite/)
[![license: MIT](https://img.shields.io/pypi/l/forecite.svg)](./LICENSE)

Official Python SDK for the [Forecite](https://forecite.dev) API — the scored
news feed (REST), the Verdict scoring engine, and the realtime WebSocket stream.
Fully type-hinted, sync, minimal dependencies.

## Install

```bash
pip install forecite
```

## Quick start

```python
from forecite import Forecite

forecite = Forecite("fc_live_your_key")
# or: Forecite(api_key, base_url=..., ws_url=...)

# REST — list scored feeds
res = forecite.feeds.list(symbol="TSLA", limit=20)
print(res["data"], res["next_cursor"])

# Score an artifact (Pro+)
verdict = forecite.score({
    "type": "news",
    "title": "Acme beats earnings",
    "body": "Acme reported Q2 revenue of …",
})

# Account + usage
me = forecite.me()
usage = forecite.usage(days=14)
```

## Realtime stream

```python
def on_feed(item):
    print(item["title"], "→", item.get("scoring"))

stream = forecite.stream(
    filters={"symbols": ["TSLA", "AAPL"]},
    snapshot=10,
    on_feed=on_feed,
    on_welcome=lambda w: print("connected:", w["tier"]),
)
stream.run()              # blocks; or stream.run_in_thread()
# stream.close()
```

## API surface

| Group | Methods |
|---|---|
| Feeds | `feeds.list(**query)`, `feeds.get(id)` |
| Scoring | `score(artifact, options=None)` |
| Account | `me()`, `usage(days=30)` |
| Reference | `providers.list/get`, `sources.list/get`, `symbols.list/get`, `tags.list/get` |
| Webhooks | `webhooks.list/create/get/update/delete` |
| Realtime | `stream(filters=…, snapshot=…, on_feed=…)` |

## Config

```python
Forecite(
    api_key="fc_live_…",
    base_url="http://localhost:3000/api",  # local dev (default: https://api.forecite.com)
    ws_url="ws://localhost:8080",          # local dev (default: wss://ws.forecite.com)
)
```

Errors raise `ForeciteError` with `.status` and `.code`.
