hyperaim-sdk 1.0.0__py3-none-any.whl

hyperaim_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+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

hyperaim_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+hyperaim_sdk.py,sha256=rUXEY5J4RQ1MMfsDanBvTwt8cdwIAiuQj9Htp1Tg9r4,12978
+hyperaim_sdk-1.0.0.dist-info/METADATA,sha256=kWPa3G8oHKoireM01KOhGlksUEB7JKOvqduN93_fqUg,4536
+hyperaim_sdk-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hyperaim_sdk-1.0.0.dist-info/top_level.txt,sha256=KX5AIpd0HEnm-kgb_IyV2Z8fqovTmMf9n-CjD1Pv-oM,13
+hyperaim_sdk-1.0.0.dist-info/RECORD,,

hyperaim_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hyperaim_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hyperaim_sdk

hyperaim_sdk.py

@@ -0,0 +1,380 @@
+"""
+HyperSDK v1.0.0 — AIM Intelligence Middleware
+
+Add intelligence to any HyperCycle AIM with 2 lines of code:
+
+    from hypersdk import HyperSDK
+    hs = HyperSDK(app, api_key="qt_your_key_here")
+
+What you get for free:
+    - Automatic request telemetry (latency, errors, callers)
+    - /health endpoint with live stats
+    - /qt/stats endpoint with detailed metrics
+    - Rate limiting per caller
+    - Request ID tracking
+    - Automatic batched telemetry upload
+
+What the intelligence server does with your data:
+    - Quality scoring (reliability, performance, demand, consistency)
+    - Anomaly detection (latency spikes, error bursts, traffic drops)
+    - Demand prediction (when your peak hours are, trend direction)
+    - Network-wide AIM rankings
+    - Cross-AIM correlation patterns
+
+Published by QyraTech — AI Agent Intelligence Infrastructure
+https://github.com/qyratech/hypersdk
+"""
+
+import time
+import uuid
+import hashlib
+import asyncio
+import threading
+import statistics
+from collections import deque, defaultdict
+from datetime import datetime, timezone
+from typing import Optional, Callable
+
+try:
+    import httpx
+except ImportError:
+    httpx = None
+
+__version__ = "1.0.0"
+__author__ = "QyraTech"
+
+# Default intelligence server
+DEFAULT_SERVER = "http://62.171.162.38:8095"
+
+
+class TelemetryBuffer:
+    """Thread-safe buffer that batches telemetry events and flushes periodically."""
+
+    def __init__(self, server_url: str, api_key: str, flush_interval: int = 60,
+                 max_buffer: int = 500):
+        self.server_url = server_url
+        self.api_key = api_key
+        self.flush_interval = flush_interval
+        self.max_buffer = max_buffer
+        self.buffer = deque(maxlen=max_buffer)
+        self._running = False
+        self._flush_task = None
+
+    def add(self, event: dict):
+        self.buffer.append(event)
+        if len(self.buffer) >= self.max_buffer:
+            asyncio.ensure_future(self.flush())
+
+    async def flush(self):
+        if not self.buffer or not httpx:
+            return
+
+        events = []
+        while self.buffer:
+            try:
+                events.append(self.buffer.popleft())
+            except IndexError:
+                break
+
+        if not events:
+            return
+
+        try:
+            async with httpx.AsyncClient() as client:
+                await client.post(
+                    f"{self.server_url}/telemetry",
+                    json={"events": events},
+                    headers={"Authorization": f"Bearer {self.api_key}"},
+                    timeout=10,
+                )
+        except Exception:
+            # Re-add failed events (best effort)
+            for e in events[:50]:
+                self.buffer.appendleft(e)
+
+    async def start_periodic_flush(self):
+        self._running = True
+        while self._running:
+            await asyncio.sleep(self.flush_interval)
+            await self.flush()
+
+    def stop(self):
+        self._running = False
+
+
+class RateLimiter:
+    """Per-caller sliding window rate limiter."""
+
+    def __init__(self, max_requests: int = 100, window_seconds: int = 60):
+        self.max_requests = max_requests
+        self.window = window_seconds
+        self.callers = defaultdict(deque)
+
+    def is_allowed(self, caller_id: str) -> bool:
+        now = time.time()
+        window = self.callers[caller_id]
+
+        # Remove expired entries
+        while window and window[0] < now - self.window:
+            window.popleft()
+
+        if len(window) >= self.max_requests:
+            return False
+
+        window.append(now)
+        return True
+
+    def get_usage(self, caller_id: str) -> dict:
+        now = time.time()
+        window = self.callers[caller_id]
+        while window and window[0] < now - self.window:
+            window.popleft()
+        return {
+            "used": len(window),
+            "limit": self.max_requests,
+            "remaining": max(0, self.max_requests - len(window)),
+            "window_seconds": self.window,
+        }
+
+
+class LiveStats:
+    """Real-time rolling statistics for the AIM."""
+
+    def __init__(self, window_size: int = 1000):
+        self.window_size = window_size
+        self.latencies = deque(maxlen=window_size)
+        self.status_codes = deque(maxlen=window_size)
+        self.endpoints = defaultdict(int)
+        self.callers = set()
+        self.total_requests = 0
+        self.total_errors = 0
+        self.start_time = time.time()
+        self._hourly_calls = defaultdict(int)
+
+    def record(self, latency_ms: float, status_code: int, endpoint: str, caller: str):
+        self.latencies.append(latency_ms)
+        self.status_codes.append(status_code)
+        self.endpoints[endpoint] += 1
+        self.callers.add(caller)
+        self.total_requests += 1
+        if status_code >= 400:
+            self.total_errors += 1
+
+        hour = datetime.now(timezone.utc).strftime("%H")
+        self._hourly_calls[hour] += 1
+
+    def get_stats(self) -> dict:
+        uptime = time.time() - self.start_time
+        lats = list(self.latencies)
+        sorted_lats = sorted(lats) if lats else [0]
+
+        return {
+            "uptime_seconds": round(uptime),
+            "total_requests": self.total_requests,
+            "total_errors": self.total_errors,
+            "error_rate_pct": round(self.total_errors / max(self.total_requests, 1) * 100, 2),
+            "unique_callers": len(self.callers),
+            "requests_per_minute": round(self.total_requests / max(uptime / 60, 1), 2),
+            "latency": {
+                "avg_ms": round(statistics.mean(lats), 1) if lats else 0,
+                "p50_ms": round(sorted_lats[len(sorted_lats) // 2], 1) if sorted_lats else 0,
+                "p95_ms": round(sorted_lats[int(len(sorted_lats) * 0.95)], 1) if len(sorted_lats) > 1 else 0,
+                "p99_ms": round(sorted_lats[int(len(sorted_lats) * 0.99)], 1) if len(sorted_lats) > 1 else 0,
+                "min_ms": round(min(lats), 1) if lats else 0,
+                "max_ms": round(max(lats), 1) if lats else 0,
+            },
+            "top_endpoints": dict(sorted(self.endpoints.items(),
+                                         key=lambda x: x[1], reverse=True)[:10]),
+            "hourly_distribution": dict(self._hourly_calls),
+        }
+
+
+class HyperSDK:
+    """
+    HyperSDK — AIM Intelligence Middleware.
+
+    Wraps a FastAPI app with automatic telemetry, rate limiting,
+    health endpoints, and intelligence server reporting.
+
+    Usage:
+        from fastapi import FastAPI
+        from hypersdk import HyperSDK
+
+        app = FastAPI()
+        hs = HyperSDK(
+            app,
+            api_key="qt_your_key_here",
+            aim_name="my-awesome-aim",
+        )
+    """
+
+    def __init__(
+        self,
+        app,
+        api_key: str,
+        aim_name: str = "unknown",
+        server_url: str = DEFAULT_SERVER,
+        rate_limit: int = 100,
+        rate_window: int = 60,
+        flush_interval: int = 60,
+        enable_telemetry: bool = True,
+        enable_rate_limiting: bool = True,
+        enable_health: bool = True,
+        enable_stats: bool = True,
+        excluded_paths: list = None,
+    ):
+        self.app = app
+        self.api_key = api_key
+        self.aim_name = aim_name
+        self.server_url = server_url
+        self.enable_telemetry = enable_telemetry
+        self.enable_rate_limiting = enable_rate_limiting
+        self.excluded_paths = set(excluded_paths or [
+            "/health", "/qt/stats", "/qt/rate-limit", "/docs",
+            "/openapi.json", "/favicon.ico",
+        ])
+
+        self.stats = LiveStats()
+        self.rate_limiter = RateLimiter(rate_limit, rate_window) if enable_rate_limiting else None
+        self.telemetry = TelemetryBuffer(server_url, api_key, flush_interval) if enable_telemetry else None
+
+        # Add middleware
+        self._add_middleware()
+
+        # Add endpoints
+        if enable_health:
+            self._add_health_endpoint()
+        if enable_stats:
+            self._add_stats_endpoint()
+        if enable_rate_limiting:
+            self._add_rate_limit_endpoint()
+
+        # Start periodic flush
+        if self.telemetry:
+            @app.on_event("startup")
+            async def _start_telemetry():
+                asyncio.create_task(self.telemetry.start_periodic_flush())
+
+            @app.on_event("shutdown")
+            async def _stop_telemetry():
+                await self.telemetry.flush()
+                self.telemetry.stop()
+
+    def _caller_hash(self, request) -> str:
+        ip = request.client.host if request.client else "unknown"
+        return hashlib.md5(ip.encode()).hexdigest()[:12]
+
+    def _add_middleware(self):
+        sdk = self
+
+        @self.app.middleware("http")
+        async def qyratech_middleware(request, call_next):
+            path = request.url.path
+            caller = sdk._caller_hash(request)
+
+            # Skip excluded paths
+            if path in sdk.excluded_paths:
+                return await call_next(request)
+
+            # Rate limiting
+            if sdk.rate_limiter and not sdk.rate_limiter.is_allowed(caller):
+                from fastapi.responses import JSONResponse
+                return JSONResponse(
+                    status_code=429,
+                    content={
+                        "error": "Rate limit exceeded",
+                        "retry_after_seconds": sdk.rate_limiter.callers[caller][0] + sdk.rate_limiter.window - time.time()
+                        if sdk.rate_limiter.callers.get(caller) else 60,
+                    },
+                    headers={"X-HyperSDK": __version__},
+                )
+
+            # Track request
+            request_id = str(uuid.uuid4())[:8]
+            start = time.time()
+
+            try:
+                response = await call_next(request)
+                latency_ms = round((time.time() - start) * 1000, 2)
+                status_code = response.status_code
+
+                # Record stats
+                sdk.stats.record(latency_ms, status_code, path, caller)
+
+                # Buffer telemetry event
+                if sdk.telemetry:
+                    sdk.telemetry.add({
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
+                        "endpoint": path,
+                        "method": request.method,
+                        "status_code": status_code,
+                        "latency_ms": latency_ms,
+                        "caller_hash": caller,
+                        "error_type": None,
+                    })
+
+                # Add tracking headers
+                response.headers["X-Request-ID"] = request_id
+                response.headers["X-HyperSDK"] = __version__
+                response.headers["X-Response-Time-Ms"] = str(latency_ms)
+
+                return response
+
+            except Exception as e:
+                latency_ms = round((time.time() - start) * 1000, 2)
+                sdk.stats.record(latency_ms, 500, path, caller)
+
+                if sdk.telemetry:
+                    sdk.telemetry.add({
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
+                        "endpoint": path,
+                        "method": request.method,
+                        "status_code": 500,
+                        "latency_ms": latency_ms,
+                        "caller_hash": caller,
+                        "error_type": type(e).__name__,
+                    })
+                raise
+
+    def _add_health_endpoint(self):
+        sdk = self
+
+        @self.app.get("/health")
+        async def qt_health():
+            stats = sdk.stats.get_stats()
+            return {
+                "status": "ok",
+                "aim": sdk.aim_name,
+                "sdk_version": __version__,
+                "uptime_seconds": stats["uptime_seconds"],
+                "total_requests": stats["total_requests"],
+                "error_rate_pct": stats["error_rate_pct"],
+                "avg_latency_ms": stats["latency"]["avg_ms"],
+                "unique_callers": stats["unique_callers"],
+                "intelligence_server": sdk.server_url,
+                "telemetry_enabled": sdk.enable_telemetry,
+                "rate_limiting_enabled": sdk.enable_rate_limiting,
+            }
+
+    def _add_stats_endpoint(self):
+        sdk = self
+
+        @self.app.get("/qt/stats")
+        async def qt_stats():
+            return {
+                "aim": sdk.aim_name,
+                "sdk_version": __version__,
+                "stats": sdk.stats.get_stats(),
+                "telemetry_buffer_size": len(sdk.telemetry.buffer) if sdk.telemetry else 0,
+            }
+
+    def _add_rate_limit_endpoint(self):
+        sdk = self
+        from fastapi import Request as FastAPIRequest
+
+        @self.app.get("/qt/rate-limit")
+        async def qt_rate_limit(request: FastAPIRequest):
+            caller = sdk._caller_hash(request)
+            if sdk.rate_limiter:
+                return sdk.rate_limiter.get_usage(caller)
+            return {"rate_limiting": "disabled"}