Metadata-Version: 2.4
Name: tqnn
Version: 2.0.1
Summary: Official Python SDK for the TQNN Fault-Tolerant Inference Platform.
Author: TQNN Labs
License: MIT
Project-URL: Homepage, https://tqnnlabs.com
Project-URL: Documentation, https://tqnn-anyengine-api-914075492772.northamerica-northeast1.run.app/docs
Project-URL: Repository, https://github.com/tqnnlabs/tqnn-sdk
Project-URL: Issues, https://github.com/tqnnlabs/tqnn-sdk/issues
Project-URL: API, https://github.com/tqnnlabs/tqnn-anyengine-api
Project-URL: PyPI, https://pypi.org/project/tqnn/
Keywords: tqnn,python-sdk,api-client,inference,fault-tolerant-inference,confidence-aware,structured-data,diagnostics,machine-learning,rest-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# TQNN Python SDK

Official Python SDK for the **TQNN Fault-Tolerant Inference Platform**.

The TQNN Python SDK provides a lightweight interface for interacting with the managed TQNN cloud runtime.

Build confidence-aware applications that continue operating when real-world data is noisy, incomplete, uncertain, or partially unavailable.

---

# Features

- Official Python SDK for TQNN
- Managed cloud inference
- Confidence-aware predictions
- Input-integrity reporting
- Controlled decision states
- Runtime diagnostics
- Domain-agnostic inference
- Zero endpoint configuration

---

# Installation

```bash
pip install -U tqnn
```

---

# Requirements

- Python 3.9+
- Active TQNN API key

Don't have one yet?

Create a free **Explorer** account and receive **100 free API calls** at:

**https://tqnnlabs.com**

---

# Quick Start

```python
from tqnn import TQNNClient

client = TQNNClient(
    api_key="TQNN_xxxxxxxxxxxxxxxxx"
)

response = client.run_any(
    data=[1.2, 1.4, 1.6, 2.1],
    mode="TABULAR",
    task="fault_diagnosis"
)

print(response)
```

The SDK automatically connects to the official TQNN cloud runtime.

No endpoint configuration is required.

---

# Creating a Client

```python
from tqnn import TQNNClient

client = TQNNClient(
    api_key="YOUR_API_KEY"
)
```

---

# Running Inference

```python
response = client.run_any(
    data=data,
    mode="TABULAR",
    task="fault_diagnosis",
    label="pump_sensor_window",
    metadata={
        "class_labels": [
            "healthy",
            "fault"
        ]
    }
)
```

---

# Parameters

| Parameter | Description |
|------------|-------------|
| data | Structured numerical input |
| mode | EEG, FINANCE, TABULAR, IMAGE or ANY |
| task | Optional inference context |
| label | Optional request label |
| sfreq | Optional sampling frequency |
| metadata | Optional application metadata |

---

# Example Response

```json
{
  "platform": "TQNN",
  "engine": "TQNN Fault-Tolerant Inference Engine",
  "engine_version": "2.0.0",
  "mode": "TABULAR",

  "result": {
    "prediction_index": 1,
    "prediction_label": "fault",
    "confidence": 0.94,
    "decision": "ACCEPT"
  },

  "tqnn_report": {
    "primary_capability": "fault-tolerant inference",

    "confidence": {
      "score": 0.94,
      "label": "high",
      "margin": 0.28,
      "entropy": 0.17
    },

    "data_integrity": {
      "score": 0.98,
      "label": "valid",
      "feature_count": 4,
      "finite_fraction": 1.0,
      "missing_fraction": 0.0,
      "constant_input": false
    },

    "decision": {
      "status": "ACCEPT",
      "threshold_met": true
    },

    "warnings": []
  },

  "diagnostics": {
    "probabilities": [0.06, 0.94],
    "confidence_margin": 0.28,
    "normalized_entropy": 0.17,
    "acceptance_threshold": 0.61,
    "threshold_met": true,
    "qualia": {},
    "intent": [],
    "meta": {}
  }
}
```

---

# Convenience Methods

```python
result = client.result(response)

report = client.report(response)

diagnostics = client.diagnostics(response)
```

---

# Decision States

Every inference returns a standardized decision.

- ACCEPT
- REVIEW
- REJECT

Applications can use these states to determine whether an inference should proceed automatically or be reviewed before action.

---

# Supported Modes

| Mode | Description |
|------|-------------|
| ANY | Domain-agnostic inference |
| TABULAR | Structured datasets |
| EEG | Biosignal inference |
| FINANCE | Financial time-series |
| IMAGE | Structured image features |

---

# Example Applications

- Fault Detection
- Fault Diagnosis
- Industrial Monitoring
- Sensor Health
- Predictive Maintenance
- Biosignal Analysis
- Financial Analytics
- Scientific Data
- General Structured Data

---

# Error Handling

```python
try:
    response = client.run_any(
        data=data,
        mode="TABULAR"
    )

except Exception as e:
    print(e)
```

---

# Best Practices

Store API keys using environment variables.

```bash
export TQNN_API_KEY="TQNN_xxxxxxxxxxxxxxxxx"
```

```python
import os
from tqnn import TQNNClient

client = TQNNClient(
    api_key=os.environ["TQNN_API_KEY"]
)
```

Never commit API keys to public repositories.

---

# Version Compatibility

This SDK targets the public **TQNN Fault-Tolerant Inference API v2**.

Future SDK releases will remain compatible with the evolving public API contract.

---

# Philosophy

The SDK is intentionally lightweight.

Rather than abstracting platform responses, it exposes the complete standardized output returned by the managed runtime.

Applications receive:

- Predictions
- Confidence scores
- Decision states
- Input-integrity metrics
- Runtime diagnostics
- Structured metadata

This allows developers to build reliable systems while retaining full visibility into every inference.

---

# License

The TQNN Python SDK is released under the MIT License.

### Open Source

- Python SDK
- Client utilities
- Integration helpers
- Example code

### Proprietary

- Managed inference runtime
- Execution substrate
- Platform orchestration
- Production infrastructure

---

# About TQNN Labs

TQNN Labs develops cloud-hosted fault-tolerant inference infrastructure for applications operating on noisy, incomplete, uncertain, or unreliable data.

The platform combines:

- Hybrid quantum-classical execution
- Confidence-aware inference
- Input-integrity reporting
- Controlled decision logic
- Managed cloud deployment

Website:

**https://tqnnlabs.com**

Built in Canada 🇨🇦

---

# Vision

TQNN Labs is building infrastructure that helps applications understand not only **what** was predicted, but **how confidently** that prediction can be trusted.

Reliable inference should continue working even when real-world data does not.

**Build once. Infer through uncertainty.**
