TQNN Fault-Tolerant Inference API

Public API version: 2.0.1

Commercial fault-tolerant inference infrastructure from TQNN Labs.

TQNN is a managed cloud platform for confidence-aware inference under noisy, incomplete, corrupted, or uncertain real-world data conditions.

Instead of returning only a prediction, every successful inference includes confidence scoring, input-integrity analysis, controlled decision logic, and public runtime diagnostics.

Developers can integrate through the REST API or the official Python SDK without deploying the private TQNN core or managing specialized hardware.

Core capability

Fault-tolerant, confidence-aware inference under imperfect data conditions.

TQNN evaluates both the prediction and the integrity of the supplied input before producing a controlled decision.

Applications can distinguish between:

accepted predictions;
results requiring review;
rejected results;
missing or non-finite inputs;
constant or low-information inputs;
results that do not meet the configured acceptance threshold.

TQNN does not invent the real-world meaning of arbitrary data. The caller supplies the intended task and, when applicable, class labels and domain metadata.

Get started

1. Create an Explorer account

Visit tqnnlabs.com and create a free Explorer account.

The API key is delivered by email and is never returned by the signup endpoint.

Explorer includes:

100 API calls;
Python SDK access;
REST API access;
hosted cloud execution;
confidence-aware inference;
public runtime diagnostics.

2. Install the Python SDK

pip install -U tqnn

3. Run an inference

from tqnn import TQNNClient

client = TQNNClient(
    api_key="TQNN_xxxxxxxxxxxxxxxxx"
)

response = client.run_any(
    data=[1, 2, 3, 4],
    mode="TABULAR",
    task="fault_diagnosis",
    label="example",
    metadata={
        "class_labels": [
            "healthy",
            "fault"
        ]
    }
)

print(response)

The official SDK connects to the managed public endpoint automatically. Normal SDK use does not require base-URL configuration.

REST API

Endpoint

POST /run/any

Authentication

Every inference request requires an API key:

x-api-key: TQNN_xxxxxxxxxxxxxxxxx

Keep API keys private. Do not place them in source code, notebooks committed to GitHub, browser-side JavaScript, screenshots, or public logs.

Use an environment variable whenever possible:

export TQNN_API_KEY="TQNN_xxxxxxxxxxxxxxxxx"

Request contract

Field	Type	Required	Description
`data`	any JSON-compatible value	yes	Input supplied to the selected inference path.
`mode`	string	no	Inference mode or accepted alias. Defaults to `ANY`.
`task`	string or null	no	Caller-defined task, such as `fault_diagnosis`.
`label`	string or null	no	Optional caller-defined label for the request.
`sfreq`	number or null	no	Sampling frequency for time-series or EEG inputs.
`metadata`	object	no	Caller metadata, including optional class labels or source information.

When sfreq is supplied, the API forwards it both as a top-level field and inside metadata for runtime compatibility.

Example request

curl -X POST "https://YOUR_API_ENDPOINT/run/any" \
  -H "Content-Type: application/json" \
  -H "x-api-key: TQNN_xxxxxxxxxxxxxxxxx" \
  -d '{
    "data": [1, 2, 3, 4],
    "mode": "TABULAR",
    "task": "fault_diagnosis",
    "label": "example",
    "metadata": {
      "class_labels": ["healthy", "fault"],
      "source": "curl-demo"
    }
  }'

Modes and aliases

The API accepts canonical mode names and compatibility aliases. Mode names are case-insensitive and normalized to uppercase before the private core receives them.

Input family	Accepted names
Domain-agnostic or tabular	`ANY`, `GENERIC`, `NUMERIC`, `VECTOR`, `TABLE`, `TABULAR`
Time-series	`TIME`, `SENSOR`, `SENSORS`, `TIMESERIES`, `TIME-SERIES`, `TIME_SERIES`, `SEQUENCE`
EEG	`EEG`
Finance	`FINANCE`
Text	`TEXT`, `NLP`, `STRING`
Image	`IMAGE`, `PIXELS`, `VISION`

The private core remains the authority that resolves an accepted request name to its internal intermediate representation.

Stable successful-response contract

Every successful inference returns these top-level fields:

platform
engine
engine_version
mode
task
label
result
tqnn_report
diagnostics

Example response shape

{
  "platform": "TQNN",
  "engine": "TQNNCoreEngine",
  "engine_version": "2.0.1",
  "mode": "TABULAR",
  "task": "fault_diagnosis",
  "label": "example",
  "result": {
    "prediction_index": 1,
    "prediction_label": "fault",
    "confidence": 0.76,
    "decision": "accept"
  },
  "tqnn_report": {
    "primary_capability": "Fault Diagnosis",
    "task": "fault_diagnosis",
    "inference_mode": "tabular",
    "confidence": {
      "score": 0.76,
      "label": "high",
      "margin": 0.52,
      "normalized_entropy": 0.79
    },
    "data_integrity": {
      "score": 1.0,
      "label": "nominal",
      "feature_count": 4,
      "finite_fraction": 1.0,
      "missing_fraction": 0.0,
      "constant_input": false
    },
    "decision": {
      "status": "accept",
      "threshold_met": true
    },
    "warnings": []
  },
  "diagnostics": {
    "probabilities": [0.24, 0.76],
    "acceptance_threshold": 0.70,
    "threshold_met": true,
    "confidence_margin": 0.52,
    "normalized_entropy": 0.79,
    "qualia": null,
    "intent": [],
    "meta": {
      "probability_source": "completed_chunks"
    }
  }
}

The values above illustrate the schema only. Actual values depend on the supplied input, task, runtime configuration, and model state.

Result

result provides the primary prediction:

prediction_index;
prediction_label;
confidence;
decision.

TQNN report

tqnn_report provides the public interpretation layer:

primary capability;
task and inference mode;
confidence score, label, margin, and normalized entropy;
data-integrity score and diagnostics;
controlled decision status;
warnings.

Diagnostics

diagnostics provides the public numerical context behind the decision:

output probabilities;
acceptance threshold;
threshold status;
confidence margin;
normalized entropy;
public qualia and intent fields;
allowlisted metadata.

The public API currently permits probability_source inside diagnostics.meta. Undeclared diagnostic metadata and private-core fields are removed before the response reaches the client.

Controlled decisions

Decision states include:

accept;
review;
reject.

Applications should use the returned decision status and integrity report rather than relying only on the highest probability.

A high probability does not automatically prove that an input is reliable, in-domain, or safe for autonomous action.

Input integrity

Public integrity reporting includes:

feature count;
finite-value fraction;
missing-value fraction;
constant-input detection;
integrity score and label;
warnings associated with degraded inputs.

Input-integrity reporting describes detectable properties of the submitted data. It is not a guarantee that the caller assigned the correct real-world task or supplied representative training data.

Error behavior

The API returns controlled public errors without exposing private-core bodies, internal traces, credentials, circuit details, or infrastructure responses.

Status	Meaning
`400`	Invalid signup, checkout, email, webhook, or other public request.
`401`	Missing, invalid, inactive, deleted, or otherwise unauthorized API key.
`402`	Paid subscription is inactive.
`403`	The API key has no configured quota or access is forbidden.
`409`	An Explorer key has already been issued for the normalized email.
`422`	Unsupported mode or inference-request validation failure.
`429`	API quota exhausted.
`502`	Private core unavailable, unauthorized internally, invalid, or outside the public response contract.
`503`	A required public service, such as Explorer email delivery, is unavailable.
`504`	Private-core request timed out.

Usage and quota enforcement

Usage is counted only after the private core returns a valid public response.

The final usage update runs inside a Firestore transaction that rechecks:

key existence;
active status;
configured quota;
current usage.

This prevents concurrent requests from silently recording usage beyond the configured limit. When the quota is exhausted, the API returns 429 with the plan, quota, usage, remaining calls, and upgrade URL.

Public/private boundary

The public API does not return the private core response dictionary directly.

Before delivery, the response is:

validated against the complete nested public contract;
reconstructed through public response models;
filtered to remove undeclared fields;
restricted to approved diagnostic metadata.

This boundary protects contract stability and reduces the risk of proprietary execution details being exposed accidentally.

Versioning

TQNN components are versioned independently:

Field or package	Meaning
`api_version`	Version of the public API service. Current release: `2.0.1`.
`engine_version`	Version reported by the private TQNN core for the executed inference.
Python SDK version	Version of the separately distributed `tqnn` client package.

These values are not required to match. An API hardening release does not imply that the private inference engine or SDK changed.

Health endpoint

GET /health

The health response reports public service configuration state, including:

service name;
API version;
core configuration;
internal authentication configuration;
Firestore availability;
email and Stripe configuration;
Explorer quota;
paid-tier price configuration.

The endpoint returns configuration booleans, not credentials or secret values.

Automated contract testing

The repository includes:

tests/test_inference_contract.py
.github/workflows/contract-tests.yml
requirements-dev.txt

The GitHub Actions workflow runs on relevant pushes and pull requests under Python 3.11.

Coverage includes:

nested core-response validation;
undeclared-field removal;
diagnostic metadata allowlisting;
mode aliases;
sampling-frequency payload behavior;
usage ordering;
private error redaction;
atomic quota enforcement;
inactive, deleted, and exhausted keys;
API version reporting;
Pydantic compatibility helpers.

The workflow does not require production credentials and does not consume TQNN API calls.

Dependency policy

Production dependencies use bounded compatibility ranges.

The ranges allow compatible updates while preventing unreviewed major-version upgrades from changing production behavior unexpectedly. The GitHub Actions contract suite installs from a fresh environment to verify that the selected dependency set remains compatible.

Subscription plans

Plan	Price	Included calls
Explorer	Free	100
Starter	CA$23.99/month	10,000
Builder	CA$79.99/month	50,000
Scale	CA$249.99/month	200,000

Current plan details and signup are available at tqnnlabs.com.

Managed cloud runtime

Applications can connect using standard HTTPS requests from:

Python applications;
backend services;
desktop and mobile applications;
embedded and sensor systems;
research notebooks;
automation pipelines.

No local private-core deployment or specialized client hardware is required.

Security

The platform uses:

API-key authentication;
HTTPS transport;
Google-signed identity tokens between the public API and private Cloud Run core;
an internal application-secret layer;
hashed API-key storage;
managed execution;
runtime isolation;
transactional usage metering;
signed Stripe webhook verification.

The raw API key is delivered once by email. Only a cryptographic hash and short suffix are stored for lookup and support purposes.

Proprietary components

The following remain proprietary intellectual property of TQNN Labs:

private inference substrate;
circuit and execution architecture;
internal embeddings and parameters;
private execution runtime;
production orchestration;
runtime optimization;
managed cloud infrastructure;
monitoring and billing systems.

The public contract, client integrations, documentation, and approved diagnostics do not grant access to those components.

Licensing

The MIT License applies only to the public materials identified by the repository license, such as eligible client code, examples, and integration utilities.

The hosted runtime, private inference substrate, execution engine, orchestration system, production services, and associated proprietary components are not released under the MIT License.

Enterprise and research

For enterprise licensing, research collaboration, commercial partnerships, or custom integration inquiries:

tqnnlabs@gmail.com

About TQNN Labs

TQNN Labs develops cloud-hosted, confidence-aware inference infrastructure for applications operating under imperfect real-world data conditions.

Build once. Infer through uncertainty.

Built in Canada 🇨🇦

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
examples		examples
tests		tests
.gitignore.		.gitignore.
CONTRIBUTING.md		CONTRIBUTING.md
Changelog.md		Changelog.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TQNN-Core-License.md		TQNN-Core-License.md
main.py		main.py
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
tqnn_client.py		tqnn_client.py

Latest commit

History

Folders and files

Repository files navigation