qdsv-runtime 0.1.0a1__py3-none-any.whl

qdsv_runtime/__init__.py

@@ -0,0 +1,4 @@
+from .runtime import QDSVRuntime
+
+__all__ = ["QDSVRuntime"]
+__version__ = "0.1.0a1"

qdsv_runtime/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .runtime import QDSVRuntime
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="qdsv",
+        description="QDSV Runtime Alpha CLI for problem-first QDSV workflows.",
+    )
+    parser.add_argument("--root", default=".", help="Workspace root directory.")
+    parser.add_argument("--api-url", default=None, help="QDSV API base URL.")
+    parser.add_argument("--local", action="store_true", help="Use local/private Docker API.")
+    parser.add_argument("--timeout", type=float, default=30.0, help="Request timeout in seconds.")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="Create a QDSV Runtime Alpha workspace.")
+    init.add_argument("--force", action="store_true", help="Overwrite generated examples.")
+
+    validate = sub.add_parser("validate", help="Validate a QIntent file.")
+    validate.add_argument("source", help="Path to .qintent source.")
+    validate.add_argument("--rows", default=None, help="Optional rows JSON file.")
+    validate.add_argument("--backend", default="quest", help="Requested backend for QIntent.")
+    validate.add_argument("--shots", type=int, default=256, help="Requested shots.")
+
+    explain = sub.add_parser("explain", help="Explain a QIntent file.")
+    explain.add_argument("source", help="Path to .qintent source.")
+    explain.add_argument("--rows", default=None, help="Optional rows JSON file.")
+    explain.add_argument("--backend", default="quest", help="Requested backend for QIntent.")
+    explain.add_argument("--shots", type=int, default=256, help="Requested shots.")
+
+    build = sub.add_parser("build", help="Build a target artifact.")
+    build.add_argument("input", help="Input file. For --target bridge, use a Bridge spec JSON.")
+    build.add_argument("--target", choices=["bridge"], default="bridge", help="Build target.")
+
+    report = sub.add_parser("report", help="Generate a local runtime report.")
+    report.add_argument("--title", default="QDSV Runtime Alpha Report", help="Report title.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    runtime = QDSVRuntime(root=args.root, api_url=args.api_url, local=args.local, timeout=args.timeout)
+
+    try:
+        if args.command == "init":
+            workspace = runtime.init_workspace(force=args.force)
+            print(f"QDSV workspace ready: {Path(args.root).resolve() / '.qdsv'}")
+            print(f"Runtime: {workspace['runtime']}")
+            return 0
+        if args.command == "validate":
+            artifact = runtime.validate_intent(args.source, rows_path=args.rows, backend=args.backend, shots=args.shots)
+            print("QIntent validation artifact saved.")
+            print(f"Status: {artifact['payload'].get('status', 'UNKNOWN')}")
+            return 0
+        if args.command == "explain":
+            artifact = runtime.explain_intent(args.source, rows_path=args.rows, backend=args.backend, shots=args.shots)
+            print("QIntent explain artifact saved.")
+            print(f"Status: {artifact['payload'].get('status', 'UNKNOWN')}")
+            return 0
+        if args.command == "build":
+            artifact = runtime.build_bridge(args.input)
+            print("Bridge build artifact saved.")
+            print(f"Status: {artifact['payload'].get('status', 'UNKNOWN')}")
+            return 0
+        if args.command == "report":
+            report_path = runtime.write_report(title=args.title)
+            print(f"Runtime report written: {report_path}")
+            return 0
+    except Exception as exc:  # pragma: no cover - CLI boundary
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

qdsv_runtime/runtime.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+
+from qdsv_bridge import QDSVBridgeClient
+from qintent import QIntentClient
+
+
+WORKSPACE_DIR = ".qdsv"
+ARTIFACTS_DIR = "artifacts"
+REPORTS_DIR = "reports"
+WORKSPACE_FILE = "workspace.json"
+
+
+@dataclass
+class QDSVRuntime:
+    """Small public execution layer for QDSV developer workflows.
+
+    Runtime Alpha orchestrates public SDK calls and local artifacts. It does
+    not embed or expose the private QDSV semantic engine.
+    """
+
+    root: str | Path = "."
+    api_url: str | None = None
+    local: bool = False
+    timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        self.root_path = Path(self.root).resolve()
+        if self.local:
+            self.qintent = QIntentClient.local(timeout=self.timeout)
+            self.bridge = QDSVBridgeClient.local(timeout=self.timeout)
+        else:
+            self.qintent = QIntentClient(api_url=self.api_url, timeout=self.timeout)
+            self.bridge = QDSVBridgeClient(api_url=self.api_url, timeout=self.timeout)
+
+    @property
+    def workspace_path(self) -> Path:
+        return self.root_path / WORKSPACE_DIR
+
+    @property
+    def artifacts_path(self) -> Path:
+        return self.workspace_path / ARTIFACTS_DIR
+
+    @property
+    def reports_path(self) -> Path:
+        return self.workspace_path / REPORTS_DIR
+
+    def init_workspace(self, *, force: bool = False) -> dict[str, Any]:
+        self.workspace_path.mkdir(parents=True, exist_ok=True)
+        self.artifacts_path.mkdir(parents=True, exist_ok=True)
+        self.reports_path.mkdir(parents=True, exist_ok=True)
+        examples_path = self.root_path / "examples"
+        examples_path.mkdir(parents=True, exist_ok=True)
+
+        workspace = {
+            "name": self.root_path.name,
+            "runtime": "qdsv-runtime-alpha",
+            "version": "0.1.0a1",
+            "created_at": self._now(),
+            "engine_exposed": False,
+            "default_api_route": "local" if self.local else "public",
+            "artifacts_dir": str(self.artifacts_path.relative_to(self.root_path)),
+            "reports_dir": str(self.reports_path.relative_to(self.root_path)),
+        }
+        workspace_file = self.workspace_path / WORKSPACE_FILE
+        if force or not workspace_file.exists():
+            self._write_json(workspace_file, workspace)
+
+        qintent_example = examples_path / "basic.qintent"
+        if force or not qintent_example.exists():
+            qintent_example.write_text(
+                'find_rows("candidate_index").where("score", ">=", 850).rank_by("score").top_k(2)\n',
+                encoding="utf-8",
+            )
+
+        rows_example = examples_path / "rows.json"
+        if force or not rows_example.exists():
+            self._write_json(
+                rows_example,
+                [
+                    {"candidate_index": 0, "score": 720, "risk_ok": True},
+                    {"candidate_index": 1, "score": 910, "risk_ok": True},
+                    {"candidate_index": 2, "score": 840, "risk_ok": False},
+                ],
+            )
+
+        bridge_example = examples_path / "bridge_spec.json"
+        if force or not bridge_example.exists():
+            self._write_json(
+                bridge_example,
+                {
+                    "family": "bounded_semantic_marking",
+                    "bridge_mode": "build",
+                    "name": "runtime_alpha_demo",
+                    "description": "Small public Runtime Alpha example for Bridge handoff.",
+                    "state_space": {
+                        "kind": "finite_candidates",
+                        "candidate_count": 8,
+                        "candidate_id": "candidate",
+                    },
+                    "signals": ["eligibility_score", "risk_score"],
+                    "goal": {
+                        "kind": "marking",
+                        "predicate": "eligible_candidate",
+                    },
+                    "target": {"format": "qasm3", "backend_family": "qiskit"},
+                    "limits": {"max_qubits": 5, "max_depth": 160},
+                },
+            )
+
+        return workspace
+
+    def validate_intent(
+        self,
+        source_path: str | Path,
+        *,
+        rows_path: str | Path | None = None,
+        backend: str = "quest",
+        shots: int = 256,
+    ) -> dict[str, Any]:
+        source = self._read_text(source_path)
+        rows = self._read_json(rows_path) if rows_path else None
+        payload = self.qintent.validate(source, rows=rows, backend=backend, shots=shots)
+        return self._save_artifact("qintent-validate", payload)
+
+    def explain_intent(
+        self,
+        source_path: str | Path,
+        *,
+        rows_path: str | Path | None = None,
+        backend: str = "quest",
+        shots: int = 256,
+    ) -> dict[str, Any]:
+        source = self._read_text(source_path)
+        rows = self._read_json(rows_path) if rows_path else None
+        payload = self.qintent.explain(source, rows=rows, backend=backend, shots=shots)
+        return self._save_artifact("qintent-explain", payload)
+
+    def build_bridge(self, spec_path: str | Path) -> dict[str, Any]:
+        spec = self._read_json(spec_path)
+        if not isinstance(spec, Mapping):
+            raise ValueError("Bridge spec must be a JSON object.")
+        payload = self.bridge.build(spec)
+        return self._save_artifact("bridge-build", payload)
+
+    def write_report(self, *, title: str = "QDSV Runtime Alpha Report") -> Path:
+        self.reports_path.mkdir(parents=True, exist_ok=True)
+        artifacts = sorted(self.artifacts_path.glob("*.json"))
+        lines = [
+            f"# {title}",
+            "",
+            f"- Generated at: {self._now()}",
+            "- Runtime: qdsv-runtime-alpha",
+            "- Private semantic engine exposed: no",
+            "- Purpose: tie QIntent and Bridge into a reproducible public workflow.",
+            "",
+            "## Artifacts",
+            "",
+        ]
+        if not artifacts:
+            lines.append("No artifacts found yet.")
+        for artifact in artifacts:
+            lines.append(f"- `{artifact.relative_to(self.root_path)}`")
+        lines.extend(
+            [
+                "",
+                "## Public Alpha Boundary",
+                "",
+                "This report was generated by the public Runtime Alpha shell. It does not include private QDSV semantic compiler internals, lowering logic, backend-selection heuristics, private formulas, credentials, or production runtime configuration.",
+                "",
+            ]
+        )
+        report_path = self.reports_path / "runtime-report.md"
+        report_path.write_text("\n".join(lines), encoding="utf-8")
+        return report_path
+
+    def _save_artifact(self, name: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+        self.artifacts_path.mkdir(parents=True, exist_ok=True)
+        artifact = {
+            "runtime": "qdsv-runtime-alpha",
+            "generated_at": self._now(),
+            "engine_exposed": False,
+            "artifact_kind": name,
+            "payload": dict(payload),
+        }
+        path = self.artifacts_path / f"{name}.json"
+        self._write_json(path, artifact)
+        return artifact
+
+    def _read_text(self, path: str | Path) -> str:
+        return (self.root_path / path).read_text(encoding="utf-8") if not Path(path).is_absolute() else Path(path).read_text(encoding="utf-8")
+
+    def _read_json(self, path: str | Path | None) -> Any:
+        if path is None:
+            return None
+        full_path = self.root_path / path if not Path(path).is_absolute() else Path(path)
+        return json.loads(full_path.read_text(encoding="utf-8"))
+
+    @staticmethod
+    def _write_json(path: Path, payload: Any) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).isoformat(timespec="seconds")

qdsv_runtime-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: qdsv-runtime
+Version: 0.1.0a1
+Summary: QDSV Runtime Alpha: a lightweight execution layer for problem-first QDSV workflows.
+Project-URL: Homepage, https://qdsv.cloud/
+Project-URL: Source, https://github.com/qdsvquantum-afk/qdsv-runtime
+Project-URL: QIntent, https://qdsvquantum-afk.github.io/qintent/
+Project-URL: Bridge, https://qdsvquantum-afk.github.io/qdsv-bridge/
+Project-URL: Qruba, https://qdsvquantum-afk.github.io/qruba/
+Author: QDSV / Qruba
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bridge,qdsv,qintent,quantum-software,runtime,semantic-workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: qdsv-bridge>=0.1.6
+Requires-Dist: qdsv-qintent>=0.1.11
+Description-Content-Type: text/markdown
+
+# QDSV Runtime Alpha
+
+[![Status](https://img.shields.io/badge/status-alpha-f59e0b.svg)](#public-alpha-scope)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**QDSV Runtime Alpha** is a lightweight execution layer for problem-first QDSV workflows.
+
+It ties together the public QDSV developer stack:
+
+```text
+QIntent -> QDSV Runtime Alpha -> QDSV Bridge -> OpenQASM / Qiskit / reports
+
+Qruba -> visual human interaction layer
+QDSV -> semantic model and private engine
+```
+
+Runtime Alpha does **not** embed or expose the private QDSV semantic engine. It provides a small workspace, CLI and SDK that call the public QIntent and Bridge clients, save artifacts, and generate reproducibility reports.
+
+## Install
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+When published:
+
+```bash
+pip install qdsv-runtime
+```
+
+Before the PyPI release, users can install from GitHub after the public repository is created:
+
+```bash
+pip install git+https://github.com/qdsvquantum-afk/qdsv-runtime.git
+```
+
+## CLI Quickstart
+
+Create a workspace:
+
+```bash
+qdsv init
+```
+
+Validate a QIntent file:
+
+```bash
+qdsv validate examples/basic.qintent
+```
+
+Build a Bridge artifact from a supported Bridge spec:
+
+```bash
+qdsv build examples/bridge_spec.json --target bridge
+```
+
+Generate a local runtime report:
+
+```bash
+qdsv report
+```
+
+Docker/private demo images can also include the same CLI:
+
+```bash
+docker exec qruba-api-private qdsv --help
+```
+
+## Python SDK
+
+```python
+from qdsv_runtime import QDSVRuntime
+
+runtime = QDSVRuntime()
+runtime.init_workspace()
+runtime.validate_intent("examples/basic.qintent")
+runtime.build_bridge("examples/bridge_spec.json")
+runtime.write_report()
+```
+
+## Public Alpha Scope
+
+This alpha includes:
+
+- workspace creation;
+- QIntent validation/explain calls through the public API or configured local/private node;
+- Bridge build calls for supported public Bridge specifications;
+- local artifact storage;
+- reproducibility report generation;
+- CLI commands for small examples.
+
+This alpha does **not** include:
+
+- private QDSV Runtime internals;
+- semantic compiler internals;
+- lowering logic;
+- backend selection internals;
+- private scoring formulas;
+- production scheduler;
+- user/tenant management;
+- marketplace/plugins;
+- local execution of the private semantic engine.
+
+## Positioning
+
+QDSV Runtime Alpha is not a quantum operating system. It is an early semantic execution layer for problem-first QDSV workflows. The goal is to show how QIntent, Bridge and future visual environments such as Qruba can be tied together through a small executable layer without exposing the private engine.

qdsv_runtime-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,8 @@
+qdsv_runtime/__init__.py,sha256=JVS-0cYDQ6nBN62L4KqvtWszrNzpP-bjZM1CFOjdhcw,84
+qdsv_runtime/cli.py,sha256=jmi_Z0DsahGe6npK6tI58LXS6Mkey0kfvO7FdkKDuMI,3945
+qdsv_runtime/runtime.py,sha256=XOcR2nNE78taJCGppR6kpa3pUUKpHZynFEN2gDnOKLU,8161
+qdsv_runtime-0.1.0a1.dist-info/METADATA,sha256=stTL3hQQmwXzHQB6jJmG2gftk6YE9pD756h4jOh_HV8,3782
+qdsv_runtime-0.1.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+qdsv_runtime-0.1.0a1.dist-info/entry_points.txt,sha256=0aTstFYWJpySnGuEIdLT0VRZt5-WQYvM-ELXTKP-JVg,47
+qdsv_runtime-0.1.0a1.dist-info/licenses/LICENSE,sha256=yoNayV2fcGyHGUbPl4faQjXbfKFiirxIDiC9RcTokhs,1069
+qdsv_runtime-0.1.0a1.dist-info/RECORD,,

qdsv_runtime-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

qdsv_runtime-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qdsv = qdsv_runtime.cli:main

qdsv_runtime-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QDSV / Qruba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.