Metadata-Version: 2.4
Name: hyperaim-sdk
Version: 1.0.0
Summary: HyperSDK — AIM Intelligence Middleware. Add telemetry, quality scoring, rate limiting, anomaly detection, and demand prediction to any HyperCycle AIM with 2 lines of code.
Author-email: QyraTech <info@qyratech.com>
License: MIT
Project-URL: Homepage, https://github.com/qyratech/hyperaim-sdk
Project-URL: Documentation, http://62.171.162.38:8095/docs
Project-URL: Repository, https://github.com/qyratech/hyperaim-sdk
Keywords: hypercycle,aim,ai,telemetry,intelligence,sdk,hypersdk,middleware
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: fastapi>=0.100.0

# HyperSDK

**AIM Intelligence Middleware for the HyperCycle IoAI Network.**

Add intelligence to any AIM with 2 lines of code.

```python
from hyperaim_sdk import HyperSDK
hs = HyperSDK(app, api_key="qt_your_key_here", aim_name="my-aim")
```

## What You Get (Free Tier)

- **Automatic telemetry** — every request tracked: latency, errors, callers, endpoints
- **Live /health endpoint** — uptime, error rate, avg latency, unique callers
- **Live /qt/stats endpoint** — detailed rolling metrics with percentiles
- **Per-caller rate limiting** — protect your AIM from abuse
- **Request ID tracking** — trace any request via response headers
- **Batched telemetry upload** — minimal overhead, flushes every 60s

## Intelligence Engine (powered by QyraTech)

Your telemetry feeds the QyraTech Intelligence Server, which provides:

- **Quality scoring** — reliability, performance, demand, consistency (0-100 each)
- **Anomaly detection** — latency spikes, error bursts, traffic drops detected automatically
- **Demand prediction** — peak hours, trend direction, future call volume
- **Network rankings** — how your AIM compares to all others on the IoAI
- **Cross-AIM patterns** — which AIMs are frequently used together

## Installation

```bash
pip install hyperaim-sdk
```

## Quick Start

```python
from fastapi import FastAPI
from hyperaim_sdk import HyperSDK

app = FastAPI(title="My AIM")

# Register at http://62.171.162.38:8095/register to get your API key
hs = HyperSDK(
    app,
    api_key="qt_your_key_here",
    aim_name="my-awesome-aim",
)

@app.post("/my-endpoint")
async def my_endpoint():
    # Your AIM logic here — HyperSDK tracks everything automatically
    return {"result": "hello"}
```

## Configuration

```python
hs = HyperSDK(
    app,
    api_key="qt_...",                    # Required: your API key
    aim_name="my-aim",                   # Name shown in dashboards
    server_url="http://62.171.162.38:8095",  # Intelligence server
    rate_limit=100,                      # Max requests per window per caller
    rate_window=60,                      # Rate limit window in seconds
    flush_interval=60,                   # Telemetry flush interval in seconds
    enable_telemetry=True,               # Send telemetry to server
    enable_rate_limiting=True,           # Enable per-caller rate limiting
    enable_health=True,                  # Add /health endpoint
    enable_stats=True,                   # Add /qt/stats endpoint
    excluded_paths=["/health", "/docs"], # Paths to skip tracking
)
```

## Response Headers

Every tracked request gets these headers:

| Header | Description |
|--------|-------------|
| `X-Request-ID` | Unique request identifier |
| `X-HyperSDK` | SDK version |
| `X-Response-Time-Ms` | Request latency in milliseconds |

## Endpoints Added

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check with live stats |
| `GET /qt/stats` | Detailed rolling metrics |
| `GET /qt/rate-limit` | Current rate limit status for caller |

## Get Your API Key

```bash
curl -X POST http://62.171.162.38:8095/register \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-aim", "owner": "your-name", "url": "http://your-server:port"}'
```

## View Your Dashboard

```
http://62.171.162.38:8095/dashboard/{your_aim_id}
```

## Built By

**QyraTech** — AI Agent Intelligence Infrastructure on the HyperCycle IoAI Network.

- Intelligence Server: http://62.171.162.38:8095
- QyraTech Home: http://62.171.162.38:8085
- HyperCycle: https://www.hypercycle.ai
