Metadata-Version: 2.4
Name: qaiss-sdk
Version: 0.1.0
Summary: Official Python SDK for QAISS — Non-blocking telemetry, observability, and passive auditing for AI agents and LLMs.
License-Expression: Apache-2.0
Project-URL: Homepage, https://qaiss.com
Project-URL: Documentation, https://docs.qaiss.com
Project-URL: Repository, https://github.com/QodeRepo/qaiss-tools-sdk
Project-URL: Changelog, https://github.com/QodeRepo/qaiss-tools-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/QodeRepo/qaiss-tools-sdk/issues
Keywords: llm,ai-agents,observability,telemetry,opentelemetry,guardrails,monitoring,hallucination-detection,fastapi,flask,django
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic<3.0.0,>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"
Dynamic: license-file

# QAISS SDK Monorepo (`QodeRepo-sdk`)

Welcome to the **QAISS SDK Monorepo**. This repository contains the lightweight, non-blocking client SDKs that power the **QAISS LLM Security & Observability Platform**.

---

## 🎯 The Mission
QAISS is a **Passive AI Auditing Platform**. It silently captures the exact JSON payloads returned by tools, databases, and APIs. This ground-truth data is evaluated by our backend 4-Stage Judge engine to provide clients with undeniable proof of:
1. **Data Hallucinations:** When the LLM's response contradicts database facts.
2. **Access Control Leaks (BOLA/IDOR):** When User A accesses data belonging to User B.
3. **Broken Workflows:** When tools are executed in an unauthorized or invalid order.

---

## 📂 Repository Structure

```text
QodeRepo-sdk/
├── python/
│   ├── pyproject.toml             # Packaging & build configuration (v0.1.0)
│   └── qaiss/
│       ├── __init__.py            # 1-line init (`qaiss.init()`) & public exports
│       ├── core.py                # Pure Python framework-agnostic request engine
│       ├── asgi.py                # Universal ASGI 3.0 middleware (FastAPI, Litestar, Quart)
│       ├── wsgi.py                # Universal WSGI PEP 3333 middleware (Flask, Bottle, Falcon)
│       ├── django_middleware.py   # Django native middleware (with request.user visibility)
│       ├── middleware.py          # Backward-compat shim
│       ├── client.py              # QaissClient core runtime & lifecycle manager
│       ├── context.py             # Async/thread-isolated ContextVar security context
│       ├── decorator.py           # @client.track_tool & @client.track_agent decorators
│       ├── instrumentation.py     # Universal choke-point monkey-patching & noise filtering
│       ├── models.py              # Pydantic wire schema (QaissEventModel, SecurityContext)
│       ├── redaction.py           # PII scrubber (Luhn credit cards, SSN, Emails, sensitive keys)
│       ├── truncation.py          # Smart structural field-level payload truncator (64 KB)
│       └── transport.py           # Non-blocking bounded background worker (micro-batching)
├── tests/                         # Comprehensive unit, integration, and concurrency test suite
├── examples/                      # Live runnable client examples
├── docs/                          # Architecture & client integration guides
├── shared/
│   └── schema.json                # Universal JSON Schema contract
└── README.md
```

---

## 🌐 Framework Support: Universal Protocol Architecture

QAISS provides **framework independence** via protocol-level adapters built over a single, zero-dependency core engine (`QaissRequestEngine`):

### 1. Universal Coverage (Zero SDK Code for New Frameworks)
- **`QaissASGIMiddleware` (ASGI 3.0)**: Supports **every** current and future ASGI framework (FastAPI, Starlette, Litestar, Quart, BlackSheep, Sanic, Django ASGI). Features immediate chunk passthrough so token-by-token streaming (SSE) is never delayed.
- **`QaissWSGIMiddleware` (WSGI PEP 3333)**: Supports **every** current and future WSGI framework (Flask, Bottle, Pyramid, Falcon, CherryPy, Django WSGI).

### 2. Optional Enhanced Integration
- **`QaissDjangoMiddleware`**: A thin translator over `QaissRequestEngine` that extracts Django's post-auth `request.user` which is only visible within Django's internal middleware pipeline.

---

## 🚀 Quickstart (Python)

### 1. Installation
```bash
pip install qaiss-sdk
```

### 2. Framework-Independent Integration

#### A. FastAPI / Starlette / Litestar / Quart (ASGI)
```python
from fastapi import FastAPI
import qaiss
from qaiss import QaissASGIMiddleware

app = FastAPI()
client = qaiss.init(api_key="your_api_key", environment="production")
app.add_middleware(QaissASGIMiddleware, qaiss_client=client)
```

#### B. Flask / Bottle / Falcon / Pyramid (WSGI)
```python
from flask import Flask
import qaiss
from qaiss import QaissWSGIMiddleware

app = Flask(__name__)
client = qaiss.init(api_key="your_api_key", environment="production")
app.wsgi_app = QaissWSGIMiddleware(app.wsgi_app, qaiss_client=client)
```

#### C. Django (`settings.py`)
```python
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    # ... other middlewares ...
    "qaiss.django_middleware.QaissDjangoMiddleware",  # ⬅️ Add 1 line
]

QAISS_API_KEY = "your_api_key"
QAISS_ENVIRONMENT = "production"
```

---

## ⚙️ Key Technical Guarantees
1. **Zero-Touch Auto-Instrumentation:** Automatically intercepts LLMs (OpenAI, Anthropic, Gemini), Agent frameworks (Agno, LangChain, CrewAI, LlamaIndex), and HTTP calls (Requests, HTTPX).
2. **Streaming Preserved:** ASGI streaming/SSE responses are forwarded immediately to clients with 0ms buffering delay.
3. **Multi-Tenant Async Isolation:** Request-scoped `ContextVar` client resolution guarantees zero crosstalk across concurrent tenants.
4. **Local PII Redaction:** Credit card numbers (Luhn-verified), SSNs, Emails, and secrets are scrubbed in-flight before leaving process memory.
5. **Smart Structural Truncation:** Payloads are capped at 64 KB with cycle-safe ancestor stacks to prevent memory leaks and false-positive cycle errors.
