Metadata-Version: 2.4
Name: invespider
Version: 0.1.1
Summary: Official Python client for the InveSpider API — deterministic macroeconomic regime data (Growth x Inflation quadrant classification) across 27 countries.
Author: mete-dotcom
License: Copyright (c) 2026 mete-dotcom
        
        All Rights Reserved.
        
        This software and associated documentation files (the "Software") are the
        proprietary property of the copyright holder. No permission is granted to
        copy, modify, merge, publish, distribute, sublicense, decompile, reverse
        engineer, or create derivative works of the Software, in whole or in part,
        without prior written permission from the copyright holder.
        
        The Software is provided "AS IS", without warranty of any kind, express or
        implied, including but not limited to the warranties of merchantability,
        fitness for a particular purpose, and noninfringement. In no event shall
        the copyright holder be liable for any claim, damages, or other liability
        arising from, out of, or in connection with the Software or the use or
        other dealings in the Software.
        
Project-URL: Homepage, https://invespider.com
Keywords: macroeconomics,economic-data,api-client,finance,regime-classification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary 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: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Dynamic: license-file

# invespider

Official Python client for the **InveSpider API** — deterministic macroeconomic
regime data. No AI, no black box: every number traces back to a real, cited
source (CBRT EVDS, World Bank Open Data, IMF World Economic Outlook, Fitch
sovereign ratings) and a documented, literature-standard method (rolling
Z-score normalization, Winsorization, and Growth×Inflation quadrant
classification — the "Investment Clock" framework, Merrill Lynch / Trevor
Greetham, 2004).

**This API never gives investment advice.** It answers "what regime is this
economy in, and what does history say it most resembles" — never "buy",
"sell", or "hold".

## Install

```bash
pip install invespider
```

## Quick start

```python
from invespider import InveSpiderClient

client = InveSpiderClient(api_key="YOUR_API_KEY")  # optional -- omit for anonymous access, shares a lower rate limit

result = client.compare(
    country="TR",
    year_a="2024", quarter_a="Q2",
    year_b="2018", quarter_b="Q3",
)

for period_id, period in result.periods.items():
    print(period_id, period.regime.quadrant, "-", period.regime.description)

print("Axis deltas:", result.deltas)
print("Quadrant stability (last periods):", result.stability)
```

## Why this is cheap to build on

All data is precomputed server-side on a scheduled batch cadence (monthly/
quarterly ingestion + recompute) — every API call is a fast read against
already-computed results. There's no per-request compute cost passed on to
you, and no rate-limit pressure from "expensive" queries: similarity search
and N-way comparisons cost the same as a single vector lookup.

## Access and rate limits

Free during this initial phase, for everyone -- there is currently no paid
tier. All 27 supported countries, full ingested history, and N-way
comparison (2-4 periods) are available whether or not you pass an
`api_key`.

The only thing an API key changes today is rate limiting: anonymous
requests share one limit; a key gets its own tracked 200 requests/24h
(sliding window). Create a key from your account's API Keys page at
https://invespider.com. If paid tiers with higher limits are introduced
later, a key will be required to use them -- this README will be updated
when that happens, not before.

Regime-shift email alerts (`/api/subscriptions`) are a separate, free,
public feature -- no API key needed.

## Error handling

```python
from invespider import InveSpiderClient, InveSpiderNotComputedError, InveSpiderAuthError, InveSpiderRateLimitError

client = InveSpiderClient(api_key="YOUR_API_KEY")

try:
    result = client.compare("TR", "2024", "Q2", "1999", "Q1")
except InveSpiderNotComputedError:
    print("No data ingested yet for one of these periods.")
except InveSpiderAuthError:
    print("Your API key is missing, invalid, or has been revoked.")
except InveSpiderRateLimitError:
    print("Rate limit exceeded for this key -- wait 24h or use a different key.")
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

This package is prepared for PyPI publication but has not yet been
published or uploaded.
