sourcesql 0.1.0__py3-none-any.whl

sourcesql/__init__.py

@@ -0,0 +1,2 @@
+"""sourcesQL: bounded research datasets, independent of provider and host."""
+__version__ = "0.1.0"

sourcesql/bridge.py

@@ -0,0 +1,87 @@
+"""Bounded JSON-lines interface for the existing research service; stdout is machine-only."""
+
+from __future__ import annotations
+from concurrent.futures import ThreadPoolExecutor
+import os
+from pathlib import Path
+import sys
+import threading
+from sourcesql.contracts import SourcesQLError, canonical
+from sourcesql.contracts import digest
+from sourcesql.engine import Engine, strict_json
+
+
+def main():
+    profiles = {}
+    path = os.environ.get("SOURCESQL_PROFILES_FILE")
+    if path:
+        profiles = strict_json(Path(path).read_bytes())
+    principal = os.environ.get("SOURCESQL_PRINCIPAL", "local-owner")
+    store_root = (
+        Path(os.environ.get("SOURCESQL_DATA_DIR", "local/engine"))
+        / "principals"
+        / digest(principal)[:32]
+    )
+    engine = Engine(
+        store_root,
+        profiles=profiles,
+        allow_private=os.environ.get("SOURCESQL_ALLOW_PRIVATE", "1") == "1",
+    )
+    methods = {
+        "capabilities": engine.capabilities,
+        "query": engine.query,
+        "explain": engine.explain,
+        "read_result": engine.read_result,
+        "import_table": engine.import_table,
+        "export": engine.export,
+        "import": engine.import_bundle,
+        "run_status": engine.run_status,
+        "cancel": engine.cancel,
+    }
+    output_lock = threading.Lock()
+
+    def respond(line):
+        request_id = None
+        try:
+            if len(line) > 4 * 1024 * 1024:
+                raise SourcesQLError("budget_exhausted", "Bridge input exceeds byte limit")
+            request = strict_json(line)
+            request_id = request.get("id")
+            if (
+                not isinstance(request, dict)
+                or set(request) - {"id", "method", "params"}
+                or request.get("method") not in methods
+            ):
+                raise SourcesQLError("invalid_request", "Invalid bridge request")
+            params = request.get("params", {})
+            if not isinstance(params, dict):
+                raise SourcesQLError("invalid_request", "Invalid method parameters")
+            result = methods[request["method"]](**params)
+            response = {"id": request_id, "result": result}
+        except SourcesQLError as error:
+            response = {
+                "id": request_id,
+                "error": {"code": error.code, "message": error.safe_message, "stage": error.stage},
+            }
+        except Exception:
+            response = {
+                "id": request_id,
+                "error": {"code": "invalid_request", "message": "Request failed safely"},
+            }
+        with output_lock:
+            sys.stdout.buffer.write(canonical(response) + b"\n")
+            sys.stdout.buffer.flush()
+
+    with ThreadPoolExecutor(max_workers=4) as executor:
+        while line := sys.stdin.buffer.readline(4 * 1024 * 1024 + 1):
+            if not line.endswith(b"\n"):
+                while chunk := sys.stdin.buffer.readline(4 * 1024 * 1024 + 1):
+                    if chunk.endswith(b"\n"):
+                        break
+                respond(b"{}")
+            else:
+                executor.submit(respond, line)
+
+
+if __name__ == "__main__":
+    main()

sourcesql/cli.py

@@ -0,0 +1,93 @@
+"""Headless developer entry point; fixture mode by default."""
+
+import argparse
+import os
+from pathlib import Path
+import sys
+from sourcesql import __version__
+from sourcesql.contracts import SourcesQLError, canonical
+from sourcesql.engine import Engine, strict_json
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = argparse.ArgumentParser(prog="sourcesql")
+    parser.add_argument("--version", action="version", version=f"sourcesQL {__version__}")
+    parser.add_argument("--store", default=os.environ.get("SOURCESQL_DATA_DIR", "local/engine"))
+    commands = parser.add_subparsers(dest="command", required=True)
+    setup = commands.add_parser("setup", help="Prepare or resume an adopter-owned deployment")
+    setup.add_argument("setup_target", choices=["personal-cloud"])
+    setup.add_argument("arguments", nargs=argparse.REMAINDER)
+    commands.add_parser("capabilities").add_argument("--json", action="store_true")
+    for command in ["query", "explain"]:
+        p = commands.add_parser(command)
+        p.add_argument("--file", type=Path)
+        p.add_argument("--sql")
+        p.add_argument("--request", type=Path)
+        p.add_argument("--profile", default="fixture")
+        p.add_argument("--json", action="store_true")
+    p = commands.add_parser("read")
+    p.add_argument("result_id")
+    p.add_argument("--offset", type=int, default=0)
+    p.add_argument("--limit", type=int, default=100)
+    p = commands.add_parser("export")
+    p.add_argument("--result", required=True)
+    p.add_argument("--output", type=Path, required=True)
+    p = commands.add_parser("import")
+    p.add_argument("file", type=Path)
+    p.add_argument("--no-network", action="store_true")
+    p = commands.add_parser("demo")
+    p.add_argument("--profile", choices=["fixture"], default="fixture")
+    p.add_argument("--output", type=Path, default=Path("artifacts/demo"))
+    args = parser.parse_args(argv)
+    if args.command == "setup":
+        from sourcesql.onboarding import run_personal_cloud
+
+        return run_personal_cloud(args.arguments)
+    try:
+        profile_path = os.environ.get("SOURCESQL_PROFILES_FILE")
+        engine = Engine(
+            args.store,
+            profiles=strict_json(Path(profile_path).read_bytes()) if profile_path else None,
+        )
+        if args.command == "capabilities":
+            result = engine.capabilities()
+        elif args.command in ["query", "explain"]:
+            request = (
+                strict_json(args.request.read_bytes())
+                if args.request
+                else {
+                    "query": args.file.read_text() if args.file else args.sql,
+                    "profile": args.profile,
+                }
+            )
+            result = getattr(engine, args.command)(**request)
+        elif args.command == "read":
+            result = engine.read_result(args.result_id, args.offset, args.limit)
+        elif args.command == "export":
+            result = engine.export(args.result)
+            args.output.parent.mkdir(parents=True, exist_ok=True)
+            args.output.write_bytes(canonical(result))
+        elif args.command == "import":
+            result = engine.import_bundle(strict_json(args.file.read_bytes()))
+        else:
+            result = engine.query(
+                query="SELECT url, SEM_EXTRACT(content, 'project name explicitly stated') AS project, SEM_EXTRACT(content, 'planned capacity in MW, number only') AS planned_mw FROM WEB_SEARCH('fictional Aurora Birch campuses') WHERE SEM_MATCH(content, 'describes a specific data-center campus')",
+                profile="fixture",
+            )
+            args.output.mkdir(parents=True, exist_ok=True)
+            (args.output / "result.json").write_bytes(canonical(result))
+            (args.output / "bundle.json").write_bytes(canonical(engine.export(result["result_id"])))
+        print(canonical(result).decode())
+    except SourcesQLError as error:
+        print(
+            canonical(
+                {"error": {"code": error.code, "message": error.safe_message, "stage": error.stage}}
+            ).decode(),
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sourcesql/contracts.py

@@ -0,0 +1,109 @@
+"""Shared engine/provider/planner contracts. Coordinator-owned."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable
+import hashlib
+import json
+import threading
+
+
+class SourcesQLError(Exception):
+    def __init__(self, code: str, message: str, stage: str = "admission"):
+        super().__init__(message)
+        self.code, self.safe_message, self.stage = code, message, stage
+
+
+def canonical(value: Any) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+    ).encode()
+
+
+def digest(value: Any) -> str:
+    return hashlib.sha256(canonical(value)).hexdigest()
+
+
+@dataclass(frozen=True)
+class Column:
+    key: str
+    logical_type: str = "VARCHAR"
+    nullable: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "label": self.key,
+            "logical_type": self.logical_type,
+            "nullable": self.nullable,
+        }
+
+
+@dataclass
+class Table:
+    columns: list[Column]
+    rows: list[dict[str, Any]]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"columns": [c.to_dict() for c in self.columns], "rows": self.rows}
+
+
+@dataclass
+class SemanticOutcome:
+    value: Any
+    status: str
+    support: list[dict[str, Any]] = field(default_factory=list)
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+DEFAULT_LIMITS = {
+    "max_search_queries": 8,
+    "max_search_requests": 16,
+    "max_candidates": 200,
+    "max_fetches": 40,
+    "max_semantic_documents": 40,
+    "max_model_requests": 96,
+    "max_concurrency": 4,
+    "dispatch_deadline_seconds": 180,
+    "max_output_rows": 1000,
+    "max_output_bytes": 4194304,
+    "max_input_tokens": 200000,
+    "max_output_tokens": 16000,
+    "max_cost_microusd": 0,
+}
+
+
+class Budget:
+    """One shared allowance for the whole run. Provider attempts reserve before dispatch."""
+
+    def __init__(
+        self,
+        limits: dict[str, Any] | None = None,
+        on_reserve: Callable[[str, int], None] | None = None,
+    ):
+        self.limits = dict(DEFAULT_LIMITS)
+        for key, value in (limits or {}).items():
+            if key not in self.limits or type(value) is not int or value < 0:
+                raise SourcesQLError("invalid_request", "Invalid budget")
+            if key != "max_cost_microusd" and value > DEFAULT_LIMITS[key]:
+                raise SourcesQLError("invalid_request", "Requested budget exceeds v0.1 ceiling")
+            self.limits[key] = value
+        self.counts: dict[str, int] = {}
+        self.lock = threading.Lock()
+        self.cancelled = False
+        self.on_reserve = on_reserve
+
+    def reserve(self, counter: str, amount: int = 1, limit: str | None = None) -> None:
+        with self.lock:
+            if self.cancelled:
+                raise SourcesQLError("cancelled", "Run cancelled", "dispatch")
+            cap = self.limits.get(limit or "max_" + counter)
+            value = self.counts.get(counter, 0) + amount
+            if cap is not None and value > cap:
+                raise SourcesQLError("budget_exhausted", "Work allowance exhausted", "dispatch")
+            self.counts[counter] = value
+            observer = self.on_reserve
+        # Persistence/authorization observers finish before the caller can dispatch.
+        # Exceptions propagate; the reserved allowance remains conservatively consumed.
+        if observer is not None:
+            observer(counter, amount)