Metadata-Version: 2.4
Name: haruspex-sdk
Version: 0.1.0
Summary: Official Haruspex SDK. Stock intelligence scores (0-100) across 16 dimensions.
Project-URL: Homepage, https://haruspex.guru
Project-URL: Repository, https://github.com/Haruspex-guru/haruspex-sdk
Project-URL: Documentation, https://github.com/Haruspex-guru/haruspex-sdk#readme
Project-URL: Issues, https://github.com/Haruspex-guru/haruspex-sdk/issues
Author-email: Haruspex <support@haruspex.guru>
License: MIT
Keywords: api,finance,haruspex,intelligence,scoring,sdk,stocks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.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.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# haruspex-sdk

Official Python SDK for the [Haruspex](https://haruspex.guru) API. Stock
intelligence scores (0–100) across 16 dimensions, with outlook, trading
signal, history, search, and news.

```bash
pip install haruspex-sdk
```

Python 3.9+. Built on `httpx` and `pydantic` v2. Both sync and async
clients ship in the same package.

## Quickstart

```python
import os
from haruspex import Haruspex

client = Haruspex(api_key=os.environ.get("HARUSPEX_API_KEY"))

aapl = client.scores.get("AAPL")
print(f"{aapl.symbol}: {aapl.score}/100 ({aapl.outlook})")
print(f"Rate-limit remaining: {aapl.meta.rate_limit.remaining}")
```

Async:

```python
import asyncio
from haruspex import AsyncHaruspex

async def main():
    async with AsyncHaruspex() as client:
        scores = await client.scores.batch(["AAPL", "NVDA", "MSFT"])
        for s in scores.scores:
            print(s.symbol, s.score, s.outlook)

asyncio.run(main())
```

Every response carries a `.meta` accessor with `request_id`,
`credits_remaining`, and `rate_limit`, so you can observe credit/rate
headroom without a separate request.

## API

### `Haruspex(api_key=None, base_url=..., timeout=10.0, max_retries=2)`

If `api_key` is omitted, reads `HARUSPEX_API_KEY` from the environment.
Throws `HaruspexValidationError` if neither is present.

`AsyncHaruspex` exposes the same constructor and methods as `async`
coroutines.

### Methods

| Method                                            | Returns            |
| ------------------------------------------------- | ------------------ |
| `client.scores.get(symbol)`                       | `ScoreResponse`    |
| `client.scores.batch(symbols)`                    | `BatchResponse`    |
| `client.scores.history(symbol, from_=, to=, limit=)` | `HistoryResponse` |
| `client.search(query, limit=)`                    | `SearchResponse`   |
| `client.news(symbol, limit=)`                     | `NewsResponse`     |

`from_` is the keyword for the historical range start (Python keyword
`from` is reserved).

## Errors

All exceptions extend `HaruspexError`:

| Class                       | Trigger                                  |
| --------------------------- | ---------------------------------------- |
| `HaruspexAuthError`         | 401 / 403                                |
| `HaruspexNotFoundError`     | 404 — ticker not in the scoring universe |
| `HaruspexRateLimitError`    | 429 — carries `retry_after_ms`           |
| `HaruspexValidationError`   | 400 / client-side bad input              |
| `HaruspexServerError`       | 5xx                                      |
| `HaruspexNetworkError`      | timeout, DNS, connection reset           |

Every error carries `status`, `code`, `request_id`, and `body` when
available.

## Retries

Retries automatically on 429, 502, 503, 504, and network errors with
exponential backoff (250ms × 2^attempt, capped at 4s, with jitter).
Respects `Retry-After` on 429. Default `max_retries=2`.

## Authentication

Get a free API key at
[haruspex.guru/developers](https://haruspex.guru/developers). For
evaluation without signup, use the public demo key
(`hrspx_live_a7c52f9315a65c377fec9c30b53f266b`) documented in the
[root README](../../README.md).

## License

MIT. The SDK source code in this repository is MIT-licensed; the Haruspex
scoring algorithm and data are proprietary and access is governed by the
Haruspex API Terms of Service.
