qdsv-qintent 0.1.4

Lightweight Python client for QIntent, the native intent language powered by QDSV.

QIntent Developer Preview

Lightweight Python SDK for QIntent, the native quantum-intent language powered by QDSV.

QIntent lets you write declarative computational intent over state spaces, predicates, rows, ranking, and sampling without writing circuits first or installing the QDSV Runtime locally.

QIntent is designed for quantum-oriented semantic computation: users describe what states, candidates, constraints, and evidence matter; QDSV decides how that intent is compiled, routed, and executed by statevector, simulator, or quantum-capable backends.

QIntent does not require circuits as the starting point. QDSV may execute a problem directly through semantic/statevector routes when possible, and only materializes circuits when a selected backend requires that representation. The public SDK defaults to the QDSV QuEST route because it is designed to execute QIntent over state spaces without requiring users to write circuits first.

pip install qdsv-qintent

Developer Preview: this package is a client SDK. It does not include QDSV Runtime, CAP, backend selection, QuEST/Aer/IBM adapters, lowering, noise mitigation internals, crypto internals, private endpoints, credentials, or advanced orchestration logic.

Open SDK, Private Runtime

This repository is intentionally open-core:

• Open under MIT: Python SDK, CLI, examples, notebooks, public preview docs, and public grammar notes.
• Not included: QDSV Runtime, CAP, backend selector, lowering, QuEST/Aer/IBM adapters, optimization layers, noise mitigation internals, crypto internals, private endpoints, keys, secrets, or production platform configuration.

QIntent SDKs and examples are released under the MIT License. QDSV Runtime, backend execution, optimization layers, quantum adapters, and internal orchestration components are not included in this repository and remain proprietary/private unless explicitly released under a separate license.

QDSV, QIntent, and Qruba names and marks are project marks of their respective owners. The MIT License for this repository does not grant trademark rights.

Quick Start

from qintent import QIntentClient

client = QIntentClient()

rows = [
    {"candidate_index": 0, "score": 720, "risk_ok": True},
    {"candidate_index": 1, "score": 910, "risk_ok": True},
    {"candidate_index": 2, "score": 840, "risk_ok": False},
]

result = client.run(
    'find_rows("candidate_index").where("score", ">=", 850).rank_by("score").top_k(5)',
    rows=rows,
)

print(result["status"])
print(result["result"]["selected_rows"])

QIntent Syntax

source = """
x = domain(0, 15)
score = clip(round(max(x["score"], 0)), 0, 1000)
find(x).where(all([700 <= score <= 950, x not in [0, 1]])).rank_by(score).top_k(3)
"""

compiled = client.compile(source)
print(compiled["compiled_summary"])

QIntent uses Python-inspired syntax for ergonomics, but its semantics are QDSV-native: state spaces, predicates, ranking, sampling, evidence, and backend-independent execution intent.

How QIntent Differs

QIntent works from the intention and formulation of the problem: users declare the search, condition, ranking, decision, or state-space relationship they need, and QDSV decides how to execute it. Circuits are not the starting point; they are only a possible materialization when a backend requires them.

Lenguaje / capa	Qué intenta ser	Diferencia de QIntent	Beneficio para el usuario
Classiq Qmod	Modelo de alto nivel para diseñar algoritmos cuánticos y sintetizar circuitos.	Qmod abstrae la creación de circuitos. QIntent parte de la intención del problema y solo materializa circuitos si el backend lo exige.	Permite formular problemas como búsqueda, ranking o decisión sin empezar diseñando circuitos.
Q#	Lenguaje formal para programar algoritmos cuánticos e híbridos.	Q# sigue siendo programación cuántica. QIntent es declaración de intención sobre espacios de estados.	Reduce la necesidad de saber programación cuántica detallada para expresar problemas ejecutables.
QIR	Representación intermedia para conectar lenguajes y backends.	QIR no está pensado para usuarios finales. QIntent sí es una interfaz declarativa usable por personas y SDKs.	El usuario escribe intención legible y QDSV decide la ruta de ejecución.
OpenQASM 3	Lenguaje para describir circuitos, operaciones y control cercano al hardware.	OpenQASM describe cómo ejecutar operaciones cuánticas. QIntent describe qué condición, búsqueda o decisión debe resolverse.	Evita obligar al usuario a escribir compuertas, mediciones y control de bajo nivel desde el inicio.
Qiskit / Cirq / QPanda	Frameworks para construir, simular y ejecutar circuitos o algoritmos cuánticos.	Son herramientas potentes, pero circuit/program-first. QIntent es intent/state-space-first.	Permite llevar problemas de datos, decisión o búsqueda a ejecución QDSV, QuEST, Aer o hardware sin rediseñarlos manualmente como circuitos.
PennyLane	Framework para QML, diferenciación y optimización híbrida.	PennyLane es fuerte en modelos entrenables y QML. QIntent es más general para predicados, scoring, ranking, búsqueda y selección.	Sirve cuando el usuario no quiere entrenar un modelo QML, sino evaluar candidatos o condiciones con evidencia.
Silq / Qrisp	Lenguajes de alto nivel para hacer más cómoda la programación cuántica.	Buscan simplificar la programación cuántica. QIntent busca evitar programar cuando el problema puede expresarse semánticamente.	Baja la barrera de entrada: el usuario declara el problema y QDSV decide cómo ejecutarlo.

Supported preview patterns include:

• find_rows(...).where(...)
• find_rows(...).where_between(...)
• find_rows(...).where_all(...)
• find_rows(...).where_any(...)
• find_rows(...).rank_by(...).top_k(...)
• domain(...), range(...), find(...).where(...)
• field(variable, column) and row["column"]
• not, in, not in, chained comparisons
• all([...]), any([...])
• abs(...), round(...), min(...), max(...), clip(...)

See grammar/QINTENT_PREVIEW.md for the public preview grammar notes.

Methods

client.spec()
client.examples()
client.validate(source, rows=None, backend="quest")
client.compile(source, rows=None, backend="quest")
client.run(source, rows=None, backend="quest")

Authentication and access

The public preview can be used without a user key for small examples and public QIntent endpoints:

client = QIntentClient()

The SDK can also send credentials when your Qruba/QDSV deployment or license requires them:

client = QIntentClient(
    api_key="...",
    license_key="...",
)

Environment variables are also supported:

QINTENT_API_URL=https://api.qdsv.cloud/api
QINTENT_API_KEY=...
QDSV_LICENSE_KEY=...

The SDK is a client. It does not grant access to private backends by itself; available capabilities depend on the API endpoint, account, license, deployment, and backend policy.

Data and workload policy

The public QIntent API is intended for lightweight evaluation:

• quickstarts
• notebooks
• examples
• small datasets
• public preview experiments

It should not be used for large datasets, private business data, long-running jobs, or heavy backend usage. Public endpoints may enforce row limits, payload limits, backend limits, and execution time limits to protect the shared free/preview infrastructure.

For larger datasets, sensitive data, or heavier workloads, use Qruba Cloud with an appropriate license or a private Docker/local QDSV node.

Backends

The SDK defaults to the QDSV QuEST route:

client.run(source)
client.run(source, backend="quest")
client.run(source, backend="aer")

Backend availability depends on the public API or Qruba deployment you are using.

• quest: default QDSV statevector route. This path can inspect and execute the semantic problem directly over the state space without requiring the user to write circuits.
• aer: circuit/simulator materialization when the deployment supports it.
• IBM/hardware routes are not part of the default public SDK preview; they are available through Qruba/full platform configurations when enabled.

For large datasets or production workloads, use a licensed Qruba/QDSV deployment. Public preview endpoints may enforce row, payload, backend, and execution limits.

For a local Docker/private demo API:

client = QIntentClient.local()

Private Docker/local execution is available only when a private QDSV node is online:

client = QIntentClient(api_url="https://qintent-local.qdsv.cloud/api")

If the private node is unavailable, it may be offline, reserved for private processing, or temporarily busy. Try again later or use the public cloud endpoint for lightweight examples:

client = QIntentClient()

CLI

qintent spec
qintent examples
qintent compile 'x = domain(0, 15); find(x).where(x in [3, 6, 9])'
qintent run 'find_rows("candidate_index").where("score", ">=", 850)' --rows candidates.csv

Public Preview Limits

The public preview intentionally exposes a stable subset. Advanced QDSV families such as crypto, sensing, AI semantic operations, hardware routing, large-data execution, and mitigation internals may compile or run only through Qruba full platform endpoints depending on your license.

Write QIntent locally. Execute on QDSV.

Links

• QDSV landing: https://qdsv.cloud
• QIntent site: https://qintent.qdsv.cloud
• Public API spec: https://api.qdsv.cloud/api/qintent/spec
• PyPI: https://pypi.org/project/qdsv-qintent/